forge.draw

Colours, plot styles and drawing calls for Forge indicators.

Style is data, separate from logic: nothing here can change a value an indicator computes.

Colours A colour is one of: a name (``color.red``), ``rgb(30, 144, 255)`` with an optional alpha, a ``'#rrggbb'`` or ``'#rrggbbaa'`` string, or a theme colour (``color.theme.up``, written ``theme.up`` or ``theme.up/0.50`` with an alpha). A theme colour is chosen by the chart's theme, so it follows light and dark mode; a fixed colour never changes. The theme colours are ``up``, ``down``, ``neutral``, ``accent``, ``warning``, ``background``, ``text``, ``grid`` and the eight series colours ``series_a`` to ``series_h``. ``chart.bg_color`` is the chart's own background.

Up and down colours A line-style value output with ``color_up`` and ``color_down`` takes ``color_up`` where the value is above the previous bar's value, ``color_down`` where it is below, and keeps the previous colour where it is equal. A ``histogram`` or ``columns`` output takes ``color_up`` at or above its ``base`` and ``color_down`` below. An event takes ``color_up`` on +1 and ``color_down`` on -1.

Styles ``value``: line, step, line_gaps, histogram, columns, area, area_gaps, dots, cross, square, dash, marker, zigzag. ``state``: background, bar_color, marker. ``event``: marker, background, bar_color. ``zone``: area. ``width`` applies to every value style but ``marker``; ``dash`` (``solid``, ``dot``, ``dash``) to line, step, line_gaps and zigzag; ``base`` to histogram, columns and the two area styles; ``shift`` (bars, drawing only) to every style but background and bar_color.

Drawings ``label``, ``line``, ``hline``, ``vline``, ``level`` and ``box`` draw on the chart while an indicator runs (in ``setup``, ``calculate`` or ``on_bar``). Each returns a ``Drawing`` handle with ``update`` and ``delete``; ``find(id)`` and ``all(kind)`` list the live ones. Drawings are for eyes: a handle exposes no coordinate, text or colour, so anything a strategy needs must be an output.

Points A ``Point`` is anchored by ``bar=`` or by ``time=`` (nanoseconds since the epoch in Python, milliseconds on the wire). On time bars a time after the last bar is counted forward by the bar length; on other bar types (renko, range, and so on) draw by bar. A drawing reaches at most 500 bars past the last bar.

When drawings are kept A chart run keeps them; a test run (engine mode) keeps none, so a backtest never pays for drawing. An indicator that draws in ``calculate`` is recalculated from bar 0 on each update. A bar-by-bar indicator's drawings on the forming bar are shown, then rolled back like its state. Code drawings live only in the indicator's own series payload, never in the chart's saved drawings, so clearing the drawings a user made cannot remove them.

Caps At most 500 drawings of each kind and ``max_drawings`` in all are kept; past either the oldest goes. The first drop of a run adds one warning to the log and nothing is raised.