# The dashboard editor

> The workbench behind Edit: the palette and adding components, the Components locator, selection and the canvas gestures, the property sections every kind shares, the Dashboard area, the connections drawn between symbol terminals, and the autosave behind all of it.

Press **Edit** on the stage bar of the [View](home) page to open the editor on the screen
that is open. It needs the role's **Edit dashboards** permission (the verb is not drawn
without it), a screen of your own (a unit panel or a unit screen is arranged in the Process
workspace), and a station that takes writes: while engineering is locked or the runtime is
stopped the verb is greyed and says why. The screen keeps running while you edit: the
components read live values on the canvas, so you configure against what the plant is
reading.

There is no save step. Every change persists the moment it is made: a field when you leave
it, a switch when you flip it, a move when you drop it. A write the station refuses is
reported in the status bar's action feed ("Dashboard edit was not saved: …") and the screen
reloads from what was saved. **Done editing** leaves the mode and is never refused, even
when a lock arrives mid-edit; picking a unit panel or a folder in the column, a sign-out, a
role change, a unit starting a run or the runtime stopping all end it too. While the editor
is open the bar withholds Expand and Full screen and F11 does nothing.

## The workbench {#the-workbench}

The editor puts three surfaces side by side: the Visualization column, the canvas with grid
lines, and a tool rail on the right. The rail opens 380 px wide, drags wider or narrower
(never under 320 px), and collapses to a strip of four buttons; a press on that strip
floats the chosen area over the canvas until you press elsewhere, and the pin puts the
fixed rail back. The four areas are **Add**, **Components**, **Properties** and
**Dashboard**. Entering the editor opens Components; selecting anything on the canvas
opens Properties; Dashboard opens only when you choose it.

## Add {#add}

**Add** is the catalog: a search over name, description and category, a **Category**
filter (All categories, then Display, Control, Alarm, Media, Layout), and the kinds grouped
under those headings ([Dashboard components](components) has one page per kind). Click a
kind and it lands on the first free cell where its default size fits, or at the top-left
corner clamped into the grid when no free cell is left; drag it onto the canvas to choose
the exact cell. A new component takes the layer above everything else and opens in
Properties.

**Symbol** is the one kind chosen before it is placed: its palette row opens the symbol
library instead of dropping anything. The library is the same gallery the
[Symbols](assets-symbols) page uses, in a two-column form twelve cards a page: a search by
name, library, category or tag, a **Library** filter (each with its count), a **Category**
filter, and an **Origin** filter (All, System, Mine). A card names the symbol, its library
and category, whether it is System or Mine, and what it declares ("Static", "1 input",
"3 inputs", "· 2 terminals"). Click a card to place that symbol in a free cell at the size
its author suggested, or drag it onto a cell; **‹ All components** returns to the catalog.
When your own library cannot be read the gallery says so and lists the system libraries
alone.

Beside Symbol, the Media category offers **Connection point**: "Place a named typed
endpoint without adding a Symbol." It adds a free-standing, untyped connection point near
the centre of the grid, ready to be wired; see [Connections](#connections) below.

## Components {#components}

**Components** lists every persisted item of the screen, front to back, with the count in
its heading. A row shows the kind's icon, the component's identification, its type and its
place ("Grid 3,2 · 4×2 · Layer 5"). The search matches type, name or identification.
Pressing a row selects the component, reveals it on the canvas and opens Properties. A
component this version has no renderer for still has its row and its cell, so a screen is
never missing a piece without a word; its Properties offer only **Remove component**.

The identification is the name you gave the component in Properties, or, while it has
none, what already identifies it: its corner title, its configured text or label, the
address or unit it is bound to, the symbol it draws, or its type.

## The canvas {#the-canvas}

The canvas is the running screen with grid lines. A click selects a component and opens its
Properties; **Ctrl+click** adds it to the selection or takes it out again (the last one
touched is the primary, the one the per-kind sections and the resize grip belong to); a
click on empty grid clears the selection. Drag a component to move it, drag the grip on its
corner to resize it; both snap to cells, are clamped inside the grid, and commit when you
release. Overlap is allowed. Escape drops the selection and Delete removes it, but only
while the canvas holds the keyboard focus, so a keystroke in a property field never
reaches them.

Right-click a component for its menu: **Edit properties**, **Duplicate**, **Bring to
front**, **Send to back**, on a Symbol also **Rotate 90°**, **Flip horizontal** and **Flip
vertical**, and **Delete**. Inside a multi-selection the verbs name their count
("Duplicate (3)", "Delete (3)") and act on the whole batch. Right-click empty grid for
**Add component**, which opens the Add area. There is no clipboard and no Paste: Duplicate
is the copy.

A removal is immediate and reported in the status bar with **Undo** beside it: one level,
the last removal, valid as long as that entry is on screen. Undo puts the components back
with the connection terminals they owned, and says what could not come back ("One
connection stayed a loose end: its line changed after the removal."). An offer whose screen
is no longer open answers "The removal was not undone: the screen it belongs to is not
open any more."

On the edit canvas the components draw live values but take no presses: the controls answer
only in view mode.

## Properties {#properties}

**Properties** edits the selection. Its heading names what is in hand: the kind's icon and
name, and under them the component's identification. With nothing selected it says "Select
a component, connection line, point or junction on the canvas. Hold Ctrl to add more and
edit what they share."

The sections run in one order whatever the kind, so a subject keeps its place when you
change component:

1. **Identification**: the component's **Name**, which names it in the Components list,
   in its search and in this heading, and draws nothing on the screen. The placeholder
   shows what the list would call it with the field empty.
2. The kind's own sections, in the order **Content**, **Data**, **Format**, then the
   sections only that kind asks (Type, Dial, Indication, Mini-chart, Track, State, Alarms,
   Options, Travel, Step, Number, Action, Color and icon, Color and size, Episodes,
   Columns, Chart, Evaluation, Bars, Slices, Fit, Connections, Orientation), then
   **History**, **Scale**, **Fidelity and performance** and **Toolbox**. Each is
   documented on the component's own page; the controls that repeat across kinds are
   below.
3. **Appearance**, the same section for every kind.
4. **Position and layer**.
5. **Advanced**, closed by default and drawn only on the kinds that have infrequent
   extras: the KPI card's **Window s** and **Sample ms**, the Icon's **Glyph code
   (advanced)**.
6. **Actions**: **Duplicate component** and **Remove component**.

With several components selected the panel says "N components selected, editing what they
share. Per-kind fields need a single component." (a batch of one kind is named by it, "3
Value components") and offers Appearance, the two layer commands and **Duplicate N
components** / **Remove N components**. A batch write is one save for the whole screen.

### Address fields and the live reading {#address-fields-and-the-live-reading}

Every field that names a Logic point is a combo box you can type into freely, with
suggestions drawn from the live point list and capped at 50 rows. The list is narrowed to
the value category the field consumes (a gauge is offered numbers, a lamp leads with Bool
points, a control that writes lists only what can be written, the Button's run command
lists the unit command points), and every row carries its type as a tooltip. An address
the list does not offer is still accepted, including one that does not exist yet. On a
screen defined on a Process model the model's abstract channels lead every list; picking
one binds the channel and leaves the unit to be answered when a unit opens the screen.

Once a field names a point, a line under it says what the point reads right now, led by
the word **now**: the value written the way the station writes numbers, or, where reading
the text would say nothing, the thing itself: a colour arrives as a swatch beside its hex,
an icon as the glyph, an image as a thumbnail. A point that is not answering says so in a
soft caution tint instead of leaving a stale number, and an empty field draws no line at
all. The line follows the editor's own tick and adds no timer of its own.

### Appearance {#appearance}

One section carries what every component has, for one component or a whole selection
alike ("Applies to all N selected components."). A field the members disagree on reads
**Mixed** and takes the value you enter for all of them.

| Field | What it does | Values | Default |
|---|---|---|---|
| Show frame | Draws the component's own outline. | on / off | off |
| Frame thickness (px) | How heavy that outline is. One px is a card's edge; a heavier stroke tells a group from its surroundings. | 1 to 4, taken at the nearest edge | 1 |
| Show background | Fills the rectangle with the colour pair, making it a card. Off, the grid shows through. | on / off | off |
| Background color | The fill as a pair, Light and Dark, each a swatch and a hex box: the running theme decides which half is on screen, so recolouring means recolouring both. A half-typed hex is not an edit and snaps back. | `#RRGGBB` each | `#FFFFFF` light, `#2B2B2B` dark |
| Title (corner) | The component's own corner label, above whatever the kind renders. Blank means no caption row. Committed when you leave the field. | text, 200 characters | empty |
| Title size (px) | Blank lets each card size its own title from its cell; a size is the size on screen, so the titles of a whole screen agree. A title too long for its box is cut short with the whole of it in the tooltip. | 11 to 96, or blank | blank (Automatic) |
| Title color | The title's ink pair. Untouched, the title follows the theme's own quiet tone. | `#RRGGBB` each | `#6B6B6B` light, `#A0A0A0` dark |
| Content scale | How much of its box the content takes: 1 fills the cell as drawn; artwork answers geometrically, a readout typographically, and a number still never renders cut. | 0.25 to 3, step 0.05 | 1 |

### Position and layer {#position-and-layer}

**X**, **Y**, **W** and **H** are the cells the component occupies; a value that would put
it outside the grid is clamped and the field snaps back. **Layer (Z)** is its place in the
stack. **Bring to front** lifts the selection above everything else and **Send to back**
drops it below, keeping the batch's relative order. Move and resize stay per component.

### Display size {#display-size}

Every kind that writes a number (Value, Gauge, KPI card, Progress, Point table) carries the
same pair inside its Format section:

| Field | What it does | Values | Default |
|---|---|---|---|
| Digits (or Characters, on a Value that reads text) | How many digits the field holds before the separator. A reading past it is marked rather than written short, with the whole of it in the tooltip; text past its characters is written short instead. | a count; blank keeps the kind's derived default, shown as the placeholder | derived per kind |
| Type size | **As big as the cell affords** lets the cell decide, bounded by the width the digits reserve; **A size I state** is literal in any cell and is what makes the same reading on two screens agree. | the two modes | As big as the cell affords |
| Points | The stated size, offered only in the stated mode. What no longer fits is marked, not shrunk. | points | |

### Reads as {#reads-as}

The same kinds carry **Reads as**: **Number**, **Percentage** (the same number with the
sign against it) or **Duration**; the Value alone also offers **Text**, because it is the
one kind that can draw a point's words. Duration adds **The value counts**: **Seconds**,
**Milliseconds** or **Minutes**, since the elapsed value reaches the dashboard as a plain
number. A sentence under the fields says when the decimal places you typed were taken at
the edge of their band.

### Scale {#scale}

The Value, Gauge, KPI card, Progress, Bar chart and Pie chart carry a **Scale** section of
bands: "A band covers up to its bound, from where the one above it ended. Colour is the
meaning: the theme decides the paint." Each band is a card headed by its wording (or "Band
N") and where it ends ("up to 80", "no bound yet"), painted in its meaning, with the upper
bound, the meaning (**Neutral**, **Information**, **Success**, **Caution**, **Critical**),
on the kinds that have one state to name a wording field ("names this state", which the
component writes beside its reading), and **Move up** / **Move down**, which trade meanings
between neighbours and leave the bounds where they are. **Add band** appends one; the ✕ on
the head removes it. On the two categorical charts the bands are a palette that tints bars
and slices, so no wording is asked.

The Gauge, KPI card and Progress add a **Reference** under the bands: "A setpoint or
nominal, marked on the scale where it falls. It is drawn only while the scale reaches it."
**Marks** is **Nothing**, **A fixed value** (then a **Value** field) or **A point** (then
an **Address** field with its live reading).

### Fidelity and performance {#fidelity-and-performance}

The Line chart carries the section that decides how much of the data reaches the canvas: a
**Preset** (Maximum fidelity, Balanced, Maximum performance; Custom is a reading, not a
choice, shown when the fields match no named set and never selectable), **Draw every
sample up to** (100 to 100,000 points), **Above it, keep** (Preserve peaks, Preserve shape,
Average), **One symbol per sample up to** (0 to 5,000; 0 never draws them), **Draw what
lies outside the frame**, **Animate the drawing** and **Say in the corner which mode the
chart is in**. A count past its band is taken at the edge and the panel says which count
it took. Under the fields an estimate says how many points the station keeps and how many
reach the canvas, and warns past 20,000 drawn points or past the memory the chart may
keep. The values and their meaning are on [Line chart](component-line-chart).

### Toolbox {#toolbox}

Every chart kind carries a **Toolbox** section: one tick box per button its drawing can
honour, each drawn with the button's own glyph, in the order the bar draws them. "With
none of them ticked no bar is drawn at all." A Line chart offers Zoom into an area, Reset
the zoom, Set the scale by hand, Read the window's minimum, average and maximum, Draw
reference lines, Save as PNG, Copy as PNG, Show or hide series, Turn the tooltip on and off
and Full screen; a Bar chart or Pie chart offers only Save as PNG, Copy as PNG and Full
screen. What each button does is on [Charts](view-charts).

### The categorical charts {#the-categorical-charts}

The Bar chart and the Pie chart share one set of sections above their own drawing:
**Content** holds the **Chart title** drawn inside the plot (not the corner title);
**Data** holds one card per **point** (an address, a **Name** that falls back to the
address, a **Color** that falls back to the palette's turn, and the live reading), **Add
point**, and **Order** (**as declared**, **smallest first**, **largest first**);
**Format** holds **Unit**, **Decimals** and Reads as. "A point that is not reading is left
out of the comparison instead of being drawn at zero." Below that, **Bars** or **Slices**
is each kind's own: see [Bar chart](component-bar-chart) and
[Pie chart](component-pie-chart).

## The Dashboard area {#the-dashboard-area}

**Dashboard** holds what the screen declares about itself: name, description, icon, the
grid, the startup flag, the status bar in full screen, the visible roles and deletion. It
is [Dashboard settings](view-settings). On a screen defined on a Process model the area
says so: "This screen belongs to a Process model. One definition serves every unit of it:
each unit opens it over its own bound channels."

## Connections {#connections}

A [Symbol](component-symbol) that declares terminals shows them in the editor as markers
on its artwork: a free terminal, an occupied one (with a core dot, painted in its
connection's own colour), and one wearing a warning when its connection is undefined.
Connections are typed networks drawn on a layer of their own, under the equipment and over
the cards, in the colour and thickness the [connection type](assets-connection-types)
declares; the eight types are Liquid, Gas, Air / duct, Electrical, Signal, Network,
Material and Mechanical shaft. A symbol's terminals declare their type (or a type
configuration the symbol's Connections section lets you choose), and a network's type
resolves only when every endpoint agrees.

| Gesture | What it does |
|---|---|
| Drag a free terminal onto another free terminal | Creates a connection between the two. Matching types make a defined connection ("Connected Liquid terminals."); conflicting or untyped ends still connect, as an **undefined** network drawn in a neutral thin dashed style, and the feed says so ("Connected as undefined: Liquid × Gas."). |
| Drag a free terminal onto empty grid | Creates a **connection point** there and wires the terminal to it ("Created a connection point."). |
| Drag a free terminal onto an existing line | Splits the line through a **junction** and branches to the terminal ("Created a connection branch."). The line must be defined and its type must match the terminal's; otherwise the gesture is refused with the reason. |
| Drag a free terminal onto a junction, an open end or a connection point | Joins it there. A loose end or a point already carrying a line becomes the terminal in place; a free-standing point gains the line that reaches the terminal. |
| Drag a selected line's centre handle onto a free terminal | The same branch, started from the line. |
| Drag a line | Bends it: the route becomes **Manual** with the bends you left ("Saved the manual connection route."). |
| Drag a connection point, junction or open end | Moves it; every attached route follows, and a manual route attached to it is marked as needing adjustment. Terminals cannot be dragged: their position follows the symbol. |
| Drag a loose open end or a connection point onto a free terminal | Reconnects it there ("Reconnected the loose connection end."). |

The keyboard does the same: a terminal, a line, its centre handle and a node all take
focus; Enter or Space on a free terminal marks it as the source, Enter or Space on the
target completes the gesture, and Escape clears the source. Delete removes the selected
line or connection point; on a junction or an open end it says which line to select
instead.

A press on a line or a node selects it and opens Properties:

- **Connection** (a line): the type's name or "Undefined" in the heading; a caution note
  when endpoint types conflict or are incomplete ("Branching is disabled until they
  agree.") and another when a preserved manual route needs adjustment after an endpoint
  moved; **Route** (Automatic or Manual), **Start** and **End** (each endpoint with its
  type); the hint "Drag the line to preserve a manual bend. Select its center handle to
  start a branch."; **Rebuild automatic route** on a manual route, which clears the bends;
  and **Delete this segment**, which removes that line only, never the equipment or an
  unrelated branch. Removing the last line of a network takes its endpoints with it
  ("Removed the connection with its endpoints."); a junction left with two sides merges
  into one line, one left with one side becomes an open end, and a network cut in two
  becomes two networks.
- **Connection point**: **Name** (200 characters), **Connection type** (Not selected, or
  one of the eight), **Role** (Bidirectional, Input, Output), **Direction** (North,
  NorthEast, East, SouthEast, South, SouthWest, West, NorthWest), and **Remove this
  point**, or **Remove point, keep open end** when a line ends on it.
- **Junction**: "Drag the junction handle to reposition every attached route. Remove a
  branch by selecting its segment; the junction simplifies automatically when only two
  sides remain."
- **Open end**: where it is preserved ("grid 12.5, 4") and how to reconnect it: drag it
  onto a free terminal, drag a terminal here, or delete the attached line.

Automatic routes are orthogonal and take no obstacle into account; a manual route keeps its
bends until you rebuild it. Moving, resizing, rotating, flipping or scaling a symbol never
disconnects it: the routes re-attach to where the terminals now are, and an attached manual
route is flagged for adjustment when its end moved. Removing a symbol turns its terminals
into open ends at their last position. Changing a symbol's drawing (**Change symbol…**)
keeps every connection the new drawing still declares a terminal for and releases the
others to loose ends, and the feed names how many. Connection removals (a line, a point, a
rebuilt route) report with the same **Undo**, which puts the whole network back as it
stood; an edit made to the same connection in between is replaced, and the feed says so.

A connection edit the station refuses is shown inline at the top of Properties and in the
feed ("Connection edit was not saved: …"); while a network write is in flight the
connection buttons are disabled. In view mode the same lines and end markers are drawn
without handles, and an undefined network keeps its neutral dashed style without any
warning: you may have left it that way on purpose.

## What the editor does not do {#what-the-editor-does-not-do}

It has no undo beyond the last removal and no history of edits: every other change is
saved as it is made. It has no clipboard across screens, no arrow-key nudging, no
alignment or distribution tools, no free-pixel placement and no per-edit confirmation. It
does not edit a unit panel (arranged on the [Panels](process-panels) row of its model) and
does not create screens for a model (that is the model's
[Dashboards](process-dashboards) row, which opens this same editor). It never sizes the
grid in a way that pushes a component outside it, and it never writes a value to the
plant: the controls on the edit canvas are inert.