Table of Contents

Scrolling & scroll bars

Pixel-smooth or cell-snapping, continuous or release-only redraws, programmatic scroll-to, custom-styled or external scroll bars.

Overview

Scrolling is configured through three top-level grid properties — ScrollMode, ScrollUpdate, and CustomScrollBars — plus a handful of API methods for programmatic control. The defaults match Excel: smooth pixel scrolling with continuous redraw and OS-native scroll bars.

Scroll mode

Grid.ScrollMode := gsmCellScrolling;
Value Effect
gsmPixelScrolling Smooth pixel-by-pixel scrolling (default).
gsmCellScrolling Snaps so the top-left visible cell is always fully aligned.

Pick gsmCellScrolling when fractional row/column visibility looks odd — for example a grid that imitates a paper form.

Scroll update strategy

Grid.ScrollUpdate := gsuOnce;
Value Effect
gsuContinuous Redraws while the user drags the scroll thumb (default).
gsuOnce Redraws only when the thumb is released.

Use gsuOnce on very large grids where continuous repaint costs become noticeable.

Programmatic scrolling

Grid.Scroll(0, 500);                              // pixel offset (h, v)
Grid.GoToCell(MakeCell(3, 20));                   // navigate to a specific cell

Reading the current scroll position:

var H := Grid.GetHScrollValue;
var V := Grid.GetVScrollValue;

Save and restore around a rebuild:

Grid.Root.SaveScrollPosition;
Grid.LoadFromCSVData('data.csv');
Grid.Root.RestoreScrollPosition;

Scroll events

procedure TForm1.GridHScroll(Sender: TObject; APosition: Single);
begin
  StatusBar1.SimpleText := Format('H-scroll: %.0f', [APosition]);
end;

procedure TForm1.GridVScroll(Sender: TObject; APosition: Single);
begin
  StatusBar1.SimpleText := Format('V-scroll: %.0f', [APosition]);
end;

Assign via OnHScroll and OnVScroll.

Custom scroll bars

Replace the OS scroll bars with the grid's own styled scroll bars (TTMSFNCScrollBar) for a consistent look across platforms:

Grid.CustomScrollBars := True;

// access them directly
var HSB := Grid.CustomHorizontalScrollBar;
var VSB := Grid.CustomVerticalScrollBar;

StretchScrollBars := True makes the scroll bars fill the full edge of the grid (touching the corners) rather than leaving a gap:

Grid.StretchScrollBars := True;

Hide a scroll bar without disabling scroll:

Grid.HorizontalScrollBarVisible := False;
Grid.VerticalScrollBarVisible   := True;

External scroll bars

For layouts where the scroll bars need to live outside the grid control (e.g. in a separate panel), implement ITMSFNCDataGridExternalScrollBar on any control and assign it:

Grid.ExternalVerticalScrollBar   := MyVerticalScrollBarAdapter;
Grid.ExternalHorizontalScrollBar := MyHorizontalScrollBarAdapter;

The interface requires: Value, Min, Max, PageSize, SmallChange, LargeChange, Visible, and OnChange. The grid drives all properties automatically; the implementation forwards them to the underlying scroll control.

Mouse-wheel scrolling

Grid.Options.Mouse controls wheel behaviour:

Grid.Options.Mouse.WheelScrollSize        := 3;       // rows per tick
Grid.Options.Mouse.WheelScrollKeepSelection := True;  // don't move cursor on scroll

Touch scrolling

Grid.Options.Mouse.TouchScrolling           := True;   // enable swipe scroll
Grid.Options.Mouse.TouchScrollingSensitivity := 5;     // pixels before scroll starts

Auto-scroll while dragging

When the user drags a selection (or a row/column) past the edge of the visible area, the grid auto-scrolls:

Grid.Options.Mouse.AutoScrolling         := True;
Grid.Options.Mouse.AutoScrollingInterval := 50;        // ms per tick
Grid.Options.Mouse.AutoScrollingSpeed    := 2;         // rows/cols per tick
  • Grid.ScrollMode, Grid.ScrollUpdate
  • Grid.Scroll(H, V), Grid.GoToCell(Cell)
  • Grid.GetHScrollValue / GetVScrollValue
  • Grid.Root.SaveScrollPosition / RestoreScrollPosition
  • OnHScroll, OnVScroll
  • Grid.CustomScrollBars, StretchScrollBars
  • Grid.HorizontalScrollBarVisible, Grid.VerticalScrollBarVisible
  • Grid.CustomHorizontalScrollBar, Grid.CustomVerticalScrollBar
  • Grid.ExternalHorizontalScrollBar, Grid.ExternalVerticalScrollBar
  • Grid.Options.Mouse.WheelScrollSize, WheelScrollKeepSelection
  • Grid.Options.Mouse.TouchScrolling, TouchScrollingSensitivity
  • Grid.Options.Mouse.AutoScrolling, AutoScrollingInterval, AutoScrollingSpeed

See also

  • Large datasets — gsuOnce and other patterns for big grids.
  • Keyboard & mouse — page-up/page-down navigation also drives scrolling.
  • Paging — paging is an alternative to long-scroll datasets.