windowsforms-404339-controls-and-libraries-gantt-control-timeline.md
The WinForms Gantt Control ships with an integrated Timeline.
Use the OptionsTimeline.TimelinePosition property to display a timeline at the top or bottom of the Gantt control. Set the TimelinePosition property to TimelinePosition.None to hide the timeline.
// Displays a timeline at the top of the Gantt control.
ganttControl1.OptionsTimeline.TimelinePosition = DevExpress.XtraGantt.TimelinePosition.Top;
' Displays a timeline at the top of the Gantt control.
ganttControl1.OptionsTimeline.TimelinePosition = DevExpress.XtraGantt.TimelinePosition.Top
The following image shows timeline UI elements:
Use the GanttControl.OptionsTimeline property to access and customize the timeline settings.
| Property Name | Description |
|---|---|
| TimelinePosition | Specifies the visibility and position of a timeline. |
| AllowResize | Specifies whether the height of a timeline can be changed by a user or in code. |
| TimelineHeight | Specifies the height of a timeline, in pixels. |
| ShowTodayIndicator | Specifies whether to display the Today indicator. |
| MinUnit | Specifies the minimum time interval that corresponds to a unit of measure on the time scale. |
| MaxUnit | Specifies the maximum time interval that corresponds to a unit of measure on the time scale. |
The timeline can display multiple timeline bars (TimelineBar). Use the GanttControl.TimelineBars property to access a collection of timeline bars displayed on the timeline.
Use the GanttControl.AddTimelineBar and GanttControl.RemoveTimelineBar methods to add/remove timeline bars to/from the collection.
using DevExpress.XtraGantt;
using DevExpress.XtraGantt.TimeLine;
// Creates a timeline bar and displays it on the timeline.
TimelineBar timelineBar = ganttControl1.AddTimelineBar();
// Displays the focused task on the timeline bar.
timelineBar.AddTask(ganttControl1.FocusedNode as GanttControlNode);
Imports DevExpress.XtraGantt
Imports DevExpress.XtraGantt.TimeLine
' Creates a timeline bar and displays it on the timeline.
Private timelineBar As TimelineBar = ganttControl1.AddTimelineBar()
' Displays the focused task on the timeline bar.
timelineBar.AddTask(TryCast(ganttControl1.FocusedNode, GanttControlNode))
Use the timeline bar’s Nodes property to access its tasks. The following methods allow you to manage the TimelineBar.Nodes collection:
Tip
Use the FocusedTimelineBar property to get or set the focused timeline bar.
The following example demonstrates how to create a timeline bar, display and focus it on the timeline.
TimelineBar timelineBar = ganttControl1.AddTimelineBar();
ganttControl1.FocusedTimelineBar = timelineBar;
Dim timelineBar As TimelineBar = ganttControl1.AddTimelineBar()
ganttControl1.FocusedTimelineBar = timelineBar
The following table lists APIs that allow you to customize a date range of the timeline:
The date range of timeline bars matches the duration of the project. Use the TimelineBar.Options.StartDate and TimelineBar.Options.FinishDate properties to specify a custom date range.
You can also use the Gantt control’s SetTimelineBarRange method to specify a custom date range for a specific timeline bar.
Tip
Ctrl and use the mouse wheel to change the visible date range.Use the AllowResize property to specify whether the height of a timeline can be changed by a user or in code. The TimelineHeight property specifies the height of the timeline, in pixels.
The following example demonstrates how to specify and lock a custom timeline height:
// Specifies the height of a timeline, in pixels.
ganttControl1.OptionsTimeline.TimelineHeight = 250;
// Locks the height of a timeline.
ganttControl1.OptionsTimeline.AllowResize = false;
' Specifies the height of a timeline, in pixels.
ganttControl1.OptionsTimeline.TimelineHeight = 250
' Locks the height of a timeline.
ganttControl1.OptionsTimeline.AllowResize = False
The Gantt control raises the TimelineSplitterPositionChanging event before the timeline height is changed by a user and allows you to cancel the action. The TimelineSplitterPositionChanged event is raised after the height of the timeline was changed.
The following example demonstrates how to allow a user to resize the timeline within the specified range:
using System;
using DevExpress.XtraGantt;
using DevExpress.XtraGantt.TimeLine;
// Unlocks the timeline.
ganttControl1.OptionsTimeline.AllowResize = true;
ganttControl1.TimelineSplitterPositionChanging += GanttControl1_TimelineSplitterPositionChanging;
private void GanttControl1_TimelineSplitterPositionChanging(object sender, SplitterPositionChangingEventArgs e) {
e.Cancel = (int)e.NewValue <= 150 || (int)e.NewValue >= 300;
}
Imports System
Imports DevExpress.XtraGantt
Imports DevExpress.XtraGantt.TimeLine
' Unlocks the timeline.
Private Sub GanttControl1_TimelineSplitterPositionChanging(ByVal sender As Object, ByVal e As SplitterPositionChangingEventArgs)
e.Cancel = CInt(Math.Truncate(e.NewValue)) <= 150 OrElse CInt(Math.Truncate(e.NewValue)) >= 300
End Sub
Note
The Gantt control does not raise the TimelineSplitterPositionChanging and TimelineSplitterPositionChanged events when changing the value of the TimelineHeight property.
End user options include:
Use the following properties to map fields in a data source to task properties:
The following example demonstrates how to specify timeline mappings:
public Form1() {
InitializeComponent();
// Bind the Gantt control to a data source.
ganttControl1.DataSource = TaskData.InitData();
// Configures the Gantt control's mappings.
ganttControl1.TreeListMappings.KeyFieldName = "Id";
ganttControl1.TreeListMappings.ParentFieldName = "ParentId";
ganttControl1.ChartMappings.StartDateFieldName = "StartDate";
ganttControl1.ChartMappings.FinishDateFieldName = "EndDate";
ganttControl1.ChartMappings.TimelineCaption = "TimelineCaption";
// Maps the Gantt control to a field in a data source with Boolean values that
// specify which tasks to display on the timeline when the application starts.
ganttControl1.ChartMappings.VisibleInTimelineFieldName = "ShowInTimeline";
// Displays the timeline at the top of the Gantt control.
ganttControl1.OptionsTimeline.TimelinePosition = DevExpress.XtraGantt.TimelinePosition.Top;
}
public class TaskData {
public TaskData(int id) {
this.id = id;
}
int id;
public int Id {
get { return id; }
}
public string TimelineCaption {
get { return string.Format("Timeline Caption: {0}", Name); }
}
public bool ShowInTimeline { get; set; } = false;
public int ParentId { get; set; }
public string Name { get; set; }
public DateTime StartDate { get; set; }
public DateTime EndDate { get; set; }
public static List<TaskData> InitData() {
return new List<TaskData>() {
new TaskData(0){ Name = "Task A", ParentId = 0, StartDate = new DateTime(2023, 3, 1), EndDate = new DateTime(2024, 3, 31) },
new TaskData(1){ Name = "Task B", ParentId = 0, StartDate = new DateTime(2023, 3, 1), EndDate = new DateTime(2023, 7, 1), ShowInTimeline = true },
new TaskData(2){ Name = "Task C", ParentId = 0, StartDate = new DateTime(2023, 7, 1), EndDate = new DateTime(2023, 11, 1) },
new TaskData(3){ Name = "Task D", ParentId = 0, StartDate = new DateTime(2023, 11, 1), EndDate = new DateTime(2024, 3, 31) },
};
}
}
Public Sub New()
InitializeComponent()
' Binds the Gantt control to a data source.
ganttControl1.DataSource = TaskData.InitData()
' Configures the Gantt control's mappings.
ganttControl1.TreeListMappings.KeyFieldName = "Id"
ganttControl1.TreeListMappings.ParentFieldName = "ParentId"
ganttControl1.ChartMappings.StartDateFieldName = "StartDate"
ganttControl1.ChartMappings.FinishDateFieldName = "EndDate"
ganttControl1.ChartMappings.TimelineCaption = "TimelineCaption"
' Maps the Gantt control to a field in a data source with Boolean values that
' specify which tasks to display on the timeline when the application starts.
ganttControl1.ChartMappings.VisibleInTimelineFieldName = "ShowInTimeline"
' Displays the timeline at the top of the Gantt control.
ganttControl1.OptionsTimeline.TimelinePosition = DevExpress.XtraGantt.TimelinePosition.Top
End Sub
Public Class TaskData
Public Sub New(ByVal id As Integer)
Me.id_Renamed = id
End Sub
'INSTANT VB NOTE: The variable id was renamed since Visual Basic does not allow variables and other class members to have the same name:
Private id_Renamed As Integer
Public ReadOnly Property Id() As Integer
Get
Return id_Renamed
End Get
End Property
Public ReadOnly Property TimelineCaption() As String
Get
Return String.Format("Timeline Caption: {0}", Name)
End Get
End Property
Public Property ShowInTimeline() As Boolean
= False
public Integer ParentId {get;set;}
public String Name {get;set;}
public DateTime StartDate {get;set;}
public DateTime EndDate {get;set;}
public static List(Of TaskData) InitData()
Return New List(Of TaskData)() From {
New TaskData(0) With {.Name = "Task A", .ParentId = 0, .StartDate = New Date(2023, 3, 1), .EndDate = New Date(2024, 3, 31)},
New TaskData(1) With {.Name = "Task B", .ParentId = 0, .StartDate = New Date(2023, 3, 1), .EndDate = New Date(2023, 7, 1), .ShowInTimeline = True},
New TaskData(2) With {.Name = "Task C", .ParentId = 0, .StartDate = New Date(2023, 7, 1), .EndDate = New Date(2023, 11, 1)},
New TaskData(3) With {.Name = "Task D", .ParentId = 0, .StartDate = New Date(2023, 11, 1), .EndDate = New Date(2024, 3, 31)}
}
End Class
The Gantt control ships with an integrated context menu that allows a user to display and hide tasks on/from the timeline.
Use the following methods to display and hide tasks on/from a timeline:
The following example demonstrates how to display tasks on the timeline:
// Displays the focused task on the focused timeline bar.
ganttControl1.AddTaskToTimeline(ganttControl1.FocusedNode as GanttControlNode);
// Displays the focused task on the first timeline bar.
ganttControl1.AddTaskToTimeline(ganttControl1.FocusedNode as GanttControlNode, ganttControl1.TimelineBars[0]);
' Displays the focused task on the focused timeline bar.
ganttControl1.AddTaskToTimeline(TryCast(ganttControl1.FocusedNode, GanttControlNode))
' Displays the focused task on the first timeline bar.
ganttControl1.AddTaskToTimeline(TryCast(ganttControl1.FocusedNode, GanttControlNode), ganttControl1.TimelineBars(0))
Tip
Ctrl key to select the task.The Gantt control fires the CustomTimelineItemText event for each task displayed on the timeline and allows you to change its caption and details based on a condition. Use the e.Caption and e.Details event properties to specify the caption and details of a task. The e.Task property returns the task.
Read the following topic for detailed information and example: CustomTimelineItemText.
Handle the following events to paint timeline bars and tasks displayed on the timeline:
The Gantt control exports and prints a timeline if it is displayed.