app_model.backends.qt #

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

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

def __init__(
    self,
    command_id: str,
    app: Application | str,
    parent: QObject | None = 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)

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.

Methods:

• update_from_context –

  Update the enabled state of this menu item from ctx.

 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112

def __init__(
    self,
    command_rule: CommandRule,
    app: Application | str,
    parent: QObject | None = None,
    *,
    use_short_title: bool = False,
) -> None:
    super().__init__(command_rule.id, app, parent)
    self._cmd_rule = command_rule
    self._tooltip = command_rule.tooltip or ""
    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.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(ctx: Mapping[str, object]) -> None

123
124
125
126
127
128
129
130

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))

Bases: QKeySequence

A QKeySequence based on a KeyBinding instance.

71
72
73

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

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

Methods:

• create –

  Create a new QMenuItemAction for the given menu item.

• update_from_context –

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

159
160
161
162
163
164
165
166
167
168

def __init__(
    self,
    menu_item: MenuItem,
    app: Application | str,
    parent: QObject | None = 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(
    menu_item: MenuItem,
    app: Application | str,
    parent: QObject | None = None,
) -> Self

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

174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201

@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._update_keybinding()
        res.setParent(parent)
        return res

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

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

203
204
205
206

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)

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.

Methods:

• keyBinding –

  Return app_model KeyBinding instance for the current keySequence.

keyBinding() -> Optional[KeyBinding]

18
19
20
21
22

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

Bases: QMainWindow

QMainWindow with app-model support.

Methods:

• addModelToolBar –

  Add a tool bar to the main window.

• setModelMenuBar –

  Set the menu bar to a list of menu ids.

19
20
21

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

37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

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(
    menu_ids: Mapping[str, str]
    | Sequence[str | tuple[str, str]],
) -> QModelMenuBar

23
24
25
26
27
28
29
30
31
32
33
34
35

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

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

Methods:

• findAction –

  Find an action by its ObjectName.

• rebuild –

  Rebuild menu by looking up self._menu_id in menu_registry.

• update_from_context –

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

34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

def __init__(
    self,
    menu_id: str,
    app: Application | str,
    title: str | None = None,
    parent: QWidget | None = 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(object_name: str) -> QAction | QModelMenu | None

58
59
60
61
62
63
64
65
66
67

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(
    include_submenus: bool = True,
    exclude: Collection[str] | None = None,
) -> None

84
85
86
87
88
89
90
91
92
93
94

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(ctx: Mapping[str, object]) -> None

69
70
71
72
73
74
75
76
77
78
79
80
81
82

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)

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

Methods:

• update_from_context –

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

253
254
255
256
257
258
259
260
261
262
263
264

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(ctx: Mapping[str, object]) -> None

266
267
268
269
270
271
272
273
274
275
276
277
278
279

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)

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

Methods:

• findAction –

  Find an action by its ObjectName.

• rebuild –

  Rebuild menu by looking up self._menu_id in menu_registry.

• update_from_context –

  Update the enabled state of this menu item from ctx.

125
126
127
128
129
130
131
132
133
134
135
136
137

def __init__(
    self,
    submenu: SubmenuItem,
    app: Application | str,
    parent: QWidget | None = 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(object_name: str) -> QAction | QModelMenu | None

58
59
60
61
62
63
64
65
66
67

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(
    include_submenus: bool = True,
    exclude: Collection[str] | None = None,
) -> None

84
85
86
87
88
89
90
91
92
93
94

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(ctx: Mapping[str, object]) -> None

139
140
141
142

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)

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

Methods:

• addMenu –

  No-op for toolbar.

• findAction –

  Find an action by its ObjectName.

• rebuild –

  Rebuild toolbar by looking up self._menu_id in menu_registry.

• update_from_context –

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

165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189

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(menu: QMenu) -> None

191
192

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

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

194
195
196
197
198
199
200
201
202
203

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(
    include_submenus: bool = True,
    exclude: Collection[str] | None = None,
) -> None

220
221
222
223
224
225
226
227
228
229
230

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(ctx: Mapping[str, object]) -> None

205
206
207
208
209
210
211
212
213
214
215
216
217
218

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)