Properties Panel

• Jul 02, 2024
• 5 minutes to read

The Properties Panel is a PropertyGridControl object set as the value of the DiagramControl.PropertyGrid property.

Users can toggle the auto-hide mode or close the panel. To show the panel, right-click a diagram item or empty space in the canvas and select Properties in the menu. You can also use the Ribbon UI (View > Panes) to show or hide the Properties panel.

The table below lists the main customization options.

Characteristics	Members
Availability	DiagramOptionsBehavior.AllowPropertiesPanel
Display mode	DiagramOptionsView.PropertiesPanelVisibility
Measure Unit	DiagramOptionsView.MeasureUnit
Display measure unit next to values	DiagramOptionsView.ShowMeasureUnit

Add Properties

To add a property to the Properties panel, handle the CustomGetEditableItemProperties event. The following code snippet illustrates how to add the DiagramItem.CanSnapToThisItem property for shapes:

C#

private void Diagram_CustomGetEditableItemProperties(object sender, DiagramCustomGetEditableItemPropertiesEventArgs e) {
    if (e.Item is DiagramShape) {
        e.Properties.Add(TypeDescriptor.GetProperties(typeof(DiagramShape))["CanSnapToThisItem"]);
    }
}

VB.NET

Private Sub Diagram_CustomGetEditableItemProperties(ByVal sender As Object, ByVal e As DiagramCustomGetEditableItemPropertiesEventArgs)
    If TypeOf e.Item Is DiagramShape Then
        e.Properties.Add(TypeDescriptor.GetProperties(GetType(DiagramShape))("CanSnapToThisItem"))
    End If
End Sub

You can add properties from a custom DiagramItem descendant and other sources, for example, objects stored in a DataContext.

Add a Shape Descendant’s Property

To add a property from a DiagramShape descendant, use the TypeDescriptor.GetProperties method to obtain the PropertyDescriptor and add it to the DiagramItemCreatingEventArgs.Properties collection:

C#

public class CustomDiagramShape : DiagramShape {
    public string Info {
        get;
        set;
    }
} 

private void DiagramDesignerControl_CustomGetEditableItemProperties(object sender, DevExpress.XtraDiagram.DiagramCustomGetEditableItemPropertiesEventArgs e) {
    if (e.Item is CustomDiagramShape)
    {
        PropertyDescriptor infoPropertyDescriptor = TypeDescriptor.GetProperties(typeof(CustomDiagramShape))["Info"];
        e.Properties.Add(infoPropertyDescriptor);
    }
}

VB.NET

Public Class CustomDiagramShape
    Inherits DiagramShape
    Private privateInfo As String
    Public Property Info() As String
        Get
            Return privateInfo
        End Get
        Set(ByVal value As String)
            privateInfo = value
        End Set
    End Property
End Class

Private Sub DiagramDesignerControl_CustomGetEditableItemProperties(ByVal sender As Object, ByVal e As DevExpress.XtraDiagram.DiagramCustomGetEditableItemPropertiesEventArgs)
    If TypeOf e.Item Is CustomDiagramShape Then
        Dim infoPropertyDescriptor As PropertyDescriptor = TypeDescriptor.GetProperties(GetType(CustomDiagramShape))("Info")
        e.Properties.Add(infoPropertyDescriptor)
    End If
End Sub

The Properties panel uses the INotifyPropertyChanged interface for notifications about updates in the source object. To enable synchronization when the Info property is modified, implement the INotifyPropertyChanged interface in the CustomDiagramShape class and raise the PropertyChanged event in the Info property setter.

Note

Use the DevExpress.Diagram.Core.DiagramItemTypeRegistrator.Register method to register diagram item descendants in a DiagramControl. To use custom diagram item types instead of the regular ones, handle the DiagramControl.ItemCreating event.

Add Independent Properties

The Properties panel allows users to edit properties that are not defined directly at the DiagramItem level. This can be useful when your diagram is bound to a data source and you need to edit data item properties. For this purpose, DiagramCustomGetEditableItemPropertiesEventArgs provides the CreateProxyProperty method that allows you to create a custom property descriptor.

Add the property descriptor to the DiagramCustomGetEditableItemPropertiesEventArgs.Properties collection to edit a custom property. For instance, you can use the following code to add the Customer.Name property to the Properties panel if the DiagramShape‘s DataContext contains a Customer class instance:

C#

private void DiagramDesignerControl_CustomGetEditableItemProperties(object sender,
        DevExpress.XtraDiagram.DiagramCustomGetEditableItemPropertiesEventArgs e) {
    if (e.Item is DiagramShape)
    {
        PropertyDescriptor namePropertyDescriptor = e.CreateProxyProperty("Name", item => ((Customer)item.DataContext).Name, (item, value) => ((Customer)item.DataContext).Name = value);
        e.Properties.Add(namePropertyDescriptor);
    }
}

VB.NET

Private Sub DiagramDesignerControl_CustomGetEditableItemProperties(ByVal sender As Object,
        ByVal e As DevExpress.XtraDiagram.DiagramCustomGetEditableItemPropertiesEventArgs)
    If TypeOf e.Item Is DiagramShape Then
        Dim namePropertyDescriptor As PropertyDescriptor = e.CreateProxyProperty(Of String)
            ("Name", New Func(Of IDiagramItem, String)(AddressOf GetNameFromItem), New Action(Of IDiagramItem, String)(AddressOf SetItemName))
        e.Properties.Add(namePropertyDescriptor)
    End If
End Sub
Public Function GetNameFromItem(ByVal item As IDiagramItem) As String
    Return (CType(item.DataContext, Customer)).Name
End Function
Public Sub SetItemName(ByVal item As IDiagramItem, ByVal value As String)
    CType(item.DataContext, Customer).Name = value
End Sub

Remove Properties

Tip

If you use protection options to restrict user actions, the corresponding properties are automatically removed from the Properties panel. For example, the Width and Height properties are removed from the panel if you set the DiagramOptionsProtection.AllowResizeItems property to false. The diagram protection options are listed in the DiagramOptionsProtection.IsReadOnly property’s description.

To remove a property from the Properties panel, handle the DiagramControl.CustomGetEditableItemProperties and remove the corresponding property descriptor from the Properties collection:

C#

private void DiagramDesignerControl_CustomGetEditableItemProperties(object sender,
        DevExpress.XtraDiagram.DiagramCustomGetEditableItemPropertiesEventArgs e) {
    if (e.Item is DiagramShape)
    {
        e.Properties.Remove(e.Properties["Content"]);
    }
}

VB.NET

Private Sub DiagramDesignerControl_CustomGetEditableItemProperties(ByVal sender As Object,
        ByVal e As DevExpress.XtraDiagram.DiagramCustomGetEditableItemPropertiesEventArgs)
    If TypeOf e.Item Is DiagramShape Then
        e.Properties.Remove(e.Properties("Content"))
    End If
End Sub

Customize Properties

Customize Property Names

To customize a property name, handle the DiagramControl.CustomGetEditableItemProperties event. Create a custom property descriptor wrapper with the CreateProxyProperty method and use the DisplayNameAttribute attribute.

The example below illustrates how to rename the Content property.

C#

private void DiagramDesignerControl_CustomGetEditableItemProperties(object sender,
        DevExpress.XtraDiagram.DiagramCustomGetEditableItemPropertiesEventArgs e) {
    if (e.Item is DiagramShape)
    {
        Attribute[] additionalAttriutes = new Attribute[] { new DisplayNameAttribute("Custom content") };
        PropertyDescriptor contentPropertyDescriptorWrapper = e.CreateProxyProperty(e.Properties["Content"], item => item, additionalAttriutes);
        e.Properties.Remove(e.Properties["Content"]);
        e.Properties.Add(contentPropertyDescriptorWrapper);
    }
}

VB.NET

Private Sub DiagramDesignerControl_CustomGetEditableItemProperties(ByVal sender As Object,
        ByVal e As DevExpress.XtraDiagram.DiagramCustomGetEditableItemPropertiesEventArgs)
    If TypeOf e.Item Is DiagramShape Then
        Dim additionalAttriutes As Attribute() = New Attribute() {New DisplayNameAttribute("Custom content")}
        Dim contentPropertyDescriptorWrapper As PropertyDescriptor = e.CreateProxyProperty(e.Properties("Content"), Function(item) item, additionalAttriutes)
        e.Properties.Remove(e.Properties("Content"))
        e.Properties.Add(contentPropertyDescriptorWrapper)
    End If
End Sub

Use Different Properties for Items of the Same Type

The DiagramControl caches property descriptors for items of the same type. Handle the CustomGetEditableItemPropertiesCacheKey event to conditionally choose properties for diagram items of the same type.

Validation

The PropertyGridControl supports attribute-based validation. This type of validation allows you to define validation rules for edited properties. The following code snippet adds a validation attribute that prevents users from typing a text string longer than five characters:

C#

private void DiagramDesignerControl_CustomGetEditableItemProperties(object sender,
        DevExpress.XtraDiagram.DiagramCustomGetEditableItemPropertiesEventArgs e) {
    if (e.Item is DiagramShape) {
        Attribute[] additionalAttriutes = new Attribute[] { new System.ComponentModel.DataAnnotations.StringLengthAttribute(5) };
        PropertyDescriptor contentPropertyDescriptorWrapper = e.CreateProxyProperty(e.Properties["Content"], item => item, additionalAttriutes);
        e.Properties.Remove(e.Properties["Content"]);
        e.Properties.Add(contentPropertyDescriptorWrapper);
    }
}

VB.NET

Private Sub DiagramDesignerControl_CustomGetEditableItemProperties(ByVal sender As Object,
        ByVal e As DevExpress.XtraDiagram.DiagramCustomGetEditableItemPropertiesEventArgs)
    If TypeOf e.Item Is DiagramShape Then
        Dim additionalAttriutes() As Attribute = { New System.ComponentModel.DataAnnotations.StringLengthAttribute(5) }
        Dim contentPropertyDescriptorWrapper As PropertyDescriptor = e.CreateProxyProperty(e.Properties("Content"), Function(item) item, additionalAttriutes)
        e.Properties.Remove(e.Properties("Content"))
        e.Properties.Add(contentPropertyDescriptorWrapper)
    End If
End Sub

You can use the following attributes for validation:

• CustomValidationAttribute
• DataTypeAttribute
• EnumDataTypeAttribute
• RangeAttribute
• RegularExpressionAttribute
• RequiredAttribute
• StringLengthAttribute

Note: You should add a reference to the System.ComponentModel.DataAnnotations assembly to use these attributes.