Generate Diagrams from a Data Source

• Jul 02, 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):

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

These objects allow you to use the Item Template Designer or Runtime Item Generation 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

DiagramDataBindingController and DiagramOrgChartController 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 in the GenerateItem event handler, bind DiagramItem.Position to a source property, and add this object to the template item’s Bindings collection:

   C#

   void DiagramDataBindingController1_GenerateItem(object sender, DiagramGenerateItemEventArgs e) {
       var item = new DiagramShape {
           // ...
       };
       item.Bindings.Add(new DiagramBinding("Content", "PositionString"));
       item.Bindings.Add(new DiagramBinding("Position", "Position", DiagramBindingMode.TwoWay));
       e.Item = item;
   }
   

   VB.NET

   Private Sub DiagramDataBindingController1_GenerateItem(ByVal sender As Object, ByVal e As DiagramGenerateItemEventArgs)
       Dim item = New DiagramShape With {.X = 27, .Width = 75, .Height = 50, .Shape = BasicShapes.Rectangle}
       item.Bindings.Add(New DiagramBinding("Content", "PositionString"))
       item.Bindings.Add(New DiagramBinding("Position", "Position", DiagramBindingMode.TwoWay))
       e.Item = item
   End Sub
   

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

   C#

   void DiagramDataBindingController1_CustomLayoutItems(object sender, DiagramCustomLayoutItemsEventArgs e) {
       e.Handled = true;
   }
   

   VB.NET

   Private Sub DiagramDataBindingController1_CustomLayoutItems(ByVal sender As Object, ByVal e As 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.XtraDiagram.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.XtraDiagram.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 DiagramDataBindingController to Generate a Diagram from a Collection
• Use DiagramOrgChartController to Generate a Diagram from a Collection
• Generate Diagrams with Grouped Items
• Bind Item Positions to Source Objects