Skip to main content
All docs
V24.1

Timeline

  • 8 minutes to read

The WinForms Gantt Control ships with an integrated Timeline.

Timeline - WinForms Gantt Control, DevExpress

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.

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

Timeline UI - WinForms Gantt Control, DevExpress

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.

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

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;

Date Range

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

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

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

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:

Chart Mappings - WinForms Gantt Timeline

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

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.

Display and Hide Tasks - WinForms Gantt Timeline

Manage Tasks in Code

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

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:

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