CreateReadOnlyView method

Creates a lightweight read-only view over a loaded Classic or XLSX workbook model

Syntax

function CreateReadOnlyView: IXLSReadOnlyWorkbookView;

CreateReadOnlyView is declared by Classic IXLSWorkbook in lxHandle and XLSX IXLSXWorkbookOwner in lxHandleX; the shared view interface, options, and snapshot types are declared in lxStandard

View state and lifetime

Creating a view is constant time and does not traverse worksheets, cells, styles, names, or drawings

Each view has its own one-based ActiveSheetIndex, so several views can select different worksheets without changing Classic ActiveSheetIndex or XLSX ActiveIndex, IsSelected, and ActiveTab

The view holds a read lease while it exists, and workbook mutations fail fast with EXLSWorkbookWriteGuardUnavailable before changing the model

Hold Classic workbooks through IXLSWorkbook and XLSX workbooks through IXLSXWorkbookOwner when using views; the owner interface and every view then retain the same reference-counted workbook and may be released in either order

Do not call Free on a concrete TXLSWorkbook or TXLSXWorkbook while an owner interface or view still references it

Cell snapshots

TryReadCell uses one-based row and column coordinates on the view's active sheet and returns False only when no stored cell exists at that coordinate

A missing-cell read does not create storage or advance the workbook generation

TXLSReadOnlyCellSnapshot owns its sheet name, value, formula text, cache and evaluation information, coordinates, kind, and style index and never exposes a writable workbook object

Formula policy

By default formula cells use the existing stored cache and never calculate, invoke a user function, update dirty state, or write a cache back to the workbook

Add xlsvIncludeFormulaText to Options when formula text is required; the option set has type TXLSReadOnlyViewOptions = set of TXLSReadOnlyViewOption. Classic creates a view-private decoder on demand, while XLSX copies its stored formula string, and neither path initializes or modifies the workbook calculator

A formula without a loaded or calculated cache reports HasFormulaCache=False and leaves Value as Unassigned

Add xlsvEvaluateFormulas to evaluate formulas through a view-private calculator, recursion state, scalar cache, array-matrix cache, and XLSX compiled-formula cache; the resulting Value and FormulaEvaluation.Value never replace the workbook's stored cache or compiled formula runtime fields

Standard spreadsheet errors are returned as Variant error values with xlfesCalculated, while unsupported or internal evaluation failures report xlfesFailed and retain the original stored cache in FormulaCache

Repeated reads through one view reuse its private evaluation cache for the lease generation, while different views remain independent and may evaluate the same shared formula concurrently

XLSX external formula evaluation reads only the file-local externalLink cache and never dereferences a weak live-workbook registration or performs external I/O

Threading and performance

Use one view per worker thread; separate views may scan different worksheets or evaluate the same formula concurrently, while callers must not mutate one view's active sheet or options from another thread

After creation, ordinary cell reads do not enter a monitor or critical section because the lease prevents concurrent workbook mutation

Release validation keeps each idle view below 64 KiB of fixed state, one hundred idle views below 8 MiB, and view creation independent of workbook size with a one-millisecond p95 gate on a one-million-cell model

The performance suite also limits the effect of an idle view on existing single-thread cursor scans to five percent and requires eight views scanning independent worksheets to reach at least five times the single-view throughput on the validation host

Example

var
  Workbook: IXLSWorkbook;
  View: IXLSReadOnlyWorkbookView;
  Cell: TXLSReadOnlyCellSnapshot;
begin
  Workbook := TXLSWorkbook.Create;
  Workbook.Sheets.Add;
  Workbook.Sheets[1].Cells[1, 1].Value := 'ready';

  View := Workbook.CreateReadOnlyView;
  View.Options := [xlsvEvaluateFormulas];
  if View.TryReadCell(1, 1, Cell) then
    Memo1.Lines.Add(VarToStr(Cell.Value));
end;

For XLSX, retain the concrete workbook through its owner interface before creating views

var
  Owner: IXLSXWorkbookOwner;
  Workbook: TXLSXWorkbook;
  View: IXLSReadOnlyWorkbookView;
begin
  Workbook := TXLSXWorkbook.Create;
  Owner := Workbook;
  Workbook.Sheets.Add('Data').Cells[1, 1].Value := 42;
  View := Owner.CreateReadOnlyView;
end;

See also

• IXLSWorkbook interface
• TXLSXWorkbook class
• TryGetCachedFormulaValue method
• CreateLoadedCellCursor method