DiagramControl.CustomGetEditableItemProperties Event

Allows you to modify the list of diagram item properties that can be edited by end-users in the Properties Panel.

Namespace: DevExpress.Xpf.Diagram

Assembly: DevExpress.Xpf.Diagram.v24.1.dll

NuGet Package: DevExpress.Wpf.Diagram

Declaration

C#

public event EventHandler<DiagramCustomGetEditableItemPropertiesEventArgs> CustomGetEditableItemProperties

VB.NET

Public Event CustomGetEditableItemProperties As EventHandler(Of DiagramCustomGetEditableItemPropertiesEventArgs)

Event Data

The CustomGetEditableItemProperties event's data class is DiagramCustomGetEditableItemPropertiesEventArgs. The following properties provide information specific to this event:

Property	Description
Item	Returns the diagram item selected by the user.
Properties	Provides access to the collection of item properties the user can edit in the Properties panel.

The event data class exposes the following methods:

Method	Description
CreateProxyProperty(PropertyDescriptor, Func<IDiagramItem, Object>, IEnumerable<Attribute>)	Allows you to create a custom property descriptor.
CreateProxyProperty<TProperty>(String, Func<IDiagramItem, TProperty>, Action<IDiagramItem, TProperty>, IEnumerable<Attribute>)	Allows you to create a custom property descriptor.

Remarks

Add Properties

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, such as objects stored in DataContext.

Add a Shape Descendant’s Property

To add a property from a DiagramShape descendant, obtain the PropertyDescriptor for the required property using the TypeDescriptor.GetProperties method and add it to the DiagramItemCreatingEventArgs.Properties collection. See the example below.

C#

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

private void DiagramDesignerControl_CustomGetEditableItemProperties(object sender, DevExpress.Xpf.Diagram.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.Xpf.Diagram.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 to receive notifications about updates in the source object. To support property 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

To use diagram item descendants in a DiagramControl, register them using the DevExpress.Diagram.Core.DiagramItemTypeRegistrator.Register method. 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, if the DiagramShape‘s DataContext contains an instance of the Customer class, you can add the Customer.Name property to the Properties panel using the following code:

C#

private void DiagramDesignerControl_CustomGetEditableItemProperties(object sender,
        DevExpress.Xpf.Diagram.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.Xpf.Diagram.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

Use Different Properties for Items of the Same Type

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

Remove Properties

Tip

If you restrict user actions using protection options, the corresponding properties will automatically be removed from the Properties panel. For instance, if you set the DiagramControl.AllowResizeItems property to false, the Width and Height properties will be removed from the panel. The diagram protection options are listed in the DiagramControl.IsReadOnly property description.

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

C#

private void DiagramDesignerControl_CustomGetEditableItemProperties(object sender,
        DevExpress.Xpf.Diagram.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.Xpf.Diagram.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 by calling 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.Xpf.Diagram.DiagramCustomGetEditableItemPropertiesEventArgs e) {
    if (e.Item is DiagramShape)
    {
        Attribute[] additionalAttributes = new Attribute[] { new DisplayNameAttribute("Custom content") };
        PropertyDescriptor contentPropertyDescriptorWrapper = e.CreateProxyProperty(e.Properties["Content"], item => item, additionalAttributes);
        e.Properties.Remove(e.Properties["Content"]);
        e.Properties.Add(contentPropertyDescriptorWrapper);
    }
}

VB.NET

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

Customize Property Editors

To use a custom control to edit a property, create a property descriptor wrapper using CreateProxyProperty and pass an instance of PropertyGridEditorAttribute to this wrapper. Add this attribute to the property descriptor wrapper and define a template for your editor in diagram resources. The example below illustrates how to use a ComboBoxEdit to edit the diagram item’s content.

C#

private void DiagramDesignerControl_CustomGetEditableItemProperties(object sender,
        DevExpress.Xpf.Diagram.DiagramCustomGetEditableItemPropertiesEventArgs e) {
    if (e.Item is DiagramShape)
    {
        Attribute[] additionalAttributes = new Attribute[] { new PropertyGridEditorAttribute() { TemplateKey = "contentComboBoxEditor" } };
        PropertyDescriptor contentPropertyDescriptorWrapper = e.CreateProxyProperty(e.Properties["Content"], item => item, additionalAttributes);
        e.Properties.Remove(e.Properties["Content"]);
        e.Properties.Add(contentPropertyDescriptorWrapper);
    }
}

VB.NET

Private Sub DiagramDesignerControl_CustomGetEditableItemProperties(ByVal sender As Object,
        ByVal e As DevExpress.Xpf.Diagram.DiagramCustomGetEditableItemPropertiesEventArgs)
    If TypeOf e.Item Is DiagramShape Then
        Dim additionalAttributes As Attribute() = New Attribute() {New PropertyGridEditorAttribute() With {
.TemplateKey = "contentComboBoxEditor"
}}
        Dim contentPropertyDescriptorWrapper As PropertyDescriptor = e.CreateProxyProperty(e.Properties("Content"), Function(item) item, additionalAttributes)
        e.Properties.Remove(e.Properties("Content"))
        e.Properties.Add(contentPropertyDescriptorWrapper)
    End If
End Sub

XAML

<dxdiag:DiagramDesignerControl CustomGetEditableItemProperties="DiagramDesignerControl_CustomGetEditableItemProperties">
    <dxdiag:DiagramDesignerControl.Resources>
        <DataTemplate x:Key="contentComboBoxEditor">
            <dxe:ComboBoxEdit Name="PART_Editor">
                <dxe:ComboBoxEditItem Content="Director"/>
                <dxe:ComboBoxEditItem Content="Manager"/>
            </dxe:ComboBoxEdit>
        </DataTemplate>
    </dxdiag:DiagramDesignerControl.Resources>
</dxdiag:DiagramDesignerControl>

The PropertyGridControl locates your template using the specified TemplateKey. Note that the editor’s name should be set to PART_Editor.

Validation

The PropertyGridControl supports attribute-based validation that 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 symbols:

C#

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

VB.NET

Private Sub DiagramDesignerControl_CustomGetEditableItemProperties(ByVal sender As Object,
        ByVal e As DevExpress.Xpf.Diagram.DiagramCustomGetEditableItemPropertiesEventArgs)
    If TypeOf e.Item Is DiagramShape Then
        Dim additionalAttributes() As Attribute = { New System.ComponentModel.DataAnnotations.StringLengthAttribute(5) }
        Dim contentPropertyDescriptorWrapper As PropertyDescriptor = e.CreateProxyProperty(e.Properties("Content"), Function(item) item, additionalAttributes)
        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 that it’s necessary to add a reference to the System.ComponentModel.DataAnnotations assembly to use these attributes.

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the CustomGetEditableItemProperties event.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

XAML

wpf-diagram-create-diagramshape-descendant-with-editable-and-serializable-properties/CS/DXDiagram.CustomShapeProperties/MainWindow.xaml#L11

<Grid>
    <dxdiag:DiagramDesignerControl Name="diagramControl" CustomGetEditableItemProperties="diagramControl_CustomGetEditableItemProperties" />
</Grid>