MacroPanel

Class

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

Name	Description
`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; MacroPanel input values are restored from and saved to Storage by variable name, not by version. Optional · Keyword only Default: `""`

Returns

MacroPanel

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

Name	Description
`titleString`	Panel title. Writable after construction. Default: `""`
`subtitleString`	Panel subtitle/helper text. Writable after construction. Default: `""`
`versionString`	Optional version label kept for compatibility; MacroPanel input values are restored from and saved to Storage by variable name, not by version. Writable after construction. Default: `""`
`confirm_textString`	Confirm button label. Default: `"Run"`
`cancel_textString`	Cancel button label. Default: `"Cancel"`

Methods

12 methods

MacroPanel.notify

Static Method

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

Name	Description
`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

Static Method

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

Name	Description
`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

Method

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

Name	Description
`nameString`	Non-empty key for this field in the returned dict and Storage. Each input in a panel must have a different key. Required · Positional or named No default
`labelString?`	Display label. Leave empty to hide label. Optional · Positional or named Default: `None`
`defaultString\|Number`	Default value. A floating numeric field needs a valid initial value from default or Storage; 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). 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

Method

Add a box the user can check or uncheck.

Syntax

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

Parameters

Name	Description
`nameString`	Non-empty key for this field in the returned dict and Storage. Each input in a panel must have a different key. Required · Positional or named No default
`labelString?`	Display label. Leave empty to hide label. Optional · Positional or named Default: `None`
`checkedBoolean`	Default checked state. 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

Method

Add a switch the user can turn on or off.

Syntax

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

Parameters

Name	Description
`nameString`	Non-empty key for this field in the returned dict and Storage. Each input in a panel must have a different key. Required · Positional or named No default
`labelString?`	Display label. Leave empty to hide label. Optional · Positional or named Default: `None`
`checkedBoolean`	Default toggle state. 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

Method

Add a radio-group selector, or render it as a dropdown when dropdown=True.

Syntax

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

Parameters

Name	Description
`nameString`	Non-empty key for this field in the returned dict and Storage. Each input in a panel must have a different key. Required · Positional or named No default
`optionslist[String]`	Selectable options. Required · Positional or named No default
`labelString?`	Display label. Leave empty to hide label. Optional · Positional or named Default: `None`
`defaultString\|Int\|None`	Default option label or 0-based option index; None selects the first option. Optional · Positional or named Default: `None`
`dropdownBoolean`	Render this selector as a dropdown instead of radio options. 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.radio_group("mode", ["slow", "fast"], label="Mode", default="slow")
result = panel.show()
print(result)

MacroPanel.slider

Method

Add a numeric slider.

Syntax

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

Parameters

Name	Description
`nameString`	Non-empty key for this field in the returned dict and Storage. Each input in a panel must have a different 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?`	Default value, 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

Method

Add a numeric stepper with +/- controls.

Syntax

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

Parameters

Name	Description
`nameString`	Non-empty key for this field in the returned dict and Storage. Each input in a panel must have a different 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?`	Default value, 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

Method

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

Name	Description
`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.show

Method

Show the panel and return a dict of field names and values. Matching Storage entries supply the starting values; confirmed dialog values and valid floating-panel edits update Storage. 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

Name	Description
`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. 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 Storage, 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

Method

Copy the last valid field values after show(). Later panel edits do not change this copy. Valid floating-panel edits update 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

Method

Close this floating panel and save its last valid values to Storage. 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()