Dashboard for WinForms - Custom Item Extensions

This example contains the source code of the most requested custom items. Custom items allow you to embed any WinForms control into a Dashboard. You can use the complete custom items from this example as they are, or modify them according to your needs. In a test dashboard of this example, you can add custom items from the Ribbon and switch between tabs in the ribbon UI main menu at the left edge to display each custom item on the dashboard surface.

Prerequisites

A custom Web Page item requires WebView2 Runtime to be installed on your machine.

Example Overview

The example consists of two projects:

• CustomItemExtension (VB: CustomItemExtension)

  Contains the source code of custom items and can be used in customer solutions.

• CustomItemTest (VB: CustomItemTest)

  Contains a dashboard with custom items and can be used as a test project.

Refer to the following list for detailed item descriptions:

• Custom Sankey item

• Custom Sunburst item

• Custom Tree List item

• Custom Waypoint Map item

• Custom Funnel item

• Custom Gantt item

• Custom Web Page Item

• Custom Heatmap Item

Custom Sankey Item

View file: (C#/VB)

The Sankey diagram visualizes data as weighted flows or relationships between nodes.

This custom item implements the following functionality:

• Master-Filter
• Coloring
• Export

Custom Sunburst Item

View file: (C#/VB)

The Sunburst chart combines a Treemap and Pie chart to visualize hierarchical data in a circular layout.

This custom item implements the following functionality:

• Master-Filter
• Coloring
• Export

Custom Tree List Item

View file: (C#/VB)

The hybrid item combines a Tree List and Grid. The Tree List uses the parent-child relationships to generate the hierarchical data structure.

This custom item implements the following functionality:

• Master-Filter
• Export

Custom Waypoint Map Item

View file: (C#/VB)

The Waypoint map visualizes data as linked points.

This custom item implements the following functionality:

• Master-Filter
• Export

Custom Funnel Item

View file: (C#/VB)

The Funnel chart visualizes the progressive reduction of data as it passes from one stage to another in a process or procedure.

This custom item implements the following functionality:

• Master-Filter
• Drill-Down
• Coloring
• Export

Custom Gantt Item

View file: (C#/VB)

The Gantt chart visualizes project schedule data as bars.

This custom item implements the following functionality:

• Master-Filter
• Export

Custom Web Page Item

View file: (C#/VB)

The Web Page displays the web content. You can specify the URI pattern to create the page address from a data column at run-time.

This custom item implements the following functionality:

• Master-Filter
• Export

Custom Heatmap Item

View file: (C#/VB)

The Heatmap item uses color variation to show the relationship between two dimensions.

This custom item implements the following functionality:

• Export
• Coloring

Example Structure

Custom item files are stored in the CustomItems folder. Each custom item has the following classes:

CustomItemExtensionModule

Implements the IExtensionModule interface with the following methods:

• AttachViewer / AttachDesigner

  Execute the binding code. Subscribe the CustomDashboardItemControlCreating event, create custom item bars, and remove buttons from the Ribbon if necessary. For example, the custom Sunburst item does not support Drill-Down. The RemoveDrillDownBarItem method removes this option from the Ribbon.

• DetachViewer / DetachDesigner

  Execute the unbinding code. Unsubscribe from the CustomDashboardItemControlCreating event.

CustomItemMetaData

Contains metadata for a custom item that describes options and settings available to a user in the UI.

CustomItemControlProvider

Contains configuration settings for a custom control. A custom control displays a custom item in a dashboard.

This class contains the following methods:

• CustomItemControlProvider () - provider constructor. This is where the default control settings and event subscriptions are performed.

• UpdateControl

  • Creates and updates a custom control.

  • Creates a custom item data source.

  • Validates data members in metadata.

  • Binds custom item to data.

  • Sets Master Filter mode and Drill-Down.

• GetPrintableControl

  Obtains the printable control to export a custom item. You need to create a PrintableComponentContainer from the current custom control.

• SetSelection

  Updates a custom control according to the current master filter selection.

The Images folder contains icons for custom items and their options.

The file that is used for an icon must be embedded in the file assembly. The file’s BuildAction property is set to Embedded Resource.

Integrate a Custom Item to Your Project

Add Custom Items

You can add custom items to your project one of the following ways:

• Add the CustomItemExtension (VB: CustomItemExtension) project to your solution. Add a reference to this project to "References" in your project with a dashboard control.

• Install the NuGet package.

Register Custom Items

1. Register the CustomItemMetadata type for a custom item and attach its module in your application:

For example, call the following code to register the SankeyItemMetadata type in your application:

C# code:

using DevExpress.DashboardWin.CustomItemExtension;
using DevExpress.DashboardCommon;

namespace CustomItemsSample {
    static class Program {
        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        [STAThread]
        static void Main() {
            //...
            Dashboard.CustomItemMetadataTypes.Register<SankeyItemMetadata>();
            Application.Run(new Form1());
        }
    }
}

VB code:

Imports DevExpress.DashboardWin.CustomItemExtension
Imports DevExpress.DashboardCommon

Namespace CustomItemsSample
    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 SankeyItemMetadata)()
          Application.Run(New Form1())
        End Sub
    End Class
End Namespace

2. Call the following code to attach the extension to the DashboardDesigner control:

C# code:

using DevExpress.XtraBars.Ribbon;
using DevExpress.DashboardWin.CustomItemExtension; 

public Form1() {
        InitializeComponent();
	var sankeyItemModule = new SankeyItemExtensionModule();
	dashboardDesigner1.CreateRibbon();
        sankeyItemModule.AttachDesigner(dashboardDesigner1);
}

VB code:

Imports DevExpress.XtraBars.Ribbon
Imports DevExpress.DashboardWin.CustomItemExtension

Public Sub New()
	InitializeComponent()
	Dim sankeyItemModule = New SankeyItemExtensionModule()
	dashboardDesigner1.CreateRibbon()
	sankeyItemModule.AttachDesigner(dashboardDesigner1)
End Sub 

Documentation

• Custom Item Tutorials
• Custom Item Troubleshooting

More Examples

Custom Items - Tutorial