# Application shell

A VCL program that builds a small application shell entirely in code with the
layout and display components of Atlas VCL:

- `TAtlasWorkspace` with three panes: a navigation pane on the left, a command
  pane on top and a client pane for the content.
- `TAtlasCommandBar` with a Home tab (groups Pages and Sales) and a View tab
  (groups Appearance and Layout), each button bound to an ordinary `TAction`.
- `TAtlasNavigation` and `TAtlasTileBoard` sharing the same page actions as
  the command bar, so a list item, a tile and a button all switch the page.
- A Sales page with a two-series `TAtlasChart`: six months to start with, a
  missing value in April for West (the line breaks there), an Add month
  command that disables itself after December, and a Bars / lines toggle.
- A Gauges page with three `TAtlasGauge` controls (one custom range with its
  own thresholds) and a track bar that moves the first one.
- `TAtlasThemer` on the workspace, with a Next theme command that cycles
  through the eleven palettes and shows the theme name in the title bar.
- A Float navigation command that moves the navigation pane into a tool window
  and back, and layout persistence: the layout is saved to
  `shell-layout.json` next to the executable when the window closes and
  restored the next time it is first activated.

This is the project of the tutorial in
[Atlas VCL interface components](https://youseful.software/delphi/atlas-vcl-interface.html).

## Build and run

Open `ApplicationShell.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.

The program is interactive. To look at it without clicking, pass a PNG file name, and optionally a page number (0 Home, 1 Sales, 2 Gauges):

```
ApplicationShell.exe shell.png 1
```

The window is then painted off screen, saved and closed. In this mode the layout file is not written (the window is never closed by the user), but a file left by an earlier interactive run is still restored.

## Expected output

A 1000 × 680 window. Across the top, the command bar with the Home tab open:
a Pages group with Home, Sales and Gauges buttons and a Sales group with Add
month and Bars / lines. Below it, on the left, the navigation list (Home,
Sales, Gauges) and, on the right, three dark blue tiles with the same captions.
The Harbor theme gives white surfaces and dark text.

- Sales shows "Regional sales (thousands)" with East and West lines for
  January to June; West has a gap at month 4. The X axis shows numbers because
  a line chart does not use point captions. Bars / lines switches to grouped
  bars labelled Jan, Feb, ... from the East captions. Add month adds one month
  per click; after December the button is disabled.
- Gauges shows Queue depth at 120 (green), CPU % at 62 (green) and Disk % at
  91 (red). Dragging the track bar past 300 turns the queue gauge amber and
  past 450 red.
- View / Next theme recolours the workspace. Index 10, Midnight, is the dark
  palette; native buttons and tab strips keep the Windows look.
- View / Float navigation opens the navigation list in a tool window titled
  "Navigation". Closing that window, or the command again, docks it back.
  Close the program while it floats and it opens floating next time.

## What to change first

- Replace the Sales series data with your own values. Keep the X values
  increasing; give every point of the first series a caption if you want the
  bar chart to label its categories.
- Add a page: call `NewPage` after the Gauges page and put your control on it.
  The loop that follows creates a page action for every page and adds it to
  the navigation, the tiles and the command bar.
- Put a fourth pane on the right with `AddPane('details', 'Details', alRight, 240)`.
  Right and bottom panes get a working splitter from `AddPane`, but lose it
  after `MovePane` or `LoadLayout` (see Troubleshooting in the guide). If a
  layout file from an older version exists, `LoadLayout` rejects it because it
  does not describe the new pane; the program then keeps the default layout.
- Start with another palette: set `FThemer.ThemeIndex` after assigning `Root`.