Add a Custom Control to the End-User Report Designer Toolbox

• Aug 18, 2023
• 5 minutes to read

This document describes how to create a WinForms project with a custom control and add the control to the WinForms End-User Report Designer Toolbox.

View Example: Add a Custom Control to the End-User Report Designer Toolbox (WinForms)

Create a Project and Custom Control

1. Create a new WinForms project named WinFormsApp_CustomNumericLabel.
2. Add a new blank report to the project.

3. Implement a custom numeric label:

   NumericLabel.cs

   using DevExpress.Utils.Serializing;
   using DevExpress.XtraReports;
   using DevExpress.XtraReports.UI;
   using System.ComponentModel;
   using DevExpress.XtraReports.Expressions;
   using DevExpress.Utils.Design;
   
   namespace WinFormsApp_CustomNumericLabel {
       [ToolboxItem(true)]
       [DefaultBindableProperty("Number")]
       [ToolboxSvgImage("WinFormsApp_CustomNumericLabel.NumericLabel.svg, WinFormsApp_CustomNumericLabel")]
       public class NumericLabel : XRLabel {
           [DefaultValue(0)]
           [XtraSerializableProperty]
           public int Number { get; set; }
   
           // Set the "Browsable" and "EditorBrowsable" attributes to "false" and "Never"
           // to hide the "Text" property from the "Properties" window and editor (IntelliSense).
           [Browsable(false), EditorBrowsable(EditorBrowsableState.Never)]
           public override string Text {
               get { return Number.ToString(); }
               set {
                   int i;
                   Number = (int.TryParse(value, out i)) ? i : 0;
               }
           }
   
           // Implement a static constructor as shown below to add
           // the "Number" property to the property grid's "Expressions" tab.
           static NumericLabel() {
               // Specify an array of events in which the property should be available.
               string[] eventNames = new string[] { "BeforePrint" };
   
               // Specify the property position in the property grid's "Expressions" tab.
               // 0 - fist, 1000 - last.
               int position = 0;
   
               // Specify an array of the property's inner properties.
               string[] nestedBindableProperties = null;
   
               // Specify the property's category in the property grid's "Expressions" tab.
               // The empty string corresponds the root category.
               string scopeName = "";
   
               // Create and set a description for the "Number" property.
               ExpressionBindingDescription description = new ExpressionBindingDescription(
                   eventNames, position, nestedBindableProperties, scopeName
               );
   
               ExpressionBindingDescriptor.SetPropertyDescription(
                   typeof(NumericLabel), nameof(Number), description
               );
           }
       }
   }
   

   NumericLabel.vb

   Imports DevExpress.Utils.Serializing
   Imports DevExpress.XtraReports
   Imports DevExpress.XtraReports.UI
   Imports System.ComponentModel
   Imports DevExpress.XtraReports.Expressions
   Imports DevExpress.Utils.Design
   
   Namespace WinFormsApp_CustomNumericLabel
       <ToolboxItem(True), DefaultBindableProperty("Number"), ToolboxSvgImage("NumericLabel.svg, WinFormsApp_CustomNumericLabel")>
       Public Class NumericLabel
           Inherits XRLabel
   
           <DefaultValue(0), XtraSerializableProperty>
           Public Property Number() As Integer
   
           ' Set the "Browsable" and "EditorBrowsable" attributes to "false" and "Never"
           ' to hide the "Text" property from the "Properties" window and editor (IntelliSense).
           <Browsable(False), EditorBrowsable(EditorBrowsableState.Never)>
           Public Overrides Property Text() As String
               Get
                   Return Number.ToString()
               End Get
               Set(ByVal value As String)
                   Dim i As Integer = Nothing
                   Number = If(Integer.TryParse(value, i), i, 0)
               End Set
           End Property
   
           ' Implement a static constructor as shown below to add
           ' the "Number" property to the property grid's "Expressions" tab.
           Shared Sub New()
               ' Specify an array of events in which the property should be available.
               Dim eventNames() As String = { "BeforePrint" }
   
               ' Specify the property position in the property grid's "Expressions" tab.
               ' 0 - fist, 1000 - last.
               Dim position As Integer = 0
   
               ' Specify an array of the property's inner properties.
               Dim nestedBindableProperties() As String = Nothing
   
               ' Specify the property's category in the property grid's "Expressions" tab.
               ' The empty string corresponds the root category.
               Dim scopeName As String = ""
   
               ' Create and set a description for the "Number" property.
               Dim description As New ExpressionBindingDescription(eventNames, position, nestedBindableProperties, scopeName)
   
               ExpressionBindingDescriptor.SetPropertyDescription(GetType(NumericLabel), NameOf(Number), description)
           End Sub
       End Class
   End Namespace
   

Specify an Icon for the Custom Control

Add an .svg icon named NumericLabel.svg to the project and set the icon’s Build Action property to Embedded Resource.

Apply the ToolboxSvgImage attribute to the custom control:

C#

using DevExpress.Utils.Design;
//..

[ToolboxSvgImage("WinFormsApp_CustomNumericLabel.NumericLabel.svg, WinFormsApp_CustomNumericLabel")]
public class NumericLabel : XRLabel { ... }

VB.NET

Imports DevExpress.Utils.Design
'..

<ToolboxSvgImage("WinFormsApp_CustomNumericLabel.NumericLabel.svg, WinFormsApp_CustomNumericLabel")>
Public Class NumericLabel
    Inherits XRLabel

    Private ...}

Use Non-SVG Icons for Custom Controls

The ToolboxBitmap attribute allows you to specify a 16x16 bitmap icon for a custom control. The icon is displayed in the Report Explorer and the Toolbox. In the Toolbox, the icon is scaled to 24x24 for the standard Report Designer and 32x32 for the ribbon-based Report Designer. You can use ToolboxBitmap24Attribute and ToolboxBitmap32Attribute to specify icons of the 24x24 and 32x32 sizes.

C#

using DevExpress.Utils.Design;
using System.Drawing;
//...

namespace WinFormsApp_CustomNumericLabel {
    [ToolboxBitmap(typeof(NumericLabel), "NumericLabel.png")]
    [ToolboxBitmap24Attribute("WinFormsApp_CustomNumericLabel.NumericLabel24x24.png, WinFormsApp_CustomNumericLabel")]
    public class NumericLabel : XRLabel { ... }
}

VB.NET

Imports DevExpress.Utils.Design
Imports System.Drawing
'...

Namespace WinFormsApp_CustomNumericLabel
    <ToolboxBitmap(GetType(NumericLabel), "NumericLabel.png"), ToolboxBitmap24Attribute("WinFormsApp_CustomNumericLabel.NumericLabel2.png, WinFormsApp_CustomNumericLabel")>
    Public Class NumericLabel
        Inherits XRLabel

        Private ...}
    End Class

Add the Custom Control to the Toolbox

Handle the XRDesignMdiController.DesignPanelLoaded event to add the custom control to the Toolbox:

Form1.cs

using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.UserDesigner;
using System;
using System.Drawing.Design;
using System.Windows.Forms;
// ...
        void ShowDesignerWithCustomControl()
        {
            // Creates a Design Tool instance with the specified report instance.
            ReportDesignTool designTool = new ReportDesignTool(new XtraReport1());
            IDesignForm designForm = designTool.DesignForm;
            designForm.DesignMdiController.DesignPanelLoaded += DesignMdiController_DesignPanelLoaded;
            designTool.ShowDesignerDialog();
        }

        void DesignMdiController_DesignPanelLoaded(object sender, DesignerLoadedEventArgs e) {
            IToolboxService toolboxService =
                (IToolboxService)e.DesignerHost.GetService(typeof(IToolboxService));
            // Removes the XRLabel toolbox item.
            toolboxService.RemoveToolboxItem(
                GetToolBoxControl(toolboxService, "DevExpress.XtraReports.UI.XRLabel"));
            // Creates a new toolbox item for the custom control.
            ToolboxItem numericLabelItem = new ToolboxItem(typeof(NumericLabel))
            {
                // Specifies the name in the toolbox.
                DisplayName = "Numeric Label"
            };
            // Adds the new control to the toolbox.
            toolboxService.AddToolboxItem(numericLabelItem);
        }

        ToolboxItem GetToolBoxControl(IToolboxService toolboxService, string name) {
            foreach (ToolboxItem item in toolboxService.GetToolboxItems()) {
                if (item.TypeName == name) { return item; };
            }
            return null;
        }

Form1.vb

Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraReports.UserDesigner
Imports System
Imports System.Drawing.Design
Imports System.Windows.Forms
' ...
        Private Sub ShowDesignerWithCustomControl()
            ' Creates a Design Tool instance with the specified report instance.
            Dim designTool As New ReportDesignTool(New XtraReport1())
            Dim designForm As IDesignForm = designTool.DesignForm
            AddHandler designForm.DesignMdiController.DesignPanelLoaded, AddressOf DesignMdiController_DesignPanelLoaded
            designTool.ShowDesigner()
        End Sub

        Private Sub DesignMdiController_DesignPanelLoaded(ByVal sender As Object, ByVal e As DesignerLoadedEventArgs)
            Dim toolboxService As IToolboxService = DirectCast(e.DesignerHost.GetService(GetType(IToolboxService)), IToolboxService)
            ' Removes the XRLabel toolbox item.
            toolboxService.RemoveToolboxItem(GetToolBoxControl(toolboxService, "DevExpress.XtraReports.UI.XRLabel"))
            ' Creates a new toolbox item for the custom control.
            Dim numericLabelItem As New ToolboxItem(GetType(NumericLabel)) With {.DisplayName = "Numeric Label"}
            ' Adds the new control to the toolbox.
            toolboxService.AddToolboxItem(numericLabelItem)
        End Sub

        Private Function GetToolBoxControl(ByVal toolboxService As IToolboxService, ByVal name As String) As ToolboxItem
            For Each item As ToolboxItem In toolboxService.GetToolboxItems()
                If item.TypeName = name Then
                    Return item
                End If
            Next item
            Return Nothing
        End Function

Tip

The added control is available for any report opened in the Report Designer. You can also make a custom control available for specific reports only.