surfaces reference

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(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.

Returns ChartPanel

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

heatmap.new

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).

Returns HeatmapPanel

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

pane

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.

Returns Pane

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

table.cell

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.

Returns TableCell

Available in Handlers and functions called from handlers.

table.col

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.

Returns TableColumn

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

table.new

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.

Returns TablePanel

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

window

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.

Returns Window

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

Methods

surfaces.heatmap.set

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.

Available in Handlers and functions called from handlers.

surfaces.pane.setTitle

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.

Available in Handlers and functions called from handlers.

surfaces.table.clear

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.

Available in Handlers and functions called from handlers.

surfaces.table.row

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.

Available in Handlers and functions called from handlers.

surfaces.table.rowBg

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.

Available in Handlers and functions called from handlers.

surfaces.table.set

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.

Available in Handlers and functions called from handlers.

Constants