View source for Documentation:Creating CustomControl that Shows Data in a Gantt Chart

You can bind hierarchical, time-based data from a [[Documentation:ViewModel|ViewModel]] to a WPF Gantt custom control when you build the ViewModel around the control's required list, column, and association names.
== What you build ==
The Gantt control renders a tree on the left and time items on the right. Each tree row can display two text values and a collection of dated time items. Rows can contain child rows, so the hierarchy can continue to any depth.

For example, a project-plan Gantt can show:

{| class="wikitable"
! Tree row
! Column1
! Column2
! Time item
|-
| Project Alpha
| Alpha
| Planning
| Planning, 2026-01-05 to 2026-01-12
|-
| Design
| Design
| In progress
| Create mock-ups, 2026-01-13 to 2026-01-20
|}

The control uses WPF data binding. It does not require your domain classes to be named <code>TreeNode</code> or <code>TimeItem</code>; those are the names it expects in the ViewModel contract.
== Understand the binding contract ==
Create a ViewModel list named <code>TreeNodes</code>. Its items must expose the columns and associations in the following table.

{| class="wikitable"
! ViewModel element
! Required name
! Type or purpose
|-
| Root list column
| <code>TreeNodes</code>
| A list of the rows at the top of the Gantt tree.
|-
| Tree-row column
| <code>Column1</code>
| The first value displayed in the tree grid.
|-
| Tree-row column
| <code>Column2</code>
| The second value displayed in the tree grid.
|-
| Tree-row association
| <code>TimeItems</code>
| The time items rendered on this row.
|-
| Child-row association
| <code>TreeNodes</code>
| Child rows. Each child must expose the same row contract, including <code>Column1</code>, <code>Column2</code>, <code>TimeItems</code>, and its own <code>TreeNodes</code> association.
|-
| Time-item column
| <code>Start</code>
| Start date and time (<code>DateTime</code>).
|-
| Time-item column
| <code>Stop</code>
| End date and time (<code>DateTime</code>).
|-
| Time-item column
| <code>Text</code>
| Text displayed for the time item (<code>string</code>).
|-
| Time-item column
| <code>Color</code>
| Item color (<code>int</code>).
|}

''Names are significant.'' The wrapper binds to <code>TreeNodes</code>, <code>TimeItems</code>, <code>Start</code>, <code>Stop</code>, <code>Text</code>, and <code>Color</code>. A domain attribute named <code>PlannedStart</code>, for example, must be exposed in the ViewModel as a column named <code>Start</code>.
== Prepare the model ==
Start with a model that can represent rows, hierarchy, and dated items. The class names below are examples; use names that fit your model.

# Create a class for a Gantt row, such as <code>WorkItem</code>.
# Add attributes or derived values that will supply the two tree-grid values. For example, <code>Name</code> and <code>Status</code>.
# Add a recursive association from <code>WorkItem</code> to child <code>WorkItem</code> objects. This is the source for the ViewModel association named <code>TreeNodes</code>.
# Create a class for a dated item, such as <code>ScheduleItem</code>.
# Add <code>DateTime</code> attributes for its start and stop times, a string attribute for its label, and an integer attribute for its color.
# Associate each <code>ScheduleItem</code> with the <code>WorkItem</code> row that owns it.

A recursive row association is what lets the control show a project, its phases, and work items as expandable tree levels. The Gantt custom control can bind child rows repeatedly as long as each level follows the same contract.

<message>Write the content here to display this box</message>
A simple model to hold the data:[[File:Sample Model .png|link=http://wiki.mdriven.net/index.php/File:Sample%20Model%20.png|none|thumb]]Then, a ViewModel can show and create data defined by that model:[[File:Gantt example.png|link=http://wiki.mdriven.net/index.php/File:Gantt%20example.png|none|thumb|419x419px]]I hook up the newly created Gantt-wrapper that has this text to describe its requirements:<blockquote>''A list column with name '''TreeNodes'''.''</blockquote><blockquote>''Each TreeNode should have '''Column1''' and '''Column2''' to display in grid''</blockquote><blockquote>''TreeNodes can also have an association '''TimeItems'''; each TimeItem should have Start,Stop(DateTime), Text(string),Color(int)''</blockquote><blockquote>''TreeNodes can also have a association TreeNodes to sub TreeNodes; these tree nodes should also have Column1,2, and TimeItems''</blockquote><blockquote>''To allow for a TimeItem to move from one row to another add an Action column on TimeItem named MoveToNewRow, also declare viewmodel variable vNewRow of the type your class representing the TimeItem has''</blockquote><blockquote>''Can then implement the move in the Action execute expression; vNewRow.SomeTimeItem.add(self)''</blockquote>We need to read and understand to make our ViewModel fit the need of the rather complex UI control.
== Create the ViewModel data shape ==
Create a [[Documentation:ViewModel|ViewModel]] that exposes the required names, mapping them to your model. The following mapping illustrates a project-plan model:

{| class="wikitable"
! Domain data
! ViewModel contract name
! Example
|-
| List of top-level <code>WorkItem</code> objects
| <code>TreeNodes</code>
| Projects with no parent
|-
| <code>WorkItem.Name</code>
| <code>Column1</code>
| <code>Design</code>
|-
| <code>WorkItem.Status</code>
| <code>Column2</code>
| <code>In progress</code>
|-
| Child <code>WorkItem</code> objects
| <code>TreeNodes</code>
| Tasks below Design
|-
| <code>WorkItem.ScheduleItems</code>
| <code>TimeItems</code>
| Schedule items for Design
|-
| <code>ScheduleItem.PlannedStart</code>
| <code>Start</code>
| 2026-01-13 08:00
|-
| <code>ScheduleItem.PlannedStop</code>
| <code>Stop</code>
| 2026-01-20 17:00
|-
| <code>ScheduleItem.Caption</code>
| <code>Text</code>
| Create mock-ups
|-
| <code>ScheduleItem.DisplayColor</code>
| <code>Color</code>
| An integer color value
|}

Expose all data that the control needs in the ViewModel. If a value is needed for a binding but does not need to be edited in the ordinary ViewModel user interface, it can still be present as a column for the control.
== Attach the Gantt UI override ==
Use the Gantt wrapper or UI override that is available in your solution, then connect it to the ViewModel that implements the contract.

# Add the Gantt custom-control override to the ViewModel UI.
# Verify that its tree binding is set to the list named <code>TreeNodes</code>.
# Verify that the row template uses <code>Column1</code> and <code>Column2</code>.
# Verify that the Gantt-row binding uses <code>TimeItems</code>.
# Verify that the time-item template uses <code>Start</code>, <code>Stop</code>, <code>Text</code>, and <code>Color</code>.
# Run the ViewModel with at least one top-level row and one time item. Confirm that the row appears in the tree and its time item appears in the timeline.

When the names and types match, changes to the bound data are reflected through WPF data binding. This lets users work with tree text and time items in the Gantt UI.
== Enable moving a time item to another row ==
To let a user move a time item from one Gantt row to another, provide an action on the time-item ViewModel item and a variable that identifies the destination row.

# Add an Action column named <code>MoveToNewRow</code> on the ViewModel item that represents a time item.
# Declare a ViewModel variable named <code>vNewRow</code>. Its type must be the class that represents a tree row, not the time-item class.
# In the action's execute expression, add the current time item to the destination row's time-item association.

For a model where the row class is <code>WorkItem</code> and its association to schedule items is named <code>ScheduleItems</code>, the action expression is:

<syntaxhighlight lang="ocl">
vNewRow.ScheduleItems.add(self)
</syntaxhighlight>

Here, <code>self</code> is the time item on which the action runs. Replace <code>ScheduleItems</code> with the actual association-end name from your model. The ViewModel contract still calls the displayed association <code>TimeItems</code>; the action expression must use the association name that exists on the object held by <code>vNewRow</code>.
== Test the finished control ==
Use this checklist before extending the control further:

* A top-level object appears in the <code>TreeNodes</code> tree.
* <code>Column1</code> and <code>Column2</code> display the expected row values.
* A child row appears under its parent through the row-level <code>TreeNodes</code> association.
* A time item with valid <code>Start</code> and <code>Stop</code> values appears on its row.
* The item shows its <code>Text</code> and uses its <code>Color</code> value.
* Moving an item selects or sets a destination in <code>vNewRow</code> and updates the destination row association through <code>MoveToNewRow</code>.

If rows appear but no bars appear, first check that <code>TimeItems</code> is exposed from the row and that every time item supplies <code>DateTime</code> values through the exact names <code>Start</code> and <code>Stop</code>. If bars appear but the tree is incomplete, check that every child level exposes the same <code>TreeNodes</code> contract.

If we follow these guidelines, we get data shown in the control – bound by WPF-databinding:[[File:Complex UI.png|link=http://wiki.mdriven.net/index.php/File:Complex%20UI.png|none|thumb|575x575px]]We can do things like select and move, resize, switch rows, edit texts in the tree, etc.
== Sample ==
For a downloadable interactive implementation, see the ''Gantt Chart Interactive'' example on [[Documentation:Complete model examples]]. The [[Documentation:Turnkey sample Board Map Balls Gantt]] page covers a separate Turnkey playground for HTML5 component development; it is not a replacement for this WPF binding contract.
== See also ==
* [[Documentation:Complete model examples]]
* [[Documentation:Turnkey sample Board Map Balls Gantt]]
* [[Documentation:Using Google Charts]]
* [[Documentation:Model Examples Old]]

[[Category:Advanced-Friendly]]
[[Category:Custom UI Controls and Overrides]]
[[Category:Desktop UI (WPF/WinForms)]]
[[Category:Priority 70]]
[[Category:UI & Styling]]