Indicators, Sections, and Annotations

TTMSFNCTimeline displays two kinds of items on the timeline: indicators (point-in-time markers) and sections (spans with a start and end). Both support rich appearance customisation, hover and selected states, and an optional annotation label.

Value and position concepts

Timeline positions are stored as Double values.

TimelineValue / TimelineDate — the logical position on the timeline. TimelineDate and TimelineValue are linked: setting one updates the other automatically.
Position — the pixel coordinate on screen for drawing. Convert between the two using GetPositionForValue and GetValueAtPosition.

Indicators

An TTMSFNCTimelineIndicator marks a single point in time. Add one via the helper method or through the Indicators collection:

uses
  FMX.TMSFNCTimeline;

procedure TFormMain.AddIndicators;
var
  ind: TTMSFNCTimelineIndicator;
begin
  TMSFNCTimeline1.BeginUpdate;

  // Quick add via helper method
  TMSFNCTimeline1.AddIndicator(EncodeDate(2025, 6, 10), 'Release');

  // Full control via the Indicators collection
  ind := TMSFNCTimeline1.Indicators.Add;
  ind.TimelineDate := EncodeDate(2025, 6, 15);
  ind.Annotation.Text := 'Review';
  ind.Annotation.Position := tlapTopLeft;

  // Appearance overrides for this indicator
  ind.Appearance.Shape := tlisSquare;
  ind.Appearance.Fill.Color := gcRed;
  ind.Appearance.Size := 16;

  // Prevent user from moving this indicator
  ind.Fixed := True;

  TMSFNCTimeline1.EndUpdate;
end;

// Navigate to a specific indicator by date
procedure TFormMain.ScrollToToday;
begin
  TMSFNCTimeline1.CenterValue(Now);
end;

// React to indicator selection
procedure TFormMain.TMSFNCTimeline1IndicatorSelectionChanged(
  Sender: TObject; AIndicator: TTMSFNCTimelineIndicator; ASelected: Boolean);
begin
  if ASelected then
    ShowMessage(AIndicator.Annotation.Text);
end;

Indicator properties

Property	Description
`TimelineDate` / `TimelineValue`	Position on the timeline. Setting one updates the other.
`Annotation`	Label shown alongside the marker.
`Fixed`	When `True`, the user cannot drag the indicator.
`Selectable`	When `False`, the indicator cannot be clicked/selected.
`Selected`	Read or set selection state in code.
`Hint` / `ShowHint`	Tooltip text when hovered.
`Tag`	Custom integer for app-level data association.

Indicator appearance

Override the default appearance (set via Appearance.DefaultIndicatorAppearance) per indicator:

Property	Description
`Shape`	`tlisCircle`, `tlisSquare`, `tlisDiamond`, `tlisTriangleUp/Down/Left/Right`, `tlisBitmap`.
`Size`	Pixel size of the marker. `-1` inherits the timeline bar size.
`Fill` / `Stroke`	Normal state background and border.
`HoverFill` / `HoverStroke`	Hover state overrides.
`SelectedFill` / `SelectedStroke`	Selected state overrides.
`Bitmap` / `BitmapName`	Custom image when `Shape = tlisBitmap`.

Annotations

Every indicator has an TTMSFNCTimelineAnnotation sub-object accessible via Annotation.

Property	Description
`Text`	HTML-capable label text.
`Position`	`tlapTopLeft`, `tlapMiddle`, `tlapBottomRight` — which side of the timeline the annotation appears on.
`Width` / `Height`	Annotation box dimensions. `-1` = auto-size.
`Visible`	Show or hide the annotation without removing the indicator.

Annotation appearance:

Property	Description
`Font` / `HoverFont` / `SelectedFont`	Font for normal, hover, and selected states.
`Fill` / `Stroke` / `HoverFill` / etc.	Background and border for each state.
`Alignment`	Horizontal alignment relative to the indicator: `gtaLeading`, `gtaCenter`, `gtaTrailing`.
`TextHorizontalAlign` / `TextVerticalAlign`	Text alignment within the annotation box.
`TextMargins`	Padding between text and box edges.
`TextWordWrap`	Wrap long text.
`Rounding` / `RoundedCorners`	Corner radius of the annotation box.
`AnnotationLine` / `AnnotationLineVisible`	Line connecting annotation to indicator.
`TextOrientation`	Rotate annotation text.

Sections

A TTMSFNCTimelineSection spans a range from StartTimelineDate to EndTimelineDate:

uses
  FMX.TMSFNCTimeline;

procedure TFormMain.AddSections;
var
  sec: TTMSFNCTimelineSection;
begin
  TMSFNCTimeline1.BeginUpdate;

  // Quick add via helper method
  TMSFNCTimeline1.AddSection(
    EncodeDate(2025, 1, 6), EncodeDate(2025, 1, 10), 'Phase 1');

  // Full control via the Sections collection
  sec := TMSFNCTimeline1.Sections.Add;
  sec.StartTimelineDate := EncodeDate(2025, 1, 13);
  sec.EndTimelineDate := EncodeDate(2025, 1, 17);
  sec.Text := 'Phase 2';
  sec.Appearance.Fill.Color := gcLightBlue;
  sec.Appearance.Rounding := 4;
  sec.Fixed := False; // user can move and resize

  TMSFNCTimeline1.EndUpdate;
end;

// Constrain section movement in OnSectionMove
procedure TFormMain.TMSFNCTimeline1SectionMove(
  Sender: TObject; ASection: TTMSFNCTimelineSection;
  var AStartValue, AEndValue: Double; var AAllow: Boolean);
begin
  // Prevent moving past the overall range start
  if AStartValue < TMSFNCTimeline1.Range.MinimumValue then
  begin
    AAllow := False;
  end;
end;

Section properties

Property	Description
`StartTimelineDate` / `StartTimelineValue`	Span start. Setting the date updates the value and vice versa.
`EndTimelineDate` / `EndTimelineValue`	Span end.
`Text`	Label shown inside the section.
`Fixed`	Prevents user from moving or resizing.
`Selectable` / `Selected`	Selection state.

Section appearance

Property	Description
`Fill` / `Stroke`	Normal state.
`HoverFill` / `HoverStroke`	Hover state.
`SelectedFill` / `SelectedStroke`	Selected state.
`TextHorizontalAlign` / `TextVerticalAlign`	Text alignment within the section.
`TextOrientation`	Rotate the section label.
`Rounding` / `RoundedCorners`	Rounded corners.
`TextWordWrap`	Wrap long section labels.

Overlapping sections

By default, overlapping sections share the available space proportionally. Set Layout.OverlapSections to True to allow them to draw on top of each other instead.

Navigating items

Use these helper methods to iterate through items within a value range:

Method	Description
`GetFirstIndicator(AMin, AMax)`	First indicator in the range.
`GetNextIndicator(AIndicator, AMax)`	Next indicator after the given one.
`GetPreviousIndicator(AIndicator, AMin)`	Previous indicator before the given one.
`GetLastIndicator(AMin, AMax)`	Last indicator in the range.
`GetFirstSection` / `GetNextSection` / …	Same navigation for sections.

Hit testing

Convert a screen coordinate to a timeline item:

var
  item: TTMSFNCTimelineIndicator;
begin
  item := TMSFNCTimeline1.GetIndicatorAtXY(X, Y);
  if Assigned(item) then
    ShowMessage(item.Annotation.Text);
end;

Method	Returns
`GetIndicatorAtXY(X, Y)`	Indicator under the cursor.
`GetIndicatorAnnotationAtXY(X, Y)`	Annotation under the cursor.
`GetItemAtXY(X, Y)`	Any item (indicator or section) under the cursor.
`GetValueAtXY(X, Y)`	Timeline value at the cursor position.
`GetPositionAtXY(X, Y)`	Pixel position at the cursor.

Table of Contents