All docs
V20.1
20.1
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

Display Custom Properties

  • 5 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:

Level Description Property
Dashboard Custom data related to the dashboard. Dashboard.CustomProperties
Dashboard item Custom data related to a particular dashboard item. DashboardItem.CustomProperties
Data item container Custom 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.

<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:

var 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:

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);
        }
    }
}

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

var newValue = designer.Dashboard.Items[itemName].CustomProperties.GetValue<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:

Event Description
DashboardViewer.DashboardItemControlUpdated Allows you to access underlying WinForms controls.
DashboardViewer.DashboardItemControlCreated Allows you to access underlying WinForms controls.
DashboardViewer.DashboardCustomPropertyChanged Occurs when the custom property's value in the Dashboard Viewer is changed.
DashboardViewer.CustomizeDashboardTitle Allows you to customize the dashboard title at runtime.
Dashboard.OptionsChanged Occurs after any option in the current Dashboard is changed.
DashboardViewer.CustomizeDashboardItemCaption Allows you to customize the dashboard item caption at runtime.
DashboardViewer.PopupMenuShowing Allows 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:

API Description
ChartContext.GetDashboardItemSeries
ChartContext.GetControlSeries
Provides a connection between the ChartSeries object and corresponding Series.
GaugeContext.GetDashboardGauge
GaugeContext.GetControlGauges
Provides a connection between the Gauge object and corresponding control's gauge element.
GridContext.GetDashboardItemColumn
GridContext.GetControlColumn
Provides 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:

public Form1() {
    InitializeComponent();
    new WinDashboardDescriptionViewer(dashboardViewer1);
    dashboardViewer1.LoadDashboard("../../Dashboard/newDashboard.xml");
}

Examples

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

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;
        }
    }
}

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

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);
            }
        }
    }
}