Back to Devexpress

Display Custom Properties

dashboard-401684-winforms-dashboard-winforms-viewer-display-custom-properties.md

latest16.4 KB
Original Source

Display Custom Properties

  • May 13, 2021
  • 6 minutes to read

Custom properties allow you to store custom settings in dashboard definition. You can read these settings and use these values to natively implement and embed your own functionality into the Dashboard Viewer.

If a custom property is stored in your dashboard definition, you can display its value in the WinForms Dashboard Viewer.

Read a Custom Property’s Value

You can read custom properties’ data that is stored on the following levels:

LevelDescriptionProperty
DashboardCustom data related to the dashboard.Dashboard.CustomProperties
Dashboard itemCustom data related to a particular dashboard item.DashboardItem.CustomProperties
Data item containerCustom data related to the Grid’s columns, the Chart’s series and other elements of a dashboard item.DataItemContainer.CustomProperties

Use the CustomProperties.GetValue method to read a value of the specified custom property.

For example, the DashboardDescription custom property is stored in a dashboard XML file at the dashboard’s level. The custom property’s value is stored as a string.

xml
<Dashboard>
...
    <CustomProperties>
        <DashboardDescription>This dashboard shows statistics on sales of bicycles, related equipment and accessories. ...</DashboardDescription>
    </CustomProperties>
</Dashboard>

The following code snippet illustrates how to read the property’s value:

csharp
var currentDescription = viewer.Dashboard.CustomProperties.GetValue("DashboardDescription");
vb
Dim currentDescription = viewer.Dashboard.CustomProperties.GetValue("DashboardDescription")

All property values are stored in string format. You can use system methods like Convert.ToBoolean or Convert.ToInt32 to convert the custom property’s value to a base data type.

For complex conversions, use the class below:

csharp
using DevExpress.DashboardCommon;
using System;
using System.Collections.Generic;
using System.Linq;

namespace WindowsFormsAppCustomProperties {
    public static class CustomPropertyExtensions {

        public static T GetValue<T>(this CustomProperties property, string name) where T : struct {
            var value = property.GetValue(name);
            if(value == null) return default(T);
            return (T)Convert.ChangeType(value, typeof(T));
        }

        public static EnumType ConvertToEnum<EnumType>(this String enumValue) {
            return (EnumType)Enum.Parse(typeof(EnumType), enumValue);
        }
        public static string ConvertToString(this Enum enumValue) {
            return Enum.GetName(enumValue.GetType(), enumValue);
        }
    }
}
vb
Imports DevExpress.DashboardCommon
Imports System
Imports System.Collections.Generic
Imports System.Linq

Namespace WindowsFormsAppCustomProperties
    Public NotInheritable Class CustomPropertyExtensions

        Private Sub New()
        End Sub
         _
        Public Shared Function GetValue(Of T As Structure)(ByVal [property] As CustomProperties, ByVal name As String) As T
            Dim value = [property].GetValue(name)
            If value Is Nothing Then
                Return Nothing
            End If
            Return CType(Convert.ChangeType(value, GetType(T)), T)
        End Function

         _
        Public Shared Function ConvertToEnum(Of EnumType)(ByVal enumValue As String) As EnumType
            Return CType(System.Enum.Parse(GetType(EnumType), enumValue), EnumType)
        End Function
         _
        Public Shared Function ConvertToString(ByVal enumValue As System.Enum) As String
            Return System.Enum.GetName(enumValue.GetType(), enumValue)
        End Function
    End Class
End Namespace

The code line below converts a string to a CheckMode enumeration value:

csharp
var newValue = designer.Dashboard.Items[itemName].CustomProperties.GetValue<CheckMode>(PropertyName);
vb
Dim newValue = designer.Dashboard.Items(itemName).CustomProperties.GetValue(Of CheckMode)(PropertyName)

Update the Behavior Based on the Custom Property’s Value

To update a dashboard and underlying controls according to the custom property’s value, use a set of API listed below:

EventDescription
DashboardViewer.DashboardItemControlUpdatedAllows you to access underlying WinForms controls.
DashboardViewer.DashboardItemControlCreatedAllows you to access underlying WinForms controls.
DashboardViewer.DashboardCustomPropertyChangedOccurs when the custom property’s value in the Dashboard Viewer is changed.
DashboardViewer.CustomizeDashboardTitleAllows you to customize the dashboard title at runtime.
Dashboard.OptionsChangedOccurs after any option in the current Dashboard is changed.
DashboardViewer.CustomizeDashboardItemCaptionAllows you to customize the dashboard item caption at runtime.
DashboardViewer.PopupMenuShowingAllows you to customize a popup menu invoked by end-users in the DashboardViewer.

Use context to provide a connection between data item containers and an underlying control’s elements when you apply a custom property for a data item container:

APIDescription
ChartContext.GetDashboardItemSeries
ChartContext.GetControlSeriesProvides a connection between the ChartSeries object and corresponding Series.
GaugeContext.GetDashboardGauge
GaugeContext.GetControlGaugesProvides a connection between the Gauge object and corresponding control’s gauge element.
GridContext.GetDashboardItemColumn
GridContext.GetControlColumnProvides a connection between the GridColumnBase descendant and corresponding control’s column.

You can handle the DashboardViewer.CustomExport event to customize the exported document and display the same modifications the custom property provides.

Create a Custom Functionality Module

You can organize the code related to a custom functionality into a separate module you can integrate in any dashboard application.

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

  • a dashboard control that you pass as a parameter when you register the module (you can also use the IDashboardControl interface to provide common API for WinForms Designer and Viewer),
  • a custom property’s unique name,
  • event subscriptions that used to provide custom functionality.

To integrate the created functionality in your dashboard application, call the created module’s constructor, and pass the dashboard control’s instance in it.

You should register the created module before you load a dashboard to apply settings to this dashboard:

csharp
public Form1() {
    InitializeComponent();
    new WinDashboardDescriptionViewer(dashboardViewer1);
    dashboardViewer1.LoadDashboard("../../Dashboard/newDashboard.xml");
}
vb
Public Sub New()
    InitializeComponent()
    Dim TempWinDashboardDescriptionViewer As WinDashboardDescriptionViewer = New WinDashboardDescriptionViewer(dashboardViewer1)
    dashboardViewer1.LoadDashboard("../../Dashboard/newDashboard.xml")
End Sub

Examples

The code below display Chart’s scale breaks. The information about scale breaks visibility is saved as a custom property:

csharp
using DevExpress.DashboardWin;
using DevExpress.Utils.Svg;
using DevExpress.XtraCharts;
using System;

namespace WindowsFormsAppCustomProperties {
    public class ViewerScaleBreak {
        public static readonly string PropertyName = "ScaleBreak";
        readonly IDashboardControl dashboardControl;
        readonly SvgImage titleDescriptionImage;
        public ViewerScaleBreak(DashboardViewer dashboardControl, SvgImage barImage = null) {
            this.dashboardControl = dashboardControl;
            dashboardControl.DashboardItemControlUpdated += DashboardControl_DashboardItemControlUpdated;
        }
        void DashboardControl_DashboardItemControlUpdated(object sender, DashboardItemControlEventArgs e) {
            if(e.ChartControl != null) {
                bool value = Convert.ToBoolean(dashboardControl.Dashboard.Items[e.DashboardItemName].CustomProperties.GetValue(PropertyName));
                UpdateChart(e.ChartControl, value);
            }
        }
        void UpdateChart(ChartControl chart, bool scaleBreakEnabled) {
            if(chart.Diagram != null)
                ((XYDiagram)chart.Diagram).SecondaryAxesY[0].AutoScaleBreaks.Enabled = scaleBreakEnabled;
        }
    }
}
vb
Imports DevExpress.DashboardWin
Imports DevExpress.Utils.Svg
Imports DevExpress.XtraCharts
Imports System

Namespace WindowsFormsAppCustomProperties
    Public Class ViewerScaleBreak
        Public Shared ReadOnly PropertyName As String = "ScaleBreak"
        Private ReadOnly dashboardControl As IDashboardControl
        Private ReadOnly titleDescriptionImage As SvgImage
        Public Sub New(ByVal dashboardControl As DashboardViewer, Optional ByVal barImage As SvgImage = Nothing)
            Me.dashboardControl = dashboardControl
            AddHandler dashboardControl.DashboardItemControlUpdated, AddressOf DashboardControl_DashboardItemControlUpdated
        End Sub
        Private Sub DashboardControl_DashboardItemControlUpdated(ByVal sender As Object, ByVal e As DashboardItemControlEventArgs)
            If e.ChartControl IsNot Nothing Then
                Dim value As Boolean = Convert.ToBoolean(dashboardControl.Dashboard.Items(e.DashboardItemName).CustomProperties.GetValue(PropertyName))
                UpdateChart(e.ChartControl, value)
            End If
        End Sub
        Private Sub UpdateChart(ByVal chart As ChartControl, ByVal scaleBreakEnabled As Boolean)
            If chart.Diagram IsNot Nothing Then
                CType(chart.Diagram, XYDiagram).SecondaryAxesY(0).AutoScaleBreaks.Enabled = scaleBreakEnabled
            End If
        End Sub
    End Class
End Namespace

The code below displays a dashboard description. Text for the description is saved as a custom property value:

csharp
using DevExpress.DashboardWin;
using DevExpress.Utils.Svg;
using System;
using System.Windows.Forms;

namespace WindowsFormsAppCustomProperties {
    public class DescriptionViewer {
        public static readonly string PropertyName = "DashboardDescription";
        readonly IDashboardControl dashboardControl;
        readonly SvgImage titleDescriptionImage;

        public DescriptionViewer(IDashboardControl dashboardControl, SvgImage titleDescriptionImage = null) {
            this.dashboardControl = dashboardControl;
            this.titleDescriptionImage = titleDescriptionImage;
            dashboardControl.CustomizeDashboardTitle += DashboardControl_CustomizeDashboardTitle;
        }
        void DashboardControl_CustomizeDashboardTitle(object sender, CustomizeDashboardTitleEventArgs e) {
            string text = dashboardControl.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
Imports DevExpress.DashboardWin
Imports DevExpress.Utils.Svg
Imports System
Imports System.Windows.Forms

Namespace WindowsFormsAppCustomProperties
    Public Class DescriptionViewer
        Public Shared ReadOnly PropertyName As String = "DashboardDescription"
        Private ReadOnly dashboardControl As IDashboardControl
        Private ReadOnly titleDescriptionImage As SvgImage

        Public Sub New(ByVal dashboardControl As IDashboardControl, Optional ByVal titleDescriptionImage As SvgImage = Nothing)
            Me.dashboardControl = dashboardControl
            Me.titleDescriptionImage = titleDescriptionImage
            AddHandler dashboardControl.CustomizeDashboardTitle, AddressOf DashboardControl_CustomizeDashboardTitle
        End Sub
        Private Sub DashboardControl_CustomizeDashboardTitle(ByVal sender As Object, ByVal e As CustomizeDashboardTitleEventArgs)
            Dim text As String = dashboardControl.Dashboard.CustomProperties.GetValue(PropertyName)
            If (Not String.IsNullOrEmpty(text)) Then
                Dim showDataItem As New DashboardToolbarItem("Description", New Action(Of DashboardToolbarItemClickEventArgs)(Function(args) AnonymousMethod1(args, text)))
                showDataItem.SvgImage = titleDescriptionImage
                e.Items.Insert(0, showDataItem)
            End If
        End Sub

        Private Function AnonymousMethod1(ByVal args As Object, ByVal text As String) As Boolean
            MessageBox.Show(text, "Description")
            Return True
        End Function
    End Class
End Namespace