Options on a setting
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" });| Option | What it does |
|---|---|
label | the row's name in the dialog. Without one the row shows description, else the name read as words (show_bands reads "Show Bands") |
description | the long text of the setting, recorded in the sheet |
min, max | bounds 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 |
step | the 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 |
slider | true draws a bounded param.int or param.number as a slider |
hint | words behind a small glyph after the label, shown on hover |
row | rows that name the same word share one line of the dialog |
when | the 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 |
hide | with 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_default | a unit picker beside a number (Sessions and units) |
confirm | marks 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_values | param.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. shows Dollars and Contracts or coins and paints text.format: "@size_ 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_ 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 |
required | recorded in the sheet; on the chart a setting always has a value |
tz | param.session only: the zone the window is written in |
Which kind takes which option
| Option | Kinds that take it |
|---|---|
label, description, group, row, hint, when, hide, confirm, required, visible_by | every typed kind |
min, max, step, slider | the number fields: int, number, price, range |
max | also param.list, as the most items the list may hold |
unit, unit_default | one number field: int, number, price (a range's two ends have no unit picker) |
tz | param.session only |
style_values | param.choice only |
required, min, max, description | plain param, which takes no other key |
On any other kind they are refused.
What the dialog draws
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
whenon a setting names the setting that opens the row, in one of the five forms above;toggleandwhenon asection(...)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 earlyreturnthat tests it) does nothing while that branch is closed. The build warns on its line until itswhennames 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. Astyle_valueslist 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 whosestyle_valuespaint 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). hidewithoutwhen:param.int 'x' declares hide without when; hide names what happens when the when param is off, so declare when beside it.whennaming 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").whencomparing 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).