ContextQMD
Back to Devexpress

Dashboard Description

dashboard-401674-winforms-dashboard-winforms-designer-ui-elements-and-customization-create-custom-properties-dashboard-description.md

latest25.0 KB
Original Source

Dashboard Description

  • Oct 15, 2021
  • 10 minutes to read

This topic describes how to create a custom property for a dashboard. In this example, the custom property provides the editor to edit text and use this text as the dashboard’s description.

View Example: WinForms Dashboard - Custom Properties

Create the Custom Functionality Module

The code is organized into a separate module you can integrate in any dashboard application.

Create the DashboardDescriptionModule class that serves as a custom functionality module and contains:

  • a dashboard control that you pass as a parameter when you register the module,
  • a custom property’s unique name,
  • event subscriptions that are used to provide custom functionality,
  • a ribbon in which you add a button to edit custom property’s value.

Note

You can use the IDashboardControl interface that provides common API for WinForms Designer and Viewer to write code that can be used in both controls simultaneously.

You can add control elements to the Ribbon / Toolbar to change the custom property’s value in the UI.

Use the DashboardDesignerBarExtensions class static methods to get the current Ribbon / Toolbar instance. The DashboardRibbonPage / DashboardToolbar and DashboardBarItemCategory values are used to indicate the button position.

In this example, the Dashboard Description button is in the Dashboard group on the Dashboard’s Home page.

csharp
public class DashboardDescriptionModule {
public static readonly string PropertyName = "DashboardDescription";
readonly DashboardDesigner designer;
readonly SvgImage titleDescriptionImage;

public DashboardDescriptionModule(DashboardDesigner designer, SvgImage barImage = null, SvgImage titleDescriptionImage = null) {
    this.designer = designer;
    this.titleDescriptionImage = titleDescriptionImage;
    RibbonControl ribbon = (RibbonControl)designer.MenuManager;
    RibbonPage page = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.None, DashboardRibbonPage.Home);
    RibbonPageGroup group = page.Groups.GetGroupByText(DashboardWinLocalizer.GetString(DashboardWinStringId.RibbonPageDashboardCaption));
    BarButtonItem barItem = CreateBarItem("Dashboard Description", barImage);
    group.ItemLinks.Add(barItem);
    barItem.ItemClick += DescriptionBarItem_Click;
    designer.CustomizeDashboardTitle += Designer_CustomizeDashboardTitle;
    designer.DashboardCustomPropertyChanged += Designer_DashboardCustomPropertyChanged;
}
vb
Public Class DashboardDescriptionModule
Public Shared ReadOnly PropertyName As String = "DashboardDescription"
Private ReadOnly designer As DashboardDesigner
Private ReadOnly titleDescriptionImage As SvgImage

Public Sub New(ByVal designer As DashboardDesigner, Optional ByVal barImage As SvgImage = Nothing, Optional ByVal titleDescriptionImage As SvgImage = Nothing)
    Me.designer = designer
    Me.titleDescriptionImage = titleDescriptionImage
    Dim ribbon As RibbonControl = CType(designer.MenuManager, RibbonControl)
    Dim page As RibbonPage = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.None, DashboardRibbonPage.Home)
    Dim group As RibbonPageGroup = page.Groups.GetGroupByText(DashboardWinLocalizer.GetString(DashboardWinStringId.RibbonPageDashboardCaption))
    Dim barItem As BarButtonItem = CreateBarItem("Dashboard Description", barImage)
    group.ItemLinks.Add(barItem)
    AddHandler barItem.ItemClick, AddressOf DescriptionBarItem_Click
    AddHandler designer.CustomizeDashboardTitle, AddressOf Designer_CustomizeDashboardTitle
    AddHandler designer.DashboardCustomPropertyChanged, AddressOf Designer_DashboardCustomPropertyChanged
End Sub
csharp
BarButtonItem CreateBarItem(string caption, SvgImage barImage) {
    BarButtonItem barItem = new BarButtonItem();
    barItem.Caption = caption;
    barItem.ImageOptions.SvgImage = barImage;
    return barItem;
}
vb
Private Function CreateBarItem(ByVal caption As String, ByVal barImage As SvgImage) As BarButtonItem
    Dim barItem As New BarButtonItem()
    barItem.Caption = caption
    barItem.ImageOptions.SvgImage = barImage
    Return barItem
End Function

Edit and Save the Custom Property’s Value

Create a new form where a user can edit the dashboard’s description text. Add a text editor and a button that saves changes. You can add them to the Layout Control and arrange controls within a form without them being overlapped and misaligned. The form should be invoked when a user clicks the button in the Ribbon. Closing the form saves the custom property’s value.

Use the DashboardDesigner.AddToHistory method to record a new custom property’s value and save the action to the Dashboard Designer’s history when a user changes the value. This method calls the CustomProperties.SetValue method and adds the information to the history item. You can undo/redo this action like other user actions.

csharp
void ShowDescriptionForm() {
    string currentCaption = designer.Dashboard.CustomProperties.GetValue(PropertyName);
    LayoutControl layoutControl = new LayoutControl();
    layoutControl.Dock = DockStyle.Fill;
    layoutControl.Name = "layoutControl1";

    LayoutControlItem memoEditLayoutItem = layoutControl.Root.AddItem();
    memoEditLayoutItem.TextLocation = Locations.Top;
    memoEditLayoutItem.Text = "Text:";
    MemoEdit memoEdit = new MemoEdit();
    memoEdit.Text = currentCaption;
    memoEditLayoutItem.Control = memoEdit;

    LayoutControlItem buttonLayoutItem = layoutControl.Root.AddItem();
    buttonLayoutItem.SizeConstraintsType = SizeConstraintsType.Custom;
    buttonLayoutItem.TextVisible = false;
    SimpleButton buttonOk = new SimpleButton();
    buttonOk.Text = "OK";
    buttonOk.DialogResult = DialogResult.OK;
    buttonOk.Click += (sender1, e1) => {
        string modifiedCaption = memoEdit.Text;
        if(currentCaption != modifiedCaption) {
            string status = !string.IsNullOrEmpty(modifiedCaption) ? "Remove" : "Add";
            CustomPropertyHistoryItem historyItem = new CustomPropertyHistoryItem(designer.Dashboard, PropertyName, modifiedCaption, status + " the dashboard caption");
            designer.AddToHistory(historyItem);
        }
    };
    buttonLayoutItem.Control = buttonOk;
    layoutControl.Root.AddItem(new EmptySpaceItem(), buttonLayoutItem, InsertType.Left);
    using(XtraForm form = new XtraForm()) { 
        form.Text = "Description";  
        form.Size = new System.Drawing.Size(250, 250);  
        form.StartPosition = FormStartPosition.CenterParent;    
        form.IconOptions.ShowIcon = false;  
        form.Controls.Add(layoutControl);   
        form.ShowDialog();  
        }   
    }

void DescriptionBarItem_Click(object sender, EventArgs e) {
    ShowDescriptionForm();
}
vb
Private Sub ShowDescriptionForm()
        Dim currentCaption As String = designer.Dashboard.CustomProperties.GetValue(PropertyName)
        Dim layoutControl As New LayoutControl()
        layoutControl.Dock = DockStyle.Fill
        layoutControl.Name = "layoutControl1"
        Dim memoEditLayoutItem As LayoutControlItem = layoutControl.Root.AddItem()
        memoEditLayoutItem.TextLocation = Locations.Top
        memoEditLayoutItem.Text = "Text:"
        Dim memoEdit As New MemoEdit()
        memoEdit.Text = currentCaption
        memoEditLayoutItem.Control = memoEdit
        Dim buttonLayoutItem As LayoutControlItem = layoutControl.Root.AddItem()
        buttonLayoutItem.SizeConstraintsType = SizeConstraintsType.Custom
        buttonLayoutItem.TextVisible = False
        Dim buttonOk As New SimpleButton()
        buttonOk.Text = "OK"
        buttonOk.DialogResult = DialogResult.OK
        AddHandler buttonOk.Click, Sub(sender1, e1)
            Dim modifiedCaption As String = memoEdit.Text
            If currentCaption <> modifiedCaption Then
                Dim status As String = If(Not String.IsNullOrEmpty(modifiedCaption), "Remove", "Add")
                Dim historyItem As New CustomPropertyHistoryItem(designer.Dashboard, PropertyName, modifiedCaption, status & " the dashboard caption")
                designer.AddToHistory(historyItem)
            End If
        End Sub
        buttonLayoutItem.Control = buttonOk
        layoutControl.Root.AddItem(New EmptySpaceItem(), buttonLayoutItem, InsertType.Left)
        Using form As New XtraForm()
            form.Text = "Description"
            form.Size = New System.Drawing.Size(250, 250)
            form.StartPosition = FormStartPosition.CenterParent
            form.IconOptions.ShowIcon = False
            form.Controls.Add(layoutControl)
            form.ShowDialog()
        End Using
End Sub

Private Sub DescriptionBarItem_Click(ByVal sender As Object, ByVal e As EventArgs)
    ShowDescriptionForm()
End Sub

Apply the Custom Property’s Value to the Dashboard

Handle the DashboardDesigner.CustomizeDashboardTitle event to create a new toolbar item that is used to show the dashboard’s description. Create the DashboardToolbarItem instance. If a custom property value is specified, add the created toolbar item to the CustomizeDashboardCaptionBaseEventArgs.Items collection.

Add an action that displays the description after you click it for the toolbar item. When you click the button, it invokes a window with the description text.

csharp
void Designer_CustomizeDashboardTitle(object sender, CustomizeDashboardTitleEventArgs e) {
    string text = designer.Dashboard.CustomProperties.GetValue(PropertyName);
    if(!string.IsNullOrEmpty(text)) {
        DashboardToolbarItem showDataItem = new DashboardToolbarItem("Description",
            new Action<DashboardToolbarItemClickEventArgs>((args) => {
                MessageBox.Show(text, "Description");
            }));
        showDataItem.SvgImage = titleDescriptionImage;
        e.Items.Insert(0, showDataItem);
    }
}
vb
Private Sub Designer_CustomizeDashboardTitle(ByVal sender As Object, ByVal e As CustomizeDashboardTitleEventArgs)
    Dim text As String = designer.Dashboard.CustomProperties.GetValue(PropertyName)
    If Not String.IsNullOrEmpty(text) Then
        Dim showDataItem As New DashboardToolbarItem("Description", New Action(Of DashboardToolbarItemClickEventArgs)(Sub(args)
            MessageBox.Show(text, "Description")
        End Sub))
        showDataItem.SvgImage = titleDescriptionImage
        e.Items.Insert(0, showDataItem)
    End If
End Sub

Update the Dashboard Description when the Value is Changed

Handle the DashboardDesigner.DashboardCustomPropertyChanged to update the custom property’s value when it is changed (for example, when you undo/redo actions).

Call the UpdateDashboardTitle method to raise the DashboardDesigner.CustomizeDashboardTitle event and hide/display the toolbar item according to the custom property’s value. The toolbar item should be displayed if the custom property’s value is not empty.

csharp
private void Designer_DashboardCustomPropertyChanged(object sender, DevExpress.DashboardCommon.CustomPropertyChangedEventArgs e) {
    if(e.Name == PropertyName) {
        designer.UpdateDashboardTitle();
    }
}
vb
Private Sub Designer_DashboardCustomPropertyChanged(ByVal sender As Object, ByVal e As DevExpress.DashboardCommon.CustomPropertyChangedEventArgs)
    If e.Name = PropertyName Then
        designer.UpdateDashboardTitle()
    End If
End Sub

Register the Custom Functionality Module

The code below is a complete module you need to add the Dashboard’s Dashboard Description option:

csharp
using System;
using System.Windows.Forms;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
using DevExpress.Utils;
using DevExpress.Utils.Svg;
using DevExpress.XtraBars;
using DevExpress.XtraBars.Ribbon;
using DevExpress.XtraEditors;
using DevExpress.XtraLayout;
using DevExpress.XtraLayout.Utils;
using DevExpress.DashboardWin.Localization;

namespace WindowsFormsAppCustomProperties {
    public class DashboardDescriptionModule {
        public static readonly string PropertyName = "DashboardDescription";
        readonly DashboardDesigner designer;
        readonly SvgImage titleDecriptionImage;
        public DashboardDescriptionModule(DashboardDesigner designer, SvgImage barImage = null, SvgImage titleDecriptionImage = null) {
            this.designer = designer;
            this.titleDecriptionImage = titleDecriptionImage;
            RibbonControl ribbon = (RibbonControl)designer.MenuManager;
            RibbonPage page = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.None, DashboardRibbonPage.Home);
            RibbonPageGroup group = page.Groups.GetGroupByText(DashboardWinLocalizer.GetString(DashboardWinStringId.RibbonPageDashboardCaption));
            BarButtonItem barItem = CreateBarItem("Dashboard Description", barImage);
            group.ItemLinks.Add(barItem);
            barItem.ItemClick += DescriptionBarItem_Click;
            designer.CustomizeDashboardTitle += Designer_CustomizeDashboardTitle;
            designer.DashboardCustomPropertyChanged += Designer_DashboardCustomPropertyChanged;
        }
        BarButtonItem CreateBarItem(string caption, SvgImage barImage) {
            BarButtonItem barItem = new BarButtonItem();
            barItem.Caption = caption;
            barItem.ImageOptions.SvgImage = barImage;
            return barItem;
        }
        void DescriptionBarItem_Click(object sender, EventArgs e) {
            ShowDescriptionForm();
        }
        void ShowDescriptionForm() {
            string currentCaption = designer.Dashboard.CustomProperties.GetValue(PropertyName);
            LayoutControl layoutControl = new LayoutControl();
            layoutControl.Dock = DockStyle.Fill;
            layoutControl.Name = "layoutControl1";

            LayoutControlItem memoEditLayoutItem = layoutControl.Root.AddItem();
            memoEditLayoutItem.TextLocation = Locations.Top;
            memoEditLayoutItem.Text = "Text:";
            MemoEdit memoEdit = new MemoEdit();
            memoEdit.Text = currentCaption;
            memoEditLayoutItem.Control = memoEdit;

            LayoutControlItem buttonLayoutItem = layoutControl.Root.AddItem();
            buttonLayoutItem.SizeConstraintsType = SizeConstraintsType.Custom;
            buttonLayoutItem.TextVisible = false;
            SimpleButton buttonOk = new SimpleButton();
            buttonOk.Text = "OK";
            buttonOk.DialogResult = DialogResult.OK;
            buttonOk.Click += (sender1, e1) => {
                string modifiedCaption = memoEdit.Text;
                if(currentCaption != modifiedCaption) {
                    string status = !string.IsNullOrEmpty(modifiedCaption) ? "Remove" : "Add";
                    CustomPropertyHistoryItem historyItem = new CustomPropertyHistoryItem(designer.Dashboard, PropertyName, modifiedCaption, status + " the dashboard caption");
                    designer.AddToHistory(historyItem);
                }
            };
            buttonLayoutItem.Control = buttonOk;
            layoutControl.Root.AddItem(new EmptySpaceItem(), buttonLayoutItem, InsertType.Left);

            using(XtraForm form = new XtraForm()) { 
                form.Text = "Description";  
                form.Size = new System.Drawing.Size(250, 250);  
                form.StartPosition = FormStartPosition.CenterParent;    
                form.IconOptions.ShowIcon = false;  
                form.Controls.Add(layoutControl);   
                form.ShowDialog();  
            }   
        }
        void Designer_CustomizeDashboardTitle(object sender, CustomizeDashboardTitleEventArgs e) {
            string text = designer.Dashboard.CustomProperties.GetValue(PropertyName);
            if(!string.IsNullOrEmpty(text)) {
                DashboardToolbarItem showDataItem = new DashboardToolbarItem("Description",
                    new Action<DashboardToolbarItemClickEventArgs>((args) => {
                        MessageBox.Show(text, "Description");
                    }));
                showDataItem.SvgImage = titleDecriptionImage;
                e.Items.Insert(0, showDataItem);
            }
        }
        void Designer_DashboardCustomPropertyChanged(object sender, CustomPropertyChangedEventArgs e) {
            if(e.Name == PropertyName)
                designer.UpdateDashboardTitle();
        }
    }
}
vb
Imports System
Imports System.Windows.Forms
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Imports DevExpress.Utils
Imports DevExpress.Utils.Svg
Imports DevExpress.XtraBars
Imports DevExpress.XtraBars.Ribbon
Imports DevExpress.XtraEditors
Imports DevExpress.XtraLayout
Imports DevExpress.XtraLayout.Utils
Imports DevExpress.DashboardWin.Localization

Namespace WindowsFormsAppCustomProperties
Public Class DashboardDescriptionModule
        Public Shared ReadOnly PropertyName As String = "DashboardDescription"
        Private ReadOnly designer As DashboardDesigner
        Private ReadOnly titleDescriptionImage As SvgImage

        Public Sub New(ByVal designer As DashboardDesigner, Optional ByVal barImage As SvgImage = Nothing, Optional ByVal titleDescriptionImage As SvgImage = Nothing)
            Me.designer = designer
            Me.titleDescriptionImage = titleDescriptionImage
            Dim ribbon As RibbonControl = CType(designer.MenuManager, RibbonControl)
            Dim page As RibbonPage = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.None, DashboardRibbonPage.Home)
            Dim group As RibbonPageGroup = page.Groups.GetGroupByText(DashboardWinLocalizer.GetString(DashboardWinStringId.RibbonPageDashboardCaption))
            Dim barItem As BarButtonItem = CreateBarItem("Dashboard Description", barImage)
            group.ItemLinks.Add(barItem)
            AddHandler barItem.ItemClick, AddressOf DescriptionBarItem_Click
            AddHandler designer.CustomizeDashboardTitle, AddressOf Designer_CustomizeDashboardTitle
            AddHandler designer.DashboardCustomPropertyChanged, AddressOf Designer_DashboardCustomPropertyChanged
        End Sub
        Private Function CreateBarItem(ByVal caption As String, ByVal barImage As SvgImage) As BarButtonItem
            Dim barItem As New BarButtonItem()
            barItem.Caption = caption
            barItem.ImageOptions.SvgImage = barImage
            Return barItem
        End Function
        Private Sub DescriptionBarItem_Click(ByVal sender As Object, ByVal e As EventArgs)
            ShowDescriptionForm()
        End Sub
        Private Sub ShowDescriptionForm()
            Dim currentCaption As String = designer.Dashboard.CustomProperties.GetValue(PropertyName)
            Dim layoutControl As New LayoutControl()
            layoutControl.Dock = DockStyle.Fill
            layoutControl.Name = "layoutControl1"
            Dim memoEditLayoutItem As LayoutControlItem = layoutControl.Root.AddItem()
            memoEditLayoutItem.TextLocation = Locations.Top
            memoEditLayoutItem.Text = "Text:"
            Dim memoEdit As New MemoEdit()
            memoEdit.Text = currentCaption
            memoEditLayoutItem.Control = memoEdit
            Dim buttonLayoutItem As LayoutControlItem = layoutControl.Root.AddItem()
            buttonLayoutItem.SizeConstraintsType = SizeConstraintsType.Custom
            buttonLayoutItem.TextVisible = False
            Dim buttonOk As New SimpleButton()
            buttonOk.Text = "OK"
            buttonOk.DialogResult = DialogResult.OK
            AddHandler buttonOk.Click, Sub(sender1, e1)
                Dim modifiedCaption As String = memoEdit.Text
                If currentCaption <> modifiedCaption Then
                    Dim status As String = If(Not String.IsNullOrEmpty(modifiedCaption), "Remove", "Add")
                    Dim historyItem As New CustomPropertyHistoryItem(designer.Dashboard, PropertyName, modifiedCaption, status & " the dashboard caption")
                    designer.AddToHistory(historyItem)
                End If
            End Sub
            buttonLayoutItem.Control = buttonOk
            layoutControl.Root.AddItem(New EmptySpaceItem(), buttonLayoutItem, InsertType.Left)
            Using form As New XtraForm()
                form.Text = "Description"
                form.Size = New System.Drawing.Size(250, 250)
                form.StartPosition = FormStartPosition.CenterParent
                form.IconOptions.ShowIcon = False
                form.Controls.Add(layoutControl)
                form.ShowDialog()
            End Using
        End Sub
        Private Sub Designer_CustomizeDashboardTitle(ByVal sender As Object, ByVal e As CustomizeDashboardTitleEventArgs)
            Dim text As String = designer.Dashboard.CustomProperties.GetValue(PropertyName)
            If Not String.IsNullOrEmpty(text) Then
                Dim showDataItem As New DashboardToolbarItem("Description", New Action(Of DashboardToolbarItemClickEventArgs)(Sub(args)
                    MessageBox.Show(text, "Description")
                End Sub))
                showDataItem.SvgImage = titleDescriptionImage
                e.Items.Insert(0, showDataItem)
            End If
        End Sub
        Private Sub Designer_DashboardCustomPropertyChanged(ByVal sender As Object, ByVal e As CustomPropertyChangedEventArgs)
            If e.Name = PropertyName Then
                designer.UpdateDashboardTitle()
            End If
        End Sub
    End Class
End Namespace

Register the created module before you load a dashboard to apply settings. For this, create a new DashboardDescriptionModule instance and pass the Dashboard Designer for which you register a property. You can create the SvgImageCollection instance to store vector images and use one of them as the bar item’s icon.

csharp
using WindowsFormsAppCustomProperties;
//...
public Form1() {
    InitializeComponent();
    new DashboardDescriptionModule(dashboardDesigner1, svgImageCollection1["about"], svgImageCollection1["Description"]);
    dashboardDesigner1.LoadDashboard("../../Dashboard/newDashboard.xml");
//...
}
vb
Imports WindowsFormsAppCustomProperties
'...
Public Sub New()
    InitializeComponent()
    Dim TempDashboardDescriptionModule As DashboardDescriptionModule = New DashboardDescriptionModule(dashboardDesigner1, svgImageCollection1("about"), svgImageCollection1["Description"]);
    dashboardDesigner1.LoadDashboard("../../Dashboard/newDashboard.xml")
'...
End Sub

Result

After you registered the DashboardDescriptionModule module, it adds the Dashboard Description button that invokes the editor where you can edit the dashboard’s description.

When you specify the description and click OK , the “Description” button is added to the dashboard title. Click the button to display the description.

The information about the DashboardDescription property’s state is saved in history, so you can undo/redo the current action.

See Also

Create Custom Properties