QtWidgetUtils

WD Studio's tools for developing internal/external tools with Qt. feel free to use for any reason!

WidgetInspect

WidgetInspect is a lightweight helper library that adds an inspector overlay to Qt Widgets applications.

Features

• On-demand highlights – call Inspector::highlightWidget() to visually outline any widget.
• widget metadata – name, Qt type, size, widget hierarchy path, inline QSS, and a scaled screenshot thumbnail.
• Dedicated inspector window – pop out a resizable panel that lists the selected widget's stats, style sheet, and thumbnail.
• Hierarchy explorer – browse the live widget tree, see active/hidden state badges, and jump directly to child widgets.
• Non-invasive overlay – transparent overlay that preserves pointer events and follows window resizes.

Getting started

Prerequisites

• CMake 3.16+
• Qt 5.15+ or Qt 6 (Widgets + Gui modules)
• A C++17 capable compiler

Build the library & demo

cmake -S . -B build -DCMAKE_PREFIX_PATH="<path-to-qt>"
cmake --build build

The build produces the WidgetInspect static library and the optional widgetinspect_demo sample application (enabled by default).

Getting Qt

By default WidgetInspect will fetch a matching Qt build via aqtinstall the first time you configure the project:

cmake -S . -B build
cmake --build build

Prefer to use an existing Qt install? Disable the helper with -DWIDGETINSPECT_AUTO_DOWNLOAD_QT=OFF or point CMAKE_PREFIX_PATH to your Qt prefix.

Additional cache variables you can tweak (defaults in parentheses):

• WIDGETINSPECT_QT_MODULES – Qt archives to install (default: none; qtbase is auto-added for Qt 5 builds)
• WIDGETINSPECT_QT_ARCH – override the architecture triplet (auto-detected per platform)
• WIDGETINSPECT_QT_MIRROR – custom mirror URL for Qt downloads (empty = official mirrors)
• WIDGETINSPECT_QT_OUTPUT_DIR – directory used to install the downloaded toolchain (default: <build>/qt)
• WIDGETINSPECT_QT_ARCHIVE_DIR – location where raw .7z archives are cached for reuse (default: <build>/qt-archives, set to NONE to skip caching)
• WIDGETINSPECT_QT_TOOLS – Qt tooling packages (tools_ifw:4.6.0, tools_qtcreator:13.0.2, etc.; default: none, set to NONE to skip)
• WIDGETINSPECT_COPY_RUNTIME_DLLS – when enabled (default on Windows), automatically deploy Qt runtime DLLs next to built executables via qt_generate_deploy_app_script/windeployqt

The downloader expects Python 3 with pip on your PATH. If the helper fails, install Qt manually and point CMAKE_PREFIX_PATH to it.

If you pre-populate WIDGETINSPECT_QT_ARCHIVE_DIR with Qt .7z packages (for example via python -m aqt install-qt --outputdir <temp> --archives <cache> on a connected machine), the helper reuses them and you can combine that directory with WIDGETINSPECT_QT_MIRROR=file:///path/to/cache for air-gapped CI. Tool archives follow the same pattern—specify them with explicit versions such as tools_ifw:4.6.0—with installed binaries landing in <output>/Tools.

Apply the Enfusion-inspired theme

WidgetInspect ships with a QSS skin that mirrors the Enfusion Engine tools. Enable it at runtime with:

if (auto* panel = inspector.inspectorWindow()) {
	panel->setTheme(WidgetInspect::InspectorWindow::Theme::Enfusion);
}

The inspector window exposes a theme drop-down, and the demo app includes a Cycle Theme button that rotates through Light → Dark → Enfusion.

Inspect other Qt widget apps (Windows)

You can point the inspector at another Qt Widgets application even if you don’t have its source by relying on Windows UI Automation. Open the inspector window, refresh the External Qt application menu at the top, and select any detected window to attach in one click. WidgetInspect will fetch the automation tree and highlight nodes inside the target application using their UI Automation bounding rectangles.

By the way, API is still available:

WidgetInspect::Inspector inspector;

const auto windows = WidgetInspect::AutomationProbe::enumerateTopLevelWindows("Qt Creator");
if (!windows.isEmpty()) {
	inspector.inspectExternalWindow(windows.first().second);
	inspector.showInspectorWindow();
}

This integration is currently Windows-only and depends on the target app exposing accessibility metadata (Qt enables this by default).

Embed in your app

#include "WidgetInspect/Inspector.h"

WidgetInspect::Inspector inspector;
inspector.enableHoverInspection(mainWindow);   // Ctrl + hover to inspect
inspector.showInspectorWindow();                // Optional stats window

// Highlight a widget programmatically
inspector.highlightWidget(ui->submitButton);

Hold the trigger modifier (default Ctrl) while hovering to see the overlay. You can change the modifier:

inspector.enableHoverInspection(mainWindow, Qt::AltModifier);
inspector.showInspectorWindow();

To hide the overlay, call inspector.clearHighlight(); or release the modifier key. The inspector window displays the widget's active style sheet so you can copy or tweak it while the app runs.

Installing

Standard CMake install targets are provided:

cmake --build build --target install

This installs headers to include/WidgetInspect, the library to your system lib dir, and CMake package files so you can consume the library with find_package(WidgetInspect).

Notes

• Hidden or off-screen widgets render a contextual placeholder thumbnail so you still know why a live preview is missing.
• Dynamically created widgets are tracked automatically; if one appears while hidden, the inspector shows a banner so you can surface it manually.
• External app inspection currently relies on Windows UI Automation. Non-Windows platforms fall back to in-process inspection.

License

Copyright (c) 2025-present Mikael K. Aboagye. All Rights Reserved. Licensed under the MIT license.