MagiXells developer documentation

Embeddable Delphi / C++Builder spreadsheet control (TMagiXells / TFmxMagiXells) with shared Core, XLSX/ODS/MGX/CSV I/O, formulas, charts, and an optional AI agent.

Visibility rule: API pages document only Public and Published members. Private/protected members are omitted. Guide samples call only those APIs.

Start here

1. Getting started — install Setup.exe, drop a control, load/save; measurement units
2. C++Builder — same packages from C++ (headers, SheetAPI without helpers, AI)
3. Architecture — Core vs hosts; what you own vs what MagiXells owns

Guides

Also: Formulas overview

API reference

Every exposed member includes Where used, How to use, and a Delphi example (see API index). Trial/Runtime installs ship without library source — docs are the contract. For C++Builder call shapes, see C++Builder.

Demos

After Setup, open demos from Start Menu → Binary Magic → MagiXells (VCL/FMX hosts, feature samples). View → Pivot Field List inserts/refreshes PivotTables from a selection.

Getting started

Install MagiXells with the Setup program, drop a control on a form, and load/save a workbook.

Prerequisites

• Delphi or C++Builder 12.3 Athens or 13
• MagiXells Trial or Runtime installer (MagiXells-Trial-Setup.exe or MagiXells-Runtime-Setup.exe)
• Host apps may target Win32, Win64, or WinARM64EC (Windows on ARM; Delphi 13.1+ with the ARM64EC toolchain)

C++Builder uses the same packages and Public API via generated .hpp files — see C++Builder.

Trial install

The public trial ships compiled packages only for supported Delphi / C++Builder IDEs (BPLs/DCPs/DCUs — MagiXells library .pas units are not included). The grid always shows an evaluation watermark.

1. Close RAD Studio
2. Run MagiXells-Trial-Setup.exe (installs into every supported IDE found on the machine)
3. Restart the IDE; drop TMagiXells or TFmxMagiXells from the MagiXells palette
4. Optional demos: Start Menu → Binary Magic → MagiXells → Demo Projects

Evaluation only — not licensed for distribution (see LICENSE).

Silent: MagiXells-Trial-Setup.exe /VERYSILENT /NORESTART

Runtime install (licensed)

Same binary package installer as the trial, without the watermark. After purchase, run MagiXells-Runtime-Setup.exe, restart the IDE, and build as usual. Runtime Setup also does not include MagiXells library source.

Drop a control (VCL)

1. Open a VCL form.
2. From the MagiXells palette, drop TMagiXells.
3. Set Align := alClient (Object Inspector or code).

uses
  MagiXells.Spreadsheet;

procedure TForm1.FormCreate(Sender: TObject);
begin
  MagiXells1.Align := alClient;
  MagiXells1.NewWorkbook;
end;

Drop a control (FMX)

1. Open an FMX form.
2. From the MagiXells palette, drop TFmxMagiXells.
3. Align to client.

uses
  MagiXells.Spreadsheet.Fmx;

procedure TForm1.FormCreate(Sender: TObject);
begin
  FmxMagiXells1.Align := TAlignLayout.Client;
  FmxMagiXells1.NewWorkbook;
end;

Load and save

Format is inferred from the file extension (.xlsx, .ods, .mgx, .csv).

MagiXells1.LoadFromFile('C:\Data\report.xlsx');
MagiXells1.SaveToFile('C:\Data\report.mgx');

Streams require an explicit format:

uses
  MagiXells.Types;

var
  MS: TMemoryStream;
begin
  MS := TMemoryStream.Create;
  try
    MagiXells1.SaveToStream(MS, ffXlsx);
    MS.Position := 0;
    MagiXells1.LoadFromStream(MS, ffXlsx);
  finally
    MS.Free;
  end;
end;

First edits via the control

MagiXells1.SelectRange(0, 0, 2, 0); // A1:C1 (0-based col/row)
MagiXells1.SetNumberFormat('0.00');
MagiXells1.MergeCells;

First edits via SheetAPI

uses
  MagiXells.SheetAPI;

var
  S: TAuthoringSheet;
begin
  S := MagiXells1.Workbook.UseActiveSheet;
  S.Cell['A1'].Text := 'Hello';
  S.Cell['B1'].AsNumber := 42;
  S.Cell['C1'].Formula := '=B1*2';
  MagiXells1.Recalculate;
end;

Run the demos

After install, open demos from Start Menu → Binary Magic → MagiXells → Demo Projects (VCL and FMX).

Sample workbooks may also be included with the product (for example a feature showcase .xlsx).

Measurement units

These values are not pixels unless the API says so. MagiXells matches Excel’s workbook units; the grid converts them to screen pixels using DPI and Zoom.

Character units are not CSS ch and not device pixels. A “1 px” gutter in the painted grid is one device pixel at 96 DPI / 100% zoom, and it scales with zoom the same way column pixels do.

Next steps

• C++Builder — same control from C++Builder (VCL/FMX)
• Architecture
• API: TMagiXells
• MagiXells.Types — addresses, ranges, ColToLetters
• SheetAPI
• AI agent

Architecture

High-level layout for integrators. No internal-unit APIs are documented here.

Layers

Packages link into your EXE (no separate MagiXells runtime DLL). C++Builder hosts use the same packages via generated .hpp headers — see C++Builder.

What MagiXells owns

• Spreadsheet model and paint/edit surface
• File I/O for XLSX / ODS / MGX / CSV
• Formula evaluation and undo stack
• Published host options (Behavior, ViewOptions, Appearance, Protection, TabBar)
• AI agent engine and tool catalog (when you use AI packages / units)

What the host owns

• Application chrome (menus, toolbars). The product demos include a sample format ribbon — it is not a library control.
• AI chat UI. Use host-built panels (see demos: View → AI Agent) or optional AI chat packages.
• Licensing, file dialogs, persistence of AI API keys

VCL vs FMX

Public MagiXells methods and events are parity-first. Prefer VCL Delphi snippets in API pages; swap the control type for FMX. For C++Builder hosts, see C++Builder.

Authoring paths

1. Control API — selection-based (MergeCells, PasteValues, SetFont, …). Natural for UI-driven hosts.
2. SheetAPI — A1-style Cell / Range / UseActiveSheet (Delphi helpers) or TSheetCellRef::Create / TAuthoringSheet::Create (C++Builder).
3. AI agent — natural language → tools that mutate the same workbook (undoable).

Cloud

src/Cloud/ stays in MagiXellsCore as a local preview, not a hosted product and not a Public API.

TMagiXellsCloudApiClient reads and writes %TEMP%\<DocumentId>.mgx. Login always returns False and does not mint a session token. TMagiXellsSyncEngine keeps an in-memory patch list and uploads through that same TEMP file. Do not treat BaseUrl as a live REST endpoint.

Related

• Getting started
• C++Builder
• API index

Workbook and editing

Sheets, selection, in-place edit, clipboard, undo, and protection via Public control APIs.

New / load workbook

MagiXells1.NewWorkbook;
MagiXells1.LoadFromFile('budget.xlsx');
if MagiXells1.Modified then
  MagiXells1.SaveToFile('budget.xlsx');

Sheets

MagiXells1.AddSheet('Sales');
MagiXells1.ActiveSheetIndex := MagiXells1.SheetCount - 1;
MagiXells1.RenameSheet(MagiXells1.ActiveSheetIndex, 'Q1 Sales');
// MagiXells1.RemoveSheet(1);

Listen for tab changes:

procedure TForm1.MagiXells1SheetChanged(Sender: TObject);
begin
  Caption := MagiXells1.ActiveSheet.Name;
end;

Selection and navigation

Columns and rows are 0-based on the control API. Column width is Excel character units; row height is points — see measurement units.

MagiXells1.SelectCell(0, 0);           // A1
MagiXells1.SelectRange(0, 0, 3, 10);   // A1:D11
MagiXells1.ScrollToCell(0, 50);
MagiXells1.EnsureSelectionVisible;
MagiXells1.ActiveCol := 2;
MagiXells1.ActiveRow := 5;

procedure TForm1.MagiXells1SelectionChanged(Sender: TObject);
begin
  StatusBar1.SimpleText := Format('Col=%d Row=%d',
    [MagiXells1.ActiveCol, MagiXells1.ActiveRow]);
end;

In-place editing

MagiXells1.BeginEdit('=SUM(A1:A10)');
if MagiXells1.IsEditing then
  MagiXells1.EndEdit;   // or CancelEdit

Events: OnBeforeEdit, OnEditStart, OnEditCommit, OnEditCancel, OnEditTextChanged, OnFormulaEdited.

procedure TForm1.MagiXells1BeforeEdit(Sender: TObject; ACol, ARow: Integer;
  var FAllowed: Boolean);
begin
  FAllowed := ACol > 1; // block edits in column A
end;

procedure TForm1.MagiXells1ActiveCellChanging(Sender: TObject;
  ACol, ARow: Integer; var Allow: Boolean);
begin
  Allow := ARow >= 1; // lock header row
end;

Clipboard

Copy/paste uses an internal MagiXells buffer (formulas, formats, in-cell rich text) plus Windows HTML Format and TSV so Excel/Word/browser interchange keeps bold/italic/color runs.

MagiXells1.Behavior.AllowCopy := True;
MagiXells1.Behavior.AllowPaste := True;
MagiXells1.CopySelection;
MagiXells1.CutSelection;
MagiXells1.PasteAll; { HTML from Excel/Word/browser keeps bold/italic/color; multiline becomes rows }
MagiXells1.PasteValues;
MagiXells1.PasteFormulas;
MagiXells1.PasteFormats;

Clear and structure

MagiXells1.ClearContents;
MagiXells1.ClearFormats;
MagiXells1.ClearAll;
MagiXells1.InsertSelectionRows;
MagiXells1.DeleteSelectionColumns;
MagiXells1.InsertRows(5, 2);
MagiXells1.DeleteColumns(2, 1);

Undo / redo

MagiXells1.Behavior.HistoryEnabled := True;
MagiXells1.Behavior.HistoryLimit := 100;
if MagiXells1.CanUndo then MagiXells1.Undo;
if MagiXells1.CanRedo then MagiXells1.Redo;

procedure TForm1.MagiXells1HistoryChanged(Sender: TObject);
begin
  actUndo.Enabled := MagiXells1.CanUndo;
  actRedo.Enabled := MagiXells1.CanRedo;
end;

Protection and read-only

MagiXells1.ReadOnly := True;
MagiXells1.Protect;
MagiXells1.Unprotect;
MagiXells1.ProtectStructure;
MagiXells1.UnprotectStructure;
MagiXells1.Protection.AllowFormatCells := False;

Batch updates

MagiXells1.BeginUpdate;
try
  { many SheetAPI or selection edits }
finally
  MagiXells1.EndUpdate;
end;

While updating, MagiXells defers grid painting, formula auto-calc, live chart refresh, auto row-height, and OnModified. The outer EndUpdate runs one recalc (if auto-calc is on), refreshes row heights/charts, then a single repaint.

OnCellChanged is not used for programmatic SheetAPI / SetCell writes (only interactive edits). Nested BeginUpdate/EndUpdate pairs are supported. ## View chrome

MagiXells1.ShowFormulaBar := True;
MagiXells1.ShowSheetTabs := True;
MagiXells1.ShowHeaders := True;
MagiXells1.ShowGridLines := True;
MagiXells1.FrozenRows := 1;
MagiXells1.FrozenCols := 1;
MagiXells1.Zoom := 120;

See also

• API: TMagiXells
• Host options
• Formatting

Formatting

Apply formats through the control (selection-based) or SheetAPI (A1-based).

Via the control (current selection)

uses
  MagiXells.CellFormat;

var
  Font: TCellFontInfo;
  Fill: TCellFillInfo;
  Align: TCellAlignmentInfo;
begin
  MagiXells1.SelectRange(0, 0, 4, 0);

  Font := Default(TCellFontInfo);
  Font.Name := 'Calibri';
  Font.Size := 12;
  Font.Bold := True;
  MagiXells1.SetFont(Font);

  Fill := Default(TCellFillInfo);
  Fill.PatternType := cfpSolid;
  Fill.FgColor.RGB := $00D6EAF8; // COLORREF BGR
  MagiXells1.SetFill(Fill);

  Align := Default(TCellAlignmentInfo);
  Align.Horizontal := haCenter;
  Align.Vertical := vaCenter;
  MagiXells1.SetAlignment(Align);

  MagiXells1.SetNumberFormat('$#,##0.00');
  MagiXells1.MergeCells;
end;

MagiXells1.UnmergeCells;
var
  Fmt: TCellFormat;
begin
  Fmt := MagiXells1.GetActiveCellFormat;
  // inspect Fmt.Font / Fmt.Fill / …
end;

Via SheetAPI

uses
  MagiXells.SheetAPI, MagiXells.SheetAPI.Colors;

var
  S: TAuthoringSheet;
  R: TSheetRangeRef;
begin
  S := MagiXells1.Workbook.UseActiveSheet;
  S.Cell['A1'].Text := 'Title';
  S.Cell['A1'].FontBold := True;
  S.Cell['A1'].FontSize := 14;
  S.Cell['A1'].FontColor := TColor($1F4E79);
  S.Cell['A1'].FillColor := TColor($D6EAF8);
  S.Cell['A1'].HorizontalAlignment := haCenter;

  R := S.Range('A1:D1');
  R.BorderAround(blsThin, TColor($000000));
  R.NumberFormat := '0.00';
  R.Merge;
end;

Rich text on a cell:

{ Simple HTML (bold / italic / underline / color / font): }
S.Cell['A2'].SetHtml('<b>Bold</b> and <i>italic</i>');

{ Run-based API (still supported): }
S.Cell['A3'].ClearRichText;
S.Cell['A3'].AddRun('Bold ', [rfBold]);
S.Cell['A3'].AddRun('and normal');

Behavior flags

MagiXells1.Behavior.AllowFormat := True;
MagiXells1.Behavior.AllowEdit := True;

See also

• SheetAPI reference
• TMagiXells formatting methods

Formulas

Recalculation, named ranges, and dynamic arrays through Public APIs.

Enter formulas

SheetAPI:

var
  S: TAuthoringSheet;
begin
  S := MagiXells1.Workbook.UseActiveSheet;
  S.Cell['A1'].AsNumber := 10;
  S.Cell['A2'].AsNumber := 20;
  S.Cell['A3'].Formula := '=SUM(A1:A2)';
  MagiXells1.Recalculate;
end;

User edits commit through the formula bar / in-place editor; with Behavior.AutoCalculate := True (default), dependents update automatically.

Manual recalculation

MagiXells1.Behavior.AutoCalculate := False;
// … edit many cells …
MagiXells1.Recalculate;

Named ranges

Control façade:

MagiXells1.NamedRanges.AddOrSet('SalesData', 'Sheet1!$A$1:$B$20');
if MagiXells1.NamedRanges.Contains('SalesData') then
  ShowMessage(MagiXells1.NamedRanges.GetFormula('SalesData'));

SheetAPI workbook helper:

MagiXells1.Workbook.Names.Define('TaxRate', '0.2');

Formulas can reference names: =SUM(SalesData).

Show formulas

MagiXells1.ShowFormulas := True;  // or ViewOptions.ShowFormulas

Dynamic arrays

Engine supports spill arrays (FILTER, SEQUENCE, UNIQUE, SORT, …). Write the formula normally:

S.Cell['D1'].Formula := '=SEQUENCE(5,1,1,1)';
MagiXells1.Recalculate;

See Formulas overview for categories (~500 Excel-compatible builtins).

Evaluate without changing the sheet

Use Evaluator.Evaluate to compute a formula string in memory. It does not write to any cell or mark the workbook modified. Cell references (for example A1) resolve against the given sheet index, or the active sheet when omitted.

uses
  MagiXells.Types; // TCellValue

var
  V: TCellValue;
begin
  // Literals / expressions — no sheet write
  V := MagiXells1.Evaluator.Evaluate('=1+2*3');
  ShowMessage(V.ToDisplayString); // '7'

  // Relative to the active sheet
  V := MagiXells1.Evaluator.Evaluate('=SUM(A1:A10)');

  // Pin a sheet index (0-based)
  V := MagiXells1.Evaluator.Evaluate('=B2*TaxRate', MagiXells1.ActiveSheetIndex);

  case V.Kind of
    cvkNumber:  Caption := FloatToStr(V.Number);
    cvkText:    Caption := V.Text;
    cvkBoolean: Caption := BoolToStr(V.BooleanValue, True);
    cvkError:   Caption := V.ToDisplayString; // e.g. #DIV/0!
  else
    Caption := V.ToDisplayString;
  end;
end;

Prefer this over writing a temporary cell when you only need a what-if result. Avoid EvaluateCell / Recalculate for that case — those update cell caches or the workbook.

Evaluator access

MagiXells1.Evaluator is the shared TFormulaEvaluator for the control’s workbook (Evaluate, EvaluateCell, RecalculateAll, …). Same instance is used by auto-calc and MagiXells1.Recalculate.

if MagiXells1.Evaluator <> nil then
  MagiXells1.Recalculate; // full workbook recalc (writes caches)

Pivot / cube formulas

GETPIVOTDATA, GROUPBY, PIVOTBY, FIELDVALUE, and CUBE* are implemented. See PivotTables.

Web / RTD / stock / import

Also: REGEXEXTRACT / REGEXREPLACE / REGEXMATCH / REGEXTEST, ISEMAIL, ISURL, JOIN, ARRAY_CONSTRAIN, and QUERY (GVQL subset: SELECT/WHERE/ORDER BY/LIMIT/GROUP BY).

External data providers (VCL)

type
  TMyStockFeed = class(TInterfacedObject, IMagiXellsStockHistoryProvider)
  public
    function GetHistory(const ASymbol: string; AStart, AEnd: TDateTime;
      AInterval: Integer; out ABars: TArray<TStockHistoryBar>): Boolean;
  end;

procedure TForm1.FormCreate(Sender: TObject);
begin
  MagiXells1.StockHistoryProvider := TMyStockFeed.Create;
  // MagiXells1.RtdProvider := MyRtdFeed;
  // MagiXells1.TranslateProvider := MyTranslate;
  // MagiXells1.ImportRangeProvider := MyImportRange;
  // MagiXells1.GoogleFinanceProvider := MyFinance; // else Yahoo defaults
end;

// When a live tick arrives:
MagiXells1.NotifyRtdUpdate('My.Feed', '', ['BID', 'MSFT']);

Interfaces live in MagiXells.ExternalData. Properties are on TWorkbook, TMagiXells, and TFmxMagiXells.

S.Cell['B3'].Formula := '=ENCODEURL("a b")';           // a%20b
S.Cell['B4'].Formula := '=STOCKHISTORY("MSFT",TODAY()-30,TODAY())';
S.Cell['B5'].Formula := '=RTD("My.Feed","","BID")';
{ Google-compatible live spill: }
S.Cell['A1'].Formula :=
  '=IMPORTHTML("https://en.wikipedia.org/wiki/List_of_S%26P_500_companies","table",1)';
{ MagiXells: import once as a sortable/filterable Table: }
S.Cell['A1'].Formula :=
  '=IMPORTHTML("https://en.wikipedia.org/wiki/List_of_S%26P_500_companies","table",1,TRUE)';
{ Or keep Google formula, then after Recalculate: }
{ S.MaterializeSpillAsTable('A1', 'SP500', True); }
MagiXells1.Recalculate;

WEBSERVICE / Yahoo STOCKHISTORY / IMPORTHTML run synchronously on the calc thread (bounded timeout). Prefer a host StockHistoryProvider in production apps.

See also

• PivotTables
• Formulas overview
• NamedRanges API
• TMagiXells.Evaluator
• AI evaluate_formula tool

Import and export

Load/save through Public control methods. Format enum: TMagiXellsFileFormat in MagiXells.Types.

Files

MagiXells1.LoadFromFile('report.xlsx');
MagiXells1.SaveToFile('report.mgx');
MagiXells1.SaveToFile('report.ods');
MagiXells1.SaveToFile('export.csv');
MagiXells1.SaveToFile('report.pdf'); // calls ExportToPdf

Export APIs

Use explicit export methods when you do not want to change the current workbook file path:

uses
  MagiXells.IO.Csv, MagiXells.PageSetup;

var
  Job: TPrintJobSettings;
  Csv: TCsvExportOptions;
begin
  Job := TPrintJobSettings.Default;
  MagiXells1.ExportToPdf('report.pdf', Job);

  Csv := TCsvExportOptions.Default;
  Csv.Delimiter := ';';
  Csv.Utf8Bom := True;
  Csv.What := pwEntireWorkbook; // writes one CSV per visible sheet
  MagiXells1.ExportToCsv('report.csv', Csv);
end;

Progress for large loads:

procedure TForm1.MagiXells1Progress(Sender: TObject; APercent: Integer;
  const AStatus: string);
begin
  StatusBar1.SimpleText := Format('%d%% %s', [APercent, AStatus]);
end;

Streams

uses
  MagiXells.Types;

procedure SaveXlsxToStream(AGrid: TMagiXells; AStream: TStream);
begin
  AGrid.SaveToStream(AStream, ffXlsx);
end;

procedure LoadXlsxFromStream(AGrid: TMagiXells; AStream: TStream);
begin
  AStream.Position := 0;
  AGrid.LoadFromStream(AStream, ffXlsx);
end;

Modified flag

if MagiXells1.IsModified or MagiXells1.Modified then
  MagiXells1.SaveToFile(CurrentPath);

procedure TForm1.MagiXells1Modified(Sender: TObject);
begin
  actSave.Enabled := MagiXells1.Modified;
end;

Fidelity expectations

• XLSX: high-fidelity styles, merges, sizing, rich text, drawings/charts preserve-and-paint
• ODS: import/export including images/charts/shapes
• MGX: native round-trip with format parity for MagiXells features
• CSV: values only (no formatting), RFC 4180 escaping, delimiter/BOM/scope options via ExportToCsv
• PDF: vector export through the print pipeline (selectable text; embedded images)

See also

• TMagiXells I/O methods
• MagiXells.Types — TMagiXellsFileFormat, FileFormatFromExtension

Charts and drawings

The control paints drawings from files and allows single-object select, move, and resize (corner aspect lock). Multi-select, grouping, rotation handles, and in-place shape text editing are not in this MVP.

Use SheetAPI for authoring, host Appearance for chart series colors, or AI tools insert_chart / update_chart / list_charts / insert_picture / list_drawings — see AI agent API.

Workflow 1 — Data → chart → live refresh

1. Write categories and values (or load a file).
2. Call AddChart with values/categories formulas and an anchor cell.
3. Change source numbers and Recalculate — the chart paints from live sheet data.

uses
  MagiXells.SheetAPI, MagiXells.Drawing;

var
  S: TAuthoringSheet;
begin
  S := MagiXells1.Workbook.UseActiveSheet;
  S.Cell['A1'].Text := 'Month';
  S.Cell['B1'].Text := 'Sales';
  S.Cell['A2'].Text := 'Jan';
  S.Cell['B2'].AsNumber := 100;
  S.Cell['A3'].Text := 'Feb';
  S.Cell['B3'].AsNumber := 140;
  S.Cell['A4'].Text := 'Mar';
  S.Cell['B4'].AsNumber := 125;

  { Title, type, values formula, categories formula, anchor, width cols, height rows }
  S.AddChart('Sales', sctColumn, 'Sheet1!$B$2:$B$4', 'Sheet1!$A$2:$A$4', 'D2', 8, 12);
  MagiXells1.Recalculate;

  { Later: edit B3 and recalc — chart updates }
  S.Cell['B3'].AsNumber := 180;
  MagiXells1.Recalculate;
end;

Or use the overload that takes TArray<TSheetChartSeries> when you need multiple series / combo layouts.

Chart types commonly used with SheetAPI / AI: column, bar, line, pie, area, scatter, doughnut, radar (plus bubble/combo/stock where the model preserves them).

Workflow 2 — Pictures and shapes

var
  S: TAuthoringSheet;
begin
  S := MagiXells1.Workbook.UseActiveSheet;

  { File-based logo at E2, size in pixels }
  S.AddPictureFromFile('logo.png', 'E2', 240, 120);

  { Or bytes + content type }
  // S.AddPictureFromBytes(PngBytes, 'image/png', 'E2', 240, 120);

  { Preset geometry name e.g. rect — floating shape }
  S.AddShape('rect', 'G2', 120, 80);
end;

Interaction: click a drawing to select; drag to move; corner grips resize (aspect lock). No multi-select/group/rotate/in-place text in this MVP.

Workflow 3 — Table + filter + sort next to a chart

Often you chart a table range; keep headers frozen or filtered for exploration.

var
  S: TAuthoringSheet;
begin
  S := MagiXells1.Workbook.UseActiveSheet;
  { Assume A1:B4 already filled as in Workflow 1 }
  S.AddTable('SalesTable', 'A1:B4', True, True);
  S.EnableAutoFilter('A1:B4');
  S.Sort('A1:B4', 1, True, True);  { key col index relative to range; has header }
  S.AddChart('Sales', sctLine, 'Sheet1!$B$2:$B$4', 'Sheet1!$A$2:$A$4', 'D2', 8, 10);
end;

Smooth drawing (VCL)

Prefer GDI+ for shapes/charts/ink when you want anti-aliased edges:

MagiXells1.ViewOptions.SmoothDrawing := True;

Chart colors (host theme)

Series colors come from host chrome (Appearance), not the OOXML workbook theme alone:

uses
  MagiXells.UiTheme;

MagiXells1.Appearance.ChartSeries1 := $4472C4;
MagiXells1.Appearance.ChartSeries2 := $ED7D31;
MagiXells1.Appearance.ApplyPreset(utpExcelLight);

See Host options & UiTheme and RTL and themes.

AI agent prompts (optional)

Insert a column chart of B2:B12 with categories A2:A12 titled Sales at D2.

List drawings on this sheet, then delete chart 0 and insert logo.png at E2.

See also

• SheetAPI
• UiTheme chart properties
• AI agent API

PivotTables

MagiXells PivotTables refresh into sheet cells from a PivotCache (worksheet range, multi-consolidation, or OLAP/external connection). Use SheetAPI from code, the Field List UI in demos, or AI tools list_pivots / create_pivot / configure_pivot / refresh_pivot / delete_pivot — see AI agent API.

This guide walks through full workflows, not just API names.

Workflow 1 — Create and refresh from SheetAPI

Typical path: prepare a header + data block → AddPivotTable → assign row/column/value fields → RefreshPivotTable.

uses
  MagiXells.SheetAPI, MagiXells.Pivot;

var
  S: TAuthoringSheet;
  P: TPivotTable;
begin
  S := MagiXells1.Workbook.UseActiveSheet;

  { Source: headers in row 1, data below }
  S.Cell['A1'].Text := 'Region';
  S.Cell['B1'].Text := 'Product';
  S.Cell['C1'].Text := 'Amount';
  S.Cell['A2'].Text := 'East';
  S.Cell['B2'].Text := 'Widget';
  S.Cell['C2'].AsNumber := 120;
  S.Cell['A3'].Text := 'West';
  S.Cell['B3'].Text := 'Gadget';
  S.Cell['C3'].AsNumber := 90;
  S.Cell['A4'].Text := 'East';
  S.Cell['B4'].Text := 'Gadget';
  S.Cell['C4'].AsNumber := 50;

  { Dest E1 is the top-left of the refreshed pivot layout }
  P := S.AddPivotTable('SalesPT', 'A1:C4', 'E1');
  P.AddField(TPivotFieldRef.Create(0, pfrRow));           // Region (field index 0)
  P.AddField(TPivotFieldRef.Create(1, pfrColumn));        // Product
  P.AddField(TPivotFieldRef.Create(2, pfrValue, paSum));  // Amount
  S.RefreshPivotTable('SalesPT');
  MagiXells1.Invalidate;  { if your host needs a paint }
end;

After source edits, call RefreshPivotTable again (or the AI refresh_pivot tool) so cell values rebuild from the cache.

Other cache kinds

{ Multi-consolidation ranges }
P := S.AddPivotTableMulti('MultiPT', ['Sheet1!A1:C10', 'Sheet2!A1:C10'], 'E1');

{ OLAP / connection-based (needs a workbook connection id) }
P := S.AddPivotTableOlap('OlapPT', 'MyCubeConn', 'E1');

Also: AddSlicer, AddTimeline, AddPivotChart, SetSlicerSelection / ToggleSlicerItem, SetPivotFieldShowAs, AddPivotCalculatedField, AddOlapConnection, DeletePivotTable.

Workflow 2 — Field List UI (demo)

1. Select a data range that includes a header row and data rows.
2. VCL demo: View → Pivot Field List → Insert PivotTable from selection.
3. Drag fields into Rows / Columns / Values / Filters.
4. Optionally insert a Slicer or PivotChart, set show-as / calculated fields, then Refresh.
5. FMX: use the DemoPivotPanel.Fmx sample frame (same actions).

Click slicer items on the sheet to filter and refresh linked pivots (undoable).

Workflow 3 — Slicer + PivotChart after a pivot exists

var
  S: TAuthoringSheet;
begin
  S := MagiXells1.Workbook.UseActiveSheet;
  { Assume SalesPT already created and refreshed }
  S.AddSlicer('RegionSlicer', 'SalesPT', 'Region', 'A20');
  S.AddPivotChart('SalesPT', 'E20', 8, 12);  { width cols, height rows }
  S.SetSlicerSelection('RegionSlicer', ['East']);  { or ToggleSlicerItem }
  S.RefreshPivotTable('SalesPT');
end;

Keep slicer field names aligned with the pivot model; see TAuthoringSheet in SheetAPI for related helpers (AddTimeline, ClearSlicerSelection, SetPivotFieldShowAs, …).

Formulas against pivots

S.Cell['G1'].Formula := '=GETPIVOTDATA("Amount",$E$1,"Region","East")';
MagiXells1.Recalculate;

See Formulas overview for categories and Formulas guide for recalc.

Layout and look

Refresh defaults to Excel Compact form (one “Row Labels” column, outline subtotals above children, indented leaves) with a PivotStyleMedium-like header/group/total fill.

P.LayoutForm := plfTabular;  { one column per row field }
S.RefreshPivotTable(P.Name);

Excel-loaded pivots keep their cell values and gain the same visual chrome via ApplyLoadedPivotStyles.

Filter / sort dropdowns (VCL)

Chevron buttons match Excel: report-filter value cells, Row Labels, and Column Labels (when column fields exist). Not on measure captions (“Sum of Amount”), value headers, or each product/item column. Click for Sort A↔︎Z, Clear Filter, and a value list.

Aggregates and options

Aggregates: Sum, Count, CountNums, Average, Min, Max, Product, StdDev/StdDevp, Var/Varp.

Show-values-as: % of grand/row/col, index, rank, running total — via SetPivotFieldShowAs.

Grouping: date levels, numeric buckets, manual item groups. Calculated fields (Field+Field / Field*n) and calculated items on the model (AddPivotCalculatedField).

I/O

Known limits

• Slicer/timeline painting and click-to-filter are implemented (sheet overlays + undoable selection).
• OLAP uses a mock connection provider unless you register a real one (AddOlapConnection / Connections).
• XLSX write still prefers MagiXells pivots.json for MagiXells-authored layout; Excel-authored pivots load from native OOXML.

See also

• SheetAPI
• AI agent API — pivot tools
• Formulas overview

Print

Page setup, preview, print area, and print titles via public control methods (VCL TMagiXells / FMX TFmxMagiXells) and SheetAPI. AI tools print_preview / print / set_print_area call the same host surface — see AI agent API.

Workflow 1 — Page setup → preview → print

1. Open page setup so the user can set paper, margins, orientation, headers/footers.
2. Preview with default or custom TPrintJobSettings.
3. Print (optionally showing the system print dialog).

uses
  MagiXells.PageSetup;

var
  Job: TPrintJobSettings;
begin
  { Modal page setup — True if the user accepted }
  if MagiXells1.ShowPageSetup then
    { changes are stored on the sheet/workbook page setup };

  MagiXells1.PrintPreview;           { default job }
  MagiXells1.Print(True);            { show print dialog }

  Job := TPrintJobSettings.Default;
  Job.What := pwActiveSheets;        { or pwSelection / pwEntireWorkbook }
  Job.Copies := 1;
  MagiXells1.PrintPreview(Job);
  MagiXells1.Print(Job, True);
end;

TPrintWhat: pwSelection, pwActiveSheets, pwEntireWorkbook.

Workflow 2 — Print area and repeating titles from selection

1. Select the block that should print (and/or title rows/cols).
2. Apply print area / titles from that selection.
3. Preview to confirm page breaks.

{ Selection is 0-based col/row on the control }
MagiXells1.SelectRange(0, 0, 5, 40);   { A1:F41 }
MagiXells1.SetPrintAreaFromSelection;
MagiXells1.SetPrintTitlesFromSelection;
MagiXells1.PrintPreview;
{ MagiXells1.ClearPrintArea; }

SheetAPI alternative (A1 strings)

var
  S: TAuthoringSheet;
begin
  S := MagiXells1.Workbook.UseActiveSheet;
  S.SetPrintArea('A1:F41');
  MagiXells1.PrintPreview;
  S.ClearPrintArea;
end;

Workflow 3 — Programmatic job without UI selection

Useful when a report button always prints a fixed region:

uses
  MagiXells.PageSetup;

var
  Job: TPrintJobSettings;
begin
  MagiXells1.Workbook.UseActiveSheet.SetPrintArea('A1:G50');

  Job := TPrintJobSettings.Default;
  Job.What := pwActiveSheets;
  Job.Copies := 2;
  MagiXells1.PrintPreview(Job);
  if MessageDlg('Send to printer?', mtConfirmation, [mbYes, mbNo], 0) = mrYes then
    MagiXells1.Print(Job, False);  { no extra dialog if you already confirmed }
end;

Tips

• Print area is stored on the sheet page setup and round-trips with MGX/XLSX where supported.
• Prefer setting print area before preview so the preview matches the job.
• For PDF export (vector, selectable text), use ExportToPdf — see Import / export — that path is separate from Print / PrintPreview.

See also

• TMagiXells print members
• Getting started
• AI agent API — print_preview, print, set_print_area

RTL and themes

Sheet right-to-left layout and host UI chrome (Appearance). Sheet RTL is a workbook/sheet concern; Appearance / presets are host chrome (selection, headers, tabs, editors, chart series) and are distinct from the workbook OOXML theme.

Full property lists: Host options & UiTheme API.

Workflow 1 — Enable sheet RTL for BiDi editing

1. Toggle RTL on the active sheet (control property or SheetAPI).
2. Load or type RTL text; verify caret, alignment, and grid painting.
3. Optionally match host chrome to a dark/light preset for your locale UI.

{ Control façade — active sheet }
MagiXells1.SheetRightToLeft := True;

{ SheetAPI — same effect on the authoring sheet }
MagiXells1.Workbook.UseActiveSheet.SetRtl(True);

{ Turn off later }
MagiXells1.SheetRightToLeft := False;

Load Arabic/RTL sample workbooks from the product samples folder (for example ARAB.mgx, RTL - Table.xlsx) to verify BiDi painting and editing.

AI: prompt “Turn on right-to-left for this sheet” → tool set_rtl.

Workflow 2 — Apply a UI theme preset (design-time or code)

Host chrome is Appearance: TMagiXellsUiTheme.

Design-time: select the MagiXells control → expand Appearance in the Object Inspector → set Preset. Presets are stored in the DFM/FMX (default Excel Light).

uses
  MagiXells.UiTheme;

MagiXells1.Appearance.Preset := utpExcelDarkGray;
{ or }
MagiXells1.Appearance.ApplyPreset(utpExcelDark);
{ or ApplyExcelLight / ApplyExcelDark / ApplyExcelDarkGray / ApplyMagiXellsBrand }

You can then override individual properties after the preset.

Workflow 3 — Batch custom chrome colors

Use BeginUpdate / EndUpdate so the grid does not repaint on every property:

MagiXells1.Appearance.BeginUpdate;
try
  MagiXells1.Appearance.SheetBackground := $00FFFFFF;
  MagiXells1.Appearance.SelectionBorder := $00595959;
  MagiXells1.Appearance.ActiveCellBorder := $00467321;
  MagiXells1.Appearance.ActiveCellBorderWidth := 2;
  MagiXells1.Appearance.HeaderBackground := $00F0F0F0;
  MagiXells1.Appearance.ChartSeries1 := $4472C4;
finally
  MagiXells1.Appearance.EndUpdate;
end;

Colors are TColor (COLORREF / BGR $00BBGGRR). For FMX surfaces use ColorRefToARGB when bridging to TAlphaColor.

Workflow 4 — Quick view colors (grid / freeze)

Independent of full UI presets — useful for subtle grid tweaks:

MagiXells1.ViewOptions.GridLineColor := $00D0D0D0;
MagiXells1.ViewOptions.FreezeLineColor := $00808080;

Combine with RTL:

MagiXells1.SheetRightToLeft := True;
MagiXells1.Appearance.ApplyPreset(utpExcelLight);
MagiXells1.ViewOptions.GridLineColor := $00C8C8C8;

See also

• Host options & UiTheme
• TMagiXells API
• Charts and drawings — chart series colors

AI agent guide

MagiXells ships the agent API; you own the chat UI (or use optional AI chat packages / demo panels).

Minimal VCL setup

uses
  MagiXells.AI.Types, MagiXells.AI.Agent, MagiXells.AI.Host.Vcl;

var
  Config: TMagiXellsAIConfig;
  Agent: TMagiXellsAIAgent;
begin
  Config := TMagiXellsAIConfig.Default;
  Config.Provider := aipOpenAICompatible; // or aipAnthropic
  Config.BaseUrl := 'https://api.openai.com/v1';
  Config.ApiKey := GetEnvironmentVariable('MAGIXELLS_AI_API_KEY');
  Config.Model := 'gpt-4o-mini';

  Agent := TMagiXellsAIAgent.Create(Config);
  try
    Agent.Host := TMagiXellsAIHost.Create(MagiXells1);
    Agent.OnMessage := MagiXells1Message;
    Agent.OnStatus := MagiXells1Status;
    Agent.OnToolCall := MagiXells1ToolCall;
    Agent.OnFinished := MagiXells1Finished;
    Agent.RunAsync('Build a one-page sales summary with a column chart');
  finally
    // keep Agent alive until OnFinished if using RunAsync from a field
  end;
end;

FMX: use MagiXells.AI.Host.Fmx and TFmxMagiXellsAIHost.Create(FmxMagiXells1).

C++Builder: same types via .hpp includes — see C++Builder — AI agent. Ask the agent for C++ Builder code to rebuild a sheet (export_sheet_cppbuilder).

Run vs RunAsync

Configuration tips

Config.MaxToolRounds := 40;
Config.TimeoutMs := 120000;
Config.Temperature := 0.2;
Config.MaxTokens := 0; // auto from model context
Config.ReasoningEffort := ''; // or none|low|medium|high for compatible APIs
Agent.UpdateConfig(Config);

List models from the server:

var
  Models: TArray<string>;
  I: Integer;
begin
  Models := Agent.ListModels;
  for I := 0 to High(Models) do
    cbModel.Items.Add(Models[I]);
end;

Demo settings

Copy ai-settings.ini.example from the product demos folder next to your EXE as ai-settings.ini, or set:

• MAGIXELLS_AI_BASE_URL
• MAGIXELLS_AI_API_KEY
• MAGIXELLS_AI_MODEL

Sample chat UI: product demos → View → AI Agent. Chat colors are TMagiXellsAIChatTheme (optional AI packages / demo panel) — they are not stored on TMagiXells.Appearance.

Tools

The agent exposes dozens of tools (get_range, set_cells, insert_chart, …). Mutations go through undo commands. Full catalog: AI agent API.

Confirm dangerous tools (optional)

function TForm1.AgentConfirmTool(Sender: TObject; const AToolName,
  AArgumentsJson: string): Boolean;
begin
  Result := MessageDlg('Allow tool ' + AToolName + '?', mtConfirmation,
    [mbYes, mbNo], 0) = mrYes;
end;

Agent.OnConfirmTool := AgentConfirmTool;

See also

• AI agent API
• Architecture

C++Builder

MagiXells is implemented in Delphi and ships as RAD Studio packages. C++Builder (VCL and FMX) consumes the same Public/Published API through generated .hpp headers. There is no separate C++ MagiXells library.

Delphi class helpers (for example TWorksheet.Cell['A1'] and TWorkbook.UseActiveSheet) do not appear in C++. Prefer TSheetCellRef::Create, TSheetRangeRef::Create, and TAuthoringSheet::Create — the same surface the AI export_sheet_cppbuilder tool emits.

Prerequisites

• RAD Studio with C++Builder (same supported IDE versions as the MagiXells installer: Delphi / C++Builder 12 or 13)
• MagiXells Trial or Runtime Setup.exe (see Getting started)

Install packages for C++Builder

1. Close the IDE.
2. Run MagiXells-Trial-Setup.exe or MagiXells-Runtime-Setup.exe.
3. Restart RAD Studio.
4. In a C++Builder VCL or FMX project, confirm TMagiXells / TFmxMagiXells appear on the MagiXells palette.

Project settings (typical)

• Runtime packages: link against MagiXellsCore, MagiXellsPkg (VCL) or MagiXellsFmx (FMX); optional MagiXellsAIPkg / MagiXellsAIFmx (the installer registers these for the IDE).
• Include / library path: use the paths the Setup registered under your BDS common directory (headers and libraries for C++Builder are installed with the product).

Drop a control (VCL)

1. New C++Builder VCL Application.
2. Drop TMagiXells from the MagiXells palette; set Align = alClient.

#include <MagiXells.Spreadsheet.hpp>

void __fastcall TForm1::FormCreate(TObject *Sender)
{
  MagiXells1->Align = alClient;
  MagiXells1->NewWorkbook();
}

Drop a control (FMX)

#include <MagiXells.Spreadsheet.Fmx.hpp>

void __fastcall TForm1::FormCreate(TObject *Sender)
{
  FmxMagiXells1->Align = TAlignLayout::Client;
  FmxMagiXells1->NewWorkbook();
}

Load and save

MagiXells1->LoadFromFile(L"C:\\Data\\report.xlsx");
MagiXells1->SaveToFile(L"C:\\Data\\report.mgx");

Streams (explicit format):

#include <MagiXells.Types.hpp>
#include <System.Classes.hpp>

void SaveAndReloadXlsx(TMagiXells *Grid)
{
  auto *MS = new TMemoryStream();
  try {
    Grid->SaveToStream(MS, TMagiXellsFileFormat::ffXlsx);
    MS->Position = 0;
    Grid->LoadFromStream(MS, TMagiXellsFileFormat::ffXlsx);
  } __finally {
    delete MS;
  }
}

Enum spelling in C++ follows the generated header (ffXlsx, sometimes scoped as TMagiXellsFileFormat::ffXlsx depending on RAD Studio / HPP style). Use Code Completion on TMagiXellsFileFormat.

Control API (selection-based)

Same Public methods as Delphi; use -> and C++ literals:

MagiXells1->SelectRange(0, 0, 2, 0); // A1:C1 (0-based)
MagiXells1->SetNumberFormat(L"0.00");
MagiXells1->MergeCells();

if (MagiXells1->CanUndo)
  MagiXells1->Undo();

MagiXells1->Behavior->AllowEdit = true;
MagiXells1->Zoom = 120;
MagiXells1->SheetRightToLeft = false;

Events

Wire in the Object Inspector or assign in code:

void __fastcall TForm1::MagiXells1SelectionChanged(TObject *Sender)
{
  Caption = Format(L"Col=%d Row=%d",
    ARRAYOFCONST((MagiXells1->ActiveCol, MagiXells1->ActiveRow)));
}

// FormCreate:
MagiXells1->OnSelectionChanged = MagiXells1SelectionChanged;

Active-cell gate:

void __fastcall TForm1::MagiXells1ActiveCellChanging(TObject *Sender,
  int ACol, int ARow, bool &Allow)
{
  Allow = ARow >= 1; // lock header row
}

Full event list: TMagiXells API (Delphi signatures; C++ uses the generated method-pointer types).

SheetAPI without class helpers

#include <MagiXells.SheetAPI.hpp>
#include <MagiXells.SheetAPI.Colors.hpp>

void FillDemo(TMagiXells *Grid)
{
  TWorksheet *Sheet = Grid->ActiveSheet;

  {
    TSheetCellRef C = TSheetCellRef::Create(Sheet, L"A1");
    C.Text = L"Hello";
    C.FontBold = true;
    C.FontSize = 14;
  }

  {
    TSheetCellRef C = TSheetCellRef::Create(Sheet, L"B1");
    C.AsNumber = 42;
  }

  {
    TSheetCellRef C = TSheetCellRef::Create(Sheet, L"C1");
    C.Formula = L"=B1*2";
  }

  TSheetRangeRef::Create(Sheet, L"A1:C1").BorderAround(TBorderLineStyle::blsThin);

  Grid->Recalculate();
}

Authoring sheet façade

TAuthoringSheet S = TAuthoringSheet::Create(Grid->Workbook, Grid->ActiveSheet);
TSheetCellRef C = TSheetCellRef::Create(S.Sheet, L"A2");
C.Text = L"Via TAuthoringSheet";
// Charts, tables, validation, etc. — same Public methods as Delphi SheetAPI:
// S.AddChart(...); S.AddTable(...); S.SetPrintArea(...);

See SheetAPI for the full Public member list.

Formulas and named ranges

MagiXells1->NamedRanges->AddOrSet(L"TaxRate", L"0.2");

TSheetCellRef C = TSheetCellRef::Create(MagiXells1->ActiveSheet, L"B1");
C.Formula = L"=1000*TaxRate";
MagiXells1->Recalculate();

AI agent (VCL)

#include <MagiXells.AI.Types.hpp>
#include <MagiXells.AI.Agent.hpp>
#include <MagiXells.AI.Host.Vcl.hpp>

void __fastcall TForm1::StartAgent()
{
  TMagiXellsAIConfig Config = TMagiXellsAIConfig::Default();
  Config.Provider = TMagiXellsAIProvider::aipOpenAICompatible;
  Config.BaseUrl = L"https://api.openai.com/v1";
  Config.ApiKey = GetEnvironmentVariable(L"MAGIXELLS_AI_API_KEY");
  Config.Model = L"gpt-4o-mini";

  // Keep Agent as a form field for RunAsync lifetime
  FAgent = new TMagiXellsAIAgent(Config);
  FAgent->Host = new TMagiXellsAIHost(MagiXells1);
  FAgent->OnMessage = AgentMessage;
  FAgent->OnFinished = AgentFinished;
  FAgent->RunAsync(L"Create a sales table with totals and a column chart");
}

FMX: #include <MagiXells.AI.Host.Fmx.hpp> and new TFmxMagiXellsAIHost(FmxMagiXells1).

Ask the agent for C++ Builder source to rebuild a sheet — it calls export_sheet_cppbuilder (see AI agent API).

Delphi ↔︎ C++ quick map

Demos

After install, open the VCL/FMX demos from Start Menu → Binary Magic → MagiXells. Use them as behavioral reference when writing a C++Builder host.

See also

• Getting started
• TMagiXells API
• SheetAPI
• AI agent guide
• Architecture

Formulas overview

MagiXells includes an Excel-oriented formula engine with a dependency graph, ~500 builtins, dynamic arrays, and LAMBDA/LET family support.

This page is a capability overview, not a full Excel function encyclopedia. Prefer Excel documentation for individual function semantics; MagiXells aims for compatible behavior. For recalc, named ranges, and evaluator details see Formulas guide.

Using formulas from code

var
  S: TAuthoringSheet;
begin
  S := MagiXells1.Workbook.UseActiveSheet;
  S.Cell['A1'].AsNumber := 10;
  S.Cell['A2'].Formula := '=A1*2';
  MagiXells1.Recalculate;
end;

Evaluate without writing a cell:

var
  V: TCellValue;
begin
  V := MagiXells1.Evaluator.Evaluate('=SUM(A1:A10)');
  ShowMessage(V.ToDisplayString);
end;

Named ranges:

MagiXells1.NamedRanges.AddOrSet('Rate', '0.08');
S.Cell['B1'].Formula := '=1000*Rate';
MagiXells1.Recalculate;

AI: tools evaluate_formula, explain_formula, list_formula_errors — see AI agent API.

Categories (representative)

Each category keeps a short example list, plus one worked SheetAPI snippet.

Math / trig

Examples: SUM, AVERAGE, ROUND, ABS, POWER, MOD, PI, SQRT

S.Cell['A1'].AsNumber := 2.4;
S.Cell['A2'].AsNumber := 3.6;
S.Cell['B1'].Formula := '=ROUND(SUM(A1:A2), 0)';  { 6 }
MagiXells1.Recalculate;

Statistical

Examples: MIN, MAX, STDEV, MEDIAN, COUNT, COUNTA, COUNTIF

S.Cell['A1'].AsNumber := 10;
S.Cell['A2'].AsNumber := 20;
S.Cell['A3'].AsNumber := 30;
S.Cell['B1'].Formula := '=AVERAGE(A1:A3)';
S.Cell['B2'].Formula := '=COUNTIF(A1:A3,">15")';  { 2 }
MagiXells1.Recalculate;

Logical

Examples: IF, AND, OR, NOT, IFS, IFERROR, IFNA

S.Cell['A1'].AsNumber := 0;
S.Cell['B1'].Formula := '=IFERROR(1/A1, "n/a")';
S.Cell['B2'].Formula := '=IF(AND(A1>=0, A1<100), "ok", "out")';
MagiXells1.Recalculate;

Text

Examples: LEFT, RIGHT, MID, LEN, TRIM, UPPER, LOWER, TEXT, VALUE

S.Cell['A1'].Text := '  magixells  ';
S.Cell['B1'].Formula := '=UPPER(TRIM(A1))';  { MAGIXELLS }
S.Cell['B2'].Formula := '=LEFT(B1, 4)';     { MAGI }
MagiXells1.Recalculate;

Lookup / ref

Examples: VLOOKUP, HLOOKUP, INDEX, MATCH, XLOOKUP, ADDRESS, INDIRECT, OFFSET

S.Cell['A1'].Text := 'Code';
S.Cell['B1'].Text := 'Name';
S.Cell['A2'].Text := 'W1';
S.Cell['B2'].Text := 'Widget';
S.Cell['A3'].Text := 'G1';
S.Cell['B3'].Text := 'Gadget';
S.Cell['D1'].Text := 'W1';
S.Cell['E1'].Formula := '=XLOOKUP(D1, A2:A3, B2:B3)';  { Widget }
MagiXells1.Recalculate;

Date / time

Examples: TODAY, NOW, DATE, YEAR, MONTH, DAY, EOMONTH, NETWORKDAYS

S.Cell['A1'].Formula := '=DATE(2026, 9, 5)';
S.Cell['B1'].Formula := '=EOMONTH(A1, 0)';
S.Cell['C1'].Formula := '=NETWORKDAYS(A1, B1)';
MagiXells1.Recalculate;

Financial

Examples: PMT, FV, PV, NPER, RATE, NPV, IRR

{ Loan: 5% annual, 60 months, $10,000 principal }
S.Cell['A1'].Formula := '=PMT(0.05/12, 60, -10000)';
MagiXells1.Recalculate;

Information

Examples: ISBLANK, ISNUMBER, ISTEXT, ISERROR, TYPE

S.Cell['A1'].Text := 'x';
S.Cell['B1'].Formula := '=IF(ISNUMBER(A1), A1, VALUE("0"))';
S.Cell['B2'].Formula := '=ISTEXT(A1)';  { TRUE }
MagiXells1.Recalculate;

Dynamic arrays

Examples: FILTER, SEQUENCE, UNIQUE, SORT, SORTBY, TRANSPOSE, HSTACK, VSTACK, TOROW, TOCOL, TAKE, DROP, EXPAND, RANDARRAY, GROUPBY, PIVOTBY

S.Cell['D1'].Formula := '=SEQUENCE(5)';
MagiXells1.Recalculate;
{ D1:D5 spill; conflicts surface as #SPILL! }

S.Cell['A1'].Text := 'Region';
S.Cell['B1'].Text := 'Amt';
S.Cell['A2'].Text := 'East';
S.Cell['B2'].AsNumber := 10;
S.Cell['A3'].Text := 'West';
S.Cell['B3'].AsNumber := 20;
S.Cell['A4'].Text := 'East';
S.Cell['B4'].AsNumber := 5;
S.Cell['D1'].Formula := '=UNIQUE(A2:A4)';
MagiXells1.Recalculate;

Lambda family

Examples: LAMBDA, LET, MAP, BYROW, BYCOL, REDUCE, SCAN, MAKEARRAY, ISOMITTED

S.Cell['A1'].AsNumber := 2;
S.Cell['A2'].AsNumber := 3;
S.Cell['B1'].Formula := '=LET(x, A1, y, A2, x*y+1)';  { 7 }
S.Cell['B2'].Formula := '=MAP(A1:A2, LAMBDA(v, v*10))';
MagiXells1.Recalculate;

Pivot / cube

Examples: GETPIVOTDATA, FIELDVALUE, CUBEVALUE, CUBEMEMBER, …

{ After a pivot exists with values at E1 — see guide-pivots.md }
S.Cell['G1'].Formula := '=GETPIVOTDATA("Amount",$E$1,"Region","East")';
MagiXells1.Recalculate;

CUBE* needs a workbook connection (mock OLAP supported). See PivotTables.

Implicit intersection

@ prefix (e.g. @FILTER(...)) yields a scalar.

S.Cell['A1'].Formula := '=@SEQUENCE(5)';  { scalar from spill }
MagiXells1.Recalculate;

Dynamic arrays / spill

Spill formulas write into a spill range. Conflicts surface as #SPILL!.

S.Cell['D1'].Formula := '=SEQUENCE(5)';
MagiXells1.Recalculate;

Use MaterializeSpillAsTable on SheetAPI to convert a live spill into a sheet Table + AutoFilter after the fact (see web/import notes below).

Auto vs manual calculate

MagiXells1.Behavior.AutoCalculate := True;  // default
{ or batch edits: }
MagiXells1.Behavior.AutoCalculate := False;
{ … many cell writes … }
MagiXells1.Recalculate;

Show formulas

MagiXells1.ShowFormulas := True;

Web / RTD / stock / import

ENCODEURL, WEBSERVICE, FILTERXML, IMPORTHTML, IMPORTDATA, IMPORTXML, IMPORTFEED, IMPORTRANGE, GOOGLEFINANCE, GOOGLETRANSLATE / TRANSLATE, DETECTLANGUAGE, STOCKHISTORY, and RTD are implemented. Host apps can supply providers on TMagiXells (StockHistoryProvider, RtdProvider, GoogleFinanceProvider, TranslateProvider, ImportRangeProvider). Default STOCKHISTORY / GOOGLEFINANCE (common attributes) use Yahoo Finance; RTD falls back to Windows COM; translate / IMPORTRANGE need a host provider (#N/A otherwise). IMPORTHTML accepts optional MagiXells trailing args: a GVQL filter/sort string and/or TRUE to materialize as a sheet Table + AutoFilter (Google’s 3-arg form still works).

Also: REGEXEXTRACT / REGEXREPLACE / REGEXMATCH / REGEXTEST, ISEMAIL, ISURL, JOIN, ARRAY_CONSTRAIN, and QUERY (Google Visualization Query Language subset).

S.Cell['A1'].Formula := '=ENCODEURL("a b")';
S.Cell['A2'].Text := 'user@example.com';
S.Cell['B2'].Formula := '=ISEMAIL(A2)';
MagiXells1.Recalculate;

Still #N/A (not yet)

CALL, REGISTER.ID, PYTHON, locale/DBCS helpers, AGGREGATE, CELL, FORECAST.ETS*, FINV / BETA.INV, IMAGE, etc.

See also

• Formulas guide
• AI evaluate_formula / explain_formula
• PivotTables

API reference index

Only Public and Published members are documented. Developers on Trial/Runtime installs have no library source — docs must stand alone.

Member page pattern

Every constant, type, property, method, and event uses this shape (see types.md for the reference quality bar):

### MemberName
**Visibility:** public | published
**Declaration**

```delphi {.declaration}
…
```

```cpp {.declaration}
…
```
**Where used:** When/why a host needs this (scenario, pitfalls, related APIs).

**How to use:**

```delphi
{ Concrete snippet a developer can paste — not only MagiXells1.Foo; }
```

Declarations use DocWiki-style Delphi and C++ fences ({.declaration}). How to use samples stay Delphi-first; for C++ call shapes and SheetAPI without helpers, see C++Builder. - Prefer 1-based core addresses (TCellAddress) and A1 + SheetAPI in samples unless the API is explicitly 0-based. - Mention C++Builder when the call shape differs; otherwise link C++Builder. - Group related members, but do not skip Where/How on individual members.

Controls

• TMagiXells / TFmxMagiXells — drop-in spreadsheet control
  Units: MagiXells.Spreadsheet (VCL), MagiXells.Spreadsheet.Fmx (FMX)

Core types

• MagiXells.Types — addresses, ranges, cell values, file formats, ColToLetters
  Unit: MagiXells.Types

Host configuration

• Host options & UiTheme
  Units: MagiXells.HostOptions, MagiXells.UiTheme

Programmatic authoring

• SheetAPI
  Unit: MagiXells.SheetAPI (+ MagiXells.SheetAPI.Colors)

AI

• AI agent
  Units: MagiXells.AI.Types, MagiXells.AI.Agent, MagiXells.AI.Host, MagiXells.AI.Host.Vcl / .Fmx, MagiXells.AI.Tools

Related guides

• Getting started
• C++Builder
• Workbook & editing
• Import / export
• AI agent guide

TMagiXells / TFmxMagiXells

Drop-in spreadsheet control for host applications. The VCL and FMX classes share the same MagiXells workbook model; chrome and layout differ by framework.

Trial / Runtime: Installs ship compiled packages only (no library .pas). This page is the public contract for hosts without source. Prefer A1 + SheetAPI for cell authoring; use control methods for selection, chrome, I/O, and UI events. Shared types: MagiXells.Types. Formats: Import / export. Host option objects: Host options & UiTheme.

Examples use MagiXells1: TMagiXells (Delphi). For FMX, use FmxMagiXells1: TFmxMagiXells — MagiXells members match unless a VCL/FMX note says otherwise. C++Builder: C++Builder (->, .hpp, no class helpers).

Convention: Cell column/row indexes on this control (SelectCell, SelectRange, ActiveCol/ActiveRow, DeleteRows/InsertColumns, event Col/Row) are 1-based (column 1 = A, row 1 = first row), matching Excel and TCellAddress. Sheet indexes (ActiveSheetIndex, RemoveSheet, …) are 0-based.

uses
  MagiXells.Types,
  MagiXells.Spreadsheet,   { or MagiXells.Spreadsheet.Fmx }
  MagiXells.SheetAPI;

begin
  MagiXells1.NewWorkbook;
  MagiXells1.Workbook.UseActiveSheet.Cell['A1'].Text := 'Hello';
  MagiXells1.SelectCell(1, 1);  { A1 — 1-based }
  MagiXells1.SaveToFile('C:\Data\demo.mgx');
end;

Lifetime

Create

Visibility: public
Declaration

constructor Create(AOwner: TComponent); override;

__fastcall Create(System::Classes::TComponent* AOwner)/* override */;

Where used: Create the control at runtime (not dropped from the palette). Owner frees it with the form/frame.

How to use:

{ VCL }
MagiXells1 := TMagiXells.Create(Self);
MagiXells1.Parent := Self;
MagiXells1.Align := alClient;

{ FMX }
FmxMagiXells1 := TFmxMagiXells.Create(Self);
FmxMagiXells1.Parent := Self;
FmxMagiXells1.Align := TAlignLayout.Client;

Destroy

Visibility: public
Declaration

destructor Destroy; override;

__fastcall ~Destroy();/* override */

Where used: Explicit teardown when the control has no owner, or before replacing an instance. Prefer letting AOwner free it.

How to use:

MagiXells1.Free;  { or FreeAndNil(MagiXells1) }

GetChildren

Visibility: public (VCL)
Declaration

procedure GetChildren(Proc: TGetChildProc; Root: TComponent); override;

void __fastcall GetChildren(
  TGetChildProc Proc,
  System::Classes::TComponent* Root
)/* override */;

Where used: Streaming / designer. MagiXells overrides this so formula bar, grid, and sheet tabs stay subcomponents, not form children (avoids DFM grab-handle issues). Hosts almost never call this.

How to use:

{ Do not stream inner chrome as owned form controls — leave the override alone. }

SetFocus

Visibility: public (VCL)
Declaration

procedure SetFocus; override;

void __fastcall SetFocus()/* override */;

Where used: Moves keyboard focus to the grid sheet, not the formula bar. Click the formula bar to edit there. FMX uses the normal TControl focus path on the composite.

How to use:

MagiXells1.SetFocus;  { sheet receives keys }

Workbook I/O

NewWorkbook

Visibility: public
Declaration

procedure NewWorkbook;

void __fastcall NewWorkbook();

Where used: Start a blank workbook (File → New). Discards the current in-memory book — prompt to save first if Modified.

How to use:

if MagiXells1.IsModified then
  if MessageDlg('Save changes?', mtConfirmation, [mbYes, mbNo], 0) = mrYes then
    MagiXells1.SaveToFile(CurrentPath);
MagiXells1.NewWorkbook;

LoadFromFile

Visibility: public
Declaration

procedure LoadFromFile(const AFileName: string);

void __fastcall LoadFromFile(const System::UnicodeString AFileName);

Where used: Open .mgx, .xlsx/.xlsm, .ods, or .csv by extension (ffAuto). Large files report via OnProgress. See Import / export.

How to use:

MagiXells1.LoadFromFile('C:\Data\report.xlsx');
Caption := MagiXells1.ActiveSheet.Name;

SaveToFile

Visibility: public
Declaration

procedure SaveToFile(const AFileName: string);

void __fastcall SaveToFile(const System::UnicodeString AFileName);

Where used: Persist the workbook; extension selects format. A .pdf path is an export convenience — prefer ExportToPdf for PDF jobs.

How to use:

MagiXells1.SaveToFile('C:\Data\report.mgx');
MagiXells1.SaveToFile('C:\Data\report.xlsx');

LoadFromStream

Visibility: public
Declaration

procedure LoadFromStream(AStream: TStream; const AFormat: TMagiXellsFileFormat);

void __fastcall LoadFromStream(
  System::Classes::TStream* AStream,
  const TMagiXellsFileFormat AFormat
);

Where used: Load from memory, blobs, or resources with no file extension. Streams require an explicit TMagiXellsFileFormat (ffAuto is not enough).

How to use:

uses MagiXells.Types, System.Classes;

procedure LoadXlsxBytes(AGrid: TMagiXells; const ABytes: TBytes);
var
  MS: TMemoryStream;
begin
  MS := TMemoryStream.Create;
  try
    if Length(ABytes) > 0 then
      MS.WriteBuffer(ABytes[0], Length(ABytes));
    MS.Position := 0;
    AGrid.LoadFromStream(MS, ffXlsx);
  finally
    MS.Free;
  end;
end;

SaveToStream

Visibility: public
Declaration

procedure SaveToStream(AStream: TStream; const AFormat: TMagiXellsFileFormat);

void __fastcall SaveToStream(
  System::Classes::TStream* AStream,
  const TMagiXellsFileFormat AFormat
);

Where used: Serialize without touching disk (upload, tests). Pass ffMgx / ffXlsx / ffOds / ffCsv explicitly.

How to use:

var MS: TMemoryStream;
begin
  MS := TMemoryStream.Create;
  try
    MagiXells1.SaveToStream(MS, ffOds);
    MS.Position := 0;
    { upload MS }
  finally
    MS.Free;
  end;
end;

ExportToPdf

Visibility: public
Declaration

procedure ExportToPdf(const AFileName: string); overload;

void __fastcall ExportToPdf(const System::UnicodeString AFileName) /* overload */;

Where used: One-shot PDF using default print-job settings. Does not replace the workbook file.

How to use:

MagiXells1.ExportToPdf('C:\Data\report.pdf');

ExportToPdf (job)

Visibility: public
Declaration

procedure ExportToPdf(const AFileName: string; const AJob: TPrintJobSettings); overload;

void __fastcall ExportToPdf(
  const System::UnicodeString AFileName,
  const TPrintJobSettings AJob
) /* overload */;

Where used: PDF with explicit print scope (selection / sheet / workbook) and page options.

How to use:

var Job: TPrintJobSettings;
begin
  Job := TPrintJobSettings.Default;
  Job.What := pwEntireWorkbook;
  MagiXells1.ExportToPdf('C:\Data\book.pdf', Job);
end;

ExportToCsv

Visibility: public
Declaration

procedure ExportToCsv(const AFileName: string); overload;

void __fastcall ExportToCsv(const System::UnicodeString AFileName) /* overload */;

Where used: Quick CSV of the active sheet with default options.

How to use:

MagiXells1.ExportToCsv('C:\Data\sheet.csv');

ExportToCsv (options)

Visibility: public
Declaration

procedure ExportToCsv(const AFileName: string; const AOptions: TCsvExportOptions); overload;

void __fastcall ExportToCsv(
  const System::UnicodeString AFileName,
  const TCsvExportOptions AOptions
) /* overload */;

Where used: Custom delimiter, selection-only export, etc. (MagiXells.IO.Csv). See guide-io.

How to use:

uses MagiXells.IO.Csv;
var Opt: TCsvExportOptions;
begin
  Opt := TCsvExportOptions.Default;
  Opt.Delimiter := ';';
  Opt.What := pwSelection;
  MagiXells1.SelectRange(TCellRange.FromA1('A1:C20'));
  MagiXells1.ExportToCsv('C:\Data\selection.csv', Opt);
end;

Recalculate

Visibility: public
Declaration

procedure Recalculate;

void __fastcall Recalculate();

Where used: Force a full workbook formula pass after bulk programmatic edits, or when Behavior.AutoCalculate is off. Same engine as Evaluator.RecalculateAll.

How to use:

MagiXells1.BeginUpdate;
try
  MagiXells1.Workbook.UseActiveSheet.Cell['A1'].AsNumber := 10;
  MagiXells1.Workbook.UseActiveSheet.Cell['A2'].Formula := '=A1*2';
finally
  MagiXells1.EndUpdate;
end;
MagiXells1.Recalculate;

IsModified

Visibility: public
Declaration

function IsModified: Boolean;

bool __fastcall IsModified();

Where used: Dirty check before close / navigation. Same flag as published Modified.

How to use:

if MagiXells1.IsModified then
  MagiXells1.SaveToFile(Path);

BeginUpdate

Visibility: public
Declaration

procedure BeginUpdate; { FMX: reintroduce }

void __fastcall BeginUpdate(); /* FMX: reintroduce */

Where used: Nesting-safe batch. While locked: paints deferred; formula auto-calc / live charts deferred; auto row-height skipped; OnModified deferred (workbook still marks modified). Always pair with EndUpdate in try/finally.

How to use:

MagiXells1.BeginUpdate;

EndUpdate

Visibility: public
Declaration

procedure EndUpdate; { FMX: reintroduce }

void __fastcall EndUpdate(); /* FMX: reintroduce */

Where used: Ends the outer batch and flushes: full recalc (if Behavior.AutoCalculate), auto row heights, chart refresh, one grid repaint, then OnModified if needed.

How to use:

MagiXells1.BeginUpdate;
try
  { many SheetAPI / selection edits }
finally
  MagiXells1.EndUpdate;
end;

OnCellChanged is for interactive edits (inplace commit, fill, …). Programmatic SheetAPI / SetCell changes do not fire it. Selection and other events are not suppressed.

Protection

Protect

Visibility: public
Declaration

procedure Protect;

void __fastcall Protect();

Where used: Protect the active sheet (Worksheet.Protected := True). Combine with locked cells and Protection for host UI locks.

How to use:

MagiXells1.Protect;

Unprotect

Visibility: public
Declaration

procedure Unprotect;

void __fastcall Unprotect();

Where used: Clear active-sheet protection after an authorized host action (password UI is yours).

How to use:

MagiXells1.Unprotect;

ProtectStructure

Visibility: public
Declaration

procedure ProtectStructure;

void __fastcall ProtectStructure();

Where used: Lock workbook structure (add/delete/rename/reorder sheets). Sets Protection.ProtectStructure and Workbook.StructureProtected.

How to use:

MagiXells1.ProtectStructure;

UnprotectStructure

Visibility: public
Declaration

procedure UnprotectStructure;

void __fastcall UnprotectStructure();

Where used: Allow sheet structure changes again from code/UI.

How to use:

MagiXells1.UnprotectStructure;

Formatting (selection)

These apply to the current selection on the active sheet. Prefer SheetAPI when formatting by A1 without changing the user’s selection.

MergeCells

Visibility: public
Declaration

procedure MergeCells;

void __fastcall MergeCells();

Where used: Merge the selected rectangle (Excel-like). Select first, then merge.

How to use:

MagiXells1.SelectRange(1, 1, 3, 1);  { A1:C1 — 1-based }
MagiXells1.MergeCells;

UnmergeCells

Visibility: public
Declaration

procedure UnmergeCells;

void __fastcall UnmergeCells();

Where used: Split merges that intersect the selection.

How to use:

MagiXells1.SelectRange(TCellRange.FromA1('A1:C1'));
MagiXells1.UnmergeCells;

SetFont

Visibility: public
Declaration

procedure SetFont(const AFont: TCellFontInfo);

void __fastcall SetFont(const TCellFontInfo AFont);

Where used: Apply font fields to the selection (toolbar Bold/Italic, theme fonts).

How to use:

var F: TCellFontInfo;
begin
  F := MagiXells1.GetActiveCellFormat.Font;
  F.Name := 'Calibri';
  F.Size := 11;
  F.Bold := True;
  MagiXells1.SetFont(F);
end;

SetFill

Visibility: public
Declaration

procedure SetFill(const AFill: TCellFillInfo);

void __fastcall SetFill(const TCellFillInfo AFill);

Where used: Fill / highlight the selection.

How to use:

var Fill: TCellFillInfo;
begin
  Fill := Default(TCellFillInfo);
  Fill.PatternType := cfpSolid;
  Fill.FgColor.RGB := $00FFFFCC;
  MagiXells1.SetFill(Fill);
end;

SetBorder

Visibility: public
Declaration

procedure SetBorder(const ABorder: TCellBorderInfo);

void __fastcall SetBorder(const TCellBorderInfo ABorder);

Where used: Apply border sides/styles to the selection.

How to use:

var B: TCellBorderInfo;
begin
  B := Default(TCellBorderInfo);
  B.Left.Style := cbsThin;
  B.Right.Style := cbsThin;
  B.Top.Style := cbsThin;
  B.Bottom.Style := cbsThin;
  MagiXells1.SetBorder(B);
end;

SetAlignment

Visibility: public
Declaration

procedure SetAlignment(const AAlign: TCellAlignmentInfo);

void __fastcall SetAlignment(const TCellAlignmentInfo AAlign);

Where used: Horizontal/vertical align, wrap, indent on the selection.

How to use:

var A: TCellAlignmentInfo;
begin
  A := Default(TCellAlignmentInfo);
  A.Horizontal := haCenter;
  A.Vertical := vaCenter;
  A.WrapText := True;
  MagiXells1.SetAlignment(A);
end;

SetNumberFormat

Visibility: public
Declaration

procedure SetNumberFormat(const AFormat: string);

void __fastcall SetNumberFormat(const System::UnicodeString AFormat);

Where used: Excel-style number format codes on the selection (#,##0.00, yyyy-mm-dd, …).

How to use:

MagiXells1.SelectRange(TCellRange.FromA1('B2:B100'));
MagiXells1.SetNumberFormat('#,##0.00');

GetActiveCellFormat

Visibility: public
Declaration

function GetActiveCellFormat: TCellFormat;

TCellFormat __fastcall GetActiveCellFormat();

Where used: Sync a formatting ribbon/toolbar to the active cell.

How to use:

var Fmt: TCellFormat;
begin
  Fmt := MagiXells1.GetActiveCellFormat;
  actBold.Checked := Fmt.Font.Bold;
  edtNumFmt.Text := Fmt.NumberFormat;
end;

Clipboard

CopySelection

Visibility: public
Declaration

procedure CopySelection;

void __fastcall CopySelection();

Where used: Host Edit → Copy / Ctrl+C when MagiXells should own the clipboard.

How to use:

MagiXells1.CopySelection;

CutSelection

Visibility: public
Declaration

procedure CutSelection;

void __fastcall CutSelection();

Where used: Edit → Cut. Respects protection / Behavior.AllowCopy.

How to use:

MagiXells1.CutSelection;

PasteAll

Visibility: public
Declaration

procedure PasteAll;

void __fastcall PasteAll();

Where used: Full paste (values + formulas + formats) at the active cell / selection.

How to use:

MagiXells1.PasteAll;

PasteValues

Visibility: public
Declaration

procedure PasteValues;

void __fastcall PasteValues();

Where used: Paste values only (strip formulas).

How to use:

MagiXells1.PasteValues;

PasteFormulas

Visibility: public
Declaration

procedure PasteFormulas;

void __fastcall PasteFormulas();

Where used: Paste formulas (adjusted) without forcing all cosmetics.

How to use:

MagiXells1.PasteFormulas;

PasteFormats

Visibility: public
Declaration

procedure PasteFormats;

void __fastcall PasteFormats();

Where used: Paste formats only onto the selection.

How to use:

MagiXells1.PasteFormats;

Clear

ClearContents

Visibility: public
Declaration

procedure ClearContents;

void __fastcall ClearContents();

Where used: Clear Contents on the selection (keeps formats). Undoable.

How to use:

MagiXells1.SelectRange(TCellRange.FromA1('A1:C10'));
MagiXells1.ClearContents;

ClearFormats

Visibility: public
Declaration

procedure ClearFormats;

void __fastcall ClearFormats();

Where used: Strip formats from the selection; leave values/formulas.

How to use:

MagiXells1.ClearFormats;

ClearAll

Visibility: public
Declaration

procedure ClearAll;

void __fastcall ClearAll();

Where used: Clear both contents and formats on the selection.

How to use:

MagiXells1.ClearAll;

Rows / columns

Row/column start indexes are 1-based (AStart < 1 is ignored). ACount defaults to 1. Requires Behavior.AllowDelete / AllowInsert as appropriate.

DeleteRows

Visibility: public
Declaration

procedure DeleteRows(AStartRow: Integer; ACount: Integer = 1);

void __fastcall DeleteRows(int AStartRow, int ACount = 1);

Where used: Delete whole rows starting at a 1-based row.

How to use:

MagiXells1.DeleteRows(5, 2);  { delete rows 5 and 6 }

DeleteColumns

Visibility: public
Declaration

procedure DeleteColumns(AStartCol: Integer; ACount: Integer = 1);

void __fastcall DeleteColumns(int AStartCol, int ACount = 1);

Where used: Delete whole columns starting at a 1-based column (1 = A).

How to use:

MagiXells1.DeleteColumns(3, 1);  { delete column C }

InsertRows

Visibility: public
Declaration

procedure InsertRows(AStartRow: Integer; ACount: Integer = 1);

void __fastcall InsertRows(int AStartRow, int ACount = 1);

Where used: Insert blank rows before AStartRow (1-based).

How to use:

MagiXells1.InsertRows(2, 3);  { insert 3 rows above row 2 }

InsertColumns

Visibility: public
Declaration

procedure InsertColumns(AStartCol: Integer; ACount: Integer = 1);

void __fastcall InsertColumns(int AStartCol, int ACount = 1);

Where used: Insert blank columns before AStartCol (1-based).

How to use:

MagiXells1.InsertColumns(1, 1);  { insert a column before A }

DeleteSelectionRows

Visibility: public
Declaration

procedure DeleteSelectionRows;

void __fastcall DeleteSelectionRows();

Where used: Delete rows spanned by the current selection. No-ops for entire-column selections (use DeleteSelectionColumns).

How to use:

MagiXells1.SelectRange(TCellRange.FromA1('A5:C6'));
MagiXells1.DeleteSelectionRows;

DeleteSelectionColumns

Visibility: public
Declaration

procedure DeleteSelectionColumns;

void __fastcall DeleteSelectionColumns();

Where used: Delete columns spanned by the selection. No-ops for entire-row-only selections.

How to use:

MagiXells1.DeleteSelectionColumns;

InsertSelectionRows

Visibility: public
Declaration

procedure InsertSelectionRows;

void __fastcall InsertSelectionRows();

Where used: Insert as many rows as the selection height, at the selection’s start row.

How to use:

MagiXells1.InsertSelectionRows;

InsertSelectionColumns

Visibility: public
Declaration

procedure InsertSelectionColumns;

void __fastcall InsertSelectionColumns();

Where used: Insert as many columns as the selection width, at the selection’s start column.

How to use:

MagiXells1.InsertSelectionColumns;

Selection and editing

All cell coordinates below are 1-based.

SelectCell

Visibility: public
Declaration

procedure SelectCell(ACol, ARow: Integer);

void __fastcall SelectCell(int ACol, int ARow);

Where used: Move the active cell (and collapse the selection). Use for Go To, hyperlink navigation, and restoring a saved caret.

How to use:

MagiXells1.SelectCell(1, 1);   { A1 }
MagiXells1.SelectCell(2, 5);   { B5 }

SelectRange (TCellRange)

Visibility: public
Declaration

procedure SelectRange(const ARange: TCellRange); overload;

void __fastcall SelectRange(const TCellRange ARange) /* overload */;

Where used: Select a rectangle from a TCellRange (prefer FromA1 / Normalize).

How to use:

var R: TCellRange;
begin
  R := TCellRange.FromA1('A1:D6');
  MagiXells1.SelectRange(R);
  { or }
  MagiXells1.SelectRange(TCellRange.Create(1, 1, 4, 6));
end;

SelectRange (coords)

Visibility: public
Declaration

procedure SelectRange(AStartCol, AStartRow, AEndCol, AEndRow: Integer); overload;

void __fastcall SelectRange(
  int AStartCol,
  int AStartRow,
  int AEndCol,
  int AEndRow
) /* overload */;

Where used: Select by inclusive 1-based corners (order may be reversed; range is normalized).

How to use:

MagiXells1.SelectRange(1, 1, 4, 6);  { A1:D6 }

BeginEdit

Visibility: public
Declaration

procedure BeginEdit(const AInitialText: string = '');

void __fastcall BeginEdit(const System::UnicodeString AInitialText = L"");

Where used: Start inplace edit on the active cell. Optional seed text (e.g. start a formula). Blocked by OnBeforeEdit / protection / ReadOnly.

How to use:

MagiXells1.BeginEdit('=A1+1');

EndEdit

Visibility: public
Declaration

procedure EndEdit;

void __fastcall EndEdit();

Where used: Commit the current inplace / formula-bar edit.

How to use:

if MagiXells1.IsEditing then
  MagiXells1.EndEdit;

CancelEdit

Visibility: public
Declaration

procedure CancelEdit;

void __fastcall CancelEdit();

Where used: Abort the current edit without writing (Escape).

How to use:

MagiXells1.CancelEdit;

IsEditing

Visibility: public
Declaration

function IsEditing: Boolean;

bool __fastcall IsEditing();

Where used: True while inplace or formula-bar cell edit is active. Host shortcuts that mutate the sheet should no-op or commit first.

How to use:

if MagiXells1.IsEditing then
  MagiXells1.EndEdit;

IsFormulaBarFocused

Visibility: public
Declaration

function IsFormulaBarFocused: Boolean;

bool __fastcall IsFormulaBarFocused();

Where used: True while the caret is in the name box or formula field. Host Ctrl+B/I/U (and similar) should no-op so they do not restyle the whole cell.

How to use:

if MagiXells1.IsEditing or MagiXells1.IsFormulaBarFocused then
  Exit;

IsFormulaEditFocused

Visibility: public
Declaration

function IsFormulaEditFocused: Boolean;

bool __fastcall IsFormulaEditFocused();

Where used: True only while the formula field (not the name box) has edit focus. Narrower than IsFormulaBarFocused.

How to use:

if MagiXells1.IsFormulaEditFocused then
  StatusBar1.SimpleText := 'Editing formula';

ScrollToCell

Visibility: public
Declaration

procedure ScrollToCell(ACol, ARow: Integer);

void __fastcall ScrollToCell(int ACol, int ARow);

Where used: Scroll the viewport so the given 1-based cell is reachable (does not necessarily change selection).

How to use:

MagiXells1.ScrollToCell(1, 100);  { column A, row 100 }

EnsureSelectionVisible

Visibility: public
Declaration

procedure EnsureSelectionVisible;

void __fastcall EnsureSelectionVisible();

Where used: Scroll just enough so the active selection is on screen after programmatic select or layout changes.

How to use:

MagiXells1.SelectRange(TCellRange.FromA1('Z200'));
MagiXells1.EnsureSelectionVisible;

GetVisibleRange

Visibility: public
Declaration

function GetVisibleRange: TVisibleRange;

TVisibleRange* __fastcall GetVisibleRange();

Where used: On-screen bounding box (1-based cols/rows), including frozen panes. TVisibleRange has StartCol, EndCol, StartRow, EndRow (MagiXells.Grid.Types).

How to use:

var R: TVisibleRange;
begin
  R := MagiXells1.GetVisibleRange;
  Caption := Format('Visible %s%d:%s%d',
    [ColToLetters(R.StartCol), R.StartRow,
     ColToLetters(R.EndCol), R.EndRow]);
end;

GetScrollableVisibleRange

Visibility: public
Declaration

function GetScrollableVisibleRange: TVisibleRange;

TVisibleRange* __fastcall GetScrollableVisibleRange();

Where used: Visible cells in the unfrozen / scrollable pane only. Compare with GetVisibleRange when frozen rows/cols are set.

How to use:

var S: TVisibleRange;
begin
  S := MagiXells1.GetScrollableVisibleRange;
end;

GetDefaultFont

Visibility: public
Declaration

function GetDefaultFont: TCellFontInfo;

TCellFontInfo __fastcall GetDefaultFont();

Where used: Read the workbook Normal style as TCellFontInfo (includes color on both VCL and FMX). Prefer this when FMX TFont has no color.

How to use:

var Info: TCellFontInfo;
begin
  Info := MagiXells1.GetDefaultFont;
end;

SetDefaultFont

Visibility: public
Declaration

procedure SetDefaultFont(const AFont: TCellFontInfo);

void __fastcall SetDefaultFont(const TCellFontInfo AFont);

Where used: Write the workbook Normal style from TCellFontInfo. Re-apply after NewWorkbook / load if you need a non-default Normal font.

How to use:

var Info: TCellFontInfo;
begin
  Info := MagiXells1.GetDefaultFont;
  Info.Name := 'Consolas';
  Info.Size := 10;
  MagiXells1.SetDefaultFont(Info);
end;

Sheets

Sheet indexes are 0-based. Visibility uses TSheetVisibility.

AddSheet

Visibility: public
Declaration

function AddSheet(const AName: string = ''): TWorksheet;

TWorksheet* __fastcall AddSheet(const System::UnicodeString AName = L"");

Where used: Append a worksheet. Empty name auto-generates. Blocked when structure-protected.

How to use:

var Ws: TWorksheet;
begin
  Ws := MagiXells1.AddSheet('Sales');
  MagiXells1.ActiveSheetIndex := MagiXells1.SheetCount - 1;
end;

RemoveSheet

Visibility: public
Declaration

procedure RemoveSheet(AIndex: Integer);

void __fastcall RemoveSheet(int AIndex);

Where used: Delete sheet by 0-based index. Cannot remove the last sheet; respect structure protection.

How to use:

MagiXells1.RemoveSheet(1);  { second sheet }

RenameSheet

Visibility: public
Declaration

procedure RenameSheet(AIndex: Integer; const AName: string);

void __fastcall RenameSheet(int AIndex, const System::UnicodeString AName);

Where used: Rename sheet by 0-based index (unique name rules apply).

How to use:

MagiXells1.RenameSheet(0, 'Overview');

GetSheetVisibility

Visibility: public
Declaration

function GetSheetVisibility(AIndex: Integer): TSheetVisibility;

TSheetVisibility __fastcall GetSheetVisibility(int AIndex);

Where used: Returns svVisible, svHidden, or svVeryHidden. Same data as Workbook.GetSheet(I).Visibility.

How to use:

var I: Integer;
begin
  for I := 0 to MagiXells1.SheetCount - 1 do
    if MagiXells1.GetSheetVisibility(I) <> svVisible then
      Memo1.Lines.Add(MagiXells1.Workbook.GetSheet(I).Name);
end;

SetSheetVisibility

Visibility: public
Declaration

procedure SetSheetVisibility(AIndex: Integer; AVisibility: TSheetVisibility);

void __fastcall SetSheetVisibility(int AIndex, TSheetVisibility AVisibility);

Where used: Show, hide, or very-hide a sheet by index.

How to use:

MagiXells1.SetSheetVisibility(1, svHidden);
MagiXells1.SetSheetVisibility(2, svVeryHidden);
MagiXells1.SetSheetVisibility(1, svVisible);

HideSheet

Visibility: public
Declaration

procedure HideSheet(AIndex: Integer; AVeryHidden: Boolean = False);

void __fastcall HideSheet(int AIndex, bool AVeryHidden = false);

Where used: Convenience wrapper around SetSheetVisibility. AVeryHidden=True → svVeryHidden.

How to use:

MagiXells1.HideSheet(1);        { svHidden }
MagiXells1.HideSheet(2, True);  { svVeryHidden }
MagiXells1.TabBar.ShowHiddenSheets := True;  { list on tab bar }

UnhideSheet

Visibility: public
Declaration

procedure UnhideSheet(AIndex: Integer);

void __fastcall UnhideSheet(int AIndex);

Where used: Set sheet visibility back to svVisible.

How to use:

MagiXells1.UnhideSheet(1);

GetWorkbook

Visibility: public
Declaration

function GetWorkbook: TWorkbook;

TWorkbook* __fastcall GetWorkbook();

Where used: Same object as published Workbook. Useful when you prefer a function call style.

How to use:

var Wb: TWorkbook;
begin
  Wb := MagiXells1.GetWorkbook;  { = MagiXells1.Workbook }
end;

GetActiveSheet

Visibility: public
Declaration

function GetActiveSheet: TWorksheet;

TWorksheet* __fastcall GetActiveSheet();

Where used: Same object as published ActiveSheet.

How to use:

Caption := MagiXells1.GetActiveSheet.Name;

Undo / redo

Undo

Visibility: public
Declaration

procedure Undo;

void __fastcall Undo();

Where used: Undo the last command if CanUndo. Wire to Edit → Undo and OnHistoryChanged.

How to use:

if MagiXells1.CanUndo then
  MagiXells1.Undo;

Redo

Visibility: public
Declaration

procedure Redo;

void __fastcall Redo();

Where used: Redo if CanRedo.

How to use:

if MagiXells1.CanRedo then
  MagiXells1.Redo;

Print

ShowPageSetup

Visibility: public
Declaration

function ShowPageSetup: Boolean;

bool __fastcall ShowPageSetup();

Where used: Show the page-setup dialog for the active sheet. Returns True if the user accepted.

How to use:

if MagiXells1.ShowPageSetup then
  { settings applied };

PrintPreview (job)

Visibility: public
Declaration

function PrintPreview(AJob: TPrintJobSettings): Boolean; overload;

bool __fastcall PrintPreview(TPrintJobSettings AJob) /* overload */;

Where used: Preview with an explicit print job (what to print, pages, …).

How to use:

var Job: TPrintJobSettings;
begin
  Job := TPrintJobSettings.Default;
  MagiXells1.PrintPreview(Job);
end;

PrintPreview

Visibility: public
Declaration

function PrintPreview: Boolean; overload;

bool __fastcall PrintPreview() /* overload */;

Where used: Preview using default job settings for the active context.

How to use:

MagiXells1.PrintPreview;

Print (job)

Visibility: public
Declaration

function Print(AJob: TPrintJobSettings; AShowDialog: Boolean = True): Boolean; overload;

bool __fastcall Print(TPrintJobSettings AJob, bool AShowDialog = true) /* overload */;

Where used: Print with an explicit job. AShowDialog=False skips the printer dialog when the host already chose settings.

How to use:

var Job: TPrintJobSettings;
begin
  Job := TPrintJobSettings.Default;
  MagiXells1.Print(Job, True);
end;

Print

Visibility: public
Declaration

function Print(AShowDialog: Boolean = True): Boolean; overload;

bool __fastcall Print(bool AShowDialog = true) /* overload */;

Where used: Print with defaults; optionally show the system print dialog.

How to use:

MagiXells1.Print(True);

SetPrintAreaFromSelection

Visibility: public
Declaration

procedure SetPrintAreaFromSelection;

void __fastcall SetPrintAreaFromSelection();

Where used: Define the sheet print area from the current selection.

How to use:

MagiXells1.SelectRange(TCellRange.FromA1('A1:G40'));
MagiXells1.SetPrintAreaFromSelection;

ClearPrintArea

Visibility: public
Declaration

procedure ClearPrintArea;

void __fastcall ClearPrintArea();

Where used: Clear the active sheet’s print area.

How to use:

MagiXells1.ClearPrintArea;

SetPrintTitlesFromSelection

Visibility: public
Declaration

procedure SetPrintTitlesFromSelection;

void __fastcall SetPrintTitlesFromSelection();

Where used: Use the selection as repeating print titles (rows and/or columns, Excel-like).

How to use:

MagiXells1.SelectRange(1, 1, 1, 1);  { row 1 as title row example }
MagiXells1.SetPrintTitlesFromSelection;

External data providers

Host-supplied interfaces for STOCKHISTORY, RTD, GOOGLEFINANCE, translate, and IMPORTRANGE. Defaults and details: Formulas guide. Interfaces live in MagiXells.ExternalData. Properties also exist on TWorkbook.

StockHistoryProvider

Visibility: public
Declaration

property StockHistoryProvider: IMagiXellsStockHistoryProvider;

__property _di_IMagiXellsStockHistoryProvider StockHistoryProvider;

Where used: Optional host feed for STOCKHISTORY. If unset, MagiXells may use Yahoo Finance chart defaults.

How to use:

MagiXells1.StockHistoryProvider := TMyStockFeed.Create;

RtdProvider

Visibility: public
Declaration

property RtdProvider: IMagiXellsRtdProvider;

__property _di_IMagiXellsRtdProvider RtdProvider;

Where used: Optional host RTD server. If unset, Windows COM IRtdServer may be tried; else #N/A.

How to use:

MagiXells1.RtdProvider := MyRtdFeed;

GoogleFinanceProvider

Visibility: public
Declaration

property GoogleFinanceProvider: IMagiXellsGoogleFinanceProvider;

__property _di_IMagiXellsGoogleFinanceProvider GoogleFinanceProvider;

Where used: Optional host for GOOGLEFINANCE. Else Yahoo-backed defaults for common attributes.

How to use:

MagiXells1.GoogleFinanceProvider := MyFinance;

TranslateProvider

Visibility: public
Declaration

property TranslateProvider: IMagiXellsTranslateProvider;