Timeline

• Mar 23, 2023
• 8 minutes to read

The WinForms Gantt Control ships with an integrated Timeline.

Run Demo: Timeline

Display 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.

C#

// Displays a timeline at the top of the Gantt control.
ganttControl1.OptionsTimeline.TimelinePosition = DevExpress.XtraGantt.TimelinePosition.Top;

VB.NET

' Displays a timeline at the top of the Gantt control.
ganttControl1.OptionsTimeline.TimelinePosition = DevExpress.XtraGantt.TimelinePosition.Top

Timeline UI and Settings

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.

Timeline Bars

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.

C#

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);

VB.NET

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:

• AddTask
• RemoveTask
• RemoveSelectedTasks()
• ClearTasks()

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.

C#

TimelineBar timelineBar = ganttControl1.AddTimelineBar();
ganttControl1.FocusedTimelineBar = timelineBar;

VB.NET

Dim timelineBar As TimelineBar = ganttControl1.AddTimelineBar()
ganttControl1.FocusedTimelineBar = timelineBar

Date Range

The following table lists APIs that allow you to customize a date range of the timeline:

• GetTimelineStartDate()
• GetTimelineFinishDate()
• SetTimelineVisibleRange

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

• Users can hold Ctrl and use the mouse wheel to change the visible date range.
• Users can use a context menu to specify a custom date range for the focused timeline bar.

Timeline Height

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:

C#

// Specifies the height of a timeline, in pixels.
ganttControl1.OptionsTimeline.TimelineHeight = 250;
// Locks the height of a timeline.
ganttControl1.OptionsTimeline.AllowResize = false;

VB.NET

' 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:

C#

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;
}

VB.NET

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.

Timeline UX

End user options include:

• Add/Remove Tasks and Milestones to/from Timeline
• Add/Remove Timeline Bars
• Select Multiple Tasks
• Go to Task
• Zoom In and Out Timeline Scale
• Select Time Range
• Resize Timeline

Bind to Data

Use the following properties to map fields in a data source to task properties:

• TimelineCaption - Specifies the name of a field in the data source, with string values ​​that specify the captions of tasks on the timeline.
• VisibleInTimelineFieldName - Specifies the name of a field in the data source, with Boolean values that specify which tasks to display on the timeline.

The following example demonstrates how to specify timeline mappings:

C#

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) },
        };
    }
}

VB.NET

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

Display and Hide Tasks on/from the Timeline

End User Capabilities

The Gantt control ships with an integrated context menu that allows a user to display and hide tasks on/from the timeline.

Manage Tasks in Code

Use the following methods to display and hide tasks on/from a timeline:

• GanttControl.AddTaskToTimeline
• GanttControl.RemoveTaskFromTimeline
• TimelineBar.AddTask
• TimelineBar.RemoveTask
• TimelineBar.RemoveSelectedTask
• TimelineBar.ClearTasks

The following example demonstrates how to display tasks on the timeline:

C#

// 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]);

VB.NET

' 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

• Use the TimelineBar.Nodes property to get a collection of tasks displayed on a timeline bar.
• Users can select tasks on the timeline. Click on a task and hold down the Ctrl key to select the task.

Customize Tasks Displayed on the Timeline

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.

Custom Draw API

Handle the following events to paint timeline bars and tasks displayed on the timeline:

• CustomDrawTimelineBar
• CustomDrawTimelineTask

Print and Export Timeline

The Gantt control exports and prints a timeline if it is displayed.