Setting Class

Setting is the GScript entry point for building pre-run dialogs in code, and for re-opening the macro's own form during a run.

`Setting.builder()`

Create a new builder.

let builder = Setting.builder();
builder.add('mode', Dropdown().hint('Mode').options('safe', 'fast').selected('safe'));
builder.add('icon', ImagePicker().hint('Target').regionKey('iconRegion').regionDefault('0, 0, 1080, 1920'));
builder.build().show();

`Setting.get(key)`

Read one saved setting value. Returns null if that key is not part of the current macro settings or a settings dialog shown in this run.

let ok = Setting.builder()
  .add('mode', Dropdown().hint('Mode').options('safe', 'fast').selected('safe'))
  .show();
if (ok) console.log(Setting.get('mode'));

`Setting.show()`

Show the currently registered dialog (the macro's own form, or the last one this script built) and return true if the user applied values.

let builder = Setting.builder();
builder.add('name', EditText().hint('Name').text('MacroForge'));
console.log(builder.show());

`Setting.showMacro(timeout?)`

Re-open the macro's own form, the one built in the Settings Builder tab, whatever this script has built since. Returns true if the user applied values.

prepareAccount(Setting.get('target'));
// Setup is done - reopen the form the macro itself defines.
if (!Setting.showMacro()) Sys.stop();
console.log(Setting.get('target'));

`Setting.hasMacro()`

true when the macro has a settings form of its own.

if (Setting.hasMacro()) Setting.showMacro();

`Setting.lastResult()`

How the last form ended: "applied", "dismissed", "timeout", "unavailable" or "none".

if (!Setting.showMacro(30000)) {
  if (Setting.lastResult() == 'timeout') log('nobody answered');
  else Sys.stop();
}

Asking again mid-run. Setting.showMacro() shows the macro's own form again at any point. It pauses the run until the user answers, and on Apply saves the answers, so Setting.get(key) and getVar(key) see them straight away.

// Configured before the run started, in the macro's own settings.
prepareAccount(Setting.get("target"));

// Setup is finished; let the user configure the run.
if (!Setting.showMacro()) { Sys.stop(); }
log("running against " + Setting.get("target"));

Setting.show() shows the registered form: the macro's own until the script calls Setting.builder(), then the script's. Setting.showMacro() always shows the macro's.

Time limits. By default a form waits for the user. Pass milliseconds, or { timeout: ms }, to any show: Setting.showMacro(ms), Setting.show(ms), Setting.show(items, ms), builder.show(ms). A form that times out is closed without saving and returns false.

Setting.lastResult() tells the false cases apart:

`Setting.lastResult()`	What happened
`"applied"`	The user pressed Apply.
`"dismissed"`	The user closed the form.
`"timeout"`	The time limit closed it.
`"unavailable"`	There was no form to show, or nowhere to show it.
`"none"`	No form has been shown yet in this run.

if (!Setting.showMacro(30000)) {
    if (Setting.lastResult() == "timeout") {
        log("nobody answered, carrying on with the previous settings");
    } else {
        Sys.stop();
    }
}

Inside the Setting Builder's Code dialog, show(), showMacro() and builder().show() return false without showing anything. End that script with .build();.

Available builder factories:

`EditText()`

Text entry

let builder = Setting.builder();
let result = EditText();
console.log(result);

`Checkbox()`

Checkbox-style boolean input

let builder = Setting.builder();
let result = Checkbox();
console.log(result);

`Switch()`

Switch-style boolean input

let builder = Setting.builder();
let result = Switch();
console.log(result);

`RadioGroup()`

Single choice with visible radio options

let builder = Setting.builder();
let result = RadioGroup();
console.log(result);

`Dropdown()`

Single choice from a dropdown

let builder = Setting.builder();
let result = Dropdown();
console.log(result);

`Slider()`

Numeric range

let builder = Setting.builder();
let result = Slider();
console.log(result);

`ImagePicker()`

Template path + search region, two output variables

let builder = Setting.builder();
let result = ImagePicker();
console.log(result);

`Record()`

Asks the user to record a gesture and stores it in the variable. Play it with a Recording action's Advanced reference.

let builder = Setting.builder();
let result = Record();
console.log(result);

`TabLayout()`

Multiple setting tabs

let builder = Setting.builder();
let result = TabLayout();
console.log(result);

`Text()`

Read-only text

let builder = Setting.builder();
let result = Text();
console.log(result);

`Header()`

Section heading

let builder = Setting.builder();
let result = Header();
console.log(result);

`Divider()`

Visual divider

let builder = Setting.builder();
let result = Divider();
console.log(result);

TabLayout() child fields need their own .key("...") if you want to read them later with Setting.get(...).

On every view. These work on every factory above:

`.key(name)`

The variable the answer is written to. Same thing as passing the key to .add(key, view).

let builder = Setting.builder();
let result = .key('demo');
console.log(result);

`.section(name)`

Groups the setting under a shared heading.

let builder = Setting.builder();
let result = .section('demo');
console.log(result);

`.visibleWhen(expr)`

Shows the setting only while a condition is true, e.g. .visibleWhen("mode == 'advanced'"). Same syntax as Visibility Condition in the builder.

let builder = Setting.builder();
let result = .visibleWhen('demo');
console.log(result);

`.required()`

Blocks the form while the setting is visible and blank. Call .required(false) to turn it back off.

let builder = Setting.builder();
let result = .required();
console.log(result);

Per-view setters. Beyond the common ones, each factory has its own:

`EditText()`

.hint(label), .helper(description), .text(default), .method(n) where n is 1 for a number keyboard and 2 for decimal

let builder = Setting.builder();
let result = EditText();
console.log(result);

`Checkbox()`

.text(label), .checked(bool)

let builder = Setting.builder();
let result = Checkbox();
console.log(result);

`Switch()`

.text(label), .checked(bool)

let builder = Setting.builder();
let result = Switch();
console.log(result);

`RadioGroup()`

.options(a, b, c) as separate arguments, .selected(default); Dropdown() also takes .hint(label)

let builder = Setting.builder();
let result = RadioGroup();
console.log(result);

`Dropdown()`

.options(a, b, c) as separate arguments, .selected(default); Dropdown() also takes .hint(label)

let builder = Setting.builder();
let result = Dropdown();
console.log(result);

`Slider()`

.min(n), .max(n), .step(n), .value(default), .label(text)

let builder = Setting.builder();
let result = Slider();
console.log(result);

`ImagePicker()`

.hint(label), .helper(description), .template(name), .regionKey(name), .regionDefault("x, y, w, h"), .fullscreen(bool) to default the region to the whole screen, and .templatePick(bool) / .regionPick(bool) to take either picker away from the user

let builder = Setting.builder();
let result = ImagePicker();
console.log(result);

`Record()`

.hint(label), .helper(description)

let builder = Setting.builder();
let result = Record();
console.log(result);

`TabLayout()`

.addTab(title, [views]), once per tab

let builder = Setting.builder();
let result = TabLayout();
console.log(result);

`Text()`

.text(body)

let builder = Setting.builder();
let result = Text();
console.log(result);

`Header()`

.text(title), .description(subtitle)

let builder = Setting.builder();
let result = Header();
console.log(result);

Example, a grouped and conditional form:

let b = Setting.builder();
b.add("mode", Dropdown().hint("Mode").options("simple", "advanced").selected("simple"));
b.add("target", ImagePicker()
  .hint("Target icon")
  .regionKey("targetRegion")
  .section("Detection")
  .required());
b.add("retries", Slider().label("Retries").min(1).max(10).value(3)
  .section("Detection")
  .visibleWhen("mode == 'advanced'"));

if (!b.build().show()) { Sys.stop(); }

A note on booleans: every setting comes back as a string. A switch reads "true" or "false", and both are non-empty strings, so both count as true. Compare explicitly, Setting.get("x") == "true", never if (Setting.get("x")).

Example:

let builder = Setting.builder();
builder.add("title", Header().text("Run Setup").description("Choose how the macro should behave"));
builder.add("mode", Dropdown().hint("Mode").options("safe", "fast").selected("safe"));
builder.add("retries", Slider().label("Retries").min(1).max(10).step(1).value(3));

if (!builder.build().show()) {
  Sys.stop();
}

console.log(Setting.get("mode"));
console.log(Setting.get("retries"));