QtIndustrialWidgets 2.3.0
Modern, High-Performance Industrial Instruments & SCADA Widgets for Qt
Loading...
Searching...
No Matches
QtIndustrialWidgets

QtIndustrialWidgets

A C++17 widget library for Qt Widgets with 12 instrumentation widgets — gauges, displays, indicators, switches, an alarm annunciator, a live strip chart and an offline analysis chart — for test benches, SCADA and telemetry applications.

C++17 Qt 6.2+ Platform CI/CD Pipeline [License: MIT](LICENSE) REUSE status Docs

Dashboard tab of the QtIndustrialWidgets gallery

Widgets

Widget Showcase
RadialGauge
0–8000 RPM, needle in the warning zone 		RadialGauge
LinearGauge
Thermometer mode, 0–120 °C 		LinearGauge
SevenSegmentDisplay
Six digits, one decimal, skewed segments 		SevenSegmentDisplay
LedIndicator
Round lens, on, with label 		LedIndicator
IndustrialKnob
Continuous 0–8000 RPM with value pod 		IndustrialKnob
StripChart
Three channels over 10 s with a NaN dropout 		StripChart
IndustrialSwitch
Toggle lever under a safety guard 		IndustrialSwitch
LevelMeter
Stereo dB meter with held peaks 		LevelMeter
AnnunciatorPanel
ISA-18.1 tiles: acknowledged, unacknowledged and advisory alarms 		AnnunciatorPanel
Compass
Heading-up card, heading 047° with heading bug 		Compass
CircularBargraph
24 segments with peak hold 		CircularBargraph
AnalysisChart
Recorded data at two rates, a NaN dropout and a recording gap 		AnalysisChart

The images are generated by the gallery with --export-gallery (dark theme, device pixel ratio 2, shown at half their pixel width); see docs/gallery_images.md. Each widget's features are described in docs/widgets.md.

Quick start

include(FetchContent)
FetchContent_Declare(
QtIndustrialWidgets
GIT_REPOSITORY https://github.com/paolosereno/QtIndustrialWidgets.git
GIT_TAG v2.3.0
)
set(BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
set(BUILD_DESIGNER_PLUGIN OFF CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(QtIndustrialWidgets)
target_link_libraries(my_app PRIVATE QtIndustrialWidgets::QtIndustrialWidgets)
#include <QtIndustrialWidgets/RadialGauge.h>
#include <QtIndustrialWidgets/LinearGauge.h>
#include <QtIndustrialWidgets/SevenSegmentDisplay.h>
// Inside a QWidget-derived class. 'qiw' is the short alias of namespace QtIndustrialWidgets.
auto *rpmGauge = new qiw::RadialGauge(this);
rpmGauge->setRange(0.0, 8000.0);
rpmGauge->setValue(3500.0);
rpmGauge->setUnit("RPM");
rpmGauge->setWarningThreshold(6000.0);
rpmGauge->setErrorThreshold(7200.0);
auto *coolant = new qiw::LinearGauge(this);
coolant->setThermometerMode(true);
coolant->setRange(0.0, 120.0);
coolant->setValue(90.0);
coolant->setUnit("°C");
auto *speedometer = new qiw::SevenSegmentDisplay(this);
speedometer->setDigitCount(5);
speedometer->setDecimalPlaces(1);
speedometer->setValue(120.4);
speedometer->setActiveSegmentColor(QColor(0, 229, 255));
QtIndustrialWidgets::LinearGauge
Definition LinearGauge.h:45
QtIndustrialWidgets::RadialGauge
Definition RadialGauge.h:57
QtIndustrialWidgets::SevenSegmentDisplay
Definition SevenSegmentDisplay.h:38

How it is verified

  • Tests: a QtTest suite; every test program runs at device pixel ratios 1, 1.25, 1.5 and 2 (tests/CMakeLists.txt). Rendering is checked at pixel level (traces, gaps, labels, layout), and new tests are shown to fail under a deliberate sabotage of the feature they cover before they are merged; the results are reported in each pull request (CONTRIBUTING.md).
  • CI (ci.yml), on every pull request and push to main: build and the full test suite on Linux (Ubuntu 24.04, GCC, Qt 6.4.2), Windows (MSVC, Qt 6.6.3) and macOS (Apple Clang, Homebrew Qt); reuse lint; on Linux, the export of the gallery images and the Doxygen documentation.
  • Benchmarks: method, machine, command lines and raw tables in docs/benchmarks.md, including the targets that are not met.
  • Images: the documentation images are generated by the gallery and are byte-identical for the same commit, platform and options (docs/gallery_images.md).
  • Releases (release.yml): a Debian package, a Linux .tar.gz, a Windows .zip and an SPDX SBOM are attached to each GitHub release (see v2.3.0).
  • Licensing: REUSE compliant; reuse lint runs in CI.
  • Dependencies: none beyond Qt. The library links only Qt Core, Gui and Widgets; the Qt Designer plugin is a separate module that also needs Qt Designer.

Integration

Requirements: CMake 3.16 or newer, a C++17 compiler and Qt 6.2 or newer (CI builds with Qt 6.4.2, 6.6.3 and Homebrew's current Qt). Qt 5.15 is not supported at the moment, see #53.

  • FetchContent: see Quick start above.
  • Build and install, then find_package():
    cmake -B build -DCMAKE_BUILD_TYPE=Release
    cmake --build build
    ctest --test-dir build --output-on-failure
    cmake --install build --prefix /opt/QtIndustrialWidgets
    find_package(QtIndustrialWidgets REQUIRED)
    target_link_libraries(my_app PRIVATE QtIndustrialWidgets::QtIndustrialWidgets)
  • Prebuilt packages from GitHub Releases: sudo dpkg -i qtindustrialwidgets_<version>_amd64.deb on Debian / Ubuntu, or extract the .tar.gz / .zip and add the extracted directory to CMAKE_PREFIX_PATH.
  • vcpkg: vcpkg install --overlay-ports=./ports/qtindustrialwidgets qtindustrialwidgets — experimental, not yet verified: the port has not been tested with vcpkg install, and its archive hash is set only after a release is tagged (see #66).
  • Conan 2: conan install . --build=missing (the recipe is conanfile.py; it is not built in CI).

The interactive gallery is built by default (BUILD_EXAMPLES): ./build/bin/QtIndustrialWidgetsGallery.

Qt Designer

With BUILD_DESIGNER_PLUGIN (on by default, switched off when Qt Designer is not found), the plugin QtIndustrialWidgetsPlugin registers the 12 widgets in the Industrial Widgets category of Qt Designer and Qt Creator. Installation: docs/designer_plugin.md.

Documentation

API reference and guides on GitHub Pages: https://paolosereno.github.io/QtIndustrialWidgets/

To build the documentation locally (needs Doxygen; Graphviz is optional): cmake --build build --target docs, output in build/docs/html/index.html. Without a CMake build, from the project root:

mkdir -p build/docs # Doxygen creates only the last folder of OUTPUT_DIRECTORY
QIW_VERSION=$(sed -n 's/^ *VERSION \‍([0-9][0-9.]*\‍) *$/\1/p' CMakeLists.txt | head -n1) doxygen docs/Doxyfile

Contributing

How changes are made and what a pull request has to show (tests first for bugs, sabotage checks for new tests, the criteria for "done", Conventional Commits): CONTRIBUTING.md.

License

[MIT](LICENSE) (SPDX: MIT, full text in LICENSES/MIT.txt). Every file carries SPDX copyright and license information, as the REUSE specification requires; reuse lint checks it in CI.