# Grid quick start

The tutorial project for Atlas VCL. One form, built in code, shows a typed
`TAtlasTable` in a `TAtlasGrid`:

- five columns of four kinds (`ackText`, `ackNumber`, `ackBoolean`, `ackDate`),
  loaded in one step with `ImportCSV`, including a quoted field that contains a comma;
- a filter box that calls `SetFilter` on every keystroke, across all columns and
  without regard to case;
- sorting by clicking a column header (the grid does this itself: first click
  ascending, next click descending) and a **Clear sort** button that calls `Sort(-1)`;
- in-place editing: type in a cell and press Enter or move to another cell to
  store the value, or press Escape to discard it; the table rejects values that
  do not fit the column kind. A small form-level key handler makes Enter and
  Escape act at once (see below);
- a row of entry boxes where the quantity, price and restock date are
  `TAtlasValueEdit` controls: each checks its value when focus leaves it, and
  **Add row** checks them again with `Validate` before `AddRow`;
- **Delete row** for the selected row and **Export CSV** for the visible rows;
- a status line driven by `OnChange` that shows the visible and total row counts
  and the current sort.

## Build and run

Open `GridQuickStart.dpr` in Delphi 13; the IDE creates the project file. Add the Atlas VCL `src` folder and the `shared` folder to the project's search path, then build and run for Win32 or Win64. No packages need to be installed. The `shared` folder is part of the sample download. It holds `Atlas.TestVcl.pas`, which the optional snapshot mode uses to save a picture of the window.

Start it without arguments to use the window.

`GridQuickStart.exe window.png` does not show the window; it paints the form off screen and saves it as a PNG through `SaveFormImage` from `shared/Atlas.TestVcl.pas`. Remove that unit and the `if ParamCount > 0` branch if you copy the program elsewhere.

## Expected result

A 900 × 560 window with the filter row and buttons at the top, the entry row
below it and a grid with a dark header row and alternating row tint:

| Product | Quantity | Unit price | Available | Restock |
|---|---:|---:|---|---|
| Field notebook | 120 | 4.75 | true | 2026-10-03 |
| Drafting pencil | 300 | 1.2 | true | |
| Steel ruler | 45 | 6.5 | false | 2026-11-15 |
| Ink, archival | 80 | 12 | true | 2026-10-20 |

The status line reads `4 of 4 rows shown, unsorted. ...`. Things to try:

- Type `ink` in the filter box: one row remains and the status shows `1 of 4 rows`.
- Click the **Quantity** header twice: the header shows `  ^` and then `  v`, and
  the rows are ordered numerically (45 before 120), not as text.
- Type `12.50` into a **Unit price** cell and press Enter: the editor stays open
  and shows `12.5`, the normalized number the table stores.
- Type `lots` into a **Quantity** cell and press Enter: the application reports
  `Invalid finite number: lots`, the table keeps the old value and the editor keeps
  your text. Correct it, or press Escape to get the old value back.
- Type a new quantity, press Escape, then press the Down arrow: the old value
  stays.
- Type a product name and click **Add row** with the quantity box empty: the
  status line says `Quantity: A value is required` and nothing is added.
- Type `2026-02-30` into the restock box and press Tab: `TAtlasValueEdit` checks
  its value when focus leaves and the application reports
  `Expected a valid date in YYYY-MM-DD format`.
- Click **Export CSV**: `inventory.csv` is written next to the executable with the
  rows currently shown, in the current sort order.

## The Enter and Escape handler

`FormKeyDown` (with `KeyPreview := True`) works around two limitations of the
grid's in-place editing in this baseline, both verified against the source:

- The first Enter only closes the editor. The value reaches the table at the next
  Enter, cell move, header click or focus change, and until then the cell shows
  its old value. The handler sets `EditorMode := False` (which hands the editor
  text to the grid) and calls `CommitEdit` at once.
- Escape while the editor is open closes it, but `CancelEdit` closing the editor
  hands the typed text back to the grid as a pending edit, and the next cell move
  stores it. A second `CancelEdit`, with the editor already closed, discards it.
  The handler calls `CancelEdit` twice.

Without the handler the grid still stores edits when you move to another cell with
the arrow keys, Tab or the mouse, or leave the grid; only Enter and Escape behave
as described above.

## What to change first

- Replace the columns in the constructor with your own schema. Call every
  `AddColumn` before the first row is added; the table refuses schema changes
  once it holds data.
- Replace the `ImportCSV` text with your own data, or call `AddRow` in a loop.
  The CSV header must name the columns exactly, in order.
- Keep a business key (an order number, a product code) in its own column and
  pass `False` as the last `AddColumn` argument to make it read-only. View row
  indices change with every sort and filter, so they are not identifiers.
- Call `FGrid.CommitEdit` before any code of yours that sorts, filters or
  changes the table, as the handlers here do. A model change made while the
  editor is still open does not discard the typed text: the grid keeps it and
  stores it into the row that is under the cursor after the change, which may be
  a different record.