Skip to main content

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

  • 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.

Custom Numeric Label

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:

    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 {
        [ToolboxSvgImage("WinFormsApp_CustomNumericLabel.NumericLabel.svg, WinFormsApp_CustomNumericLabel")]
        public class NumericLabel : XRLabel {
            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
                    typeof(NumericLabel), nameof(Number), description

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:

using DevExpress.Utils.Design;

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

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.

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 { ... }

Add the Custom Control to the Toolbox

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

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;

        void DesignMdiController_DesignPanelLoaded(object sender, DesignerLoadedEventArgs e) {
            IToolboxService toolboxService =
            // Removes the XRLabel toolbox item.
                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.

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


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.

See Also