Extend an Existing Report Control

• Jan 12, 2021
• 4 minutes to read

Do the following to implement a custom control based on an existing report control.

1. Create a new class for a custom control and derive it from an existing report control.
2. Implement properties, methods, events, and other members for the custom control class.

Example: Create a Custom Numeric Label

The example below describes how to add a new Number property to the XRLabel control to limit the values the control can accept to numbers only.

View Example: Create a Custom Numeric Label

Get Started

Create a new Visual Studio project named CustomNumericLabel. Then, add a blank report to the project.

Extend the XRLabel Control

1. Add a new XRNumericLabel.cs file to the project.
2. Create a new XRNumericLabel class and derive it from the XRLabel control.
3. Implement a new Number property and override the label’s Text property.

C#

using DevExpress.Utils.Serializing;
using DevExpress.XtraReports.UI;
using System.ComponentModel;

namespace CustomNumericLabel {
    public class XRNumericLabel : 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;
            }
        }
    }
}

VB.NET

Imports DevExpress.Utils.Serializing
Imports DevExpress.XtraReports.UI
Imports System.ComponentModel

Namespace CustomNumericLabel
    Public Class XRNumericLabel
        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
    End Class
End Namespace

Tip

Apply the XtraSerializableProperty attribute for custom properties to serialize these properties when you save a report in the XML format. Refer to the following topic for details on control serialization: Store Report Layouts.

Add the Numeric Label to the Visual Studio Toolbox

Set the ToolboxItem attribute for the XRNumericLabel class to true:

C#

namespace CustomNumericLabel {
    [ToolboxItem(true)]
    public class XRNumericLabel : XRLabel {
        // ..
    }
}

VB.NET

Namespace CustomNumericLabel
    <ToolboxItem(True)>
    Public Class XRNumericLabel
        Inherits XRLabel

        ' ..
    End Class
End Namespace

Build the solution. The control appears in the toolbox and you can drop the control onto the report’s bands.

Specify the Default Property for Data Binding

Apply the DefaultBindableProperty attribute to the Number property. When you drop a field from the Field List onto the control, the Number property is bound to this field.

C#

using DevExpress.XtraReports;

namespace CustomNumericLabel {
    [DefaultBindableProperty("Number")]
    public class XRNumericLabel : XRLabel {
        // ..
    }
}

VB.NET

Imports DevExpress.XtraReports

Namespace CustomNumericLabel
    <DefaultBindableProperty("Number")>
    Public Class XRNumericLabel
        Inherits XRLabel

        ' ..
    End Class
End Namespace

Add the Number Property to the Property Grid’s Expressions Tab

Implement a static constructor for the XRNumericLabel class as shown below to add the Number property to the Property grid‘s Expressions tab:

C#

using DevExpress.XtraReports.Expressions;

namespace CustomNumericLabel {
    public class XRNumericLabel : XRLabel {
        static XRNumericLabel() {
            // 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 - 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 property grid's "Expressions" tab.
            // The empty string corresponds to 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(XRNumericLabel), nameof(Number), description
            );
        }
        //...
    }
}

VB.NET

Imports DevExpress.XtraReports.Expressions

Namespace CustomNumericLabel
    Public Class XRNumericLabel
        Inherits XRLabel

        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 - 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 property grid's "Expressions" tab.
            ' The empty string corresponds to 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(XRNumericLabel), nameof(Number), description)
        End Sub
        '...
    End Class
End Namespace

Rebuild the solution. The Number property appears in the Property grid‘s Expressions tab.

Click the property’s ellipsis button and use the invoked Expression Editor to specify an expression: