spacr.qt.menus

Assign explicit Qt menu roles, and name the macOS application menu.

On macOS, Qt may relocate actions according to text such as “Preferences” or “Quit”. Explicit roles prevent translated or renamed actions from moving to the wrong system-menu slot. Other platforms retain their normal menu layout.

The menu those actions are relocated INTO is named after the application, so this module also owns naming the application – before the QApplication exists, which is the only moment early enough for macOS to read it.

Functions

name_the_application(→ Tuple[str, str])

Configure the Qt application and organization names.

name_the_macos_application_menu(→ bool)

Set the application-menu title for an unbundled macOS launch.

pin_menu_roles(→ None)

Give every action in actions an explicit role.

set_menu_role(→ Any)

Assign a macOS menu role and return action.

Module Contents

spacr.qt.menus.name_the_application(name: str = APPLICATION_NAME, organization: str = ORGANIZATION_NAME) → Tuple[str, str][source]

Configure the Qt application and organization names.

Call this function before constructing QApplication so the macOS application menu and Qt window-title fallbacks receive the configured name.

Parameters:

  • name – Application and display name.

  • organization – Organization name used by QSettings.

Returns:

Effective (applicationName, applicationDisplayName) values.

spacr.qt.menus.name_the_macos_application_menu(name: str = APPLICATION_NAME) → bool[source]

Set the application-menu title for an unbundled macOS launch.

macOS derives this title from CFBundleName rather than Qt’s applicationName. Packaged applications already provide the bundle value and are left unchanged.

Parameters:

name – Application-menu title.

Returns:

True if the bundle value was updated; otherwise False.

spacr.qt.menus.pin_menu_roles(actions: Iterable[Any], preferences: Any | None = None, quit_action: Any | None = None, about: Any | None = None) → None[source]

Give every action in actions an explicit role.

Everything gets NoRole except the three named, so adding a menu item later cannot accidentally claim the Preferences slot by being called something reasonable.

Parameters:

  • actions – every action on the menu bar.

  • preferences – the action that really is Preferences, if any.

  • quit_action – the action that really is Quit, if any.

  • about – the action that really is About, if any.

spacr.qt.menus.set_menu_role(action: Any, role: str = 'none') → Any[source]

Assign a macOS menu role and return action.

Parameters:

  • action (PySide6.QtGui.QAction) – Action whose role is assigned.

  • role ({'none', 'preferences', 'quit', 'about'}, default='none') – Target system-menu role. 'none' keeps the action in its menu.

Returns:

PySide6.QtGui.QAction – The input action.

Raises:

ValueError – If role is not supported.

Nested helpers

name_the_macos_application_menu.send(receiver, selector, *args, argtypes=())

One typed objc_msgSend call. Untyped calls corrupt the ABI.

spacr/qt/menus.py:127

name_the_macos_application_menu.to_nsstring(text: bytes)

Wrap bytes as an NSString for the Objective-C call.

spacr/qt/menus.py:149