Extend a Default Diagram Item

• Feb 01, 2024
• 4 minutes to read

You can create a diagram item descendant with additional properties to extend a default diagram item.

View Example: Create a DiagramShape Descendant with Editable and Serializable Properties

Create and Register Descendants

1. Create a custom class and inherit it from the required type (DiagramShape, DiagramContainer, DiagramList, DiagramConnector, DiagramContentItem, or DiagramImage):

   C#

   public class CustomDiagramShape : DiagramShape {
       //...
   }
   

   VB.NET

   Public Class CustomDiagramShape
       Inherits DiagramShape
       ' ...
   End Class
   

   Make sure that your descendant class has a parameterless constructor.

2. Call the DiagramItemTypeRegistrator.Register method to register your descendant type and allow its serialization. You should register descendants at application startup.

   C#

   DiagramControl.ItemTypeRegistrator.Register(typeof(CustomDiagramShape));
   

   VB.NET

   DiagramControl.ItemTypeRegistrator.Register(GetType(CustomDiagramShape))
   

   If the custom item is used in the Diagram Designer or Item Template Designer, it is necessary to also register it in the item static constructor:

   C#

   public class CustomDiagramShape : DiagramShape {
       // Descendant properties
       static CustomDiagramShape() {
           DiagramControl.ItemTypeRegistrator.Register(typeof(CustomDiagramShape));
       }
   }
   

   VB.NET

   Public Class CustomDiagramShape
       Inherits DiagramShape
       ' Descendant properties
       Private Shared Sub New()
           DiagramControl.ItemTypeRegistrator.Register(GetType(CustomDiagramShape))
       End Sub
   End Class
   

   Note

   The DiagramControl registration mechanism uses short type names to register diagram item descendants of custom types. Generic types are registered only by their short names without type parameters.

3. Register a FactoryItemTool that creates your custom item:

   C#

   var stencil = new DiagramStencil("CustomStencil", "Custom Shapes");  
   var itemTool = new FactoryItemTool(  
       "CustomShape",  
       () => "Custom Shape", diagram => {  
           CustomDiagramShape customShape = new CustomDiagramShape() { Width = 100, Height = 50 };  
           return customShape;  
       },  
       new Size(100, 50),  
       false  
   );  
   stencil.RegisterTool(itemTool);  
   DiagramToolboxRegistrator.RegisterStencil(stencil);
   

   VB.NET

   Dim stencil = New DiagramStencil("CustomStencil", "Custom Shapes")
   Dim itemTool = New FactoryItemTool("CustomShape", Function() "Custom Shape", Function(diagram)
       Dim customShape As CustomDiagramShape = New CustomDiagramShape() With {.Width = 100, .Height = 50}
       Return customShape
   End Function, New Size(100, 50), False)
   stencil.RegisterTool(itemTool)
   DiagramToolboxRegistrator.RegisterStencil(stencil)
   

Define Custom Properties and Enable Their Serialization

The DiagramControl serializes items and their properties when a user performs the following actions: copy, paste, cut, undo, and redo. The serialization mechanism is also used to save diagrams to a stream or XML document. Mark your custom properties with the XtraSerializableProperty attribute to enable their serialization:

C#

[XtraSerializableProperty]
public int DatabaseObjectID { get; set; }

VB.NET

<XtraSerializableProperty>
Public Property DatabaseObjectID As Integer

Handle the DiagramControl.CustomGetSerializableItemProperties event instead if you cannot change your diagram item implementation:

C#

private void diagramControl1_CustomGetSerializableItemProperties(object sender, DiagramCustomGetSerializableItemPropertiesEventArgs e) {
    e.Properties.Add(TypeDescriptor.GetProperties(typeof(CustomDiagramShape))["DatabaseObjectID"]);
}

VB.NET

Private Sub diagramControl1_CustomGetSerializableItemProperties(ByVal sender As Object, ByVal e As DiagramCustomGetSerializableItemPropertiesEventArgs)
    e.Properties.Add(TypeDescriptor.GetProperties(GetType(CustomDiagramShape))("DatabaseObjectID"))
End Sub

You can also handle the DiagramControl.CustomGetEditableItemProperties event to allow users to edit your custom properties in the Properties Panel. Refer to the following section in the event description: Add a Shape Descendant’s Property.

Add Property Descriptors for Custom Properties

The Properties Panel allows users to edit properties that are not defined directly at the diagram item level (for example, when your diagram is bound to a data source and you need to edit source item properties). To do this, handle the DiagramControl.CustomGetEditableItemProperties event and use the CreateProxyProperty method to create a custom property descriptor. For additional information, refer to the following section in the event description: Add Independent Properties.

Assign Type Converters

The Properties Panel uses the Property Grid control to edit properties. This control supports custom TypeConverters that can be assigned to properties of a diagram item descendant. You can use these converters when editable properties are object collections or custom types.

C#

public class CollectionDescriptionConverter : CollectionConverter {
    public override PropertyDescriptorCollection GetProperties(ITypeDescriptorContext context, object value, Attribute[] attributes) {
        if (value is List<int> list)
            return new PropertyDescriptorCollection(list.Select(x => new CustomPropertyDescriptor(Guid.NewGuid().ToString())), new Attribute[] { ... });
        return base.GetProperties(context, value, attributes);
    }

    public override bool GetPropertiesSupported(ITypeDescriptorContext context) => true;
}

public class CustomPropertyDescriptor : PropertyDescriptor { ... }

public class CustomDiagramShape : DiagramShape {
    [TypeConverter(typeof(CollectionDescriptionConverter))]
    public ObservableCollection<string> _Values { get; set; }
}

VB.NET

Public Class CollectionDescriptionConverter
    Inherits CollectionConverter

    Public Overrides Function GetProperties(ByVal context As ITypeDescriptorContext, ByVal value As Object, ByVal attributes As Attribute()) As PropertyDescriptorCollection
        If TypeOf value Is List(Of Integer) Then
            Dim list = CType(value, List(Of Integer))
            Return New PropertyDescriptorCollection(list.[Select](Function(x) New CustomPropertyDescriptor(Guid.NewGuid().ToString())), New Attribute() { ... })
        End If

        Return MyBase.GetProperties(context, value, attributes)
    End Function

    Public Overrides Function GetPropertiesSupported(ByVal context As ITypeDescriptorContext) As Boolean
        Return True
    End Function
End Class

Public Class CustomPropertyDescriptor
    Inherits PropertyDescriptor
    ' ...
End Class

Public Class CustomDiagramShape
    Inherits DiagramShape

    <TypeConverter(GetType(CollectionDescriptionConverter))>
    Public Property _Values As ObservableCollection(Of String)
End Class