TTKWidgetTools and the case for a Qt widget set that spans Qt 4 through Qt 6

A catalogue of QWidget subclasses rather than a styled kit

TTKWidgetTools is a collection of custom Qt widgets for C++ desktop software, and the shape of the project is a catalogue. The feature tables in the project guide list each widget by category and mark its status as Finish. The categories are Button, Label, LineEdit, Meter, Progress, Slider, Title and Widget.

The Button category holds six classes, among them TTKCheckButtonWidget, TTKFlatButtonWidget, TTKRadioButtonWidget, TTKToggleWidget, TTKToolMenuWidget and TTKColorButtonWidget. The Label category is the largest in the visible part of the list, nineteen entries, and it shows the character of the project clearly: TTKMarqueeLabel, TTKLedPageLabel, TTKToastLabel, TTKBarRulerLabel, TTKBatteryLabel, TTKCPUMemoryLabel, TTKNetTrafficLabel, TTKScanLabel and TTKTileBackgroundLabel sit alongside more conventional ones such as TTKSplitItemLabel and TTKLcdLabel.

That mix is the honest description of the project. There is no global theme or palette contract across these classes, each widget was written to do one thing well, and the result reads as a toolbox rather than a design system. That is exactly what you want when a dashboard needs a radar meter, and exactly what you do not want when the goal is visual consistency across an application.

Meters and progress indicators are where the collection is densest

Sixteen Meter classes and sixteen Progress classes appear in the visible tables, which makes this the core of the library rather than an afterthought.

The Meter list includes TTKPaintMeterWidget, TTKRadarMeterWidget, TTKSpeedMeterWidget, TTKTimeMeterWidget, TTKCarMeterWidget, TTKSpeedRingMeterWidget, TTKDialMeterWidget, TTKCompassMeterWidget, TTKProgressMeterWidget, TTKPercentMeterWidget, TTKArcMeterWidget, TTKPanelMeterWidget, TTKMiniMeterWidget, TTKRoundMeterWidget, TTKClockMeterWidget and TTKTemperatureMeterWidget. The names describe the widget geometry directly, which is convenient when you are looking for a dial or a compass rather than a generic gauge.

The Progress list is broader in behaviour than in shape. TTKAnimationProgressWidget and TTKGifProgressWidget style the animation differently, TTKCircleProgressWidget, TTKCircularProgressWidget, TTKRoundProgressWidget and TTKRingProgressWidget cover the circular family, TTKDialMeterWidget-style dials have their own ring variant in TTKRingsProgressWidget and TTKRingsMapProgressWidget, and there are three distinct waiting indicators in TTKCircleWaitProgressWidget, TTKPieWaitProgressWidget and TTKLineWaitProgressWidget.

If your application is an instrument panel, a network tool or a monitoring console, this is where the collection earns its place, since the standard Qt progress widget covers a fraction of these shapes.

Title and Widget categories cover navigation and panels

Two categories extend beyond gauges, and the Title group is the more unusual of the two. It contains TTKFunctionAnimationWidget, TTKFunctionListHWidget, TTKFunctionListVWidget, TTKFunctionNormalWidget, TTKFunctionToolboxWidget and TTKFunctionNavigationWidget. The H and V suffixes indicate horizontal and vertical list variants, and the naming convention across the whole collection is consistent enough that you can guess a class role from its prefix.

The Widget category holds TTKAnimation2StackedWidget and TTKAnimationStackedWidget, which suggests a transition between stacked pages, plus TTKColorTableWidget, TTKGrabItemWidget, TTKPictureBannerWidget, TTKPictureFlowWidget, TTKSmoothMovingTableWidget and more entries beyond the visible portion of the table.

A common pattern is worth noting. Several classes embed a QLabel rather than a QWidget, which is the case for TTKCircleClickLabel, TTKToastLabel and the animated labels. That keeps the custom drawing lightweight and means these can be dropped into layouts that expect a label, but it also means they are not real interactive widgets and cannot take focus or handle events the way a button does.

The CI matrix spans three Qt majors and four toolchains

The build matrix is the strongest signal in the project and it is stated in detail. The CI status list covers Qt 4.x on windows-mingw 32bit and ubuntu-linux-gcc 64bit, Qt 5.x on windows-msvc 32bit and 64bit, windows-mingw 32bit and 64bit, and ubuntu-linux-gcc 64bit, and Qt 6.x on windows-msvc 64bit, windows-mingw 64bit and ubuntu-linux-gcc 64bit.

The summary table condenses it: Linux passes with 4.x, 5.x and 6.x GCC, Windows passes with 4.x, 5.x and 6.x GCC, and Windows passes with 5.x and 6.x MSVC. OS X with Clang is listed with a build status of unknown rather than passing.

That unknown matters and it is easy to skim past. Qt 6 on macOS is a supported configuration of Qt itself, so the absence is a gap in the project's own testing rather than a platform limitation. Any team targeting macOS would be the first to find out whether the widgets behave there.

The matrix also tells you the library is written in portable Qt terms rather than against a single platform idiom, which is why the same widget classes render on both Linux and Windows toolchains.

Getting the source: two mirrors, qmake and CMake, and a bundled third-party tree

The project is hosted in two places, and the guide points at both. The Gitee URL is listed as https://gitee.com/Greedysky/TTKWidgetTools and the GitHub URL as https://github.com/Greedysky/TTKWidgetTools. The presence of a Gitee mirror is a common pattern for projects maintained in China, and for a user outside that network it is the faster of the two.

There is no install command in the project guide, so the source tree is what you work with. At the repository root you will find CMakeLists.txt and Doxyfile, and a set of qmake files: TTKWidgetTools.pro as the project file, TTKWidgetTools.pri and TTKVersion.pri as included configuration. That means both build systems are supported, which is the practical answer for anyone arriving from either a Qt 4 era qmake project or a modern CMake one.

The directory names describe the internal split: TTKCommon for shared code, TTKModule for the widget modules, TTKUi for generated UI, TTKUtils for helpers, TTKThirdParty for vendored dependencies, TTKResource for images and other assets, TTKExample for the sample application and TTKRun as the runnable entry point. The Doxyfile at the root indicates the API documentation is generated with Doxygen.

LGPL-3.0 for the code, with a badge that points at both licences

The licence story has a wrinkle that is worth reading carefully. The description of the project in the repository lists the licence as LGPL-3.0, and the project guide states that TTKWidgetTools is free software licensed under the terms of the LGPL v3, with the LICENSE file in the repository root. The reader is told that using the library or its constituent libraries means adhering to the terms of the licence in question.

At the same time, the badge row at the top of the guide shows two licence badges, one for GPL V3 and one for LGPL V3. That is not necessarily a contradiction, since LGPL v3 is built on GPL v3, and a widget library that links dynamically into a proprietary application is a common reason to see both referenced. But a team doing a compliance review should read the LICENSE file itself rather than rely on a badge.

The LGPL designation is the right fit for a widget collection. Dynamic linking keeps the copyleft obligations from reaching the surrounding application, which is what makes it usable inside commercial desktop software, and that is a materially different outcome from the GPL-3.0 alternative.

Where this widget collection is the wrong choice

Three mismatches stand out.

The first is the absence of a coherent visual language. Each class was written independently, so assembling a screen from a radar meter, a toast label and a progress ring gives you three drawing styles unless you reimplement the painting for each one. If your requirement is a consistent product look, a themed kit built on a single painter will cost you less than adapting this collection.

The second is scope. A large fraction of the visible catalogue is single-purpose: TTKCircleClickLabel, TTKMarqueeLabel, TTKBatteryLabel, TTKNetTrafficLabel. Pulling in a collection of this size for one gauge means compiling code you will never call, and with header-heavy Qt widgets that compile cost is real.

The third is the macOS gap described above, and there is a fourth worth naming: the release history is dated relative to the work. The tagged versions are 3.2.0.0 from 2025-12-02, 3.1.0.0 from 2025-05-08 and 3.0.0.0 from 2024-12-05, while the last push to the repository was on 2026-10-13. The commits since the 3.2.0.0 tag are not covered by a release, so pinning a version and expecting later fixes means taking the master branch yourself.

Editorial conclusion

TTKWidgetTools suits a desktop application team that needs a panel, gauge or progress indicator that the stock Qt widgets do not provide, and that still has to build against more than one Qt major version, since the project tests Qt 4.x, 5.x and 6.x across mingw, msvc and gcc toolchains. It does not suit a team that wants a themed widget kit with a coherent design system, because the collection is a catalogue of individually styled classes rather than a coordinated set, and it does not suit a macOS target, where the build status is recorded as unknown. Before you adopt it, check the ChangeLog and the Doxyfile in the repository root for the per-version notes, confirm your compiler appears in the CI matrix, and note that the latest tagged release is 3.2.0.0 from 2025-12-02 while the last push was on 2026-10-13.

Frequently asked questions

Official sources

1. Greedysky/TTKWidgetTools on GitHub
2. Issues
3. License: LGPL-3.0
4. README
5. Releases