Show a Custom Form with the WinForms Dashboard Designer

• Oct 28, 2021
• 2 minutes to read

This topic describes how to show a custom form as the WinForms Dashboard Designer used to create and modify dashboards in WinForms XAF applications. For instance, it can be required for customizing the menu (adding custom bar items or removing certain default bar items).

• Add the new XtraForm or RibbonForm to the project.
• Add the DashboardDesigner control to the newly created form as described in the Create a Designer Application section of the Create a WinForms Designer topic.
• Add a property of the DashboardDesigner type to the custom form.
• Create a Controller in the WinForms module project (MySolution.Module.Win). If your solution does not contain this project, add the Controller to the WinForms application project (MySolution.Win). This Controller is activated in the IDashboardData Views only.
• Access the WinShowDashboardDesignerController using the Frame.GetController<ControllerType> method.
• Access the DashboardDesignerManager object using the WinShowDashboardDesignerController.DashboardDesignerManager property.
• Handle the DashboardDesignerManager.CreateCustomForm event. Create and assign a custom form to the CreateCustomFormEventArgs.Form property.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/xaf-how-to-show-a-custom-form-as-the-winforms-dashboard-designer.

CustomDashboardDesignerFormController.cs

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Dashboards.Win;
using DevExpress.Persistent.Base;
// ...
public class CustomDashboardDesignerFormController : ObjectViewController<ObjectView, IDashboardData> {
    private WinShowDashboardDesignerController showDashboardDesignerController;
    protected override void OnActivated() {
        base.OnActivated();
        showDashboardDesignerController = Frame.GetController<WinShowDashboardDesignerController>();
        if(showDashboardDesignerController != null) {
            showDashboardDesignerController.DashboardDesignerManager.CreateCustomForm += Manager_CreateCustomForm;
        }
    }
    private void Manager_CreateCustomForm(object sender, CreateCustomFormEventArgs e) {
        e.Form = new CustomDashboardDesignerForm();
    }
    protected override void OnDeactivated() {
        base.OnDeactivated();
        if(showDashboardDesignerController != null) {
            showDashboardDesignerController.DashboardDesignerManager.CreateCustomForm -= Manager_CreateCustomForm;
        }
    }
}

CustomDashboardDesignerFormController.vb

Imports DevExpress.ExpressApp
Imports DevExpress.ExpressApp.Dashboards.Win
Imports DevExpress.Persistent.Base
' ...
Public Class CustomDashboardDesignerFormController
    Inherits ObjectViewController(Of ObjectView, IDashboardData)

    Private showDashboardDesignerController As WinShowDashboardDesignerController
    Protected Overrides Sub OnActivated()
        MyBase.OnActivated()
        showDashboardDesignerController = Frame.GetController(Of WinShowDashboardDesignerController)()
        If showDashboardDesignerController IsNot Nothing Then
            AddHandler showDashboardDesignerController.DashboardDesignerManager.CreateCustomForm, AddressOf Manager_CreateCustomForm
        End If
    End Sub
    Private Sub Manager_CreateCustomForm(ByVal sender As Object, ByVal e As CreateCustomFormEventArgs)
        e.Form = New CustomDashboardDesignerForm()
    End Sub
    Protected Overrides Sub OnDeactivated()
        MyBase.OnDeactivated()
        If showDashboardDesignerController IsNot Nothing Then
            RemoveHandler showDashboardDesignerController.DashboardDesignerManager.CreateCustomForm, AddressOf Manager_CreateCustomForm
        End If
    End Sub
End Class

CustomDashboardDesignerForm.cs

using DevExpress.DashboardWin;
// ...
public partial class CustomDashboardDesignerForm : DevExpress.XtraBars.Ribbon.RibbonForm {
    public CustomDashboardDesignerForm() {
        InitializeComponent();
    }
    public DashboardDesigner Designer {
        get { return dashboardDesigner; }
    }
}

CustomDashboardDesignerForm.vb

Imports DevExpress.DashboardWin
' ...
Partial Public Class CustomDashboardDesignerForm
    Inherits DevExpress.XtraBars.Ribbon.RibbonForm

    Public Sub New()
        InitializeComponent()
    End Sub
    Public ReadOnly Property Designer() As DashboardDesigner
        Get
            Return dashboardDesigner
        End Get
    End Property
End Class