How to: Implement Custom Saving and Opening Procedures in Dashboard Designer

• Mar 31, 2018
• 4 minutes to read

The Dashboard Designer provides the capability to override default opening and saving procedures when an end-used clicks one of these buttons

or tries to save the dashboard using the save confirmation dialog when the window with the DashboardDesigner is closed.

Handle the DashboardDesigner.DashboardOpening and DashboardDesigner.DashboardSaving events for this purpose.

The following example demonstrates how to implement custom saving and opening procedures in Dashboard Designer using the DashboardDesigner.DashboardSaving and DashboardDesigner.DashboardOpening events respectively.

In this example, the dashboard XML definition can be saved (opened) only to(from) the specified default location.

The DashboardDesigner.DashboardSaving event is handled to implement a custom saving routine. Its DashboardSavingEventArgs.Command event parameter allows determining what user action raises the event. The Dashboard.SaveToXml method is used to save the dashboard to the specified XML file. Then, the DashboardSavingEventArgs.Handled event parameter is used to specify that the dashboard has been saved and no default actions are required.

Clicking the Save As button invokes a message box that allows saving the dashboard to the default location or cancel the saving procedure. The DashboardSavingEventArgs.Saved event parameter is used to notify whether the custom saving routine has succeeded.

The DashboardDesigner.DashboardOpening event is handled to implement a custom opening procedure. The DashboardDesigner.LoadDashboard method is called to load the dashboard from the default location. The DashboardOpeningEventArgs.Handled event parameter allows specifying that no default actions are required to open the dashboard.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-implement-custom-saving-and-opening-procedures-in-dashboard-designer-e4754.

Form1.cs

using System.Windows.Forms;
using DevExpress.XtraBars.Ribbon;

namespace Dashboard_LoadingAndSaving {
    public partial class Form1 : RibbonForm {

        // Specifies the path to the dashboard XML definition.
        string filePath = @"..\..\Data\DashboardDefinition.xml";

        public Form1() {
            InitializeComponent();

            // Creates and initializes a Ribbon in the DashboardDesigner's parent control.
            dashboardDesigner1.CreateRibbon();

            // Loads a dashboard from an XML file.
            dashboardDesigner1.LoadDashboard(filePath);
        }

        // Handles the DashboardSaving event.
        private void dashboardDesigner1_DashboardSaving(object sender, 
            DevExpress.DashboardWin.DashboardSavingEventArgs e) {

            // Determines whether the user has called the Save command.
            if (e.Command == DevExpress.DashboardWin.DashboardSaveCommand.Save) {

                // Saves the dashboard to the specified XML file.
                dashboardDesigner1.Dashboard.SaveToXml(filePath);

                // Specifies that the dashboard has been saved and no default actions are required.
                e.Handled = true;
            }

            // Determines whether the user has called the Save As command.
            if (e.Command == DevExpress.DashboardWin.DashboardSaveCommand.SaveAs) {
                DialogResult result = InvokeMessageBox();
                if (result == System.Windows.Forms.DialogResult.OK) {
                    dashboardDesigner1.Dashboard.SaveToXml(filePath);
                    e.Handled = true;

                    // Specifies that the dashboard has been saved.
                    e.Saved = true;
                }
                if (result == System.Windows.Forms.DialogResult.Cancel) {
                    e.Handled = true;
                    e.Saved = false;
                }
            }
        }

        // Handles the DashboardOpening event.
        private void dashboardDesigner1_DashboardOpening(object sender, 
            DevExpress.DashboardWin.DashboardOpeningEventArgs e) {

            // Loads the previously saved dashboard from an XML file.
            dashboardDesigner1.LoadDashboard(filePath);

            // Specifies that the dashboard opening procedure has been provided.
            e.Handled = true;
        }
    }
}

Form1.vb

Imports Microsoft.VisualBasic
Imports System.Windows.Forms
Imports DevExpress.XtraBars.Ribbon

Namespace Dashboard_LoadingAndSaving
    Partial Public Class Form1
        Inherits RibbonForm

        ' Specifies the path to the dashboard XML definition.
        Private filePath As String = "..\..\Data\DashboardDefinition.xml"

        Public Sub New()
            InitializeComponent()

            ' Creates and initializes a Ribbon in the DashboardDesigner's parent control.
            dashboardDesigner1.CreateRibbon()

            ' Loads a dashboard from an XML file.
            dashboardDesigner1.LoadDashboard(filePath)
        End Sub

        ' Handles the DashboardSaving event.
        Private Sub dashboardDesigner1_DashboardSaving(ByVal sender As Object, _
                                      ByVal e As DevExpress.DashboardWin.DashboardSavingEventArgs) _
                                  Handles dashboardDesigner1.DashboardSaving

            ' Determines whether the user has called the Save command.
            If e.Command = DevExpress.DashboardWin.DashboardSaveCommand.Save Then

                ' Saves the dashboard to the specified XML file.
                dashboardDesigner1.Dashboard.SaveToXml(filePath)

                ' Specifies that the dashboard has been saved and no default actions are required.
                e.Handled = True
            End If

            ' Determines whether the user has called the Save As command.
            If e.Command = DevExpress.DashboardWin.DashboardSaveCommand.SaveAs Then
                Dim result As DialogResult = InvokeMessageBox()
                If result = System.Windows.Forms.DialogResult.OK Then
                    dashboardDesigner1.Dashboard.SaveToXml(filePath)
                    e.Handled = True

                    ' Specifies that the dashboard has been saved.
                    e.Saved = True
                End If
                If result = System.Windows.Forms.DialogResult.Cancel Then
                    e.Handled = True
                    e.Saved = False
                End If
            End If
        End Sub

        ' Handles the DashboardOpening event.
        Private Sub dashboardDesigner1_DashboardOpening(ByVal sender As Object, _
                                      ByVal e As DevExpress.DashboardWin.DashboardOpeningEventArgs) _
                                  Handles dashboardDesigner1.DashboardOpening

            ' Loads the previously saved dashboard from an XML file.
            dashboardDesigner1.LoadDashboard(filePath)

            ' Specifies that the dashboard opening procedure has been provided.
            e.Handled = True
        End Sub
    End Class
End Namespace