# surfaces reference

> Panes, windows and their chart, table and heatmap panels.

The price pane is implicit. `pane(...)` adds a pane below the chart sharing its time axis; `window(...)` declares a separate window with chart, table or heatmap panels.

## Functions

### chart.panel {#chart-panel}

```flowscope
chart.panel(sub: Subscription? = null, axis: Axis? = null, title: string = "") -> ChartPanel
```

Adds a chart panel to a window.

Declare it as a named field inside a `window` block, then refer to it as
`win.main`.

Choose one data layout:

- `sub`: Use a bar subscription to set the chart's horizontal axis.
- `axis`: Choose an axis and add plot values with `set(key, ...)`. Each key
  must match the axis's type.

Provide either `sub` or `axis`, but not both. Leaving both null is also an
error. Use `title` to name the panel.

Set `on: win.main` to draw in its price pane. To draw in a separate pane,
create one with `pane(..., on: win.main)` and target that pane instead.

| Parameter | Type |
|---|---|
| `sub` | `Subscription?` |
| `axis` | `Axis?` |
| `title` | `string` |

**Returns** `ChartPanel`

**Available in** Setup only: declarations, `setup` and `state` initialisers.

### heatmap.new {#heatmap-new}

```flowscope
heatmap.new(title: string = "", x: Axis, y: Axis, capacity: int, min: float? = null, max: float? = null, palette: color[] = []) -> HeatmapPanel
```

Creates a heatmap panel.

- `title` names the panel.
- `x` and `y` choose the two axes and the types of keys used for each.
- `capacity` limits the number of cells, from 1 to 65536. Other values are
  rejected before the script runs. When the heatmap is full, a new cell
  drops the oldest one, so a heatmap keyed by bar scrolls.
- `min` and `max` set a fixed color scale when both are supplied. Leave them
  null for automatic scaling.
- `palette` supplies the gradient colors. An empty list uses the default palette.

Add or update cells with `hm.set(x, y, value)`.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `x` | `Axis` |
| `y` | `Axis` |
| `capacity` | `int` |
| `min` | `float?` |
| `max` | `float?` |
| `palette` | `color[]` |

**Returns** `HeatmapPanel`

**Available in** Setup only: declarations, `setup` and `state` initialisers.

### pane {#pane}

```flowscope
pane(title: string = "", height: float = 0.3, on: ChartPanel? = null) -> Pane
```

Adds a separate pane to a chart.

- `title` names the pane.
- `height` sets its size relative to the main price pane: `0.5` means half as
  tall. Use a value from 0.05 to 1.0, inclusive. Other values are rejected
  before the script runs.
- `on` chooses a window chart panel, such as `dash.daily`. Omit it to use the
  main chart.

Use `on: paneName` when declaring a plot to draw in this pane. Plots without
`on:` use their default pane. Panes appear in declaration order, with up to 4
per chart.

Give the pane a name and keep it stable to preserve saved appearance settings.
Moving an unnamed pane to another declaration can reset those settings. Names
starting with `$` are reserved for panes created automatically by the app.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `height` | `float` |
| `on` | `ChartPanel?` |

**Returns** `Pane`

**Available in** Setup only: declarations, `setup` and `state` initialisers.

### table.cell {#table-cell}

```flowscope
table.cell(value: scalar, fg: color? = null, bg: color? = null, align: Align? = null) -> TableCell
```

Adds text color, background color, or alignment to a table value.

`value` can be a float, int, bool, string, or time. Null displays an empty cell.

- `fg` sets the text color.
- `bg` sets the background color.
- `align` sets text alignment.

Leave a style option null to use the table or column setting. For unstyled
cells, pass values directly to `row` or `set`; no `table.cell` wrapper is needed.

| Parameter | Type |
|---|---|
| `value` | `scalar` |
| `fg` | `color?` |
| `bg` | `color?` |
| `align` | `Align?` |

**Returns** `TableCell`

**Available in** Handlers and functions called from handlers.

### table.col {#table-col}

```flowscope
table.col(title: string = "", align: Align? = null, width: float = 1) -> TableColumn
```

Defines a column for a table.

Use this inside the `columns` list of `table.new`.

- `title` names the column.
- `align` sets text alignment. Null uses left alignment.
- `width` sets the column's relative width. A value of `0.6` gives it 60% of
  the space given to a column with width `1.0`. Use 0.1 to 10.0, inclusive;
  other values are rejected before the script runs.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `align` | `Align?` |
| `width` | `float` |

**Returns** `TableColumn`

**Available in** Setup only: declarations, `setup` and `state` initialisers.

### table.new {#table-new}

```flowscope
table.new(columns: TableColumn[], title: string = "", key: Axis? = null, capacity: int = 100) -> TablePanel
```

Creates a table panel with fixed columns.

- `title` names the panel.
- `columns` defines up to 16 columns using `table.col`.
- `key` chooses the row-key type. Leave it null to use string category keys.
- `capacity` limits the number of rows. Values outside the allowed range are
  rejected before the script runs. Adding a new row when full stops the
  script with an error.

Rows stay in the table until you update or delete them. Use the table methods
to add rows, change cells, or clear data. The app handles sorting, filtering,
and resizing columns.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `columns` | `TableColumn[]` |
| `key` | `Axis?` |
| `capacity` | `int` |

**Returns** `TablePanel`

**Available in** Setup only: declarations, `setup` and `state` initialisers.

### window {#window}

```flowscope
window(title: string = "") -> Window
```

Creates a window containing charts, heatmaps, or tables.

`title` names the window. A script attached to a chart starts with its window
closed; open it from the badge beside the script's name. A script opened
without a chart shows its window immediately.

Declare each panel as a named field inside the window block, then refer to it
as `win.main`. Each field needs a different name within its window and must
contain one chart, heatmap, or table panel. A panel cannot be shared between
fields. Different windows can reuse field names.

Use `on: win.main` to add a pane to a window's chart panel. Keep the window and
panel names stable to preserve saved settings; `title` only changes the label.
A script can create up to 4 windows.

| Parameter | Type |
|---|---|
| `title` | `string` |

**Returns** `Window`

**Available in** Setup only: declarations, `setup` and `state` initialisers.

## Methods

### surfaces.heatmap.set {#surfaces-heatmap-set}

```flowscope
surfaces.heatmap.set(x: Key, y: Key, value: float?) -> void
```

Adds or updates a heatmap cell.

`x` and `y` locate the cell. `value` sets its value; null deletes the cell.
The panel's color scale determines the cell color.

Adding a new cell when `capacity` is reached stops the script with an error.

| Parameter | Type |
|---|---|
| `x` | `Key` |
| `y` | `Key` |
| `value` | `float?` |

**Available in** Handlers and functions called from handlers.

### surfaces.pane.setTitle {#surfaces-pane-settitle}

```flowscope
surfaces.pane.setTitle(text: string) -> void
```

Sets the title the chart shows for this pane's legend row.

Call this on a pane you declared, such as `wt.setTitle(text)`, or another name
referring to that pane. You can call it on every update. The chart refreshes
the title after the handler finishes when the text has changed. Pass an empty
string to restore the pane's original `title:`.

Titles are limited to 256 UTF-8 bytes; longer text is shortened. Saved
appearance settings keep using the pane's declared name. Use `script.setTitle`
to change the title on the main price pane.

| Parameter | Type |
|---|---|
| `text` | `string` |

**Available in** Handlers and functions called from handlers.

### surfaces.table.clear {#surfaces-table-clear}

```flowscope
surfaces.table.clear(key: Key? = null) -> void
```

Deletes one row or clears the table.

Pass `key` to delete that row. An unknown key does nothing. Omit `key`, or
pass null, to delete every row.

| Parameter | Type |
|---|---|
| `key` | `Key?` |

**Available in** Handlers and functions called from handlers.

### surfaces.table.row {#surfaces-table-row}

```flowscope
surfaces.table.row(key: Key, cells: TableCell...) -> void
```

Adds or replaces a whole table row.

`key` identifies the row. Supply one value in `cells` for each column, in
column order. The number of cells must match the column count. A mismatch is
rejected before the script runs when it can be checked then; otherwise it
stops the script with an error.

Pass plain values for unstyled cells or use `table.cell` to style individual
cells. Use `rowBg` to set the row's background. Updating a row replaces all
of its cells together.

| Parameter | Type |
|---|---|
| `key` | `Key` |
| `cells` | `TableCell` |

**Available in** Handlers and functions called from handlers.

### surfaces.table.rowBg {#surfaces-table-rowbg}

```flowscope
surfaces.table.rowBg(key: Key, bg: color?) -> void
```

Changes the background color of an existing row.

`key` identifies the row. `bg` sets its background color; null restores the
theme default. A missing row stops the script with an error.

Use this after `row` to style the whole row.

| Parameter | Type |
|---|---|
| `key` | `Key` |
| `bg` | `color?` |

**Available in** Handlers and functions called from handlers.

### surfaces.table.set {#surfaces-table-set}

```flowscope
surfaces.table.set(key: Key, column: int, value: TableCell) -> void
```

Changes one cell in an existing row.

`key` identifies the row. `column` selects the column, counting from 0.
`value` can be a plain value or a styled `table.cell`.

A missing row, a negative `column`, or a column at or beyond the column count
stops the script with an error. Use `row` to create a row first.

| Parameter | Type |
|---|---|
| `key` | `Key` |
| `column` | `int` |
| `value` | `TableCell` |

**Available in** Handlers and functions called from handlers.

## Constants

| Constant | Type | Value | Description |
|---|---|---|---|
| `align.center` | `Align` | `1` | Centers text. |
| `align.left` | `Align` | `0` | Aligns text to the left. This is the default for columns and cells. |
| `align.right` | `Align` | `2` | Aligns text to the right. |
| `axis.category` | `Axis` | `2` | Uses string labels as keys, for example for bars grouped by exchange or symbol. |
| `axis.index` | `Axis` | `1` | Uses integer positions as keys, for example for distributions. |
| `axis.time` | `Axis` | `0` | Uses time values as keys, for example for custom candles or session bars. |