GUI API Reference
Every function lives in the gui_api module. Data types are in ApiTypes.
See GUI API for the concepts and GUI API Tutorials for step-by-step examples.
Note
Pass arguments by position, in the order shown. The names in the signatures describe each argument; they are not keyword names. Arguments with a default value can be left out from the right.
Availability
gui_api.IsGuiAvailable() -> bool
Check whether native GUI commands can be used in the current session.
Returns: true when Marvelous Designer runs with a GUI and the call comes from the main thread, false in headless mode.
Modal dialogs
gui_api.AskConfirm(title: str, message: str, okLabel: str = "OK", cancelLabel: str = "Cancel") -> bool
Show a modal confirmation dialog with two buttons and block until the user answers.
title: Dialog title.message: Message text shown in the dialog body.okLabel: Caption of the accept button.cancelLabel: Caption of the reject button.
Returns: true when the user pressed the accept button, false when rejected, closed or in headless mode.
gui_api.AskText(title: str, label: str, defaultValue: str = "", placeholder: str = "") -> ApiTypes.CloApiGuiTextResult
Show a modal dialog with a single-line text input and block until the user answers.
title: Dialog title.label: Label shown next to the input field.defaultValue: Initial text of the input field.placeholder: Hint text shown while the field is empty.
Returns: CloApiGuiTextResult. accepted is true only when the user pressed OK, value holds the entered text.
gui_api.AskChoice(title: str, label: str, options: list[str], defaultIndex: int = 0) -> ApiTypes.CloApiGuiChoiceResult
Show a modal dialog that lets the user pick exactly one option from a list and block until answered.
title: Dialog title.label: Label shown above the option list.options: Option captions. Must not be empty.defaultIndex: Index of the option selected initially. Out-of-range values select the first option.
Returns: CloApiGuiChoiceResult. accepted is true only when the user pressed OK, selectedIndex and selectedValue hold the choice.
gui_api.AskMultiChoice(title: str, label: str, options: list[str], defaultIndices: list[int] = []) -> ApiTypes.CloApiGuiChoiceResult
Show a modal dialog that lets the user check any number of options and block until answered.
title: Dialog title.label: Label shown above the option list.options: Option captions. Must not be empty.defaultIndices: Indices of the options checked initially. Out-of-range values are ignored.
Returns: CloApiGuiChoiceResult. accepted is true only when the user pressed OK, selectedIndices holds every checked index in ascending order.
gui_api.AskForm(title: str, fields: list[ApiTypes.CloApiGuiFormField]) -> ApiTypes.CloApiGuiFormResult
Show a modal form built from a field list and block until the user answers.
title: Dialog title.fields: Field descriptions, one row per field, in display order. Each key must be unique and non-empty.
Returns: CloApiGuiFormResult. accepted is true only when the user pressed OK, values maps each field key to its text value (choice: option caption, check: true or false, number: decimal text).
Windows and dock panels
gui_api.CreateToolWindow(title: str, width: int = 400, height: int = 300) -> int
Create a non-modal tool window owned by Marvelous Designer. The window is parented to the Marvelous Designer main window so it stays in front of Marvelous Designer. Call ShowWindow to display it.
title: Window title.width: Initial width in pixels. Values below 1 use a default size.height: Initial height in pixels. Values below 1 use a default size.
Returns: Window handle (greater than 0) on success, 0 on failure or in headless mode.
gui_api.CreateDockPanel(title: str, side: str = "right", name: str = "") -> int
Create a dockable panel owned by Marvelous Designer, like the Library or History panels: it docks into the main window, can be dragged to another side or floated, and has the Marvelous Designer title bar. Use it as the parent of Add* calls and show it with ShowWindow. ShowWindow, CloseWindow, CloseAllWindows, SetWindowCloseCallback and SetWidgetText accept the panel handle.
title: Panel title shown in its title bar.side: Initial docking side, one of left, right or bottom. Anything else fails.name: Stable identifier (letters, digits, underscore). Panels with the same name keep their docking position across mode switches and sessions. Empty generates a name from the handle.
Returns: Panel handle (greater than 0) on success, 0 on failure or in headless mode.
gui_api.ShowWindow(windowHandle: int) -> bool
Show a window created by CreateToolWindow and raise it in front of Marvelous Designer. The script may return afterwards, the window stays open until the user closes it or CloseWindow is called.
windowHandle: Handle returned by CreateToolWindow.
Returns: true on success, false when the handle is invalid or in headless mode.
gui_api.CloseWindow(windowHandle: int) -> bool
Close and destroy a window created by CreateToolWindow together with every widget added to it. All handles that belonged to the window become invalid.
windowHandle: Handle returned by CreateToolWindow.
Returns: true on success, false when the handle is invalid or in headless mode.
gui_api.CloseAllWindows() -> int
Close and destroy every window created through gui_api. Useful at the start of a script so a re-run does not leave the previous window open.
Returns: Number of windows that were closed, 0 in headless mode.
gui_api.SetWindowCloseCallback(windowHandle: int, onClose: Callable[[], None]) -> bool
Register a Python callable that runs when the window closes, either by the user pressing the close button or by CloseWindow / CloseAllWindows.
windowHandle: Handle returned by CreateToolWindow.onClose: Python callable taking no arguments.
Returns: true on success, false when the handle is invalid or in headless mode.
Layout containers
gui_api.AddRow(parentHandle: int) -> int
Append a horizontal container to a window, group or row. Widgets added to the returned handle are laid out left to right.
parentHandle: Handle of a window, group or row.
Returns: Container handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
gui_api.AddGroup(parentHandle: int, title: str) -> int
Append a titled group box to a window, group or row. Widgets added to the returned handle are laid out top to bottom inside the box.
parentHandle: Handle of a window, group or row.title: Group title.
Returns: Container handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
gui_api.AddSeparator(parentHandle: int) -> int
Append a thin separator line to a window, group or row.
parentHandle: Handle of a window, group or row.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
Input widgets
gui_api.AddTextInput(parentHandle: int, defaultValue: str = "", placeholder: str = "", onChanged: Callable[[str], None] = None) -> int
Append a single-line text input. Read the current text with GetWidgetValue, write it with SetWidgetValue.
parentHandle: Handle of a window, group or row.defaultValue: Initial text.placeholder: Hint text shown while the field is empty.onChanged: Python callable taking the new text (str). Called on user edits only, not on SetWidgetValue.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
gui_api.AddTextArea(parentHandle: int, text: str = "", readOnly: bool = false) -> int
Append a multi-line text box. Read the text with GetWidgetValue, write it with SetWidgetValue.
parentHandle: Handle of a window, group or row.text: Initial text.readOnly: true shows the text without allowing edits, for logs and reports.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
gui_api.AddCheckBox(parentHandle: int, text: str, checked: bool = false, onChanged: Callable[[bool], None] = None) -> int
Append a check box. GetWidgetValue returns true or false as text, SetWidgetValue accepts true, false, 1 or 0.
parentHandle: Handle of a window, group or row.text: Caption shown next to the box.checked: Initial state.onChanged: Python callable taking the new state (bool). Called on user clicks only.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
gui_api.AddDropdown(parentHandle: int, options: list[str], defaultIndex: int = 0, onChanged: Callable[[int], None] = None) -> int
Append a drop-down list. GetWidgetSelectedIndex / SetWidgetSelectedIndex work with the index, GetWidgetValue returns the selected caption, SetWidgetItems replaces the options.
parentHandle: Handle of a window, group or row.options: Option captions.defaultIndex: Index selected initially. Out-of-range values select the first option.onChanged: Python callable taking the new index (int). Called on user selection only.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
gui_api.AddRadioGroup(parentHandle: int, options: list[str], defaultIndex: int = 0, onChanged: Callable[[int], None] = None) -> int
Append a vertical group of radio buttons where exactly one option is checked. Same value functions as AddDropdown.
parentHandle: Handle of a window, group or row.options: Option captions. Must not be empty.defaultIndex: Index checked initially. Out-of-range values check the first option.onChanged: Python callable taking the new index (int). Called on user clicks only.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid, the options are empty or in headless mode.
gui_api.AddNumberInput(parentHandle: int, defaultValue: float = 0.0, minimum: float = -1000000.0, maximum: float = 1000000.0, decimals: int = 2, onChanged: Callable[[float], None] = None) -> int
Append a decimal number input with spin buttons. GetWidgetValue returns the number as decimal text, SetWidgetValue accepts decimal text.
parentHandle: Handle of a window, group or row.defaultValue: Initial value.minimum: Smallest accepted value.maximum: Largest accepted value.decimals: Number of decimal places shown.onChanged: Python callable taking the new value (float). Called on user edits only.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
gui_api.AddSlider(parentHandle: int, defaultValue: int = 0, minimum: int = 0, maximum: int = 100, onChanged: Callable[[int], None] = None) -> int
Append a horizontal integer slider. GetWidgetValue returns the value as text, SetWidgetValue accepts integer text.
parentHandle: Handle of a window, group or row.defaultValue: Initial value.minimum: Smallest value.maximum: Largest value.onChanged: Python callable taking the new value (int). Called on user drags only.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
Lists, tables, images and progress
gui_api.AddList(parentHandle: int, items: list[str], defaultIndex: int = -1, onSelected: Callable[[int], None] = None, onDoubleClicked: Callable[[int], None] = None) -> int
Append a single-selection list. GetWidgetSelectedIndex / SetWidgetSelectedIndex work with the row, GetWidgetValue returns the selected caption, SetWidgetItems replaces the rows.
parentHandle: Handle of a window, group or row.items: Row captions.defaultIndex: Row selected initially, -1 for no selection.onSelected: Python callable taking the new row (int). Called on user selection only.onDoubleClicked: Python callable taking the double-clicked row (int).
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
gui_api.AddTable(parentHandle: int, columns: list[str], rows: list[list[str]], onSelected: Callable[[int], None] = None) -> int
Append a read-only table with a header row and whole-row selection. GetWidgetSelectedIndex returns the selected row, GetWidgetValue returns the first cell of the selected row, SetTableRows replaces the rows.
parentHandle: Handle of a window, group or row.columns: Column captions.rows: Cell texts, one inner list per row. Missing cells are shown empty.onSelected: Python callable taking the new row (int). Called on user selection only.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
gui_api.AddImage(parentHandle: int, imageFilePath: str, maxWidth: int = 0, maxHeight: int = 0) -> int
Append an image loaded from a file. SetWidgetValue with a file path replaces the image. Very large files such as 2D window snapshots are supported and decoded straight to the requested size.
parentHandle: Handle of a window, group or row.imageFilePath: Path of a PNG or JPEG file.maxWidth: Scale the image down to this width if it is wider. 0 keeps the original width.maxHeight: Scale the image down to this height if it is taller. 0 keeps the original height. When both limits are 0 an image wider or taller than 4096 px is scaled down to 4096 px.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid, the file cannot be loaded or in headless mode.
gui_api.AddProgressBar(parentHandle: int, value: int = 0) -> int
Append a progress bar from 0 to 100. SetWidgetValue with integer text updates it.
parentHandle: Handle of a window, group or row.value: Initial value from 0 to 100.
Returns: Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode.
Reading and changing widgets
gui_api.SetWidgetEnabled(handle: int, enabled: bool) -> bool
Enable or disable any widget, container or menu item.
handle: Any handle except a window.enabled: false greys the widget out.
Returns: true on success, false when the handle is invalid or in headless mode.
gui_api.SetWidgetVisible(handle: int, visible: bool) -> bool
Show or hide any widget, container or menu item without destroying it.
handle: Any handle except a window. Use ShowWindow / CloseWindow for windows.visible: false hides the widget.
Returns: true on success, false when the handle is invalid or in headless mode.
gui_api.GetWidgetValue(handle: int) -> str
Read the current value of a widget as text: the text of inputs, labels and buttons, true or false for check boxes, the selected caption for drop-downs, radio groups and lists, the first cell of the selected row for tables, decimal text for numbers, sliders and progress bars.
handle: Widget handle.
Returns: The value as text, empty when the handle is invalid, nothing is selected or in headless mode.
gui_api.SetWidgetValue(handle: int, value: str) -> bool
Write the value of a widget as text, using the same encoding GetWidgetValue returns. For drop-downs, radio groups and lists the caption must exist. For images the value is a file path. Change callbacks are not triggered.
handle: Widget handle.value: New value as text.
Returns: true on success, false when the handle is invalid, the value cannot be applied or in headless mode.
gui_api.GetWidgetSelectedIndex(handle: int) -> int
Read the selected index of a drop-down, radio group, list or table.
handle: Widget handle.
Returns: The selected index, -1 when nothing is selected, the handle is not a selection widget or in headless mode.
gui_api.SetWidgetSelectedIndex(handle: int, index: int) -> bool
Select an index in a drop-down, radio group, list or table. Change callbacks are not triggered.
handle: Widget handle.index: Index to select. -1 clears the selection of a list or table.
Returns: true on success, false when the handle is invalid, the index is out of range or in headless mode.
gui_api.SetWidgetItems(handle: int, items: list[str]) -> bool
Replace the options of a drop-down or radio group, or the rows of a list. The selection is reset.
handle: Widget handle.items: New captions.
Returns: true on success, false when the handle is invalid or in headless mode.
gui_api.SetTableRows(handle: int, rows: list[list[str]]) -> bool
Replace every row of a table created by AddTable. The selection is reset.
handle: Table handle.rows: Cell texts, one inner list per row.
Returns: true on success, false when the handle is not a table or in headless mode.
Data types
Type |
Fields |
|---|---|
|
|
|
|
|
|
|
|
Constant |
Input and value |
|---|---|
|
Single-line text input. Value: the entered text. |
|
Drop-down built from |
|
Check box. Value: |
|
Decimal number input. Value: the number as decimal text. |