Worksheet pane selection API

TXLSWorksheet and TXLSXWorksheet expose the same pane-aware methods for reading or replacing selected cell and range areas

Shared types and methods

TXLSPanePosition = (xlspTopLeft, xlspTopRight,
  xlspBottomLeft, xlspBottomRight);
TXLSSelectedAreas = array of WideString;

function GetSelectedAreas(APane: TXLSPanePosition;
  out ActiveAreaIndex: Integer): TXLSSelectedAreas;
function SelectAreas(APane: TXLSPanePosition;
  const Areas: array of WideString;
  ActiveAreaIndex: Integer = 0): Boolean;
function TryGetWindowScroll(APane: TXLSPanePosition;
  out ARow, ACol: Integer): Boolean;
function ScrollWindow(APane: TXLSPanePosition;
  ARow, ACol: Integer): Boolean;

Area text uses A1 cell or range references, and ActiveAreaIndex is a zero-based index into the returned or supplied area sequence

The area sequence keeps source order and may contain overlapping ranges because selection order and overlap are part of worksheet view state

Snapshot ownership

GetSelectedAreas returns a new dynamic array whose strings and length belong to the caller, so changing or releasing the result cannot alter the worksheet

When the requested pane has no represented selection group, the result is empty and ActiveAreaIndex is -1

Reading a missing pane never creates a pane, selection object, cell, or range in the workbook

Classic XLS record aggregation

Classic XLS keeps an independent logical selection group for every pane and aggregates consecutive BIFF Selection records with the same pane code in source order

The active row, active column, and ActiveAreaIndex are shared by every record in one group, and the index addresses the complete aggregate area sequence rather than one physical record

Saving an untouched group preserves its original record bodies, while an edited group is written in consecutive chunks of at most 1369 areas with the same aggregate active index in every chunk

Editing one pane leaves the other pane groups unchanged, and worksheet copies retain the complete pane selection state

Structural edits

Whole-row and whole-column insertions or deletions remap the ordered selection groups for every represented pane in both workbook engines

Surviving areas keep their order and the active area's identity; if the active area is removed, the first surviving successor is selected, followed by the last surviving predecessor when no successor remains

If every area is removed, the group becomes one cell at the deletion boundary, while an active cell outside the chosen surviving area falls back to that area's top-left cell

Invalid classic records

Malformed, non-contiguous, or contradictory Classic Selection records remain opaque and are not exposed through the typed area query

A physical record rejected during record validation reports xlsDiagnosticSelectionRecordInvalid with diagnostic code 1304, while an aggregate-only contradiction reports one group diagnostic at worksheet EOF; saving replays every original record body byte-for-byte

Large selections

Area parsing, normalisation, structural remapping, and snapshot construction use one-pass builders or geometric capacity growth so large selection groups remain amortised linear

Pane scroll coordinates

TryGetWindowScroll returns the first visible cell for one logical pane and ScrollWindow changes it, using 1-based worksheet row and column coordinates in both engines

Top panes share the overall window row, bottom panes share the lower pane row, left panes share the overall window column, and right panes share the right pane column

A missing pane returns False without creating view state, with query outputs set to zero; invalid coordinates also return False before any axis is changed

Classic XLS persists the upper and left axes in Window2 and the lower and right axes in Pane, while XLSX retains the corresponding sheetView and pane topLeftCell values independently

Atomic updates

SelectAreas validates every A1 reference and the active index before obtaining the worksheet write transaction

The method returns False for malformed or empty input, an invalid active index, or a pane that does not exist in the current split or frozen geometry, with the previous selection left unchanged

A successful call returns True and preserves the existing engine-specific selection objects and legacy APIs

Delphi example

if Sheet.SelectAreas(xlspBottomRight,
  ['C4:E5', 'D5:F6', 'G7'], 1) then
begin
  Areas := Sheet.GetSelectedAreas(xlspBottomRight,
    ActiveAreaIndex);
  UseSelection(Areas, ActiveAreaIndex);
end;

if Sheet.ScrollWindow(xlspBottomRight, 20, 8) and
   Sheet.TryGetWindowScroll(xlspBottomRight, Row, Col) then
  ShowVisibleCell(Row, Col);

Compatibility

The classic SelectAreas(const Areas; ActiveAreaIndex) overload and the XLSX SelectAreas(const Areas; ActiveAreaIndex; APane) overload remain available unchanged

The classic ScrollRow and ScrollColumn properties and the XLSX zero-based SetPaneScroll, GetPaneScroll, ScrollRow, and ScrollCol members also remain available unchanged

The shared façade converts logical pane names explicitly, so callers do not depend on the numeric pane codes used by either file format