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 CLO 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 CLO. The window is parented to the CLO main window so it stays in front of CLO. 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 CLO, like the Library or History panels: it docks into the main window, can be dragged to another side or floated, and has the CLO 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 CLO. 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. |