Gantt Task Definitions

Gantt task definitions describe how rows from a source table are mapped to tasks displayed on a Gantt timeline. They specify which fields provide task identifiers, time ranges, display labels, and optional behavioural information such as drag-and-drop or tooltips.

The following task definition types are available:

  • GanttTaskDefinition — defines a standard, flat mapping where each table row corresponds to a single task on the timeline.

  • CategoryGanttTaskDefinition — extends the base definition to support category-based grouping, allowing multiple tasks to appear under the same category row.

  • TreeGridGanttTaskDefinition — defines hierarchical relationships between tasks, enabling parent–child structures in tree-grid Gantt views.

class GanttTaskDefinition(id_field, display_name_field=None, drag_drop_x_source_field=None, on_click_source_field=None)[source]

Bases: Buildable

Defines the field mappings and configuration for Gantt chart tasks.

Maps source data fields to task properties such as ID, dates, display names, colors, drag behavior, and visual styling. This class serves as the central configuration for how task data is interpreted and displayed in the Gantt chart.

id_field

Field ID for the unique task identifier.

name_field

Field ID for the category name (tree-grid only).

start_date_source_field

Field ID for the task start date.

end_date_source_field

Field ID for the task end date.

break_start_date_source_field

Field ID for break period start.

break_end_date_source_field

Field ID for break period end.

display_name_field

Field ID for the task display name.

parent_field

Field ID for the parent task ID (tree-grid only).

color_source_field

Field ID for the task color.

border_color_source_field

Field ID for the task border color.

drag_drop_x_source_field

Field ID for drag-drop enabled flag.

on_click_source_field

Field ID for click event handler key.

opacity_source_field

Field ID for task opacity.

pattern_source_field

Field ID for visual pattern name.

font_properties

Font styling configuration for task text.

icon_properties

Icon configuration for task visualization.

dependencies

Task dependency configuration.

drag_drop_handle_behaviour_source_field

Field ID for drag handle behavior.

tooltip_properties_source_field

Field for tooltip property definition key.

__init__(id_field, display_name_field=None, drag_drop_x_source_field=None, on_click_source_field=None)[source]

Initialize a GanttTaskDefinition instance.

Parameters:

  • id_field (Field) – Field containing unique task identifiers.

  • display_name_field (Field | None) – Field containing the task display name.

  • drag_drop_x_source_field (Field | None) – Field containing boolean flag for drag-drop (must be BOOLEAN type).

  • on_click_source_field (Field | None) – Field containing click event handler key.

Raises:

ValueError – If validated fields are not of the required data type.

name_field: str | None
parent_field: str | None
start_date_source_field: str | None
end_date_source_field: str | None
break_start_date_source_field: str | None
break_end_date_source_field: str | None
color_source_field: str | None
border_color_source_field: str | None
drag_drop_x_source_field: str | None
on_click_source_field: str | None
opacity_source_field: str | None
pattern_source_field: str | None
font_properties: FontProperties | None
icon_properties: IconProperties | None
dependencies: Dependencies | None
drag_drop_handle_behaviour_source_field: str | None
tooltip_properties_source_field: str | None
set_opacity_source_field(field)[source]

Sets the field providing opacity values for tasks.

Return type:

GanttTaskDefinition

set_pattern_source_field(field)[source]

Sets the field providing visual pattern identifiers for tasks.

Return type:

GanttTaskDefinition

set_drag_drop_handle_behaviour_source_field(field)[source]

Sets the field providing drag handle behaviour (must be STRING type).

Return type:

GanttTaskDefinition

set_tooltip_properties_source_field(field)[source]

Sets the field identifying which tooltip definition to use.

Return type:

GanttTaskDefinition

set_date_source_fields(start, end)[source]

Configure the start and end date fields for tasks.

Validates that provided fields are of DATE and DATETIME type before setting them as the source fields for task time ranges.

Parameters:

  • start (Field | None) – Field containing the task start date.

  • end (Field | None) – Field containing the task end date.

Raises:

ValueError – If either field is not DATE or DATETIME type.

Return type:

GanttTaskDefinition

set_break_date_source_fields(start, end)[source]

Configure the break period date fields for tasks.

Defines fields that specify a break or pause period within a task’s timeline. Validates that provided fields are of DATE or DATETIME type.

Parameters:

  • start (Field | None) – Field containing the break period start date.

  • end (Field | None) – Field containing the break period end date.

Raises:

ValueError – If either field is not DATE or DATETIME type.

Return type:

GanttTaskDefinition

set_colour_source_field(colour, border_colour)[source]

Configure the colour fields for task visual styling.

Sets the fields that determine the fill colour and border colour for task bars in the Gantt chart.

Parameters:

  • colour (Field | None) – Field containing the task fill colour value.

  • border_colour (Field | None) – Field containing the task border colour value.

Return type:

GanttTaskDefinition

set_font_properties(font_color_source_field=None, font_weight_source_field=None, font_style_source_field=None)[source]

Configure font styling properties for task text.

Creates and assigns a FontProperties object that maps fields to font styling attributes.

Parameters:

  • font_color_source_field (Field | None) – Field containing the text color.

  • font_weight_source_field (Field | None) – Field containing the font weight.

  • font_style_source_field (Field | None) – Field containing the font style.

Return type:

FontProperties

Returns:

The created FontProperties instance.

set_icon_properties(icon_source_source_field=None, icon_color_source_field=None)[source]

Configure icon properties for task visualization.

Creates and assigns an IconProperties object that maps fields to icon attributes for displaying icons on tasks.

Parameters:

  • icon_source_source_field (Field | None) – Field containing the icon identifier.

  • icon_color_source_field (Field | None) – Field containing the icon color.

Return type:

IconProperties

Returns:

The created IconProperties instance.

set_dependencies(point_ids_source_field)[source]

Configure task dependency relationships.

Creates and assigns a Dependencies object that maps a field to an array of task IDs representing dependency relationships.

Parameters:

point_ids_source_field (Field) – Field containing an array of dependent task IDs (must be STRING_ARRAY type).

Return type:

Dependencies

Returns:

The created Dependencies instance.

Raises:

ValueError – If the field is not of STRING_ARRAY type.

class CategoryGanttTaskDefinition(id_field, display_name_field=None, drag_drop_x_source_field=None, on_click_source_field=None)[source]

Bases: GanttTaskDefinition

Defines a category-based Gantt task configuration.

This class extends class GanttTaskDefinition to describe how tasks should be interpreted and rendered in a category-style Gantt view. It primarily maps table fields to task-level behaviours and visual properties such as drag-and-drop behaviour, click handling, opacity, and tooltip configuration.

Note

This definition is intended for category-based Gantt views and does not introduce additional task hierarchy fields beyond those defined in the base class GanttTaskDefinition.

class TreeGridGanttTaskDefinition(id_field, display_name_field=None, drag_drop_x_source_field=None, on_click_source_field=None)[source]

Bases: GanttTaskDefinition

Specialized task definition for tree-grid Gantt views with hierarchical support.

Extends GanttTaskDefinition to provide tree-grid specific functionality, including parent-child task relationships and category grouping. This allows tasks to be organized in a hierarchical tree structure.

Inherits all attributes from GanttTaskDefinition.

set_name_field(field)[source]

Set the category name field for tree-grid Gantt views.

This field is used to group multiple tasks on the same row when they share the same category and parent ID value. Only applicable to tree-grid type Gantt charts.

Parameters:

field (Field) – The field containing the category name.

Return type:

TreeGridGanttTaskDefinition

set_parent_field(field)[source]

Set the parent task ID field for hierarchical task relationships.

Defines the field containing the parent task identifier, enabling tree-like task hierarchies. Only applicable to tree-grid type Gantt charts.

Parameters:

field (Field) – The field containing the parent task ID.

Return type:

TreeGridGanttTaskDefinition