Add a Custom Control to the Report Designer Toolbox

• Feb 02, 2024
• 4 minutes to read

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

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

Create a Project and Custom Control

1. Create a new WPF project with the Report Designer named WpfApp_CustomNumericLabel.
2. Add a new blank report to the project.

3. Implement a custom numeric label in a file named NumericLabel.cs:

   Show Code

   NumericLabel.cs

   using DevExpress.Utils.Design;
   using DevExpress.Utils.Serializing;
   using DevExpress.XtraReports;
   using DevExpress.XtraReports.Expressions;
   using DevExpress.XtraReports.UI;
   using System.ComponentModel;
   
   namespace WpfApp_CustomNumericLabel {
      [ToolboxItem(true)]
      [ToolboxSvgImage("WpfApp_CustomNumericLabel.NumericLabel.svg, WpfApp_CustomNumericLabel")]
      [DefaultBindableProperty("Number")]
      [DisplayName("Numeric Label")]
      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 Properties window'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 Properties window's "Expressions" tab.
              // 0 - first, 1000 - last.
              int position = 0;
   
              // Specify an array of the property's inner properties.
              string[] nestedBindableProperties = null;
   
              // Specify the property's category in the Properties window's "Expressions" tab.
              // The empty string corresponds the root category.
              string scopeName = "";
   
              // Create and set 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.Design
   Imports DevExpress.Utils.Serializing
   Imports DevExpress.XtraReports
   Imports DevExpress.XtraReports.Expressions
   Imports DevExpress.XtraReports.UI
   Imports System.ComponentModel
   
   Namespace WpfApp_CustomNumericLabel
      <ToolboxItem(True), ToolboxSvgImage("WpfApp_CustomNumericLabel.NumericLabel.svg, WpfApp_CustomNumericLabel"), DefaultBindableProperty("Number"), DisplayName("Numeric Label")>
      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 Properties window'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 Properties window's "Expressions" tab.
              ' 0 - first, 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 Properties window's "Expressions" tab.
              ' The empty string corresponds the root category.
              Dim scopeName As String = ""
   
              ' Create and set 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
   

Add the Custom Control to the Toolbox

Use the RegisterControl<T>() method to add the custom control to the Toolbox:

C#

using DevExpress.Xpf.Reports.UserDesigner;
//..

private void reportDesigner_Loaded(object sender, RoutedEventArgs e) {
    ReportDesigner.RegisterControl<NumericLabel>();
    reportDesigner.OpenDocument(new XtraReport1());
}

VB.NET

Imports DevExpress.Xpf.Reports.UserDesigner
'..

Private Sub reportDesigner_Loaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
    ReportDesigner.RegisterControl(Of NumericLabel)()
    reportDesigner.OpenDocument(New XtraReport1())
End Sub

The added control inherits an icon from the XRLabel control.

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 for the created custom control:

C#

using DevExpress.Utils.Design;
//..

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

VB.NET

Imports DevExpress.Utils.Design
'..

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

    Private ...}

Rebuild and run the project. The control with the specified icon appears in the toolbox.

Note

We recommend you use .svg icons for custom controls. If you need to specify non-svg icons, use the RegisterControl<T>(ImageSource) method.