qt

Qt objects for app_model.

QCommandAction

QCommandAction(command_id: str, app: Application | str, parent: QObject | None = None)

Bases: QAction

Base QAction for a command id. Can execute the command.

Parameters:

• command_id (str) –

  Command ID.

• app (Application | str) –

  Application instance or name of application instance.

• parent (QObject | None, default: None ) –

  Optional parent widget, by default None

Source code in app_model/backends/qt/_qaction.py

def __init__(
    self,
    command_id: str,
    app: Application | str,
    parent: QObject | None = None,
):
    super().__init__(parent)
    self._app = Application.get_or_create(app) if isinstance(app, str) else app
    self._command_id = command_id
    self.setObjectName(command_id)
    self._keybinding_tooltip = ""
    if kb := self._app.keybindings.get_keybinding(command_id):
        self.setShortcut(QKeyBindingSequence(kb.keybinding))
        self._keybinding_tooltip = f"({kb.keybinding.to_text()})"
    self.triggered.connect(self._on_triggered)

QCommandRuleAction

QCommandRuleAction(command_rule: CommandRule, app: Application | str, parent: QObject | None = None, *, use_short_title: bool = False)

Bases: QCommandAction

QAction for a CommandRule.

Parameters:

• command_rule (CommandRule) –

  CommandRule instance to create an action for.

• app (Application | str) –

  Application instance or name of application instance.

• parent (QObject | None, default: None ) –

  Optional parent widget, by default None

• use_short_title (bool, default: False ) –

  If True, use the short_title of the command rule, if it exists.

Source code in app_model/backends/qt/_qaction.py

def __init__(
    self,
    command_rule: CommandRule,
    app: Application | str,
    parent: QObject | None = None,
    *,
    use_short_title: bool = False,
):
    super().__init__(command_rule.id, app, parent)
    self._cmd_rule = command_rule
    if use_short_title and command_rule.short_title:
        self.setText(command_rule.short_title)  # pragma: no cover
    else:
        self.setText(command_rule.title)
    if command_rule.icon:
        self.setIcon(to_qicon(command_rule.icon))
    self.setIconVisibleInMenu(command_rule.icon_visible_in_menu)
    if command_rule.tooltip:
        self.setToolTip(command_rule.tooltip)
    if command_rule.status_tip:
        self.setStatusTip(command_rule.status_tip)
    if command_rule.toggled is not None:
        self.setCheckable(True)
        self._refresh()
    tooltip_with_keybinding = (
        f"{self.toolTip()} {self._keybinding_tooltip}".rstrip()
    )
    self.setToolTip(tooltip_with_keybinding)

update_from_context

update_from_context(ctx: Mapping[str, object]) -> None

Update the enabled state of this menu item from ctx.

Source code in app_model/backends/qt/_qaction.py

def update_from_context(self, ctx: Mapping[str, object]) -> None:
    """Update the enabled state of this menu item from `ctx`."""
    self.setEnabled(expr.eval(ctx) if (expr := self._cmd_rule.enablement) else True)
    if expr2 := self._cmd_rule.toggled:
        if isinstance(expr2, Expr) or (
            isinstance(expr2, ToggleRule) and (expr2 := expr2.condition)
        ):
            self.setChecked(expr2.eval(ctx))

QKeyBindingSequence

QKeyBindingSequence(kb: KeyBinding)

Bases: QKeySequence

A QKeySequence based on a KeyBinding instance.

Source code in app_model/backends/qt/_qkeymap.py

def __init__(self, kb: KeyBinding) -> None:
    ints = [simple_keybinding_to_qint(skb) for skb in kb.parts]
    super().__init__(*ints)

QMenuItemAction

QMenuItemAction(menu_item: MenuItem, app: Application | str, parent: QObject | None = None)

Bases: QCommandRuleAction

QAction for a MenuItem.

Mostly the same as a CommandRuleAction, but aware of the menu_item.when clause to toggle visibility.

Parameters:

• menu_item (MenuItem) –

  MenuItem instance to create an action for.

• app (Application | str) –

  Application instance or name of application instance.

• parent (QObject | None, default: None ) –

  Optional parent widget, by default None

Source code in app_model/backends/qt/_qaction.py

def __init__(
    self,
    menu_item: MenuItem,
    app: Application | str,
    parent: QObject | None = None,
):
    super().__init__(menu_item.command, app, parent)
    self._menu_item = menu_item
    with contextlib.suppress(NameError):
        self.update_from_context(self._app.context)

create classmethod

create(menu_item: MenuItem, app: Application | str, parent: QObject | None = None) -> Self

Create a new QMenuItemAction for the given menu item.

Prefer this method over __init__ to ensure that the cache is used, so that:

a1 = QMenuItemAction.create(action, full_app)
a2 = QMenuItemAction.create(action, full_app)
a1 is a2  # True

Source code in app_model/backends/qt/_qaction.py

@classmethod
def create(
    cls,
    menu_item: MenuItem,
    app: Application | str,
    parent: QObject | None = None,
) -> Self:
    """Create a new QMenuItemAction for the given menu item.

    Prefer this method over `__init__` to ensure that the cache is used,
    so that:

    ```python
    a1 = QMenuItemAction.create(action, full_app)
    a2 = QMenuItemAction.create(action, full_app)
    a1 is a2  # True
    ```
    """
    app = Application.get_or_create(app) if isinstance(app, str) else app
    cache_key = QMenuItemAction._cache_key(app, menu_item)
    if cache_key in cls._cache:
        res = cls._cache[cache_key]
        res.setParent(parent)
        return res

    cls._cache[cache_key] = obj = cls(menu_item, app, parent)
    return obj

update_from_context

update_from_context(ctx: Mapping[str, object]) -> None

Update the enabled/visible state of this menu item from ctx.

Source code in app_model/backends/qt/_qaction.py

def update_from_context(self, ctx: Mapping[str, object]) -> None:
    """Update the enabled/visible state of this menu item from `ctx`."""
    super().update_from_context(ctx)
    self.setVisible(expr.eval(ctx) if (expr := self._menu_item.when) else True)

QModelKeyBindingEdit

Bases: QKeySequenceEdit

Editor for a KeyBinding instance.

This is a QKeySequenceEdit with a method that converts the current keySequence to an app_model KeyBinding instance.

keyBinding

keyBinding() -> Optional[KeyBinding]

Return app_model KeyBinding instance for the current keySequence.

Source code in app_model/backends/qt/_qkeybindingedit.py

def keyBinding(self) -> Optional["KeyBinding"]:
    """Return app_model KeyBinding instance for the current keySequence."""
    if self.keySequence().isEmpty():
        return None
    return qkeysequence2modelkeybinding(self.keySequence())

QModelMainWindow

QModelMainWindow(app: Application | str, parent: QWidget | None = None)

Bases: QMainWindow

QMainWindow with app-model support.

Source code in app_model/backends/qt/_qmainwindow.py

def __init__(self, app: Application | str, parent: QWidget | None = None) -> None:
    super().__init__(parent)
    self._app = Application.get_or_create(app) if isinstance(app, str) else app

addModelToolBar

addModelToolBar(menu_id: str, *, exclude: Collection[str] | None = None, area: Qt.ToolBarArea | None = None, toolbutton_style: Qt.ToolButtonStyle = Qt.ToolButtonStyle.ToolButtonIconOnly) -> QModelToolBar

Add a tool bar to the main window.

Source code in app_model/backends/qt/_qmainwindow.py

def addModelToolBar(
    self,
    menu_id: str,
    *,
    exclude: Collection[str] | None = None,
    area: Qt.ToolBarArea | None = None,
    toolbutton_style: Qt.ToolButtonStyle = Qt.ToolButtonStyle.ToolButtonIconOnly,
) -> QModelToolBar:
    """Add a tool bar to the main window."""
    toolbar = QModelToolBar(menu_id, self._app, exclude=exclude, parent=self)
    toolbar.setToolButtonStyle(toolbutton_style)
    if area is not None:
        self.addToolBar(area, toolbar)
    else:
        self.addToolBar(toolbar)
    return toolbar

setModelMenuBar

setModelMenuBar(menu_ids: Mapping[str, str] | Sequence[str | tuple[str, str]]) -> QModelMenuBar

Set the menu bar to a list of menu ids.

Parameters:

• menu_ids (Mapping[str, str] | Sequence[str | tuple[str, str]]) –

  A mapping of menu ids to menu titles or a sequence of menu ids.

Source code in app_model/backends/qt/_qmainwindow.py

def setModelMenuBar(
    self, menu_ids: Mapping[str, str] | Sequence[str | tuple[str, str]]
) -> QModelMenuBar:
    """Set the menu bar to a list of menu ids.

    Parameters
    ----------
    menu_ids : Mapping[str, str] | Sequence[str | tuple[str, str]]
        A mapping of menu ids to menu titles or a sequence of menu ids.
    """
    menu_bar = QModelMenuBar(menu_ids, self._app, self)
    self.setMenuBar(menu_bar)
    return menu_bar

QModelMenu

QModelMenu(menu_id: str, app: Application | str, title: str | None = None, parent: QWidget | None = None)

Bases: QMenu

QMenu for a menu_id in an app_model MenusRegistry.

Parameters:

• menu_id (str) –

  Menu ID to look up in the registry.

• app (Application | str) –

  Application instance or name of application instance.

• title (str | None, default: None ) –

  Optional title for the menu, by default None

• parent (QWidget | None, default: None ) –

  Optional parent widget, by default None

Source code in app_model/backends/qt/_qmenu.py

def __init__(
    self,
    menu_id: str,
    app: Application | str,
    title: str | None = None,
    parent: QWidget | None = None,
):
    QMenu.__init__(self, parent)

    # NOTE: code duplication with QModelToolBar, but Qt mixins and multiple
    # inheritance are problematic for some versions of Qt, and for typing
    assert isinstance(menu_id, str), f"Expected str, got {type(menu_id)!r}"
    self._menu_id = menu_id
    self._app = Application.get_or_create(app) if isinstance(app, str) else app
    self.setObjectName(menu_id)
    self.rebuild()
    self._app.menus.menus_changed.connect(self._on_registry_changed)
    self.destroyed.connect(self._disconnect)
    # ----------------------

    if title is not None:
        self.setTitle(title)
    self.aboutToShow.connect(self._on_about_to_show)

findAction

findAction(object_name: str) -> QAction | QModelMenu | None

Find an action by its ObjectName.

Parameters:

• object_name (str) –

  Action ID to find. Note that QCommandAction have ObjectName set to their command.id

Source code in app_model/backends/qt/_qmenu.py

def findAction(self, object_name: str) -> QAction | QModelMenu | None:
    """Find an action by its ObjectName.

    Parameters
    ----------
    object_name : str
        Action ID to find. Note that `QCommandAction` have `ObjectName` set
        to their `command.id`
    """
    return _find_action(self.actions(), object_name)

rebuild

rebuild(include_submenus: bool = True, exclude: Collection[str] | None = None) -> None

Rebuild menu by looking up self._menu_id in menu_registry.

Source code in app_model/backends/qt/_qmenu.py

def rebuild(
    self, include_submenus: bool = True, exclude: Collection[str] | None = None
) -> None:
    """Rebuild menu by looking up self._menu_id in menu_registry."""
    _rebuild(
        menu=self,
        app=self._app,
        menu_id=self._menu_id,
        include_submenus=include_submenus,
        exclude=exclude,
    )

update_from_context

update_from_context(ctx: Mapping[str, object]) -> None

Update the enabled/visible state of each menu item with ctx.

See app_model.expressions for details on expressions.

Parameters:

• ctx (Mapping) –

  A namespace that will be used to eval() the 'enablement' and 'when' expressions provided for each action in the menu. ALL variables used in these expressions must either be present in the ctx dict, or be builtins.

Source code in app_model/backends/qt/_qmenu.py

def update_from_context(self, ctx: Mapping[str, object]) -> None:
    """Update the enabled/visible state of each menu item with `ctx`.

    See `app_model.expressions` for details on expressions.

    Parameters
    ----------
    ctx : Mapping
        A namespace that will be used to `eval()` the `'enablement'` and
        `'when'` expressions provided for each action in the menu.
        *ALL variables used in these expressions must either be present in
        the `ctx` dict, or be builtins*.
    """
    _update_from_context(self.actions(), ctx)

QModelMenuBar

QModelMenuBar(menus: Mapping[str, str] | Sequence[str | tuple[str, str]], app: Application | str, parent: QWidget | None = None)

Bases: QMenuBar

QMenuBar that is built from a list of model menu ids.

Parameters:

• menus (Mapping[str, str] | Sequence[str | tuple[str, str]]) –

  A mapping of menu ids to menu titles or a sequence of menu ids.

• app (Application | str) –

  Application instance or name of application instance.

• parent (QWidget | None, default: None ) –

  Optional parent widget, by default None

Source code in app_model/backends/qt/_qmenu.py

def __init__(
    self,
    menus: Mapping[str, str] | Sequence[str | tuple[str, str]],
    app: Application | str,
    parent: QWidget | None = None,
) -> None:
    super().__init__(parent)

    menu_items = menus.items() if isinstance(menus, Mapping) else menus
    for item in menu_items:
        id_, title = item if isinstance(item, tuple) else (item, item.title())
        self.addMenu(QModelMenu(id_, app, title, self))

update_from_context

update_from_context(ctx: Mapping[str, object]) -> None

Update the enabled/visible state of each menu item with ctx.

See app_model.expressions for details on expressions.

Parameters:

• ctx (Mapping) –

  A namespace that will be used to eval() the 'enablement' and 'when' expressions provided for each action in the menu. ALL variables used in these expressions must either be present in the ctx dict, or be builtins.

Source code in app_model/backends/qt/_qmenu.py

def update_from_context(self, ctx: Mapping[str, object]) -> None:
    """Update the enabled/visible state of each menu item with `ctx`.

    See `app_model.expressions` for details on expressions.

    Parameters
    ----------
    ctx : Mapping
        A namespace that will be used to `eval()` the `'enablement'` and
        `'when'` expressions provided for each action in the menu.
        *ALL variables used in these expressions must either be present in
        the `ctx` dict, or be builtins*.
    """
    _update_from_context(self.actions(), ctx)

QModelSubmenu

QModelSubmenu(submenu: SubmenuItem, app: Application | str, parent: QWidget | None = None)

Bases: QModelMenu

QMenu for a menu_id in an app_model MenusRegistry.

Parameters:

• submenu (SubmenuItem) –

  SubmenuItem for which to create a QMenu.

• app (Application | str) –

  Application instance or name of application instance.

• parent (QWidget | None, default: None ) –

  Optional parent widget, by default None

Source code in app_model/backends/qt/_qmenu.py

def __init__(
    self,
    submenu: SubmenuItem,
    app: Application | str,
    parent: QWidget | None = None,
):
    assert isinstance(submenu, SubmenuItem), f"Expected str, got {type(submenu)!r}"
    self._submenu = submenu
    super().__init__(
        menu_id=submenu.submenu, app=app, title=submenu.title, parent=parent
    )
    if submenu.icon:
        self.setIcon(to_qicon(submenu.icon))

findAction

findAction(object_name: str) -> QAction | QModelMenu | None

Find an action by its ObjectName.

Parameters:

• object_name (str) –

  Action ID to find. Note that QCommandAction have ObjectName set to their command.id

Source code in app_model/backends/qt/_qmenu.py

def findAction(self, object_name: str) -> QAction | QModelMenu | None:
    """Find an action by its ObjectName.

    Parameters
    ----------
    object_name : str
        Action ID to find. Note that `QCommandAction` have `ObjectName` set
        to their `command.id`
    """
    return _find_action(self.actions(), object_name)

rebuild

rebuild(include_submenus: bool = True, exclude: Collection[str] | None = None) -> None

Rebuild menu by looking up self._menu_id in menu_registry.

Source code in app_model/backends/qt/_qmenu.py

def rebuild(
    self, include_submenus: bool = True, exclude: Collection[str] | None = None
) -> None:
    """Rebuild menu by looking up self._menu_id in menu_registry."""
    _rebuild(
        menu=self,
        app=self._app,
        menu_id=self._menu_id,
        include_submenus=include_submenus,
        exclude=exclude,
    )

update_from_context

update_from_context(ctx: Mapping[str, object]) -> None

Update the enabled state of this menu item from ctx.

Source code in app_model/backends/qt/_qmenu.py

def update_from_context(self, ctx: Mapping[str, object]) -> None:
    """Update the enabled state of this menu item from `ctx`."""
    super().update_from_context(ctx)
    self.setEnabled(expr.eval(ctx) if (expr := self._submenu.enablement) else True)

QModelToolBar

QModelToolBar(menu_id: str, app: Application | str, *, exclude: Collection[str] | None = None, title: str | None = None, parent: QWidget | None = None)

Bases: QToolBar

QToolBar that is built from a list of model menu ids.

Parameters:

• menu_id (str) –

  Menu ID to look up in the registry.

• app (Application | str) –

  Application instance or name of application instance.

• exclude (Collection[str] | None, default: None ) –

  Optional list of menu ids to exclude from the toolbar, by default None

• title (str | None, default: None ) –

  Optional title for the menu, by default None

• parent (QWidget | None, default: None ) –

  Optional parent widget, by default None

Source code in app_model/backends/qt/_qmenu.py

def __init__(
    self,
    menu_id: str,
    app: Application | str,
    *,
    exclude: Collection[str] | None = None,
    title: str | None = None,
    parent: QWidget | None = None,
) -> None:
    self._exclude = exclude
    QToolBar.__init__(self, parent)

    # NOTE: code duplication with QModelMenu, but Qt mixins and multiple
    # inheritance are problematic for some versions of Qt, and for typing
    assert isinstance(menu_id, str), f"Expected str, got {type(menu_id)!r}"
    self._menu_id = menu_id
    self._app = Application.get_or_create(app) if isinstance(app, str) else app
    self.setObjectName(menu_id)
    self.rebuild()
    self._app.menus.menus_changed.connect(self._on_registry_changed)
    self.destroyed.connect(self._disconnect)
    # ----------------------

    if title is not None:
        self.setWindowTitle(title)

addMenu

addMenu(menu: QMenu) -> None

No-op for toolbar.

Source code in app_model/backends/qt/_qmenu.py

def addMenu(self, menu: QMenu) -> None:
    """No-op for toolbar."""

findAction

findAction(object_name: str) -> QAction | QModelMenu | None

Find an action by its ObjectName.

Parameters:

• object_name (str) –

  Action ID to find. Note that QCommandAction have ObjectName set to their command.id

Source code in app_model/backends/qt/_qmenu.py

def findAction(self, object_name: str) -> QAction | QModelMenu | None:
    """Find an action by its ObjectName.

    Parameters
    ----------
    object_name : str
        Action ID to find. Note that `QCommandAction` have `ObjectName` set
        to their `command.id`
    """
    return _find_action(self.actions(), object_name)

rebuild

rebuild(include_submenus: bool = True, exclude: Collection[str] | None = None) -> None

Rebuild toolbar by looking up self._menu_id in menu_registry.

Source code in app_model/backends/qt/_qmenu.py

def rebuild(
    self, include_submenus: bool = True, exclude: Collection[str] | None = None
) -> None:
    """Rebuild toolbar by looking up self._menu_id in menu_registry."""
    _rebuild(
        menu=self,
        app=self._app,
        menu_id=self._menu_id,
        include_submenus=include_submenus,
        exclude=self._exclude if exclude is None else exclude,
    )

update_from_context

update_from_context(ctx: Mapping[str, object]) -> None

Update the enabled/visible state of each menu item with ctx.

See app_model.expressions for details on expressions.

Parameters:

• ctx (Mapping) –

  A namespace that will be used to eval() the 'enablement' and 'when' expressions provided for each action in the menu. ALL variables used in these expressions must either be present in the ctx dict, or be builtins.

Source code in app_model/backends/qt/_qmenu.py

def update_from_context(self, ctx: Mapping[str, object]) -> None:
    """Update the enabled/visible state of each menu item with `ctx`.

    See `app_model.expressions` for details on expressions.

    Parameters
    ----------
    ctx : Mapping
        A namespace that will be used to `eval()` the `'enablement'` and
        `'when'` expressions provided for each action in the menu.
        *ALL variables used in these expressions must either be present in
        the `ctx` dict, or be builtins*.
    """
    _update_from_context(self.actions(), ctx)

qkey2modelkey

qkey2modelkey(key: Qt.Key) -> KeyCode | KeyCombo

Return KeyCode from Qt.Key.

Source code in app_model/backends/qt/_qkeymap.py

def qkey2modelkey(key: Qt.Key) -> KeyCode | KeyCombo:
    """Return KeyCode from Qt.Key."""
    if MAC and _mac_ctrl_meta_swapped():
        if key == Qt.Key.Key_Control:
            return KeyCode.Meta
        if key == Qt.Key.Key_Meta:
            return KeyCode.Ctrl
    return KEY_FROM_QT.get(key, KeyCode.UNKNOWN)

qkeycombo2modelkey

qkeycombo2modelkey(key: QKeyCombination) -> KeyCode | KeyCombo

Return KeyCode or KeyCombo from QKeyCombination.

Source code in app_model/backends/qt/_qkeymap.py

def qkeycombo2modelkey(key: QKeyCombination) -> KeyCode | KeyCombo:
    """Return KeyCode or KeyCombo from QKeyCombination."""
    if key in KEY_FROM_QT:
        # type ignore because in qt5, key may actually just be int ... but it's fine.
        return KEY_FROM_QT[key]
    qmods = _get_qmods(key)
    qkey = _get_qkey(key)
    return qmods2modelmods(qmods) | qkey2modelkey(qkey)  # type: ignore [return-value]

qkeysequence2modelkeybinding

qkeysequence2modelkeybinding(key: QKeySequence) -> KeyBinding

Return KeyBinding from QKeySequence.

Source code in app_model/backends/qt/_qkeymap.py

def qkeysequence2modelkeybinding(key: QKeySequence) -> KeyBinding:
    """Return KeyBinding from QKeySequence."""
    # FIXME: this should return KeyChord instead of KeyBinding... but that only takes 2
    parts = [SimpleKeyBinding.from_int(qkeycombo2modelkey(x)) for x in iter(key)]
    return KeyBinding(parts=parts)

qmods2modelmods

qmods2modelmods(modifiers: Qt.KeyboardModifier) -> KeyMod

Return KeyMod from Qt.KeyboardModifier.

Source code in app_model/backends/qt/_qkeymap.py

def qmods2modelmods(modifiers: Qt.KeyboardModifier) -> KeyMod:
    """Return KeyMod from Qt.KeyboardModifier."""
    mod = KeyMod.NONE
    lookup = (
        MAC_KEYMOD_FROM_QT if MAC and not _mac_ctrl_meta_swapped() else KEYMOD_FROM_QT
    )
    for modifier in lookup:
        if modifiers & modifier:
            mod |= lookup[modifier]
    return mod

to_qicon

to_qicon(icon: Icon, theme: Literal['dark', 'light'] = 'dark') -> QIcon

Create QIcon from Icon.

Source code in app_model/backends/qt/_util.py

def to_qicon(icon: Icon, theme: Literal["dark", "light"] = "dark") -> QIcon:
    """Create QIcon from Icon."""
    from superqt import QIconifyIcon, fonticon

    if icn := getattr(icon, theme, ""):
        if icn.startswith("file://"):
            return QIcon(QUrl(icn).toLocalFile())
        elif ":" in icn:
            return QIconifyIcon(icn)
        else:
            return fonticon.icon(icn)
    return QIcon()  # pragma: no cover