# Widgets and Qt helpers

## Qt helpers

### Actions

guidata.qthelpers.create_action(parent: QW.QWidget | None, title: str, triggered: Callable | None = None, toggled: Callable | None = None, shortcut: QG.QKeySequence | None = None, icon: QG.QIcon | None = None, tip: str | None = None, checkable: bool | None = None, context: QC.Qt.ShortcutContext = ShortcutContext.WindowShortcut, enabled: bool | None = None) → QW.QAction

  Create a new QAction

  Parameters:

    - parent (QWidget or None) – Parent widget

    - title (str) – Action title

    - triggered (Callable or None) – Triggered callback

    - toggled (Callable or None) – Toggled callback

    - shortcut (QKeySequence or None) – Shortcut

    - icon (QIcon or None) – Icon

    - tip (str or None) – Tooltip

    - checkable (bool or None) – Checkable

    - context (Qt.ShortcutContext) – Shortcut context

    - enabled (bool or None) – Enabled

  Returns:

    New action

  Return type:

    QAction

guidata.qthelpers.add_actions(target: QMenu | QToolBar, actions: Iterable[QAction | QMenu | QToolButton | QPushButton | None]) → None

  Add actions (list of QAction instances) to target (menu, toolbar)

  Parameters:

    - target (QMenu or QToolBar) – Target menu or toolbar

    - actions (list) – List of actions (QAction, QMenu, QToolButton, QPushButton, None)

guidata.qthelpers.add_separator(target: QMenu | QToolBar) → None

  Add separator to target only if last action is not a separator

  Parameters:

    target (QMenu or QToolBar) – Target menu or toolbar

guidata.qthelpers.keybinding(attr: str) → str

  Return keybinding

  Parameters:

    attr (str) – Attribute name

  Returns:

    Keybinding

  Return type:

    str

### Simple widgets

guidata.qthelpers.create_toolbutton(parent: QW.QWidget, icon: QG.QIcon | str | None = None, text: str | None = None, triggered: Callable | None = None, tip: str | None = None, toggled: Callable | None = None, shortcut: QG.QKeySequence | None = None, autoraise: bool = True, enabled: bool | None = None) → QW.QToolButton

  Create a QToolButton

  Parameters:

    - parent (QWidget) – Parent widget

    - icon (QIcon or str or None) – Icon

    - text (str or None) – Text

    - triggered (Callable or None) – Triggered callback

    - tip (str or None) – Tooltip

    - toggled (Callable or None) – Toggled callback

    - shortcut (QKeySequence or None) – Shortcut

    - autoraise (bool) – Auto raise

    - enabled (bool or None) – Enabled

  Returns:

    New toolbutton

  Return type:

    QToolButton

guidata.qthelpers.create_groupbox(parent: QW.QWidget, title: str | None = None, toggled: Callable | None = None, checked: bool | None = None, flat: bool = False, layout: QW.QLayout | None = None) → QW.QGroupBox

  Create a QGroupBox

  Parameters:

    - parent (QWidget) – Parent widget

    - title (str or None) – Title

    - toggled (Callable or None) – Toggled callback

    - checked (bool or None) – Checked

    - flat (bool) – Flat

    - layout (QLayout or None) – Layout

  Returns:

    New groupbox

  Return type:

    QGroupBox

### Icons

guidata.qthelpers.get_std_icon(name: str, size: int | None = None) → QIcon

  Get standard platform icon Call ‘show_std_icons()’ for details

  Parameters:

    - name (str) – Icon name

    - size (int or None) – Size

  Returns:

    Icon

  Return type:

    QIcon

guidata.qthelpers.show_std_icons() → None

  Show all standard Icons

### Application

guidata.qthelpers.qt_app_context(exec_loop: bool = False) → Generator[QApplication, None, None]

  Context manager handling Qt application creation and persistance

  Parameters:

    exec_loop (bool) – If True, execute Qt event loop

  Note

  This context manager was strongly inspired by the one in the DataLab project which is more advanced and complete than this one (it handles faulthandler and traceback log files, which need to be implemented at application level, that is why they were not included here).

guidata.qthelpers.exec_dialog(dlg: QDialog) → int

  Run QDialog Qt execution loop without blocking, depending on environment test mode

  Parameters:

    dlg (QDialog) – Dialog to execute

  Returns:

    Dialog exit code

  Return type:

    int

### Other

guidata.qthelpers.grab_save_window(widget: QWidget, name: str | None = None, save_dir: str | None = None, add_timestamp: bool = False) → None

  Grab window screenshot and save it

  Parameters:

    - widget – Widget to grab

    - name – Widget name. If None, uses `widget.objectName()`

    - save_dir – Directory to save screenshot. If None, uses `execenv.screenshot_path` or current working directory

    - add_timestamp – Whether to add timestamp suffix to filename

guidata.qthelpers.block_signals(widget: QWidget, enable: bool) → Generator[None, None, None]

  Eventually block/unblock widget Qt signals before/after doing some things (enable: True if feature is enabled)

  Parameters:

    - widget (QWidget) – Widget to block/unblock

    - enable (bool) – True to block signals

guidata.qthelpers.qt_wait(timeout: float, except_unattended: bool = False, show_message: bool = False, parent: QWidget | None = None) → None

  Freeze GUI during timeout (seconds) while processing Qt events.

  Parameters:

    - timeout – timeout in seconds

    - except_unattended – if True, do not wait if unattended mode is enabled

    - show_message – if True, show a message box with a timeout

    - parent – parent widget of the message box

guidata.qthelpers.save_restore_stds() → Generator[None, None, None]

  Save/restore standard I/O before/after doing some things (e.g. calling Qt open/save dialogs)

## Ready-to-use Qt widgets

### Data editors

class guidata.widgets.arrayeditor.ArrayEditor(parent: QWidget = None)

  Array Editor Dialog

  Parameters:

    parent – Parent widget (default: None)

class guidata.widgets.collectionseditor.CollectionsEditor(parent=None)

  Collections Editor Dialog

class guidata.widgets.dataframeeditor.DataFrameEditor(parent=None)

  Dialog for displaying and editing DataFrame and related objects.

  #### Signals

  sig_option_changed(str, object): Raised if an option is changed.

    Arguments are name of option and its new value.

class guidata.widgets.texteditor.TextEditor(text, title='', font=None, parent=None, readonly=False, size=(400, 300))

  Array Editor Dialog

guidata.widgets.objecteditor.oedit(obj: dict | list | tuple | str | np.ndarray, title: str = None, parent: QW.QWidget = None) → dict | list | tuple | str | np.ndarray

  Edit the object ‘obj’ in a GUI-based editor and return the edited copy (if Cancel is pressed, return None)

  Parameters:

    - obj (dict | list | tuple | str | np.ndarray) – object to edit

    - title (str) – dialog title

    - parent (QW.QWidget) – parent widget

  Returns:

    edited object

  Return type:

    dict | list | tuple | str | np.ndarray

### Console and code editor

class guidata.widgets.console.Console(parent=None, namespace=None, message=None, commands=None, multithreaded=True, debug=False)

  Python console that run an interactive shell linked to the running process.

  Parameters:

    - parent – parent Qt widget

    - namespace (dict) – available python namespace when the console start

    - message – banner displayed before the first prompt

    - commands (type) – commands run when the interpreter starts

    - commands – list of string

    - multithreaded – multithreaded support

class guidata.widgets.console.DockableConsole(parent, namespace, message, commands=None, multithreaded=True, debug=False)

  Dockable Python console that run an interactive shell linked to the running process.

  Parameters:

    - parent – parent Qt widget

    - namespace (dict) – available python namespace when the console start

    - message – banner displayed before the first prompt

    - commands (type) – commands run when the interpreter starts

    - commands – list of string

class guidata.widgets.codeeditor.CodeEditor(parent: QWidget = None, language: str | None = None, font: QFont | None = None, columns: int | None = None, rows: int | None = None, inactivity_timeout: int = 1000)

  Code editor widget

  Parameters:

    - parent – Parent widget

    - language – Language used for syntax highlighting

    - font – Font used for the text

    - columns – Number of columns

    - rows – Number of rows

    - inactivity_timeout – after this delay of inactivity (in milliseconds), the `CodeEditor.SIG_EDIT_STOPPED` signal is emitted

### Utilities

class guidata.widgets.iconbrowser.IconBrowserWindow(parent: QWidget | None = None, init_folder: str | None = None)

  Main window for browsing icon collections.

guidata.widgets.iconbrowser.main(args: list[str] | None = None) → int

  Launch the icon browser application.

  Parameters:

    args – Command-line arguments (if None, uses sys.argv)

  Returns:

    Exit code (0 for success)

  Examples

      >>> # Launch with folder selection dialog
      >>> main()
      >>> # Launch with specific folder
      >>> main(['/path/to/icons'])