MacroPanel

Create a panel to collect macro settings from the user. Add fields, then call show() to display it.

Syntax

MacroPanel(title="", subtitle="", confirm_text="Run", cancel_text="Cancel", *, version="")

Constructor parameters

NameDescription
titleString
Panel title.
Optional · Positional or named
Default: ""
subtitleString
Panel subtitle/helper text.
Optional · Positional or named
Default: ""
confirm_textString
Confirm button label.
Optional · Positional or named
Default: "Run"
cancel_textString
Cancel button label.
Optional · Positional or named
Default: "Cancel"
versionString
Optional version label kept for compatibility; it does not reset native saved settings or change their identity.
Optional · Keyword only
Default: ""

Returns

Example

panel = MacroPanel("Run config", "Pick options before run", confirm_text="Start", cancel_text="Back")
panel.text("<b>Ready?</b>")
panel.checkbox("safe_mode", "Safe mode", checked=True)
panel.toggle_switch("retry", "Auto retry", checked=False)
panel.edit_text("username", default="player01", desc="Shown below the field")
panel.edit_text("runs", "Runs", default=3, desc="Numbers only", input_type="number")
panel.radio_group("mode", ["farm", "pvp"], default="farm")
panel.radio_group("target", ["boss", "minion"], default="boss", dropdown=True)
panel.slider("speed", min=0, max=100, step=5, default=60)
panel.stepper("retry_count", min=0, max=10, step=1, default=2)
values = panel.show()

Fields

NameDescription
titleString
Panel title. Writable after construction.
Default: ""
subtitleString
Panel subtitle/helper text. Writable after construction.
Default: ""
versionString
Optional version label kept for compatibility; it does not reset native saved settings or change their identity. Writable after construction.
Default: ""
confirm_textString
Confirm button label.
Default: "Run"
cancel_textString
Cancel button label.
Default: "Cancel"

Methods

13 methods

MacroPanel.notify

Show a message and wait for the user to confirm before continuing the script. Strings are shown as written; other values use the readable form of str(value), with nested data on multiple lines.

Syntax

MacroPanel.notify(text)

Parameters

NameDescription
textAny
Message text or structured value to display.
Required · Positional or named
No default

Returns

None — No return value after user confirmation.

Example

# Wait for the user to acknowledge this message
MacroPanel.notify("Macro is ready")

MacroPanel.error

Raise an error with this message and stop the script. During a macro run, the error display includes the flow and action path. Other values are converted to readable text as with str(value).

Syntax

MacroPanel.error(text)

Parameters

NameDescription
textAny
Error text or structured value to display.
Required · Positional or named
No default

Returns

None — Does not return; raises a runtime error.

Example

# A failed precondition ends the entire Run
if not TfliteModel.exists("enemy_detector"):
    MacroPanel.error("Import enemy_detector in Template Manager")

MacroPanel.edit_text

Add an editable field. Numeric input accepts finite signed decimal values, scientific notation and surrounding whitespace; blank, NaN, Infinity, overflow and hexadecimal are invalid. Invalid dialog input shows an error and blocks Run; an invalid floating draft shows an error and keeps the last valid value without saving the draft.

Syntax

panel.edit_text(name, label=None, default="", desc=None, input_type="text")

Parameters

NameDescription
nameString
Non-empty field key in the returned dict and persistent settings. Each input in a panel must have a different key. Native settings use the macro scope and protected namespace (or local macroId), variant, and field name; title, version, localized labels, and runtime instance are not part of the key.
Required · Positional or named
No default
labelString?
Display label. Leave empty to hide label.
Optional · Positional or named
Default: None
defaultString|Number
Input value used only when no native saved value or matching Storage value exists. A floating numeric field needs a valid initial value from native settings, Storage, or this default; otherwise show() raises an error.
Optional · Positional or named
Default: ""
descString?
Small helper text displayed below this field.
Optional · Positional or named
Default: None
input_typeString
Use "text" for a String or "number" for a Number (float). Native saved values take priority; otherwise numeric strings previously saved in Storage can be restored.
Optional · Positional or named
Default: "text"

Returns

MacroPanel — The same panel, so another panel method can be called on the result.

Example

# Build a panel and wait for user confirmation
panel = MacroPanel("Settings")
panel.edit_text("player", label="Player", default="Guest")
result = panel.show()
print(result)

MacroPanel.checkbox

Add a box the user can check or uncheck.

Syntax

panel.checkbox(name, label=None, checked=False)

Parameters

NameDescription
nameString
Non-empty field key in the returned dict and persistent settings. Each input in a panel must have a different key. Native settings use the macro scope and protected namespace (or local macroId), variant, and field name; title, version, localized labels, and runtime instance are not part of the key.
Required · Positional or named
No default
labelString?
Display label. Leave empty to hide label.
Optional · Positional or named
Default: None
checkedBoolean
Initial value used only when no native saved value or matching Storage value exists.
Optional · Positional or named
Default: False

Returns

MacroPanel — The same panel, so another panel method can be called on the result.

Example

# Build a panel and wait for user confirmation
panel = MacroPanel("Settings")
panel.checkbox("sound", label="Sound", checked=True)
result = panel.show()
print(result)

MacroPanel.toggle_switch

Add a switch the user can turn on or off.

Syntax

panel.toggle_switch(name, label=None, checked=False)

Parameters

NameDescription
nameString
Non-empty field key in the returned dict and persistent settings. Each input in a panel must have a different key. Native settings use the macro scope and protected namespace (or local macroId), variant, and field name; title, version, localized labels, and runtime instance are not part of the key.
Required · Positional or named
No default
labelString?
Display label. Leave empty to hide label.
Optional · Positional or named
Default: None
checkedBoolean
Initial value used only when no native saved value or matching Storage value exists.
Optional · Positional or named
Default: False

Returns

MacroPanel — The same panel, so another panel method can be called on the result.

Example

# Build a panel and wait for user confirmation
panel = MacroPanel("Settings")
panel.toggle_switch("enabled", label="Enabled", checked=True)
result = panel.show()
print(result)

MacroPanel.radio_group

Add a radio-group selector, or render it as a single- or multi-select dropdown when dropdown=True. Options can be a list or a dict mapping parent option labels to sub-option lists when depends_on is set.

Syntax

panel.radio_group(name, options, label=None, default=None, dropdown=False, multi_select=False, depends_on=None)

Parameters

NameDescription
nameString
Non-empty field key in the returned dict and persistent settings. Each input in a panel must have a different key. Native settings use the macro scope and protected namespace (or local macroId), variant, and field name; title, version, localized labels, and runtime instance are not part of the key.
Required · Positional or named
No default
optionslist[String]|dict[String, list[String]]
Selectable options or dictionary mapping parent option labels to lists of options when depends_on is set.
Required · Positional or named
No default
labelString?
Display label. Leave empty to hide label.
Optional · Positional or named
Default: None
defaultString|Int|list|None
Initial option used only when no native saved value or matching Storage value exists: a label, 0-based option index, or list of labels/indices when multi_select=True; None selects the first option (or none when multi_select=True).
Optional · Positional or named
Default: None
dropdownBoolean
Render this selector as a dropdown instead of radio options.
Optional · Positional or named
Default: False
multi_selectBoolean
Allow selecting multiple options when rendered as a dropdown. The panel returns a list of 0-based option indices.
Optional · Positional or named
Default: False
depends_onString?
Variable name of the preceding parent selector this dropdown depends on for cascading dynamic options.
Optional · Positional or named
Default: None

Returns

MacroPanel — The same panel, so another panel method can be called on the result.

Example

# Build a panel and wait for user confirmation
panel = MacroPanel("Settings")
panel.radio_group("mode", ["slow", "fast"], label="Mode", default="slow")
result = panel.show()
print(result)

MacroPanel.slider

Add a numeric slider.

Syntax

panel.slider(name, min=0, max=100, step=1, label=None, default=None)

Parameters

NameDescription
nameString
Non-empty field key in the returned dict and persistent settings. Each input in a panel must have a different key. Native settings use the macro scope and protected namespace (or local macroId), variant, and field name; title, version, localized labels, and runtime instance are not part of the key.
Required · Positional or named
No default
minNumber
Minimum value.
Optional · Positional or named
Default: 0
maxNumber
Maximum value; must be at least min.
Optional · Positional or named
Default: 100
stepNumber
Positive increment between slider values.
Optional · Positional or named
Default: 1
labelString?
Display label. Leave empty to hide label.
Optional · Positional or named
Default: None
defaultNumber?
Initial value used only when no native saved value or matching Storage value exists, then clamped to min/max.
Optional · Positional or named
Default: min

Returns

MacroPanel — The same panel, so another panel method can be called on the result.

Example

# Build a panel and wait for user confirmation
panel = MacroPanel("Settings")
panel.slider("speed", min=1, max=10, step=1, default=5)
result = panel.show()
print(result)

MacroPanel.stepper

Add a numeric stepper with +/- controls.

Syntax

panel.stepper(name, min=0, max=100, step=1, label=None, default=None)

Parameters

NameDescription
nameString
Non-empty field key in the returned dict and persistent settings. Each input in a panel must have a different key. Native settings use the macro scope and protected namespace (or local macroId), variant, and field name; title, version, localized labels, and runtime instance are not part of the key.
Required · Positional or named
No default
minNumber
Minimum integer value.
Optional · Positional or named
Default: 0
maxNumber
Maximum integer value; must be at least min.
Optional · Positional or named
Default: 100
stepNumber
Positive integer increment for each + or - press. Numeric inputs are converted to integers.
Optional · Positional or named
Default: 1
labelString?
Display label. Leave empty to hide label.
Optional · Positional or named
Default: None
defaultNumber?
Initial value used only when no native saved value or matching Storage value exists, then clamped to min/max.
Optional · Positional or named
Default: min

Returns

MacroPanel — The same panel, so another panel method can be called on the result.

Example

# Build a panel and wait for user confirmation
panel = MacroPanel("Settings")
panel.stepper("count", min=1, max=20, step=1, default=3)
result = panel.show()
print(result)

MacroPanel.text

Add an HTML text block. Basic tags render inline, and CSS-styled fragments such as cards, colored sections, flex rows, gradients, and rounded boxes render in a locked-down WebView with JavaScript and external navigation disabled.

Syntax

panel.text(html)

Parameters

NameDescription
htmlString
HTML content to display.
Required · Positional or named
No default

Returns

MacroPanel — The same panel, so another panel method can be called on the result.

Example

# Build a panel and wait for user confirmation
panel = MacroPanel("Settings")
panel.text("<b>Ready</b>")
result = panel.show()
print(result)

MacroPanel.localize

Register translated panel snapshots for a floating panel. Changing the selector updates the display immediately, including built-in Pause and select-all summaries, even while the macro is paused, without Python callbacks or reopening the panel; values, drafts and window position are retained. Only text may differ: title, subtitle, field labels and descriptions, HTML, and option display text. Options correspond by position; values, Storage and defaults remain those of the base panel. Selector options must be identical. Variants must have the same widget count, order, type and name, numeric limits, input_type, multi_select and dependency structure, and option counts including dependent branch keys and order. Nested localization is not supported. Calling again replaces the snapshots; later edits to source panels do not affect them until registered again. locales, when provided, must map every selector option label to en, vi, th, id, or fil and controls the built-in panel labels; None keeps the app language. Validation runs here and at show(); incompatible changes raise an error. A localized panel cannot be shown in dialog mode.

Syntax

panel.localize(selector, variants, *, locales=None)

Parameters

NameDescription
selectorString
Name of an existing preceding single-choice radio_group or dropdown; multi_select and depends_on are not allowed for this selector.
Required · Positional or named
No default
variantsdict[String, MacroPanel]
Exactly one panel for each selector option label, keyed by that label. Panels are copied at this call; their defaults do not change the base panel's behavior.
Required · Positional or named
No default
localesdict[String, String]?
Optional map from selector option labels to supported app language codes en, vi, th, id, or fil. It must cover every variant exactly and controls built-in panel labels such as Pause and select-all summaries; None keeps the app language.
Optional · Keyword only
Default: None

Returns

MacroPanel — The same panel, so another panel method can be called on the result.

Example

# Switch a floating panel between English and Vietnamese
en = MacroPanel("Fishing")
en.radio_group("language", ["English", "Tiếng Việt"], label="Language")
en.checkbox("enabled", label="Enabled", checked=True)
vi = MacroPanel("Câu cá")
vi.radio_group("language", ["English", "Tiếng Việt"], label="Ngôn ngữ")
vi.checkbox("enabled", label="Bật", checked=True)
en.localize("language", {"English": en, "Tiếng Việt": vi}, locales={"English": "en", "Tiếng Việt": "vi"})
config = en.show(mode="floating")

MacroPanel.show

Show the panel and return a dict of field names and values. Native saved values take priority, then matching Storage entries, then each input's default. Every accepted edit saves native settings immediately and mirrors Storage, including while the macro is paused; scripts do not need Storage.set(), values(), or close(). Checkboxes and switches return Boolean, sliders and numeric fields Number, steppers Int, selectors Int indexes starting at 0, and text fields String. Reopening the same show() repeatedly without another runtime action stops the script to prevent an endless panel loop.

Syntax

panel.show(*, mode="dialog", anchor="top_left", stop_button=True, width=None, height=None, collapsed=None, dock_position=None, pause_on_expand=True)

Parameters

NameDescription
modeString
dialog waits for confirmation; Cancel returns an empty dict. floating returns immediately and stays until closed or the macro run ends. Showing another floating panel replaces the visible one.
Optional · Keyword only
Default: "dialog"
anchorString
Expanded floating panel placement: top_left, top_right, bottom_left, bottom_right, or free. free starts at top-left and allows dragging the expanded panel independently of the shared dock. Dragging the shared dock moves only the dock. Repeated show() preserves the current position.
Optional · Keyword only
Default: "top_left"
stop_buttonBoolean
Show the Stop button on the expanded floating panel. The collapsed panel has no separate Stop button; the main dock retains its normal Stop button in row mode.
Optional · Keyword only
Default: True
widthInt?
Expanded floating window width in current-screen pixels; None uses the compact automatic size. Use a positive whole number. The overlay clamps the size to fit its header and available screen; collapsed panels stay compact. Point coordinate scaling does not apply.
Optional · Keyword only
Default: None
heightInt?
Expanded floating window height in current-screen pixels; None sizes to content. Use a positive whole number. The overlay clamps the size to fit its header and available screen above the keyboard; collapsed panels stay compact. Point coordinate scaling does not apply.
Optional · Keyword only
Default: None
collapsedBoolean?
Floating mode only; a non-None value is rejected in dialog mode. True collapses the panel into an open button on the main dock; False expands it. None opens a new panel expanded and preserves the current state on repeated show(). Applies on the first display too. Repeat any custom anchor, width, or height in later show() calls to retain the expanded layout.
Optional · Keyword only
Default: None
dock_positionPoint | tuple[Number, Number] | list[Number] | None
Floating mode only; a non-None value is rejected in dialog mode. Set the shared main dock top-left position in current-screen pixels, including while the panel is expanded or before its first collapse. The dock moves with a 160 ms animation. Accepts Point(x, y) or a tuple/list of exactly two finite numbers from -2147483648 to 2147483647; Point scaling and anchors do not apply. The dock is clamped to the screen after measuring its actual size. None preserves its current placement. The expanded panel remains separate for every anchor, including free.
Optional · Keyword only
Default: None
pause_on_expandBoolean
Floating mode only; explicitly passing this argument in dialog mode raises an error. True pauses macro execution while the floating panel is expanded and visible. show() returns immediately; execution pauses at the next runtime checkpoint until the panel is collapsed, hidden, or closed. Use collapsed=True or pause_on_expand=False to continue the script while the panel is open. False disables this panel pause; manual pauses remain active. Each show() uses this call's value, defaulting to True again when omitted.
Optional · Keyword only
Default: True

Returns

dict — dialog returns a separate dict. floating returns the same dict on repeated show(); valid user edits update its entries immediately and are already saved natively and mirrored to Storage. A value assigned separately, such as speed = config["speed"], keeps the value read at that moment. values() returns a separate copy; close() keeps the final entries. Editing the returned dict in Python does not change the panel or saved settings, and the next panel update replaces those edits.

Example

# Start collapsed, then expand, collapse, and move the dock
panel = MacroPanel("Run config")
panel.show(mode="floating", collapsed=True, dock_position=Point(20, 100))
wait(1000)
panel.show(mode="floating", collapsed=False, pause_on_expand=False)
wait(1000)
panel.show(mode="floating", collapsed=True, dock_position=(100, 200))

MacroPanel.values

Copy the last valid field values after show(). Later panel edits do not change this copy. Valid floating-panel edits are already saved natively and mirrored to Storage immediately; after close(), values() returns the last values. Calling before show() raises an error.

Syntax

panel.values()

Returns

dict — A separate dict of field names and values.

Example

# Read live settings from a compact window on each loop iteration
panel = MacroPanel("Live controls")
panel.slider("speed", min=1, max=10, default=5)
config = panel.show(mode="floating", anchor="free", stop_button=True, width=320, height=240)
for index in range(10):
    print(config["speed"])
    wait(1000)
snapshot = panel.values()
panel.close()

MacroPanel.close

Close this floating panel. Its accepted values have already been saved natively and mirrored to Storage, including while the macro was paused. This does not stop the macro. Repeated calls after show() are safe; values() still returns the last values. Calling before show() raises an error.

Syntax

panel.close()

Returns

None — No return value.

Example

# Read live settings from a compact window on each loop iteration
panel = MacroPanel("Live controls")
panel.slider("speed", min=1, max=10, default=5)
config = panel.show(mode="floating", anchor="free", stop_button=True, width=320, height=240)
for index in range(10):
    print(config["speed"])
    wait(1000)
snapshot = panel.values()
panel.close()