dashboard-403088-winforms-dashboard-winforms-designer-ui-elements-and-customization-create-a-custom-item-create-a-data-aware-item.md
This tutorial shows how to create a Simple Table custom item based on the Grid control and bind the Simple Table to data. In the previous tutorial, you visualized a custom item in a dashboard. In this tutorial, you will bind a custom item to data and create a binding panel. Refer to the next tutorial for more information on how to add additional functionality to a custom item: Create a Custom Item.
First, create a WinForms Dashboard project and create the CustomItems folder to store custom item data. Then, follow the instructions below:
Metadata is a CustomItemMetadata descendant that describes options and settings available to a user in the UI. Register the metadata object to be able to create custom items of this type. The structure you specified in metadata defines these custom items in a dashboard definition.
Add the SimpleTableItem.cs file to the CustomItems folder in your project. In the file, derive a class from CustomItemMetadata and declare its properties. The properties correspond to data sections in the binding panel. The MeasureColumn property allows you to add an individual data item to the Measure section. The DimensionColumns collection property enables you to add several data items.
using DevExpress.DashboardCommon;
namespace TutorialsCustomItems.CustomItems{
class SimpleTableMetadata : CustomItemMetadata{
public Measure MeasureColumn{
get { return GetPropertyValue<Measure>(); }
set { SetPropertyValue(value); }
}
public DimensionCollection DimensionColumns { get; } = new DimensionCollection();
}
}
Imports DevExpress.DashboardCommon
Namespace TutorialsCustomItems.CustomItems
Friend Class SimpleTableMetadata
Inherits CustomItemMetadata
Public Property MeasureColumn() As Measure
Get
Return GetPropertyValue(Of Measure)()
End Get
Set(ByVal value As Measure)
SetPropertyValue(value)
End Set
End Property
Public ReadOnly Property DimensionColumns() As New DimensionCollection()
End Class
End Namespace
Add the SVG file you want to use as a custom item’s icon to the Images folder in your project. You can use SVG images from the example: WinForms Dashboard - Custom Items. Make sure the SVG file’s Build Action property is set to Embedded Resource.
Apply the following class attributes to SimpleTableMetadata:
| Name | Description |
|---|---|
| DisplayNameAttribute | Specifies a name for a custom item’s icon. |
| CustomItemDescriptionAttribute | Specifies tooltip text that is displayed for a custom item’s bar in the Ribbon. |
| CustomItemImageAttribute | Specifies an icon for a custom item’s bar in the Ribbon. |
Apply the following attributes to SimpleTableMetadata’s properties:
| Name | Description |
|---|---|
| DisplayNameAttribute | Specifies a data section’s name in the Data Items pane. |
| EmptyDataItemPlaceholderAttribute | Specifies placeholder text for a pane where you can place a data item. |
using DevExpress.DashboardCommon;
using System.ComponentModel;
namespace TutorialsCustomItems.CustomItems{
[DisplayName("Simple Table"),
CustomItemDescription("Simple Table description"),
CustomItemImage("TutorialsCustomItems.Images.CustomGrid.svg")]
class SimpleTableMetadata : CustomItemMetadata{
[DisplayName("Measure"),
EmptyDataItemPlaceholder("MeasureColumn"),]
public Measure MeasureColumn{
get { return GetPropertyValue<Measure>(); }
set { SetPropertyValue(value); }
}
[DisplayName("Dimensions"),
EmptyDataItemPlaceholder("DimensionColumn")]
public DimensionCollection DimensionColumns { get; } = new DimensionCollection();
}
}
Imports DevExpress.DashboardCommon
Imports System.ComponentModel
Namespace TutorialsCustomItems.CustomItems
<DisplayName("Simple Table"), CustomItemDescription("Simple Table description"), CustomItemImage("CustomGrid.svg")>
Friend Class SimpleTableMetadata
Inherits CustomItemMetadata
<DisplayName("Measure"), EmptyDataItemPlaceholder("MeasureColumn")>
Public Property MeasureColumn() As Measure
Get
Return GetPropertyValue(Of Measure)()
End Get
Set(ByVal value As Measure)
SetPropertyValue(value)
End Set
End Property
<DisplayName("Dimensions"), EmptyDataItemPlaceholder("DimensionColumn")>
Public ReadOnly Property DimensionColumns() As New DimensionCollection()
End Class
End Namespace
Call the CustomItemMetadataTypes.Register<T>() method before the main application form is created. Pass a new metadata type as a parameter to allow the dashboard control to read custom item data from a dashboard. The registered metadata type is stored in the CustomItemMetadataTypes collection and corresponds to the SimpleTableMetadata class.
using DevExpress.XtraEditors;
using System;
using System.Windows.Forms;
using DevExpress.DashboardCommon;
using TutorialsCustomItems.CustomItems;
namespace TutorialsCustomItems {
static class Program{
/// <summary>
/// The main entry point for the application.
/// </summary>
[STAThread]
static void Main(){
// ...
Dashboard.CustomItemMetadataTypes.Register<SimpleTableMetadata>();
Application.Run(new Form1());
}
}
}
Imports DevExpress.XtraEditors
Imports System
Imports System.Windows.Forms
Imports DevExpress.DashboardCommon
Imports TutorialsCustomItems.CustomItems
Namespace TutorialsCustomItems
Friend NotInheritable Class Program
''' <summary>
''' The main entry point for the application.
''' </summary>
Private Sub New()
End Sub
<STAThread> _
Shared Sub Main()
' ...
Dashboard.CustomItemMetadataTypes.Register(Of SimpleTableMetadata)()
Application.Run(New Form1())
End Sub
End Class
End Namespace
The Dashboard Designer automatically creates a binding panel based on SimpleTableMetadata metadata for the custom item.
Call the DashboardDesigner.CreateCustomItemBars(Type[]) method to insert a custom item’s bar in the Ribbon. Then, click the bar to create a custom item in the Dashboard Designer at runtime.
using System.Windows.Forms;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
namespace TutorialsCustomItems {
public partial class Form1 : Form {
public Form1(){
InitializeComponent();
dashboardDesigner1.CreateRibbon();
dashboardDesigner1.CreateCustomItemBars();
}
}
}
Imports System.Windows.Forms
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Namespace TutorialsCustomItems
Partial Public Class Form1
Inherits Form
Public Sub New()
InitializeComponent()
dashboardDesigner1.CreateRibbon()
dashboardDesigner1.CreateCustomItemBars()
End Sub
End Class
End Namespace
A custom control displays a custom item in a dashboard. To configure the custom control, derive the SimpleTableProvider class from CustomControlProviderBase. SimpleTableProvider creates and updates the control based on data that a dashboard transfers to the object.
The CustomControlProviderBase.Control property gets the control that displays the custom item.
The CustomControlProviderBase.UpdateControl(CustomItemData) method is called each time the custom item’s data or settings change. The method supplies data for the custom item based on measures and dimensions that are specified in metadata. Call the CustomItemData.GetFlatData() method to get custom item data and bind it to the control.
The CustomColumnDisplayText event formats display text in the SimpleTable’s cells.
using System.Windows.Forms;
using DevExpress.DashboardWin;
using DevExpress.XtraGrid;
using DevExpress.XtraGrid.Views.Grid;
using DevExpress.DashboardCommon;
namespace TutorialsCustomItems.CustomItems{
public class SimpleTableProvider : CustomControlProviderBase{
GridView view;
GridControl grid;
protected override Control Control { get { return grid; } }
public SimpleTableProvider(){
grid = new GridControl();
view = new GridView();
view.OptionsView.ShowGroupPanel = false;
view.CustomColumnDisplayText += View_CustomColumnDisplayText;
grid.MainView = view;
}
protected override void UpdateControl(CustomItemData customItemData){
DashboardFlatDataSource flatData = customItemData.GetFlatData();
grid.DataSource = flatData;
view.PopulateColumns();
view.BestFitColumns();
}
void View_CustomColumnDisplayText(object sender, DevExpress.XtraGrid.Views.Base.CustomColumnDisplayTextEventArgs e){
DashboardFlatDataSource data = (DashboardFlatDataSource)grid.DataSource;
e.DisplayText = data.GetDisplayText(e.Column.FieldName, e.ListSourceRowIndex);
}
}
}
Imports System.Windows.Forms
Imports DevExpress.DashboardWin
Imports DevExpress.XtraGrid
Imports DevExpress.XtraGrid.Views.Grid
Imports DevExpress.DashboardCommon
Namespace TutorialsCustomItems.CustomItems
Public Class SimpleTableProvider
Inherits CustomControlProviderBase
Private view As GridView
Private grid As GridControl
Protected Overrides ReadOnly Property Control() As Control
Get
Return grid
End Get
End Property
Public Sub New()
grid = New GridControl()
view = New GridView()
view.OptionsView.ShowGroupPanel = False
view.CustomColumnDisplayText += View_CustomColumnDisplayText
grid.MainView = view
End Sub
Protected Overrides Sub UpdateControl(ByVal customItemData As CustomItemData)
Dim flatData As DashboardFlatDataSource = customItemData.GetFlatData()
grid.DataSource = flatData
view.PopulateColumns()
view.BestFitColumns()
End Sub
Private Sub View_CustomColumnDisplayText(ByVal sender As Object, ByVal e As DevExpress.XtraGrid.Views.Base.CustomColumnDisplayTextEventArgs)
Dim data As DashboardFlatDataSource = CType(grid.DataSource, DashboardFlatDataSource)
e.DisplayText = data.GetDisplayText(e.Column.FieldName, e.ListSourceRowIndex)
End Sub
End Class
End Namespace
To visualize the custom control, assign the SimpleTableProvider object to the e.CustomControlProvider property in the DashboardDesigner.CustomDashboardItemControlCreating event handler.
using System.Windows.Forms;
using TutorialsCustomItems.CustomItems;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
namespace TutorialsCustomItems {
public partial class Form1 : Form {
// ...
private void DashboardDesigner1_CustomDashboardItemControlCreating(object sender,
CustomDashboardItemControlCreatingEventArgs e){
if (e.MetadataType == typeof(SimpleTableMetadata))
e.CustomControlProvider = new SimpleTableProvider();
}
}
}
Imports System.Windows.Forms
Imports TutorialsCustomItems.CustomItems
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Namespace TutorialsCustomItems
Partial Public Class Form1
Inherits Form
' ...
Private Sub DashboardDesigner1_CustomDashboardItemControlCreating(ByVal sender As Object, ByVal e As CustomDashboardItemControlCreatingEventArgs)
If e.MetadataType Is GetType(SimpleTableMetadata) Then
e.CustomControlProvider = New SimpleTableProvider()
End If
End Sub
End Class
End Namespace
Run the project and click the Simple Table Item button in the Ribbon to add the custom item to the dashboard:
This action adds the custom item to the dashboard’s layout:
Drag data fields from the Data Source Browser and drop them onto the appropriate section in the binding panel to supply the custom item with data.
Refer to the following tutorial for more information on how to add additional functionality to the custom item:
The following example shows how to implement a custom dashboard item in a WinForms application. The example contains custom items that you get once the tutorials are completed. You can find the Simple Table item’s source code in this project.