Create a Static Custom Item for the WinForms Dashboard

Aug 31, 2023
5 minutes to read

This tutorial shows how to create a custom item that displays the ‘Hello World!’ text. In this tutorial you will create and register a custom item’s metadata, create a custom control that displays the custom item, and add a button to the Ribbon. Refer to the next tutorial for more information on how to bind a custom item to data and create a binding panel: Create a Data-Aware Item.

First, create a WinForms Dashboard project and create the CustomItems folder in it to store custom item data. Then, follow the instructions below:

Create Metadata

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 HelloWorldItem.cs file to the CustomItems folder in your project. In the file, derive a class from CustomItemMetadata:

HelloWorldItem.cs
HelloWorldItem.vb

csharp

using DevExpress.DashboardCommon;

namespace TutorialsCustomItems.CustomItems{
    class HelloWorldItemMetadata : CustomItemMetadata{
    }
}

Imports DevExpress.DashboardCommon

Namespace TutorialsCustomItems.CustomItems
    Friend Class HelloWorldItemMetadata
    Inherits CustomItemMetadata
    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 attributes to HelloWorldItemMetadata:

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.

HelloWorldItem.cs
HelloWorldItem.vb

csharp

using DevExpress.DashboardCommon;
using System.ComponentModel;

namespace TutorialsCustomItems.CustomItems{
    [DisplayName("Hello World Item"),
    CustomItemDescription("Hello World Description"),
    CustomItemImage("TutorialsCustomItems.Images.HelloWorldIcon.svg")]
    class HelloWorldItemMetadata : CustomItemMetadata{
    }
}

Imports DevExpress.DashboardCommon
Imports System.ComponentModel

Namespace TutorialsCustomItems.CustomItems
    <DisplayName("Hello World Item"), CustomItemDescription("Hello World Description"), CustomItemImage("HelloWorldIcon.svg")> _
    Friend Class HelloWorldItemMetadata
        Inherits CustomItemMetadata
    End Class
End Namespace

Register a New Metadata Type

Call the CustomItemMetadataTypes.Register<T>() method before the main application form is created to allow the Dashboard Designer to read custom item data from a dashboard. Pass a new metadata type as a parameter. The metadata type is stored in the CustomItemMetadataTypes collection and corresponds to the HelloWorldItemMetadata class.

Program.cs
Program.vb

csharp

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

Add a Button to the Ribbon

Call the DashboardDesigner.CreateCustomItemBars(Type[]) method, which inserts a custom item’s bar in the Ribbon. A user can click this button to add a new custom item to a dashboard at runtime.

Form1.cs
Form1.vb

csharp

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

Create a Custom Control

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

The CustomControlProviderBase.Control property gets the control that displays the custom item.

HelloWorldItem.cs
HelloWorldItem.vb

csharp

using System.Windows.Forms;
using DevExpress.DashboardWin;
using DevExpress.XtraEditors;

namespace TutorialsCustomItems.CustomItems{
// ...
    public class HelloWorldItemProvider : CustomControlProviderBase{
        MemoEdit textbox;
        protected override Control Control { get { return textbox; } }
        public HelloWorldItemProvider(){
            textbox = new MemoEdit();
            textbox.Text = "Hello World!";
            textbox.ReadOnly = true;
            textbox.ContextMenu = new ContextMenu();
        }
    }
}

Imports System.Windows.Forms
Imports DevExpress.DashboardWin
Imports DevExpress.XtraEditors;

Namespace TutorialsCustomItems.CustomItems
'...
    Public Class HelloWorldItemProvider
        Inherits CustomControlProviderBase
        Private textbox As MemoEdit
        Protected Overrides ReadOnly Property Control() As Control
            Get
                Return textbox
            End Get
        End Property
        Public Sub New()
            textbox = New MemoEdit()
            textbox.Text = "Hello World!"
            textbox.ReadOnly = True
            textbox.ContextMenu = New ContextMenu()
        End Sub
    End Class
End Namespace

Visualize a Custom Item in a Dashboard

To visualize the custom control, assign the HelloWorldItemProvider object to the e.CustomControlProvider property in the DashboardDesigner.CustomDashboardItemControlCreating event handler.

Form1.cs
Form1.vb

csharp

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(HelloWorldItemMetadata))
                e.CustomControlProvider = new HelloWorldItemProvider();
        }
    }
}

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(HelloWorldItemMetadata) Then
                e.CustomControlProvider = New HelloWorldItemProvider()
            End If
        End Sub
    End Class
End Namespace

Run the Project to See the Result

Run the project and click the Hello World Item button in the Ribbon to add the custom item to the dashboard:

This action adds the custom item that displays the ‘Hello World!’ text to the dashboard’s layout:

Next Step

Refer to the following tutorials for more information on how to bind a custom item to data and embed additional functionality:

Example

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 Hello World item’s source code in this project.

View Example