# plot reference

> Series plots, fills and their styles.

Declare a plot at top level (`plot fast = plot.line(...)`) and feed it from handlers with `fast.plot(value)`. A null value leaves a gap. `fill.between` shades between two plots.

## Functions

### fill.between {#fill-between}

```flowscope
fill.between(a: PlotLine, b: PlotLine, color: color? = null) -> Fill
```

Creates a fill between two line plots.

`a` and `b` must be line plots on the same pane, both using subscribed bars.
Other pairs are rejected before the script runs.

`color` sets the fill color; null uses the theme default. Call `fill` on each
update to draw the fill, optionally passing a different color. Updating either
line without calling `fill` leaves that span unfilled.

| Parameter | Type |
|---|---|
| `a` | `PlotLine` |
| `b` | `PlotLine` |
| `color` | `color?` |

**Returns** `Fill`

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

### plot.arrow {#plot-arrow}

```flowscope
plot.arrow(title: string = "", colorUp: color? = null, colorDown: color? = null, minHeight: float? = null, maxHeight: float? = null, paddingPx: float? = null, shaftWidth: float? = null, headLengthPx: float? = null, headWidthRatio: float? = null, offset: int = 0, showLabel: bool = true, showValue: bool = true, on: Surface? = null) -> PlotArrow
```

Creates arrows whose direction and height follow a value.

Positive and negative values choose the direction. A larger absolute value
makes a taller arrow. Null skips a bar.

- `title` names the plot.
- `colorUp` and `colorDown` set the direction colors.
- `minHeight` and `maxHeight` set the height range, each from 0.0 to 200.0 pixels.
- `paddingPx` and `headLengthPx` each accept 0.0 to 50.0 pixels.
- `shaftWidth` accepts 0.5 to 20.0 pixels.
- `headWidthRatio` accepts 1.0 to 5.0. Null geometry options use the theme default.
- `offset` shifts values along the bars, from -500 to 500. Other values are
  rejected before the script runs.
- `showLabel` and `showValue` control the legend label and value.
- `on` chooses the panel or pane. Null uses the main price pane.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `colorUp` | `color?` |
| `colorDown` | `color?` |
| `minHeight` | `float?` |
| `maxHeight` | `float?` |
| `paddingPx` | `float?` |
| `shaftWidth` | `float?` |
| `headLengthPx` | `float?` |
| `headWidthRatio` | `float?` |
| `offset` | `int` |
| `showLabel` | `bool` |
| `showValue` | `bool` |
| `on` | `Surface?` |

**Returns** `PlotArrow`

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

### plot.bar {#plot-bar}

```flowscope
plot.bar(title: string = "", color: color? = null, offset: int = 0, showLabel: bool = true, showValue: bool = true, capacity: int = 512, on: Surface? = null) -> PlotBar
```

Creates an OHLC bar plot.

- `title` names the plot.
- `color` sets the bar color. Null uses the theme default.
- `offset` shifts values along the bars, from -500 to 500. Other values are
  rejected before the script runs.
- `showLabel` and `showValue` control the legend label and value.
- `on` chooses the panel or pane. Null uses the main price pane.
- `capacity` accepts 1 to 4096, but does not affect this plot: OHLC bars only
  support subscribed bars.

Use `plot` to draw each bar. Placement on a panel with an explicit keyed axis
is rejected before the script runs.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `color` | `color?` |
| `offset` | `int` |
| `showLabel` | `bool` |
| `showValue` | `bool` |
| `capacity` | `int` |
| `on` | `Surface?` |

**Returns** `PlotBar`

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

### plot.bg {#plot-bg}

```flowscope
plot.bg(title: string = "", color: color? = null, on: Surface? = null) -> PlotBg
```

Creates background highlights behind the chart.

`title` names the plot. `color` sets the tint; null uses the theme default.
`on` chooses the pane, with null using the main price pane.

Call `plot` to tint a bar across the full pane height, behind other drawings.
Skip the call to leave the bar clear. Background plots only support subscribed bars.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `color` | `color?` |
| `on` | `Surface?` |

**Returns** `PlotBg`

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

### plot.candle {#plot-candle}

```flowscope
plot.candle(title: string = "", bodyColor: color? = null, wickColor: color? = null, borderColor: color? = null, offset: int = 0, showLabel: bool = true, showValue: bool = true, capacity: int = 512, on: Surface? = null) -> PlotCandle
```

Creates a candlestick plot.

- `title` names the plot.
- `bodyColor`, `wickColor`, and `borderColor` set the candle colors. Null uses
  the theme default.
- `offset` shifts values along the bars, from -500 to 500. Other values are
  rejected before the script runs.
- `showLabel` and `showValue` control the legend label and value.
- `on` chooses the panel or pane. Null uses the main price pane.

Use `plot` for candles along subscribed bars. On a time-axis panel, use `set`
with your own candle times.

`capacity` limits keys to 512 by default, with a maximum of 4096. Adding a
new key when full stops the script with an error.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `bodyColor` | `color?` |
| `wickColor` | `color?` |
| `borderColor` | `color?` |
| `offset` | `int` |
| `showLabel` | `bool` |
| `showValue` | `bool` |
| `capacity` | `int` |
| `on` | `Surface?` |

**Returns** `PlotCandle`

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

### plot.cells {#plot-cells}

```flowscope
plot.cells(title: string = "", columns: int = 1, scale: CellScale = cellscale.bar, color: color? = null, borderColor: color? = null, textColor: color? = null, candles: CellCandles = cellcandles.overlay, format: CellFormat = cellformat.compact, decimals: int? = null, sign: bool = false, grouping: bool = false, on: Surface? = null) -> PlotCells
```

Creates a plot of rows of cells inside each bar, such as a footprint or a per-bar profile.

A cell is a rectangle over a price range inside a bar, with an optional width, colours and a number.

- `columns` splits each bar into 1 to 4 columns side by side. Other values are rejected before the script runs.
- `scale` says what a full-width cell means: `cellscale.bar` the largest weight on its own bar, `cellscale.view` the largest on the visible bars, `cellscale.unit` the weight is the width, from 0 to 1.
- `color`, `borderColor` and `textColor` are the defaults of cells that pass none. Without a `color` or `borderColor` there is no fill or no border; without a `textColor` the chart's text colour is used.
- `candles` says how the chart's own candles are drawn while the plot shows on the price pane: `cellcandles.overlay` as they are, `cellcandles.side` as a thin strip at the left of each bar, `cellcandles.hidden` not at all. With several cells plots, hidden wins over side, side over overlay.
- `format`, `decimals` (0 to 8), `sign` and `grouping` say how a cell's `value` is written: `3.21K` (compact), `3214.56` (fixed), `15.3%` (percent, of a ratio), `+3,215` with a sign and grouping. A number that does not fit its cell is written shorter, and left out when nothing fits.
- `on` chooses the pane. Null is the price pane.

Add cells with `cell` and empty a bar with `clear`. A cells plot has no value in the legend and does not change the price scale.

**Limits**

A bar holds at most 1024 cells per plot. A script keeps 400 000 cells over all its cells plots; beyond that the oldest bars lose theirs first.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `columns` | `int` |
| `scale` | `CellScale` |
| `color` | `color?` |
| `borderColor` | `color?` |
| `textColor` | `color?` |
| `candles` | `CellCandles` |
| `format` | `CellFormat` |
| `decimals` | `int?` |
| `sign` | `bool` |
| `grouping` | `bool` |
| `on` | `Surface?` |

**Returns** `PlotCells`

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

### plot.histogram {#plot-histogram}

```flowscope
plot.histogram(title: string = "", color: color? = null, horizontal: bool = false, showLabel: bool = true, showValue: bool = true, capacity: int = 512, on: Surface? = null) -> PlotHistogram
```

Creates a histogram or bar chart.

- `title` names the plot.
- `color` sets the bar color. Null uses the theme default.
- `horizontal` draws sideways bars. It requires an explicit category-axis panel;
  other placements are rejected before the script runs.
- `showLabel` and `showValue` control the legend label and value.
- `on` chooses the panel or pane. Without it, a vertical histogram uses the
  script's shared value pane on the main chart, named after the script.

Use `plot(value)` for bars along subscribed data or `set(key, value)` on a panel
with an explicit axis. Null leaves a gap with `plot` or deletes the key with
`set`. Multiple histograms on the same keyed panel form grouped bars. Stacking
is not supported.

`capacity` limits keys to 512 by default, with a maximum of 4096. Adding a
new key when full stops the script with an error.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `color` | `color?` |
| `horizontal` | `bool` |
| `showLabel` | `bool` |
| `showValue` | `bool` |
| `capacity` | `int` |
| `on` | `Surface?` |

**Returns** `PlotHistogram`

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

### plot.label {#plot-label}

```flowscope
plot.label(title: string = "", color: color? = null, size: float? = null, offset: int = 0, on: Surface? = null, anchor: Anchor? = null) -> PlotLabel
```

Creates a plot of text labels.

- `title` names the plot.
- `color` and `size` set the text appearance. Null uses the theme default.
  `size` must be from 6.0 to 48.0, inclusive.
- `offset` shifts values along the bars, from -500 to 500. Other values are
  rejected before the script runs.
- `on` chooses the panel or pane. Null uses the main price pane.

**Position**

Leave `anchor` null to position each mark at its plotted value. Use `anchor.top`
or `anchor.bottom` to pin it to that pane edge instead. The plotted value then
sets the distance inward from the edge in logical pixels. Negative distances
are allowed, but marks outside the pane are clipped. Edge-anchored marks do not
affect the vertical scale or show a legend value. Other anchors are rejected
before the script runs.

Use `plot` to place labels along subscribed bars. For persistent text placed
independently of a bar, use a label entity instead.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `color` | `color?` |
| `size` | `float?` |
| `offset` | `int` |
| `on` | `Surface?` |
| `anchor` | `Anchor?` |

**Returns** `PlotLabel`

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

### plot.line {#plot-line}

```flowscope
plot.line(title: string = "", color: color? = null, width: float? = null, style: LineStyle? = null, area: bool = false, offset: int = 0, showLabel: bool = true, showValue: bool = true, capacity: int = 512, on: Surface? = null) -> PlotLine
```

Creates a line plot.

- `title` names the plot.
- `color`, `width`, and `style` set its appearance. Null uses the theme default.
  `width` must be from 0.0 to 10.0, inclusive.
- `area` fills between the line and zero, using the line color.
- `offset` shifts values along the bars, from -500 to 500. Other values are
  rejected before the script runs.
- `showLabel` and `showValue` control the legend label and value.
- `on` chooses the panel or pane. Null uses the main price pane.

Use `plot(value)` for values along subscribed bars. On a panel with an explicit
axis, use `set(key, value)`. Null leaves a gap with `plot` or deletes the key
with `set`.

`capacity` limits keys to 512 by default, with a maximum of 4096. Adding a
new key when full stops the script with an error.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `color` | `color?` |
| `width` | `float?` |
| `style` | `LineStyle?` |
| `area` | `bool` |
| `offset` | `int` |
| `showLabel` | `bool` |
| `showValue` | `bool` |
| `capacity` | `int` |
| `on` | `Surface?` |

**Returns** `PlotLine`

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

### plot.marker {#plot-marker}

```flowscope
plot.marker(title: string = "", color: color? = null, shape: Shape? = null, size: float? = null, borderWidth: float? = null, borderColor: color? = null, offset: int = 0, showLabel: bool = true, showValue: bool = true, on: Surface? = null, anchor: Anchor? = null) -> PlotMarker
```

Creates a plot of shaped markers.

- `title` names the plot.
- `color`, `shape`, `size`, `borderWidth`, and `borderColor` set the appearance.
  Null uses the theme default. `size` must be from 1.0 to 60.0 and `borderWidth`
  from 0.0 to 10.0, inclusive.
- `offset` shifts values along the bars, from -500 to 500. Other values are
  rejected before the script runs.
- `showLabel` and `showValue` control the legend label and value.
- `on` chooses the panel or pane. Null uses the main price pane.

**Position**

Leave `anchor` null to position each mark at its plotted value. Use `anchor.top`
or `anchor.bottom` to pin it to that pane edge instead. The plotted value then
sets the distance inward from the edge in logical pixels. Negative distances
are allowed, but marks outside the pane are clipped. Edge-anchored marks do not
affect the vertical scale or show a legend value. Other anchors are rejected
before the script runs. `showLabel` and
`showValue` are ignored when anchored to an edge.

Use `plot` along subscribed bars. Null skips a bar. For a panel with an explicit
keyed axis, use a point plot instead.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `color` | `color?` |
| `shape` | `Shape?` |
| `size` | `float?` |
| `borderWidth` | `float?` |
| `borderColor` | `color?` |
| `offset` | `int` |
| `showLabel` | `bool` |
| `showValue` | `bool` |
| `on` | `Surface?` |
| `anchor` | `Anchor?` |

**Returns** `PlotMarker`

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

### plot.point {#plot-point}

```flowscope
plot.point(title: string = "", color: color? = null, size: float? = null, showLabel: bool = true, showValue: bool = true, capacity: int = 512, on: Surface? = null) -> PlotPoint
```

Creates a scatter plot of dots.

- `title` names the plot.
- `color` and `size` set the dots' appearance. Null uses the theme default.
  `size` must be from 0.5 to 30.0, inclusive. Shape and border options are not supported.
- `showLabel` and `showValue` control the legend label and value.
- `on` chooses the panel or pane. Null uses the main price pane.

Use `plot(value)` for dots along subscribed bars or `set(key, value)` on a panel
with an explicit axis. Null skips a dot with `plot` or deletes the key with `set`.

`capacity` limits keys to 512 by default, with a maximum of 4096. Adding a
new key when full stops the script with an error.

| Parameter | Type |
|---|---|
| `title` | `string` |
| `color` | `color?` |
| `size` | `float?` |
| `showLabel` | `bool` |
| `showValue` | `bool` |
| `capacity` | `int` |
| `on` | `Surface?` |

**Returns** `PlotPoint`

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

## Methods

### fill.fill {#fill-fill}

```flowscope
fill.fill(color: color? = null, topValue: float? = null, bottomValue: float? = null, topColor: color? = null, bottomColor: color? = null) -> void
```

Fills between the two lines on the current bar.

Pass `color` for a solid fill. For a vertical gradient, use `topValue` and
`bottomValue` to set its positions and `topColor` and `bottomColor` for its colors.

Do not mix solid and gradient colors in one call; this is rejected before the
script runs. Null colors use the fill default.

| Parameter | Type |
|---|---|
| `color` | `color?` |
| `topValue` | `float?` |
| `bottomValue` | `float?` |
| `topColor` | `color?` |
| `bottomColor` | `color?` |

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

### plot.arrow.plot {#plot-arrow-plot}

```flowscope
plot.arrow.plot(value: float?, colorUp: color? = null, colorDown: color? = null) -> void
```

Draws an arrow on the current bar.

`value` sets the arrow's height and direction; null skips the arrow. `colorUp`
and `colorDown` override the direction colors, with null keeping each plot
default. The plot declaration sets the arrow's shape and size limits.

| Parameter | Type |
|---|---|
| `value` | `float?` |
| `colorUp` | `color?` |
| `colorDown` | `color?` |

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

### plot.bar.plot {#plot-bar-plot}

```flowscope
plot.bar.plot(open: float?, high: float?, low: float?, close: float?, color: color? = null) -> void
```

Draws an OHLC bar on the current bar.

`open`, `high`, `low`, and `close` set the bar prices. If any is null, the whole
bar is skipped. `color` overrides its color; null keeps the plot default.

| Parameter | Type |
|---|---|
| `open` | `float?` |
| `high` | `float?` |
| `low` | `float?` |
| `close` | `float?` |
| `color` | `color?` |

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

### plot.bg.plot {#plot-bg-plot}

```flowscope
plot.bg.plot(color: color? = null) -> void
```

Tints the pane background on the bar being processed.

`color` sets the tint for this bar, and null keeps the default. Calling
`plot` marks the bar; not calling it leaves the bar clear.

| Parameter | Type |
|---|---|
| `color` | `color?` |

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

### plot.candle.plot {#plot-candle-plot}

```flowscope
plot.candle.plot(open: float?, high: float?, low: float?, close: float?, bodyColor: color? = null, wickColor: color? = null, borderColor: color? = null) -> void
```

Draws a candle on the current bar.

`open`, `high`, `low`, and `close` set the candle prices. If any is null, the
whole candle is skipped.

`bodyColor`, `wickColor`, and `borderColor` override its colors. Null keeps each
plot default.

| Parameter | Type |
|---|---|
| `open` | `float?` |
| `high` | `float?` |
| `low` | `float?` |
| `close` | `float?` |
| `bodyColor` | `color?` |
| `wickColor` | `color?` |
| `borderColor` | `color?` |

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

### plot.candle.set {#plot-candle-set}

```flowscope
plot.candle.set(key: Key, open: float?, high: float?, low: float?, close: float?, bodyColor: color? = null, wickColor: color? = null, borderColor: color? = null) -> void
```

Adds or updates a candle at a time key.

`key` sets the candle time. `open`, `high`, `low`, and `close` set its prices.
If any price is null, the candle is deleted.

`bodyColor`, `wickColor`, and `borderColor` override its colors. Null keeps each
plot default. Reuse the same time key to update a custom candle while it forms.

| Parameter | Type |
|---|---|
| `key` | `Key` |
| `open` | `float?` |
| `high` | `float?` |
| `low` | `float?` |
| `close` | `float?` |
| `bodyColor` | `color?` |
| `wickColor` | `color?` |
| `borderColor` | `color?` |

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

### plot.cells.cell {#plot-cells-cell}

```flowscope
plot.cells.cell(from: float?, to: float?, weight: float? = null, color: color? = null, borderColor: color? = null, value: float? = null, textColor: color? = null, column: int = 0, align: Align = align.left, time: time? = null) -> void
```

Adds a cell to a bar.

`from` and `to` are the cell's price range, in either order. Nothing happens when either is null or they are equal.

- `weight` is the width, compared as the plot's `scale` says. Null fills the column. A weight of zero or less draws no fill; border and text still draw.
- `color`, `borderColor` and `textColor` replace the plot's defaults.
- `value` is written in the cell when it fits.
- `column` chooses the column, from 0. A column the plot does not have stops the script with an error.
- `align` is the edge the width grows from: `align.left`, `align.right`, or `align.center` for both ways.
- `time` chooses the bar: null the current one, else the bar whose period contains it. A time after the current bar stops the script with an error.

The first `cell` or `clear` for a bar in one calculation step discards what the bar held from earlier steps; further `cell` calls in the step add to it. A script whose bar can go from having cells to having none calls `clear`.

| Parameter | Type |
|---|---|
| `from` | `float?` |
| `to` | `float?` |
| `weight` | `float?` |
| `color` | `color?` |
| `borderColor` | `color?` |
| `value` | `float?` |
| `textColor` | `color?` |
| `column` | `int` |
| `align` | `Align` |
| `time` | `time?` |

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

### plot.cells.clear {#plot-cells-clear}

```flowscope
plot.cells.clear(time: time? = null) -> void
```

Removes every cell this plot has on a bar.

`time` chooses the bar as for `cell`: null the current one. `cell` calls after `clear` in the same calculation step add to the emptied bar.

| Parameter | Type |
|---|---|
| `time` | `time?` |

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

### plot.histogram.plot {#plot-histogram-plot}

```flowscope
plot.histogram.plot(value: float?, color: color? = null) -> void
```

Draws a histogram bar on the current bar.

`value` sets the height from zero; null skips the bar. `color` overrides its
color, with null keeping the plot default.

| Parameter | Type |
|---|---|
| `value` | `float?` |
| `color` | `color?` |

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

### plot.histogram.set {#plot-histogram-set}

```flowscope
plot.histogram.set(key: Key, value: float?, color: color? = null) -> void
```

Adds or updates a histogram bar at a key.

`key` sets the position on the panel's axis. `value` sets the height; null deletes
the key. `color` overrides this bar's color, with null keeping the plot default.

Category axes create bar charts; `horizontal` makes sideways bars. Multiple
histograms on the same panel form grouped bars. Stacking is not supported.

| Parameter | Type |
|---|---|
| `key` | `Key` |
| `value` | `float?` |
| `color` | `color?` |

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

### plot.label.plot {#plot-label-plot}

```flowscope
plot.label.plot(price: float?, text: string, color: color? = null, size: float? = null) -> void
```

Draws a text label on the current bar.

`price` sets the position, or the pixel distance from the pane edge when the
plot uses an edge anchor. Null skips the label. `text` supplies the label text;
several labels can use the same text.

`color` and `size` override its appearance. Null keeps each plot default. A
`size` outside its allowed range stops the script with an error.

| Parameter | Type |
|---|---|
| `price` | `float?` |
| `text` | `string` |
| `color` | `color?` |
| `size` | `float?` |

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

### plot.line.plot {#plot-line-plot}

```flowscope
plot.line.plot(value: float?, color: color? = null) -> void
```

Draws a line value on the current bar.

`value` sets the price; null leaves a gap. `color` overrides this point's color;
null keeps the plot default.

Values follow the panel's time axis: the main chart's timeframe on the main
chart, or the panel's subscription timeframe in a window. A close handler places
the value at the closing candle's end time.

| Parameter | Type |
|---|---|
| `value` | `float?` |
| `color` | `color?` |

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

### plot.line.set {#plot-line-set}

```flowscope
plot.line.set(key: Key, value: float?, color: color? = null) -> void
```

Adds or updates a line value at a key.

`key` sets the position on the panel's axis. `value` sets the price; null deletes
the key. `color` overrides this point's color, with null keeping the plot default.

Plots on the same panel share the axis. Use time keys for a custom time series.

| Parameter | Type |
|---|---|
| `key` | `Key` |
| `value` | `float?` |
| `color` | `color?` |

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

### plot.marker.plot {#plot-marker-plot}

```flowscope
plot.marker.plot(value: float?, color: color? = null, shape: Shape? = null, size: float? = null, borderWidth: float? = null, borderColor: color? = null) -> void
```

Draws a marker on the current bar.

`value` sets the price, or the pixel distance from the pane edge when the plot
uses an edge anchor. Null skips the marker.

`color`, `shape`, `size`, `borderWidth`, and `borderColor` override its appearance.
Null keeps each plot default. A `size` or `borderWidth` outside its allowed range
stops the script with an error.

| Parameter | Type |
|---|---|
| `value` | `float?` |
| `color` | `color?` |
| `shape` | `Shape?` |
| `size` | `float?` |
| `borderWidth` | `float?` |
| `borderColor` | `color?` |

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

### plot.point.plot {#plot-point-plot}

```flowscope
plot.point.plot(value: float?, color: color? = null, size: float? = null) -> void
```

Draws a dot on the current bar.

`value` sets the price; null skips the dot. `color` and `size` override the dot's
appearance, with null keeping each plot default. A `size` outside its allowed
range stops the script with an error.

Calling again on the same bar replaces the dot; the last call wins.

| Parameter | Type |
|---|---|
| `value` | `float?` |
| `color` | `color?` |
| `size` | `float?` |

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

### plot.point.set {#plot-point-set}

```flowscope
plot.point.set(key: Key, value: float?, color: color? = null, size: float? = null) -> void
```

Adds or updates a dot at a key.

`key` sets the position on the panel's axis. `value` sets the price; null deletes
the key. `color` and `size` override this dot's appearance, with null keeping each
plot default. A `size` outside its allowed range stops the script with an error.

Each key has one dot. Calling again with the same key replaces the dot.

| Parameter | Type |
|---|---|
| `key` | `Key` |
| `value` | `float?` |
| `color` | `color?` |
| `size` | `float?` |

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

## Constants

| Constant | Type | Value | Description |
|---|---|---|---|
| `extend.both` | `Extend` | `3` | Entity extends in both directions. |
| `extend.down` | `Extend` | `5` | Line or box extends downward past its bottommost endpoint to the pane edge. |
| `extend.left` | `Extend` | `1` | Entity extends leftward past its leftmost endpoint along its slope. |
| `extend.none` | `Extend` | `0` | Entity does not extend beyond its x-range. |
| `extend.right` | `Extend` | `2` | Entity extends rightward past its rightmost endpoint along its slope. |
| `extend.up` | `Extend` | `4` | Line or box extends upward past its topmost endpoint to the pane edge. |
| `extend.vertical` | `Extend` | `6` | Line or box extends both upward and downward to the pane edges. |
| `linestyle.dashed` | `LineStyle` | `3` | Dashed line style. |
| `linestyle.dotted` | `LineStyle` | `2` | Dotted line style. |
| `linestyle.solid` | `LineStyle` | `1` | Solid line style. |
| `linestyle.step` | `LineStyle` | `4` | Step line style. |
| `cellcandles.overlay` | `CellCandles` | `0` | The chart's candles are drawn as usual, behind the cells. |
| `cellcandles.side` | `CellCandles` | `1` | The chart's candles are drawn as a thin strip at the left edge of each bar, beside the cells. |
| `cellcandles.hidden` | `CellCandles` | `2` | The chart's candles are not drawn. |
| `cellformat.compact` | `CellFormat` | `0` | Large numbers are shortened with a suffix, such as 3.21K or 53.1M. |
| `cellformat.fixed` | `CellFormat` | `1` | The number is written in full, such as 3214.56. |
| `cellformat.percent` | `CellFormat` | `2` | The value is a ratio written as a percentage, so 0.153 reads 15.3%. |
| `cellscale.bar` | `CellScale` | `0` | A full-width cell has the largest weight on its own bar. |
| `cellscale.view` | `CellScale` | `1` | A full-width cell has the largest weight on the visible bars. |
| `cellscale.unit` | `CellScale` | `2` | The weight is the width itself, as a fraction from 0 to 1. |
| `shape.asterisk` | `Shape` | `10` | Asterisk marker shape. |
| `shape.circle` | `Shape` | `1` | Circle marker shape. |
| `shape.cross` | `Shape` | `8` | Cross marker shape. |
| `shape.diamond` | `Shape` | `3` | Diamond marker shape. |
| `shape.down` | `Shape` | `5` | Down-triangle marker shape. |
| `shape.left` | `Shape` | `6` | Left-triangle marker shape. |
| `shape.plus` | `Shape` | `9` | Plus marker shape. |
| `shape.right` | `Shape` | `7` | Right-triangle marker shape. |
| `shape.square` | `Shape` | `2` | Square marker shape. |
| `shape.up` | `Shape` | `4` | Up-triangle marker shape. |