GUI identity and application menus

The active MPyLab device test tools and limit explorer use a small application icon and native About/Quit menu actions. About is nonmodal, shows the installed version and documentation links, and adapts its logo to the window palette. There is no additional logo header in the measurement controls.

Install mpylab[gui] before using the Qt helpers. The base installation and ApplicationIdentity metadata remain usable without PySide6 or Shiboken.

Sharing the pattern

mpylab.gui.ApplicationIdentity contains project-specific metadata. Importing that module does not load Qt. Applications that use Qt explicitly import the helpers from mpylab.gui.qt:

from mpylab.gui.qt import create_application, install_branding

app = create_application(["example-tool"])
window = build_window()  # create the window and its layout first
branding = install_branding(window)
window.show()
app.exec()

The default identity is MPyLab. A companion application supplies its own ApplicationIdentity to both helpers, including its installed version, description, URLs, author/license and package resource location. The resource directory contains icon.png, logo.svg and logo-inverse.svg. Distribute the artwork source commit and license beside them, and include the resources in both wheel and sdist. Resources are loaded via importlib.resources; the current working directory and a source checkout are not required.

install_branding accepts an existing menu bar and About/Quit actions. An existing About action must have its old callback disconnected first. An existing Quit action retains its own connection to the normal close handler. Repeated installation returns the same controller and adds no further menus.

Shutdown and macOS

New Quit actions call window.close(). The existing close handler remains responsible for RF-off, worker shutdown, unsaved results and any confirmation. If it rejects the close event, both window and About remain available. About closes after an accepted window close. About never starts or stops hardware.

Call create_application before constructing GUI windows. On macOS it sets process-local Cocoa bundle names before Qt creates the native menu; it changes no interpreter installation or on-disk plist. A newly created macOS application uses Qt dialogs to avoid a native NSAlert rendering crash observed with Qt 6.11.2 on the development Mac. Native menus remain enabled. This also means file selection uses Qt dialogs on macOS. An already running host application’s identity and dialog preferences remain unchanged.

Qt’s standard Quit shortcut supplies Command-Q on macOS and Ctrl-Q on the other supported desktop platforms. The About/Quit actions move into the native application menu on macOS; other platforms retain File/Quit and Help/About.

Verification and adoption

Tests use virtual devices and check resource loading, theme changes, repeated About, refused/accepted close events and device shutdown paths. Native macOS checks are additionally necessary: an offscreen Qt platform does not exercise Cocoa menus or alerts. Before publishing, verify an installed wheel from outside the checkout. GUI branding does not constitute hardware acceptance.

Companion applications may adopt these helpers only with a published MPyLab version that provides them as their minimum dependency. Test the editable clones locally first, then publish MPyLab before updating consumer dependencies.

See User-interface and worker API for the API and UI adapters and worker interface for safety and workers.