Table of Contents

Scrolling and events

A static panel shows only as many characters as it has cells. To present a longer message — a news ticker, a stock feed, a rolling status line — turn the matrix label into a marquee with Scroll. When scrolling is enabled the widget animates the text continuously across the grid on a timer, and raises OnScrollDone each time the message has fully passed. This chapter shows how to start scrolling, control its direction and speed, color individual segments of the message with inline codes, and react when a cycle completes. For static text, casing, sizing, and colors, see the Display and appearance chapter.

Matrix label rendering a colored scrolling ticker message Matrix label rendering a colored scrolling ticker message in dark theme

Start scrolling

Scrolling is driven by the Scroll settings object. Set Scroll.Enabled := True to start the marquee; the widget starts its internal timer and advances the text one step per tick. Scroll.Direction chooses msdRightToLeft (the default, classic ticker motion) or msdLeftToRight. Scroll.Interval is the delay in milliseconds between steps — lower values scroll faster. The snippet below builds a 12-cell ticker with a colored multi-segment message and wires the cycle-complete event.

procedure TForm1.SetupTicker;
var
  Matrix: TTMSFNCWidgetMatrixLabel;
begin
  Matrix := TTMSFNCWidgetMatrixLabel.Create(Self);
  Matrix.Parent := Self;
  Matrix.Position.X := 20;
  Matrix.Position.Y := 20;

  Matrix.BeginUpdate;
  try
    Matrix.Leds := 12;

    // %A..%G switch the lit color mid-string: %A=red, %B=lime, %C=blue, ...
    Matrix.Text := '%ASTOCK ALERT  %BTMSN +4.2%%  %CVOLUME HIGH';

    // Scrolling overrides the static alignment and runs continuously.
    Matrix.Scroll.Enabled := True;
    Matrix.Scroll.Direction := msdRightToLeft;
    Matrix.Scroll.Interval := 120; // ms between steps; lower = faster

    Matrix.OnScrollDone := MatrixScrollDone;
  finally
    Matrix.EndUpdate;
  end;
end;

procedure TForm1.MatrixScrollDone(Sender: TObject);
begin
  // Fires each time the message has fully passed across the grid.
  Inc(FCycleCount);
end;

Direction and speed

Scroll.Direction can be flipped at runtime to reverse the motion, and Scroll.Interval can be tuned to match the urgency of the content — a fast Interval of around 80–120 ms reads as an active ticker, while 400–500 ms gives a calm, easy-to-read crawl. Because the alignment setting is ignored while scrolling, the text always enters from the edge implied by the direction.

Inline color segments

The same %-code mechanism described in Display and appearance colors a scrolling message per segment: %A through %G (and %0–%9) switch the lit color for the characters that follow, so a single Text string can render, for example, a red alert prefix followed by a green value. Write a literal percent sign as %%.

Handle the scroll-done event

OnScrollDone fires once per completed scroll cycle — that is, each time the whole message has scrolled off and the position resets. Use it to count passes, rotate to the next message in a queue, or stop scrolling after a fixed number of repeats. The handler signature is a plain TNotifyEvent, where Sender is the matrix label. The snippet under Start scrolling assigns MatrixScrollDone and increments a counter on each pass; the same hook can swap the Text to advance a playlist of messages.

{ Inside the form, FMessages: TStringList holds the playlist, FIndex: Integer: }
procedure TForm1.MatrixScrollDone(Sender: TObject);
begin
  // Advance to the next message each time the current one has fully scrolled.
  FIndex := (FIndex + 1) mod FMessages.Count;
  (Sender as TTMSFNCWidgetMatrixLabel).Text := FMessages[FIndex];
end;

Pitfalls

  • Scrolling overrides alignment. Appearance.Alignment has no effect while Scroll.Enabled is True; disable scrolling to position static text.
  • Interval is per step, not per character. A very small Interval can scroll faster than it is comfortable to read; tune it against the cell count.
  • OnScrollDone fires per full cycle, not per character. Do not use it for per-frame work — it only signals that the message has completely passed.
  • Toggle through Scroll, not a top-level property. Enable and disable the marquee via Scroll.Enabled; there is no separate Scrolling flag on the control itself.

See also