GUI

The GUI window

What updater --gui shows, and how it's branded.

What it is

A plain Qt dialog: icon, heading, status line, progress bar, cancel button. That's it - no per-application UI code, because branding comes entirely from values baked in at build time (icon, accent colour, window title). The same window code renders correctly for every app that ships this updater.

Requires PySide6, which is why it's an opt-in build:

python tools/build_branded.py --brand your-brand.yaml --gui ...

A binary built without --gui doesn't bundle PySide6 and is smaller; updater --gui on that binary just isn't a supported flag.

How it stays responsive

All real work - network calls, download, verification, install - runs on a background worker thread. Qt is never touched from that thread; it reports back through signals (status, progress, finished_ok, failed). That split is what keeps Cancel responsive even mid-download, instead of freezing the window until the current operation happens to finish.

Branding it

Set in the brand file, compiled into the binary:

ui:
  window_title: MyApp Updater
  accent_color: "#4C8BF5"
  auto_close_seconds: 3

accent_color tints the progress bar and any highlighted UI elements. auto_close_seconds controls how long the window lingers on success before closing itself - set it higher if users should get a chance to read a "what's new" message, or 0 to require a manual close.

The window icon comes from --icon at build time (see DEV_GUIDE §2), embedded as bytes rather than referenced by path, since the icon file living in your app's source tree won't exist on the end user's machine.

Headless vs. GUI at call time

The same binary (if built with --gui) supports both:

updater --check-only --json   # headless, for your app to parse
updater --gui                 # shows this window

Typical shape: your app calls --check-only --json on startup or on a schedule, and only launches --gui after the user acts on a prompt (or from a Help > Check for Updates menu item). See DEV_GUIDE §5.

See also

• DEV_GUIDE - calling the updater from your app
• README - full config reference