Table of Contents

TMS FNC Gantt Chart Database Adapter — Guides

TTMSFNCGanttChartDatabaseAdapter connects a Gantt chart to a TDataSet by mapping dataset fields to task properties. It loads dataset records into the chart's project as tasks, and — when the user edits tasks interactively — writes the changes back to the dataset. Use it when the schedule lives in a database table or query rather than being built in code, so the chart becomes a live view of your data. This guide covers wiring the adapter, mapping fields, activating and reloading the binding, and customizing the mapping with events.

Wiring the adapter

The chart consumes tasks through its Adapter property; the adapter reads its records from a TDataSource set on Item.DataSource. Map each task property to a dataset field name through the adapter's Item, then set Active := True:

procedure TForm1.ConnectAdapter;
begin
  // The chart consumes tasks through its Adapter; the adapter reads a dataset.
  GanttChart1.Adapter := GanttChartDatabaseAdapter1;

  // The data source is a TDataSource, not the dataset directly.
  GanttChartDatabaseAdapter1.Item.DataSource := DataSource1;
  GanttChartDatabaseAdapter1.Item.AutoIncrementDBKey := False;

  // Map dataset field names to task properties.
  GanttChartDatabaseAdapter1.Item.DBKey := 'Id';
  GanttChartDatabaseAdapter1.Item.WBS := 'Wbs';
  GanttChartDatabaseAdapter1.Item.TaskName := 'Name';
  GanttChartDatabaseAdapter1.Item.Description := 'Description';
  GanttChartDatabaseAdapter1.Item.PlannedStart := 'PlannedStart';
  GanttChartDatabaseAdapter1.Item.PlannedEnd := 'PlannedEnd';
  GanttChartDatabaseAdapter1.Item.Duration := 'Duration';
  GanttChartDatabaseAdapter1.Item.Dependencies := 'Dependencies';
  GanttChartDatabaseAdapter1.Item.Progress := 'Progress';
  GanttChartDatabaseAdapter1.Item.StateName := 'Statename';

  // Activate the binding; the chart's tasks now reflect the dataset.
  GanttChartDatabaseAdapter1.Active := True;
end;

procedure TForm1.DisconnectAdapter;
begin
  GanttChartDatabaseAdapter1.Active := False;
end;
Note

Assign the chart with GanttChart1.Adapter := GanttChartDatabaseAdapter1. The field mappings live on the adapter's Item sub-object, and Item.DataSource takes a TDataSource — not the dataset component directly.

Field mapping

Each property on Item holds the name of the dataset field that supplies (and receives) that task value:

Item property Maps to task Typical field
WBS Work-breakdown position Wbs
TaskName Name Name
Description Description Description
PlannedStart PlannedStart PlannedStart
PlannedEnd PlannedEnd PlannedEnd
Duration PlannedDuration Duration
Dependencies TaskDependencies (serialized) Dependencies
Progress Progress Progress
StateName TaskStateName Statename
WorkTimePolicy WorkTimePolicy UseWorkingHours
IsEventMarker IsEventMarker —
DBKey persistent row key Id

AutoIncrementDBKey controls whether the adapter generates a key for new tasks that lack one. The adapter's EndType (aetPlannedEnd or aetDuration) selects whether a task's end comes from the planned-end field or the duration field — map whichever your table stores.

Loading and saving

Activating the adapter (Active := True) loads the dataset into tasks. After that, LoadTasks re-reads the dataset and SaveTasks writes task edits back. Set Active := False before making structural dataset changes to avoid a partial load:

procedure TForm1.PersistEdits;
begin
  // Push task changes made in the chart back into the bound dataset.
  GanttChartDatabaseAdapter1.SaveTasks;
end;

procedure TForm1.ReloadTasks;
begin
  // Re-read every task from the dataset (e.g. after an external change).
  GanttChartDatabaseAdapter1.LoadTasks;
end;

// Custom read mapping: derive progress from a non-standard field value.
procedure TForm1.GanttChartDatabaseAdapter1FieldsToTask(Sender: TObject;
  AFields: TFields; ATask: TTMSFNCGanttTask;
  var ADefaultSet: TTMSFNCGanttChartDatabaseAdapterFieldsParams);
begin
  if AFields.FindField('PercentDone') <> nil then
  begin
    ATask.Progress := AFields.FieldByName('PercentDone').AsInteger;
    ADefaultSet.Progress := False;   // tell the adapter not to map Progress itself
  end;
end;

Customizing the mapping

When a column does not map one-to-one, handle the adapter's mapping events. OnFieldsToTask and OnTaskToFields run for each record in each direction and receive a TTMSFNCGanttChartDatabaseAdapterFieldsParams record; set a field's flag to False to tell the adapter you handled it and to skip its default mapping. Field-specific events (OnSetTaskDurationFromField, OnSetTaskDependenciesFromField, OnSetTaskPlannedStartFromField, …) give finer control for individual values. The second snippet derives Progress from a PercentDone field via OnFieldsToTask.

Pitfalls

  • The adapter attaches through GanttChart.Adapter, and Item.DataSource expects a TDataSource. There is no adapter.GanttChart or adapter.DataSet property.
  • Set every field mapping before Active := True; changing a mapping after activation requires a reload.
  • With AutoIncrementDBKey := False, the dataset must already supply a unique key in the DBKey field, or write-back cannot locate the row.
  • Toggle Active := False before structural dataset changes to avoid partial-load errors.

See also