CustomControlProviderBase Class

A base class that contains configuration settings for a custom control.

Namespace: DevExpress.DashboardWin

Assembly: DevExpress.Dashboard.v21.2.Win.dll

NuGet Package: DevExpress.Win.Dashboard

Declaration

C#

public abstract class CustomControlProviderBase :
    ICustomControlProvider,
    ICustomExportControlProvider

VB.NET

Public MustInherit Class CustomControlProviderBase
    Implements ICustomControlProvider,
               ICustomExportControlProvider

Related API Members

The following members return CustomControlProviderBase objects:

• CustomDashboardItemControlCreatingEventArgs.CustomControlProvider

Remarks

A custom control displays a custom item in a dashboard. To configure the custom control, derive a class from CustomControlProviderBase. The class creates and updates the control based on data that a dashboard transfers to it.

The sections below illustrate how to implement a custom control:

Create a Custom Control

The CustomControlProviderBase.Control property gets the control displayed in a custom item.

The following code snippet derives a CustomFunnelControlProvider class from CustomControlProviderBase:

C#

using System.Windows.Forms;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
using DevExpress.XtraCharts;
//...
public class CustomFunnelControlProvider : CustomControlProviderBase{
    CustomDashboardItem<CustomFunnelMetadata> dashboardItem;
    ChartControl chart;
    protected override Control Control { get { return chart; } }

    public CustomFunnelControlProvider(CustomDashboardItem<CustomFunnelMetadata> dashboardItem) {
        this.dashboardItem = dashboardItem;
        chart = new ChartControl();
    }
}

VB.NET

Imports System.Windows.Forms
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Imports DevExpress.XtraCharts
'...
Public Class CustomFunnelControlProvider
    Inherits CustomControlProviderBase
    Private dashboardItem As CustomDashboardItem(Of CustomFunnelMetadata)
    Private chart As ChartControl
    Protected Overrides ReadOnly Property Control() As Control
        Get
            Return chart
        End Get
    End Property

    Private Function CustomFunnelControlProvider(ByVal dashboardItem As CustomDashboardItem(Of CustomFunnelMetadata)) As [Public]
        Me.dashboardItem = dashboardItem
        chart = New ChartControl()
    End Function
End Class

Update a Custom Control

The CustomControlProviderBase.UpdateControl(CustomItemData) method is called each time a custom item’s data or settings change. The method supplies data for a custom item based on measures and dimensions that are specified in metadata.

You can use one of the following ways to bind a control to data:

MultiDimensionalData

Use MultiDimensionalData if a custom control does not support data sources that implement IList. You can create a data source based on MultiDimensionalData for the control. Call the CustomItemData.GetMultiDimensionalData() method to get MultiDimensionalData.

DashboardFlatDataSource

Use DashboardFlatDataSource if a custom control supports a data source that implements IList. Call the CustomItemData.GetFlatData(DashboardFlatDataSourceOptions) method to get custom item data and bind it to a control.

The following code snippet binds data to a custom control:

C#

using System.Windows.Forms;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
using DevExpress.XtraCharts;

public class CustomFunnelControlProvider : CustomControlProviderBase {
  CustomDashboardItem<CustomFunnelMetadata> dashboardItem;
  //...
  protected override void UpdateControl(CustomItemData customItemData){
    chart.Series.Clear();
    if(dashboardItem.Metadata.Value != null && dashboardItem.Metadata.Arguments.Count > 0) {
      Series series = new Series("A Funnel Series", ViewType.Funnel);
      flatData = customItemData.GetFlatData(new DashboardFlatDataSourceOptions() {
          AddColoringColumns = true });
      series.DataSource = flatData;
      series.ValueDataMembers.AddRange(dashboardItem.Metadata.Value.UniqueId);
      series.ArgumentDataMember = dashboardItem.Metadata.Arguments.Last().UniqueId;
      series.ColorDataMember = flatData.GetColoringColumn(dashboardItem.Metadata.Value.UniqueId).Name;
      chart.Series.Add(series);
    }
  }
}

VB.NET

Imports System.Windows.Forms
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Imports DevExpress.XtraCharts

Public Class CustomFunnelControlProvider
    Inherits CustomControlProviderBase
  Private dashboardItem As CustomDashboardItem(Of CustomFunnelMetadata)
  '...
  Protected Overrides Sub UpdateControl(ByVal customItemData As CustomItemData)
      chart.Series.Clear()
      If dashboardItem.Metadata.Value IsNot Nothing AndAlso dashboardItem.Metadata.Arguments.Count > 0 Then
          Dim series As New Series("A Funnel Series", ViewType.Funnel)
          flatData = customItemData.GetFlatData(New DashboardFlatDataSourceOptions() With {.AddColoringColumns = True})
          series.DataSource = flatData
          series.ValueDataMembers.AddRange(dashboardItem.Metadata.Value.UniqueId)
          series.ArgumentDataMember = dashboardItem.Metadata.Arguments.Last().UniqueId
          series.ColorDataMember = flatData.GetColoringColumn(dashboardItem.Metadata.Value.UniqueId).Name
          chart.Series.Add(series)
      End If
  End Sub
End Class

Once you have configured a custom control and bound it to data, you need to visualize the control. To accomplish this, assign a CustomControlProviderBase derived class to the CustomDashboardItemControlCreatingEventArgs.CustomControlProvider property.

Implements

ICustomExportControlProvider

Inheritance

Object

CustomControlProviderBase