Generate Diagrams from a Data Source

• Jun 20, 2024
• 3 minutes to read

The DevExpress Diagram Control allows you to generate diagrams based on a collection of data items. You can generate flat or hierarchical (organizational chart) diagrams.

The DiagramControl uses behavior objects to generate diagram items (shapes, containers, and connectors):

• DiagramDataBindingBehavior generates arbitrary diagrams from two collections of data items (one for shapes/containers and a second one for connectors).
• DiagramOrgChartBehavior generates organizational chart diagrams from hierarchical data.

These objects allow you to use the Item Template Designer or Template Properties to define and configure generated items.

Refer to the following topics for additional information, code samples, and related limitations:

• Generate Diagrams from Flat Data
• Generate Diagrams from Hierarchical Data
• Define and Configure Generated Diagram Items
• Generate Multi-Level Diagrams

Specify Positions of Generated Items

DiagramDataBindingBehavior and DiagramOrgChartBehavior arrange items based on the LayoutKind property value. The following layout algorithms are available:

• Sugiyama (Default)
• Tree
• TipOverTree
• Circular
• MindMapTree
• OrgChart

You can arrange items manually if none of the algorithms above suits your requirements. To do this, handle the CustomLayoutItems event. In the event handler, set the e.Handled property to true (to disable the default layout algorithm) and arrange items based on custom logic.

Bind Item Positions to Source Properties

If your data source contains information about item locations, you can position generated items according to this information.

View Example: Bind Item Positions to Source Objects

1. Create a DiagramBinding object, bind DiagramItem.Position to a source property, and add this object to the template item’s Bindings collection:

   XAML

   <dxdiag:DiagramDataBindingBehavior.TemplateDiagram>
       <dxdiag:DiagramControl>
           <dxdiag:DiagramShape Width="100" Height="75">
               <dxdiag:DiagramShape.Bindings>
                   <dxdiag:DiagramBinding PropertyName="Position" Expression="ItemPosition" Mode="TwoWay"/>
               </dxdiag:DiagramShape.Bindings>
           </dxdiag:DiagramShape>
       </dxdiag:DiagramControl>
   </dxdiag:DiagramDataBindingBehavior.TemplateDiagram>
   

2. Handle the CustomLayoutItems event to disable the default layout algorithm.

   C#

   void DiagramDataBindingBehavior_CustomLayoutItems(object sender, DevExpress.Xpf.Diagram.DiagramCustomLayoutItemsEventArgs e) {
       e.Handled = true;
   }
   

   VB.NET

   Private Sub DiagramDataBindingBehavior_CustomLayoutItems(ByVal sender As Object, ByVal e As DevExpress.Xpf.Diagram.DiagramCustomLayoutItemsEventArgs)
       e.Handled = True
   End Sub
   

Fetch and Post Changes at Runtime

You can synchronize diagram items between the diagram UI and the bound collection bidirectionally:

Fetch New Items

Call the Refresh() method to generate new diagram items and rearrange them after you add data items to the source collection.

Post Created Items

Handle the DiagramItemAdding event to add data items to the bound collection when a user creates new items in the UI. The event handler allows you to create a new data item instance or cancel the action based on custom logic:

C#

void DiagramDataBindingBehavior_DiagramItemAdding(object sender, DevExpress.Xpf.Diagram.DiagramDiagramItemAddingEventArgs e) {
    if (e.Item is DiagramShape)
        e.DataItem = new ClassData();
    if (e.Item is DiagramContainer)
        e.Cancel = true;
}

VB.NET

Private Sub DiagramDataBindingBehavior_DiagramItemAdding(ByVal sender As Object, ByVal e As DevExpress.Xpf.Diagram.DiagramDiagramItemAddingEventArgs)
    If TypeOf e.Item Is DiagramShape Then e.DataItem = New ClassData()
    If TypeOf e.Item Is DiagramContainer Then e.Cancel = True
End Sub

Note

Do not add items directly to the DiagramControl.Items collection.

Examples

• Use DiagramDataBindingBehavior to Generate a Diagram from a Collection
• Use DiagramOrgChartBehavior to Generate a Diagram from a Collection
• Generate Diagrams with Grouped Items
• Bind Diagram Item Positions to Source Objects