gantt — u_pbt_gantt #

← Component reference · Guide contents

gantt plans a project: on the left a grid of tasks (name, start, finish, duration, progress), on the right their bars on a time scale — day, week, month or quarter — with the line of today (in the accent colour) and the days off shaded. A task that holds others is a summary whose dates and progress are computed; a milestone is a one-day diamond; an arrow links a task to the one that waits for it, and the critical path is drawn in red. The user drags a bar to move it, its end edge to change its end, the small triangle under it for its progress; ue_task_moved, ue_task_resized and ue_progress_changed tell you. The plan is filled by hand or from a DataStore, which receives the changes.

▶ See it live — Demo application, Gantt chart tile: the preview, the code behind it and this page, side by side.

At a glance #

Quick start #

// A phase : the task that holds others becomes a summary
uo_plan.of_add_task(/*keys*/ "build", /*label*/ "Build", /*start*/ "2026-11-02", /*end*/ "2026-11-20")
uo_plan.of_add_task(/*keys*/ "build/design", /*label*/ "Design", /*start*/ "2026-11-02", /*end*/ "2026-11-06")
uo_plan.of_add_task(/*keys*/ "build/code", /*label*/ "Code", /*start*/ "2026-11-09", /*end*/ "2026-11-20")

// A milestone : an instant at the end of its day, here the day the code ends
uo_plan.of_add_milestone(/*keys*/ "golive", /*label*/ "Go-live", /*date*/ "2026-11-20")

// The links : a task starts once the one before it is finished
uo_plan.of_add_dependency(/*from_keys*/ "build/design", /*to_keys*/ "build/code")
uo_plan.of_add_dependency(/*from_keys*/ "build/code", /*to_keys*/ "golive")

// What is done already
uo_plan.of_task(/*keys*/ "build/design").id_progress = 100

// event ue_task_moved of uo_plan : (string as_keys, string as_start, string as_end, string as_old_start, string as_old_end)
// Local variables
string ls_code

// The code of the task : the LAST level of its address ("build/design" -> "design")
ls_code = this.of_task(/*keys*/ as_keys).of_key()

// Save the new dates of the task
UPDATE tasks SET start_date = :as_start, end_date = :as_end WHERE code = :ls_code;

Tasks, summaries and milestones #

A task is named by its address: its key under its parent, the levels joined by / — "build" at the top, "build/design" inside the task "build", added first. A task that holds others becomes a summary: a thin bar, its dates run from the first start to the last day of what it holds, its progress is their average weighted by the durations. Neither the user nor your code writes its dates or its progress: they are computed. Its chevron, a double click on its row or ib_collapsed fold it; ue_task_toggled follows.

Dates are whole days, yyyy-mm-dd, the end included: a task from the 6th to the 10th lasts five days, counted on the calendar. of_add_task and of_add_milestone also take two PowerBuilder date values. A milestone has no length: one day, a diamond, no progress. Through the handle of a task (of_task(address)), writing is_start moves it (its length stays), is_end changes its end, id_progress its progress; a value written by your code raises nothing, like SetItem. The same handle reads what the task is now: its dates, its length (of_duration), its place among its siblings counted from 1 (of_position), its level (of_level).

// The test starts three days later : it moves, its length stays
uo_plan.of_task(/*keys*/ "test").is_start = "2026-11-26"

// Read back what the summary computed
MessageBox("Build", uo_plan.of_task(/*keys*/ "build").is_end + " - " + String(uo_plan.of_task(/*keys*/ "build").id_progress) + " %")

Links and critical path #

of_add_dependency links two tasks with an arrow. The default type is finish-to-start (DEP_FS: the next one starts once the previous one is finished); DEP_SS (start-to-start), DEP_FF (finish-to-finish) and DEP_SF (start-to-finish) are given as a third argument. A link the dates break — the next one starts too early — is drawn dashed in the danger colour. A link to itself, between a task and what it holds, a link already there or a link that would close a loop is refused (-5). of_dependency_type reads the type of a link, of_predecessors and of_successors of the handle the linked tasks.

With ib_critical_path = true, the critical path is drawn in the danger colour: the tasks and links without float, the ones that push the end of the project if they slip by a day. of_is_critical of the handle reads it, whether the path is drawn or not. With ib_link_by_mouse = true, two dots appear on each side of the bar under the pointer: the user drags one onto another task, and ue_link_requested gives the link asked for — its type follows the dot it started from and the half of the target bar. The chart adds nothing by itself: of_add_dependency once your application agrees. A click on an arrow raises ue_dependency_clicked. The float is counted in working days (is_work_days): a task that ends on a Friday followed by one that starts on the Monday has none. A milestone is an instant at the end of its day: set on the day the task it follows ends, the link holds, and the task after it starts the next day. A link that touches a summary binds the tasks it holds; a summary is never marked, and an arrow is red only between two red bars. A finished task (100 %) is never marked: it drives nothing any more. is_project_end counts the float up to a deadline instead of the last finish.

Calendar: holidays, lags, markers and delays #

A project follows a calendar. is_work_days gives the working days of the week; of_add_holiday adds a public holiday, one by one — shaded like a week-end, named in the tooltip of its day at the day scale, it counts neither in the float of the critical path nor in a lag. A link may carry a lag in working days: of_add_dependency("design", "build", DEP_FS, 2) leaves two working days between the end of one and the start of the other (a drying time, a delivery); negative, it is a lead. The rule of the arrow and the critical path count it, of_dependency_lag reads it back, a DataStore writes it after the type ("12:fs+2"). of_add_marker draws a vertical marker at the end of a day — a contractual deadline, the end of a sprint — with its label at the top. Last, with ib_show_late = true, a late task — its last day is past (is_today) and it is not finished — is drawn in amber, hatched; of_is_late() of its handle and the {late} field of the templates say it either way.

// The public holidays of the year : days off, never float
uo_plan.of_add_holiday(/*date*/ "2026-11-11", /*label*/ "Armistice Day")
uo_plan.of_add_holiday(/*date*/ "2026-12-25", /*label*/ "Christmas")

// The paint dries two working days before the second coat
uo_plan.of_add_dependency(/*from_keys*/ "paint", /*to_keys*/ "second_coat", /*type*/ u_pbt_gantt.DEP_FS, /*lag*/ 2)

// The contractual deadline, in red
uo_plan.of_add_marker(/*key*/ "deadline", /*date*/ "2026-12-18", /*label*/ "Contract", /*color*/ RGB(/*red*/ 196, /*green*/ 43, /*blue*/ 28))

// The tasks behind schedule, in amber
uo_plan.ib_show_late = true

What the user changes #

The user drags a bar to move the task, by whole days (ue_task_moved), its end edge to change its end (ue_task_resized), the small triangle under the bar for its progress (ue_progress_changed); a bubble shows the dates or the percentage while dragging, Escape cancels. With the keyboard, Ctrl + Left / Right moves the selected task by a day and Ctrl + Shift + Left / Right changes its end. The events arrive with the task already in place. Only a gesture raises them: a date written by your code is silent, like SetItem. A summary cannot be dragged, nor can an ib_read_only task or chart.

With ib_veto_changes = true, ue_task_changing is asked before each of these three changes, with the dates and the progress the task would take: returning FALSE leaves it as it was. Delete on the selected task raises ue_delete_requested: the chart removes nothing, of_remove_task once your application agrees.

Scale, grid and layout #

The scale (is_scale) is chosen in the toolbar (ib_toolbar, with the Today button), with Ctrl + wheel — the day under the pointer stays under the pointer — or by your code; ue_scale_changed follows. At the day and week scales, the days off (is_work_days) are shaded. The grid shows the columns of is_columns, in their order, its dates written by is_date_format; the user drags the line between grid and chart (ii_grid_width) and the edge of a column header for its width. What he arranged — the scale, the widths, the folded summaries — is read by of_get_layout, given back by of_set_layout, and every change raises ue_layout_changed with the whole layout: store it, give it back at the next start.

The text of the bars and tooltips #

The text beside each bar is written by a template, is_bar_template ("{label}" by default, empty for none), and the tooltip of a bar by is_tooltip_title_template and is_tooltip_template: rich text markup where {owner} is a field of the task — one of yours (of_set_field), a column of the DataStore it came from, or a built-in field (label, key, keys, start, end, duration, days, progress, percent, milestone, summary, critical, late, level, parent). {end:d mmm} writes a date with the tokens d dd ddd dddd m mm mmm mmmm yy yyyy, {?owner}…{/owner} keeps a piece when the field says something, {!owner}…{/owner} when it says nothing, {x:raw} keeps a value as markup, {{ }} are braces. {label} and {parent} are markup, as in the grid; any other value is shown as it is, never read as markup. A built-in field name is never yours: of_set_field refuses it, and a DataStore column named like it is hidden by it. A task with a tooltip of its own (is_tooltip of its handle) shows that one instead.

// Who does what : a field of our own on a task
uo_plan.of_set_field(/*keys*/ "build/design", /*field*/ "owner", /*value*/ "Ada")

// Beside each bar : the label, the owner when there is one, the end day
uo_plan.is_bar_template = "{label}{?owner} - [b]{owner}[/b]{/owner} [symbol=calendar] {end:d mmm}"

From a DataStore #

of_from_datastore makes one task of each row. Its key is the value of the ROLE_KEY column — an id — or, without it, the RowID of the row; the ROLE_PARENT column names the key of the task that holds it (empty: at the top; a parent not found or a loop puts the row at the top). A column plays a role when it is named like it (key, parent, label, start, end, progress, milestone, color, predecessors) or when of_map says so. ROLE_MILESTONE makes a milestone of any value that says yes; ROLE_COLOR colours the bar (a PowerBuilder RGB() or #rrggbb); ROLE_PREDECESSORS lists the tasks waited for, their keys separated by commas, the type after : when it is not finish-to-start: "12, 14:ss". Dates are read in the regional order of the workstation. Every column is a field of the templates. The tasks of an earlier load leave (their handles are freed), those added by hand stay. Two rows with one key: the second becomes key~RowID; a key holding a / or a | takes the RowID, and its children still find it by its value; a key a task added by hand already holds becomes key~RowID, under the same parent — no row is ever left out. A row whose start is empty is a task not scheduled: the grid says it, it has no bar and no gesture moves it. Dates and decimals are read whatever the regional settings (12,5 is 12.5). of_from_datastore also takes a DataWindow or a DataWindowChild: the rows the user sees beside the chart, written back there. After a Reset or a Retrieve of the DataStore, give it again: its RowIDs start over.

With ib_write_back = true, a gesture writes into the row before its event: the start and end dates for a move or a new end, the progress for the triangle — each value in the type of its column. The event reads the DataStore up to date, the Update stays yours. A value the DataStore refuses puts the task back as it was, and what was already written too, and raises ue_write_back_failed instead of the event of the gesture. After changing a row yourself, of_reload_row sends it to the chart again; a row inserted since arrives too. A task you remove (of_remove_task) stays out until the next of_from_datastore: of_map and the reload of another row do not bring it back, of_reload_row of its own row does. After of_clear, of_reload_row refuses (-5) until a new load.

// Which column of the DataStore plays which role
uo_plan.of_map(/*role*/ u_pbt_gantt.ROLE_KEY, /*column*/ "id")
uo_plan.of_map(/*role*/ u_pbt_gantt.ROLE_PARENT, /*column*/ "parent_id")
uo_plan.of_map(/*role*/ u_pbt_gantt.ROLE_START, /*column*/ "start_date")
uo_plan.of_map(/*role*/ u_pbt_gantt.ROLE_END, /*column*/ "end_date")
uo_plan.of_map(/*role*/ u_pbt_gantt.ROLE_PREDECESSORS, /*column*/ "after")

// A change goes into the DataStore, then the rows become tasks
uo_plan.ib_write_back = true
uo_plan.of_from_datastore(/*ads*/ ids_tasks)

Properties #

Properties of a task — n_pbt_gantt_task #

Its handle, through of_task(address). A read asks the chart what the task is now; a value written is silent, like SetItem; ib_collapsed is an order and raises ue_task_toggled. Its of_count() counts the tasks it holds and its of_keys_at(n) returns the address of the n-th.

Constants #

Methods #

Events #

Keyboard and mouse #

• Dragging a bar moves it by whole days, its end edge changes its end, the small triangle under it its progress; a bubble shows the dates or the percentage, Escape cancels.
• Up / Down: the task above, below; Home / End: the first one, the last one; Page Up / Page Down: a page higher, lower. The view follows the selected task.
• Right opens a folded summary, then goes down to its first task; Left folds an open summary, then goes up to its parent. Read right to left, Left and Right swap.
• Ctrl + Left / Right moves the task by a day, Ctrl + Shift + Left / Right changes its end by a day.
• Enter or a double click opens the task, Delete asks to delete it, a right click or the Menu key (Shift + F10): ue_task_rclicked. A double click on the row of a summary folds or opens it.
• Ctrl + wheel changes the scale, the day under the pointer staying in place; the wheel over the grid scrolls the chart.
• Dragging the line between grid and chart changes the width of the grid, dragging the edge of a header that of its column.
• The chart is one Tab stop, the line between grid and chart a second one: Left / Right move it by 10 px (Shift: 50), Home hides the grid.
• Alt + Left / Right scrolls the time, the selection stays; a click in the empty part of a line of the chart selects its task.
• Near an edge, during a drag, the chart scrolls by itself: along the time for a bar, up or down for a link.
• The toolbar is one Tab stop: Left / Right go from button to button, Enter or Space presses it. In the chart, Ctrl + Plus / Minus changes the scale, Ctrl + Home brings today into view, Ctrl + Up / Down changes the progress of the task by 10 points.
• While a link is drawn, the bar it would reach is ringed, a thick edge on the side it would hold; a link already there or one that would close a loop is ringed in grey and is not asked for.

Examples #

Planning rules #

// Once, after the plan is built : ask before each change of the user
uo_plan.ib_veto_changes = true

// event ue_task_changing of uo_plan : nothing ends after the go-live
if as_keys <> "golive" and as_end > this.of_task(/*keys*/ "golive").is_start then return false

// and nothing moves into the past : a task already started keeps its start
if as_start < String(Today(), "yyyy-mm-dd") and as_start < this.of_task(/*keys*/ as_keys).is_start then return false
return true

Links drawn with the mouse #

// Once : two dots beside the bar under the pointer, the critical path in red
uo_plan.ib_link_by_mouse = true
uo_plan.ib_critical_path = true

// event ue_link_requested of uo_plan : the chart adds nothing by itself
if this.of_add_dependency(/*from_keys*/ as_from_keys, /*to_keys*/ as_to_keys, /*type*/ as_type) = -5 then
	MessageBox("Plan", "This link cannot be added.")
end if

// event ue_dependency_clicked of uo_plan : a click on an arrow removes it
this.of_remove_dependency(/*from_keys*/ as_from_keys, /*to_keys*/ as_to_keys)

Finding the layout again at the next start #

// The layout stored at the last start, if any
uo_plan.of_set_layout(/*layout_json*/ ProfileString(gs_ini, "plan", "layout", ""))

// event ue_layout_changed of uo_plan : store every change
SetProfileString(gs_ini, "plan", "layout", as_layout_json)

Opening a task in your window #

// event ue_task_opened of uo_plan
// Local variables
long ll_row

// The row of the task in the DataStore, whatever key the task had to take
ll_row = this.of_task(/*keys*/ as_keys).of_row()

// A task added by hand has no row
if ll_row = 0 then return

// Edited in your window, then the task follows its row
OpenWithParm(w_task_edit, ll_row)
this.of_reload_row(/*row*/ ll_row)

Good practice #

• Phases as summaries: two or three levels are enough, the user folds what he does not follow.
• Links rather than copied dates: a link the dates break shows, a copied date goes wrong silently.
• The critical path switched on when a date must be kept: it shows where a day late costs the project a day.
• Save in ue_task_moved (or let ib_write_back write the DataStore): the chart shows the new schedule before the database knows it.
• Give the layout back (ue_layout_changed, of_set_layout): the scale and widths the user chose are his.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents