Options on a setting

View as MarkdownOpen the editor

Every kind takes one options object, every key optional, and a key the kind cannot use is refused by name, on the declaration's line.

What it is

An option is one of the dialog's words on a declaration: the row's name, its stepper, a glyph with a tooltip, which rows share a line, which toggle dims it, where it lands, and the bounds of a number field. Plain param(...) keeps its four keys, required, min, max and description; the dialog's words belong to the typed settings, param.int(...), param.bool(...) and the rest.

Declare it

wrun
// Two fields on one line of the dialog, the first with a hint.
param.int("fast", 9, { min: 1, max: 200, row: "lengths", hint: "Bars in the fast average" });
param.int("slow", 21, { min: 2, max: 400, row: "lengths" });
param.color("slow_color", "#f59e0b", { label: "Color" });
param.bool("smooth", false);
// Dimmed until the toggle it names is on.
param.number("smoothing", 0.3, { min: 0, max: 1, step: 0.05, slider: true, when: "smooth" });
// Dimmed unless the choice holds its third option (option index 2).
param.choice("band", ["none", "average", "average and bands"], "none");
param.number("band_width", 2, { min: 0, step: 0.1, when: "band=2" });
OptionWhat it does
labelthe row's name in the dialog. Without one the row shows description, else the name read as words (show_bands reads "Show Bands")
descriptionthe long text of the setting, recorded in the sheet
min, maxbounds of a number field: a setting outside them is refused by name before the module runs; required by slider and by param.range; on param.list, max is the most items the list may hold
stepthe stepper's increment, nothing more: a setting between two steps runs as typed, as on TradingView. A param.int steps by 1 unless you say otherwise
slidertrue draws a bounded param.int or param.number as a slider
hintwords behind a small glyph after the label, shown on hover
rowrows that name the same word share one line of the dialog
whenthe setting that opens the row, in one of five forms: "name" while it is on (any value but 0), "!name" while it is off, "name=v", "name!=v", or "name in a,b" while it holds one of the listed values. A toggle holds 0 or 1, a choice its option index (when: "smoothing=2" opens the row on the third choice). The named setting is a param.bool, param.choice, param.int, param.number or param.multi; the row is dimmed while the gate is closed
hidewith when: hide the row instead of dimming it
group"Page" or "Page/Section": where the row lands, shorthand for the layout words (Pages, sections, dividers, notes)
unit, unit_defaulta unit picker beside a number (Sessions and units)
confirmmarks a setting whose change is worth confirming before it applies (one that refetches); recorded in the sheet, and the dialog applies edits as you make them for now
visible_by{ size_unit: [codes] }: the dialog shows the row only on markets whose size unit is listed, and leaves it out elsewhere while its value still reaches onStart() (Size units)
style_valuesparam.choice only: one word a choice, in the choices' order, the word the setting paints where a key takes words, such as a marks caption's text.format (Marks, spans and rays), while the choices stay the dialog's labels (option_labels). param.choice("size_shown_as", ["Dollars", "Contracts or coins"], "Dollars", { style_values: ["usd", "units"] }) shows Dollars and Contracts or coins and paints text.format: "@size_shown_as" with "usd" or "units". An option knob that takes a word from a setting reads the pick's word the same way: expiries: "@expiries" on option_strike_flow over style_values: ["all", "0dte", "after_today"] (Knobs from a setting). Kept in the sheet and stripped from the literal before the AssemblyScript build, like visible_by: the module never reads it
requiredrecorded in the sheet; on the chart a setting always has a value
tzparam.session only: the zone the window is written in

Which kind takes which option

OptionKinds that take it
label, description, group, row, hint, when, hide, confirm, required, visible_byevery typed kind
min, max, step, sliderthe number fields: int, number, price, range
maxalso param.list, as the most items the list may hold
unit, unit_defaultone number field: int, number, price (a range's two ends have no unit picker)
tzparam.session only
style_valuesparam.choice only
required, min, max, descriptionplain param, which takes no other key

On any other kind they are refused.

What the dialog draws

a toggle and a timeframe menu sharing one line of the dialog
the hint glyph after a label, with its words shown on hover
a bounded whole number drawn as a slider with its readout

The dialog adds the rest by itself. A row that differs from its default shows a dot and a reset button that names the default, and a dialog with more than twelve settings gets a filter box over every page.

Gotchas

  • when on a setting names the setting that opens the row, in one of the five forms above; toggle and when on a section(...) take the toggle's HANDLE (Pages, sections, dividers, notes).
  • A setting the code reads only inside a branch another setting decides (an if, a ? :, an && or an early return that tests it) does nothing while that branch is closed. The build warns on its line until its when names that setting, so the dialog dims the row then (What the build checks).
  • A key the kind does not take: param.int options accept only { required, min, max, description, label, step, group, row, hint, when, hide, slider, unit, unit_default, confirm, visible_by }, not 'tooltip'.
  • A size-unit list that is empty, repeats a code or names one past 3: param.bool 'x' visible_by takes { size_unit: [codes] }, the size units of the markets where the row shows, at least one and each once: 0 units, 1 coins, 2 shares, 3 contracts.
  • A typed key on plain param: param options accept only { required, min, max, description }, not 'label'.
  • A choice whose labels are not the words of the key it paints, and no style_values: plot.marks 'trades' text.format references "@size_shown_as", which is not a param.choice over compact|price|int|usd|units. A style_values list that is not one word a choice: param.choice 'size_shown_as' style_values lists 1 word for 2 choices; give one word a choice, in the choices' order (Dollars, Contracts or coins). A choice whose style_values paint no word key and feed no option knob is refused by name too.
  • A number-field key on a toggle: param.bool 'x' takes no min option (its value is not a number field).
  • A unit picker on a range: param.range 'r' takes no unit option (a unit picker sits beside one number field, not a range).
  • hide without when: param.int 'x' declares hide without when; hide names what happens when the when param is off, so declare when beside it.
  • when naming a setting that cannot open a row: param.int 'x' when names 'y', which is a param.color (when names a param.bool, param.choice, param.int, param.number or param.multi: "name", "!name", "name=v", "name!=v" or "name in a,b", e.g. when: "show_bands").
  • when comparing a choice with a value it does not hold: param.int 'x' when compares the choice 'y' with 2; a choice holds its option index, 0 to 1 (a, b).
  • A slider without both bounds: param.int 'x' declares slider without min and max (a slider needs both bounds).