Customize the Properties Window in the End-User Report Designer

• Oct 09, 2023
• 3 minutes to read

This topic explains how you can customize the Office-inspired Properties window in the End-User Report Designer.

Move a Property to Another Tab

Original	Result

Handle the static XtraReport.FilterComponentProperties event to access a property and apply the PropertyGridTab attribute to it. Pass the name of the property’s target tab as the attribute’s constructor parameter.

The following code snippet demonstrates how to move the “PaperKind” property to the “Appearance” tab.

C#

using System;
using System.Windows.Forms;
using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.UserDesigner;
using DevExpress.XtraReports.Localization;
// ...

public partial class Form1 : Form {

    public Form1() {
        InitializeComponent();
        XtraReport.FilterComponentProperties +=
         XtraReport_FilterComponentProperties;
    }

    private void XtraReport_FilterComponentProperties(object sender, 
     FilterComponentPropertiesEventArgs e) {
        PropertyDescriptor propertyDescriptor1 = 
            e.Properties["PaperKind"] as PropertyDescriptor;
        if(propertyDescriptor1 != null) {
            List<Attribute> attributes = new List<Attribute>(propertyDescriptor1.Attributes
                .Cast<Attribute>()
                .Where(att => !(att is PropertyGridTabAttribute)));
            attributes.Add(
                new PropertyGridTabAttribute(ReportStringId.UD_PropertyGrid_TabAppearance));
            e.Properties["PaperKind"] = TypeDescriptor.CreateProperty(
                propertyDescriptor1.ComponentType,
                propertyDescriptor1,
                attributes.ToArray());
        }
    }
}

VB.NET

Imports System
Imports System.Windows.Forms
Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraReports.UserDesigner
Imports DevExpress.XtraReports.Localization
' ...

Partial Public Class Form1
    Inherits Form

    Public Sub New()
        InitializeComponent()
        AddHandler XtraReport.FilterComponentProperties, AddressOf XtraReport_FilterComponentProperties
    End Sub

    Private Sub XtraReport_FilterComponentProperties(ByVal sender As Object, ByVal e As FilterComponentPropertiesEventArgs)
        Dim propertyDescriptor1 As PropertyDescriptor = TryCast(e.Properties("PaperKind"), PropertyDescriptor)
        If propertyDescriptor1 IsNot Nothing Then
            Dim attributes As New List(Of Attribute)(propertyDescriptor1.Attributes.Cast(Of Attribute)().Where(Function(att) Not (TypeOf att Is PropertyGridTabAttribute)))
            attributes.Add(New PropertyGridTabAttribute(ReportStringId.UD_PropertyGrid_TabAppearance))
            e.Properties("PaperKind") = TypeDescriptor.CreateProperty(propertyDescriptor1.ComponentType, propertyDescriptor1, attributes.ToArray())
        End If
    End Sub
End Class

If you pass a new tab name as the PropertyGridTab attribute’s constructor parameter and apply this attribute to a property, the Properties window creates the new tab and adds this property to it. The following code snippet demonstrates this:

C#

using System;
using System.Windows.Forms;
using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.UserDesigner;
// ...

public partial class Form1 : Form {

    public Form1() {
        InitializeComponent();
        XtraReport.FilterComponentProperties += 
            XtraReport_FilterComponentProperties;
    }

    private void XtraReport_FilterComponentProperties(object sender, 
     FilterComponentPropertiesEventArgs e) {
        PropertyDescriptor propertyDescriptor1 = 
        e.Properties["PaperKind"] as PropertyDescriptor;
        if(propertyDescriptor1 != null) {
            List<Attribute> attributes = new List<Attribute>(propertyDescriptor1.Attributes
            .Cast<Attribute>()
            .Where(att => !(att is PropertyGridTabAttribute)));
            attributes.Add(new PropertyGridTabAttribute("My tab"));
            e.Properties["PaperKind"] = TypeDescriptor.CreateProperty(
                propertyDescriptor1.ComponentType,
                propertyDescriptor1,
                attributes.ToArray());
        }
    }
}

VB.NET

Imports System
Imports System.Windows.Forms
Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraReports.UserDesigner
' ...

Partial Public Class Form1
    Inherits Form

    Public Sub New()
        InitializeComponent()
        AddHandler XtraReport.FilterComponentProperties, AddressOf XtraReport_FilterComponentProperties
    End Sub

    Private Sub XtraReport_FilterComponentProperties(ByVal sender As Object, ByVal e As FilterComponentPropertiesEventArgs)
        Dim propertyDescriptor1 As PropertyDescriptor = TryCast(e.Properties("PaperKind"), PropertyDescriptor)
        If propertyDescriptor1 IsNot Nothing Then
            Dim attributes As New List(Of Attribute)(propertyDescriptor1.Attributes.Cast(Of Attribute)().Where(Function(att) Not (TypeOf att Is PropertyGridTabAttribute)))
            attributes.Add(New PropertyGridTabAttribute("Mytab"))
            e.Properties("PaperKind") = TypeDescriptor.CreateProperty(propertyDescriptor1.ComponentType, propertyDescriptor1, attributes.ToArray())
        End If
    End Sub
End Class

Original	Result

Provide a Custom Tab Icon

Handle the XRDesignMdiController.DesignPanelLoaded event to access tab icons collection and add/replace an icon.

The code snippet below demonstrates how to provide an icon for the “My tab” Properties window tab.

C#

using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.UserDesigner;
using DevExpress.Utils.Svg;
using DevExpress.XtraReports.Design;
// ...

public partial class Form1 : Form {

    public Form1() {
        InitializeComponent();
        reportDesigner1.DesignPanelLoaded += 
            ReportDesigner1_DesignPanelLoaded;
    }

    private void ReportDesigner1_DesignPanelLoaded(object sender,
     DevExpress.XtraReports.UserDesigner.DesignerLoadedEventArgs e) {
        // Access the tab icon provider
        IPropertyGridIconsProvider propertyGridImagesProvider = 
            (IPropertyGridIconsProvider)e.DesignerHost.GetService(typeof(IPropertyGridIconsProvider));

        // Assign an svg icon to the "My tab" tab if it does not have any
        if(!propertyGridImagesProvider.Icons.ContainsKey("My tab")) {
            SvgImage customTabIcon = SvgImage.FromFile(@"..\..\CustomTabIcon.svg");
            propertyGridImagesProvider.Icons.Add("My tab", new IconImage(customTabIcon));
        }
    }
}

VB.NET

Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraReports.UserDesigner
Imports DevExpress.Utils.Svg
Imports DevExpress.XtraReports.Design
' ...

Partial Public Class Form1
    Inherits Form

    Public Sub New()
        InitializeComponent()
        AddHandler reportDesigner1.DesignPanelLoaded, AddressOf ReportDesigner1_DesignPanelLoaded
    End Sub

    Private Sub ReportDesigner1_DesignPanelLoaded(ByVal sender As Object, ByVal e As DevExpress.XtraReports.UserDesigner.DesignerLoadedEventArgs)
        ' Access the tab icon provider
        Dim propertyGridImagesProvider As IPropertyGridIconsProvider = DirectCast(e.DesignerHost.GetService(GetType(IPropertyGridIconsProvider)), IPropertyGridIconsProvider)

        ' Assign an svg icon to the "My tab" tab if it does not have any
        If Not propertyGridImagesProvider.Icons.ContainsKey("My tab") Then
            Dim customTabIcon As SvgImage = SvgImage.FromFile("..\..\CustomTabIcon.svg")
            propertyGridImagesProvider.Icons.Add("My tab", New IconImage(customTabIcon))
        End If
    End Sub
End Class