qtkaifajingyan: Practical Qt C++ Development Tips from Ten Years of Projects

What the repository contains and how it is organized

qtkaifajingyan is a numbered list of Qt C++ development tips, each identified by a two-digit index. The README opens at section 01 covering tips 001 through 010, section 02 covering 011 through 020, section 03 covering 021 through 030, and so on. The format is consistent: each tip has a brief statement of the principle followed by a code example or configuration instruction, written in Simplified Chinese prose with embedded C++ or qmake code.

The top-level repository structure shows a set of directories containing Qt e-books: `Qt5编程入门` (Qt5 Programming Introduction), `QtCreator快速入门` (QtCreator Quick Start), `QtQuick核心编程` (QtQuick Core Programming), `Qt其他电子书` (Other Qt E-books), `Qt官方教材` (Official Qt Teaching Materials), `Qt秘籍宝典` (Qt Secret Treasure), and `其他电子书` (Other E-books). These books are bundled as PDFs or similar formats organized by title.

The repository's stated support is for Qt 4, 5, and 6 for all referenced project work. The README notes a change in QtCreator 8 where the Options configuration menu moved from the Tools menu to the Edit menu, and that multi-thread compilation became automatic with detection of core count from approximately 2019 onwards.

Build configuration and compilation tips

The README opens with a tip about build errors: when compilation produces many errors, fix the first one before looking at the next. A single mistake can cascade into hundreds of reported errors in Qt's moc-generated code.

Multi-thread compilation receives a dedicated tip because the default QtCreator build on some compilers is single-threaded. Two methods are described for enabling parallel compilation. The first adds `-j16` to the make arguments in the project's build settings, but this is stored in the `.pro.user` file and must be reconfigured after deletion. The second, which the README recommends, adds `MAKEFLAGS=-j4` to the environment of the build kit under Tools, then Options, then Build & Run, then Kits, then Environment. The number after `-j` should match the machine's core count.

Product metadata can be embedded in Windows executables through the `.pro` file. The qmake variables for this are:

#程序版本
VERSION  = 2025.10.01
#程序图标
RC_ICONS = main.ico
#产品名称
QMAKE_TARGET_PRODUCT = quc
#版权所有
QMAKE_TARGET_COPYRIGHT = feiyangqingyun
#文件说明
QMAKE_TARGET_DESCRIPTION = QQ: 517216493  WX: feiyangqingyun

qmake converts these to an `.rc` file on Windows. These variables require Qt 5.8 or later.

Asynchronous loading and QTimer patterns

A recurring issue in Qt applications is that a heavy initialization call in a window constructor blocks the main thread, causing the window to appear frozen until loading completes. The README recommends deferring such calls with either `QMetaObject::invokeMethod` using a queued connection, or a single-shot timer:

//异步执行load函数
QMetaObject::invokeMethod(this, "load", Qt::QueuedConnection);
//延时10毫秒执行load函数
QTimer::singleShot(10, this, SLOT(load()));

//定时器lambda表达式方式
QTimer::singleShot(10, [&]() {
  load();
});

QTimer *timer = new QTimer(this);
timer->setSingleShot(true);
connect(timer, &QTimer::timeout, this, [timer, this] {

});
timer->start(5000);

These patterns make the window appear first and then perform the heavy load in the next event loop iteration. The README specifically notes this is necessary when the initialization must run on the main thread, for example when loading child widgets into a `QStackedWidget`.

The README also notes that `QTimer::singleShot` with a lambda is convenient but that the timer object needs careful lifetime management when using a raw lambda with captured references.

Meta-object system: inspecting properties and methods at runtime

The Qt meta-object system exposes a widget's properties and methods at runtime through `QMetaObject`. The README shows how to iterate over a widget's custom properties:

//拿到控件元对象
const QMetaObject *metaObject = widget->metaObject();

//所有属性的数量
int propertyCount = metaObject->propertyCount();
//propertyOffset是自定义的属性开始的位置
int propertyOffset = metaObject->propertyOffset();
//循环取出控件的自定义属性, int i = 0 表示所有属性
for (int i = propertyOffset; i < propertyCount; ++i) {
    QMetaProperty metaProperty = metaObject->property(i);
    const char *name = metaProperty.name();
    const char *type = metaProperty.typeName();
    QVariant value = widget->property(name);
    qDebug() << name << type << value;
}

The `propertyOffset()` value indicates where custom properties begin, separating them from Qt's own built-in properties. This is useful when building property editors or when debugging a widget that is not behaving as expected.

For finding child widgets, the README explains `findChildren` with its three main forms: searching by type only, by type and object name, and restricting to direct children only:

//查找指定类名objectName的控件
QList<QWidget *> widgets = fatherWidget.findChildren<QWidget *>("widgetname");
//查找所有QPushButton
QList<QPushButton *> allPButtons = fatherWidget.findChildren<QPushButton *>();
//查找一级子控件,不然会一直遍历所有子控件
QList<QPushButton *> childButtons = fatherWidget.findChildren<QPushButton *>(QString(), Qt::FindDirectChildrenOnly);

The third form is particularly important when a parent widget has deeply nested children but you only want direct children.

Stylesheet management and common widget pitfalls

The README recommends consolidating all stylesheets into a single `.qss` file loaded at startup rather than calling `setStyleSheet` in multiple places throughout the code. For development and quick testing, setting styles directly in QtCreator's design view is acceptable, but production code benefits from centralized style management.

When a stylesheet needs to be replaced on a specific widget, a three-step process is required: call `style()->unpolish(widget)`, then call `widget->setStyleSheet("")`, then call `style()->polish(widget)`. The README warns that omitting the `setStyleSheet("")` call means the old stylesheet is not fully removed.

For `QLCDNumber`, the README notes that setting styles through `setStyleSheet` has no effect unless the `segmentStyle` property is set to `flat`. This is not documented clearly in Qt's own documentation and is a common source of confusion.

The tip about `QComboBox::addItem`'s second parameter illustrates the value of checking Qt function overloads. The second parameter is a `QVariant` that can carry any data alongside the display text, not just a simple string. This allows a combo box to present readable labels while storing structured data per item, such as a student's display name with their full record attached, without maintaining a separate parallel data structure.

Limitations and scope of the repository

The primary limitation of qtkaifajingyan is language. All prose explanations are in Simplified Chinese. The code snippets are in C++ and qmake, which are language-agnostic, but understanding the context and the reason for each tip requires reading Chinese. For developers who do not read Chinese, the code blocks are accessible but the surrounding explanation is not.

The repository does not provide runnable project files. It is a tips collection with code fragments, not a set of complete examples you can clone and build. Developers must integrate the patterns into their own projects.

The e-book directory contains PDFs and similar files, but the README provides Baidu Pan links with extraction codes for downloads, not direct GitHub file downloads. Accessing those books requires a Baidu account and may depend on regional availability.

The README has no English translation, and there is no indication from the repository of plans to add one. Qt's own documentation covers many of the same topics in English, and Qt's official examples repository on GitHub provides runnable code for many patterns. qtkaifajingyan's value is in the practitioner perspective: it covers the gaps and edge cases that official documentation omits, written by someone who encountered these issues in real projects over ten years.

Editorial conclusion

qtkaifajingyan is the right resource for Qt C++ developers who read Chinese and want a practical reference for build, widget, and meta-object system issues that documentation tends to gloss over. The numbered format makes it easy to scan for relevant tips without reading in order. It is not the right resource for developers who do not read Chinese, because the prose explanations are entirely in Simplified Chinese. The bundled e-book collection adds value for someone building a Qt library independently of any course, but it requires downloading books separately. The last push was on 2026-04-18, approximately five months before 2026-09-28, with all projects stated to support Qt 4, 5, and 6.

Frequently asked questions

Official sources

1. feiyangqingyun/qtkaifajingyan on GitHub
2. Issues
3. README