gallery_images

Documentation images

The widget images in docs/images/ and the "Widgets Included" table of the README are generated by the gallery executable, so they can be regenerated after any visual change with one command.

Regenerate

cmake --build build --target QtIndustrialWidgetsGallery
./build/bin/QtIndustrialWidgetsGallery --export-gallery docs/images

The export runs headless: when QT_QPA_PLATFORM is not set it uses the offscreen platform by itself. It prints one line per written file and exits with:

Exit code	Meaning
0	every image written
1	at least one image failed; the error names the widget showcase or the gallery tab
2	invalid command-line options

Options

QtIndustrialWidgetsGallery --export-gallery <output-dir> [--dpr 1|2] [--theme dark|light|both]

Option	Default	Effect
--export-gallery <output-dir>	—	export instead of opening the window; the directory is created if needed
--dpr 1\|2	2	device pixel ratio of the images (sets QT_SCALE_FACTOR before the application starts)
--theme dark\|light\|both	dark	light and both also write the light variants, with a -light suffix

Only the dark theme at DPR 2 is committed. CI exports both themes and uploads them as a workflow artifact.

What is exported

• One image per widget showcase, each widget rendered on its own at a fixed logical size (or at its sizeHint()) on the gallery's group-box colour: <widget>-<variant>[-light].png, e.g. radial-gauge-warning.png, circular-bargraph-overrange.png.
• One image per gallery tab at 1200×820: tab-<name>[-light].png, e.g. tab-daq.png.

Determinism

The same commit, platform and options give byte-identical files. The export:

• renders each showcase right after configuring it, without running the event loop, so no timer fires: LED and segment blinking, annunciator flashing, peak hold and decay stay in their initial state, and switches are not animated (setAnimated(false));
• for the gallery tabs, does not start the simulation or the auto-tour, stops LED blinking, resets held peaks, disables the DAQ paint-time measurement, and only delivers posted events (layout, polish), never timer events;
• uses fixed analytic data only, with explicit timestamps for time-axis strip charts: no wall clock and no random numbers.

Check it by exporting twice and comparing the directories (diff -r).

Fonts differ between platforms, so images from different platforms (or from machines with different fonts) are not expected to match. Regenerate the committed images on one machine; do not compare images across platforms.

Add a showcase for a new widget

Every public widget needs at least one showcase: tst_GalleryShowcases reads the public headers in include/QtIndustrialWidgets/ and fails, naming the class, when a widget has none.

1. In examples/gallery/Showcases.cpp, write a factory that builds and configures the widget for a Theme (no parent, no event loop needed, fixed data only).
2. Add an entry to showcases(): widget class name, kebab-case variant, logical size and factory. A size of QSize() renders the widget at its own sizeHint().
3. Rebuild, run tst_GalleryShowcases, regenerate the images and add the new PNG to the README table.