.. This page is generated by scripts/gui_api_reference_gen.py from the public GUI API header. Do not edit by hand. **GUI API Reference** ===================== Every function lives in the ``gui_api`` module. Data types are in ``ApiTypes``. See :doc:`gui_api` for the concepts and :doc:`gui_api_tutorial` 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. .. contents:: On this page :local: :depth: 1 Availability ------------ .. code-block:: python 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 ------------- .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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 ----------------------- .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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 ----------------- .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | Text and buttons ---------------- .. code-block:: python gui_api.AddLabel(parentHandle: int, text: str) -> int Append a text label to a window created by CreateToolWindow. - ``parentHandle``: Handle of the parent window. - ``text``: Label text. **Returns:** Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode. | .. code-block:: python gui_api.AddButton(parentHandle: int, text: str, onClick: Callable[[], None]) -> int Append a push button to a window created by CreateToolWindow. The Python callable runs on the main thread every time the button is clicked, also after the creating script has finished. Exceptions raised inside the callable are logged and do not close the window. - ``parentHandle``: Handle of the parent window. - ``text``: Button caption. - ``onClick``: Python callable taking no arguments. **Returns:** Widget handle (greater than 0) on success, 0 when the parent handle is invalid or in headless mode. | .. code-block:: python gui_api.SetWidgetText(handle: int, text: str) -> bool Replace the text of a label, a button or the title of a window. - ``handle``: Handle returned by CreateToolWindow, AddLabel or AddButton. - ``text``: New text. **Returns:** true on success, false when the handle is invalid or in headless mode. | Input widgets ------------- .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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 ---------------------------------- .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | Menus ----- .. code-block:: python gui_api.AddMenu(windowHandle: int, title: str) -> int Add a menu to the menu bar of a window. The menu bar is created on the first call. - ``windowHandle``: Handle returned by CreateToolWindow. - ``title``: Menu title shown in the menu bar. **Returns:** Menu handle (greater than 0) on success, 0 when the handle is not a window or in headless mode. | .. code-block:: python gui_api.AddMenuItem(menuHandle: int, text: str, onClick: Callable[[], None]) -> int Add a clickable item to a menu created by AddMenu. - ``menuHandle``: Handle returned by AddMenu. - ``text``: Item caption. - ``onClick``: Python callable taking no arguments. **Returns:** Item handle (greater than 0) on success, 0 when the handle is not a menu or in headless mode. | Reading and changing widgets ---------------------------- .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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. | .. code-block:: python 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 ---------- .. list-table:: :header-rows: 1 :widths: 30 70 * - Type - Fields * - ``ApiTypes.CloApiGuiTextResult`` - ``accepted`` (bool): True only when the user pressed OK. ``value`` (str): the entered text, empty unless accepted. * - ``ApiTypes.CloApiGuiChoiceResult`` - ``accepted`` (bool). ``selectedIndex`` (int): the picked option (AskChoice) or the first checked one (AskMultiChoice), -1 unless accepted. ``selectedValue`` (str): caption of that option. ``selectedIndices`` (list[int]): every selected index in ascending order. * - ``ApiTypes.CloApiGuiFormResult`` - ``accepted`` (bool). ``values`` (dict[str, str]): field key to value as text. * - ``ApiTypes.CloApiGuiFormField`` - ``key`` (str): unique result key. ``label`` (str): caption next to the input. ``type``: one of the field types below (default ``GUI_FIELD_TEXT``). ``defaultValue`` (str): initial value as text. ``options`` (list[str]): captions for ``GUI_FIELD_CHOICE``. .. list-table:: Form field types :header-rows: 1 :widths: 35 65 * - Constant - Input and value * - ``ApiTypes.GUI_FIELD_TEXT`` - Single-line text input. Value: the entered text. * - ``ApiTypes.GUI_FIELD_CHOICE`` - Drop-down built from ``options``. Value: the selected caption. * - ``ApiTypes.GUI_FIELD_CHECK`` - Check box. Value: ``true`` or ``false``. * - ``ApiTypes.GUI_FIELD_NUMBER`` - Decimal number input. Value: the number as decimal text.