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``:

.. code-block:: python

   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 :doc:`../../api/ui` for the API and :doc:`ui-workers` for safety and workers.