Qt之Q_OBJECT 宏的神奇之旅（一）-阿里云开发者社区

前言

只有加入了Q_OBJECT，你才能使用QT中的signal和slot机制。

凡是QObject类（不管是直接子类还是间接子类），都应该在第一行代码写上Q_OBJECT。不管是不是使用信号槽，都应该添加这个宏。

这时候，就必须在头文件派生类的时候，首先像下面那样引入Q_OBJECT宏：

class MyMainWindow : public QWidget
{
        Q_OBJECT
         ......
}

值得注意的地方： Q_OBJECT应该放在头文件中，而不是放在cpp文件中。

一、Q_OBJECT 宏的概述 (Overview of the Q_OBJECT Macro)

1.1 Q_OBJECT 宏的定义与用途 (Definition and Purpose of the Q_OBJECT Macro)

Q_OBJECT 宏是 Qt 对象模型中的一个关键要素。它通常定义在继承自 QObject 的类的私有部分，为该类提供元对象（meta-object）系统所需的底层支持。

元对象系统是 Qt 的核心概念，提供了以下功能：

动态类型信息（Dynamic Type Information）：它允许在运行时查询对象的类型信息。
信号-槽机制（Signal-Slot Mechanism）：信号槽机制是 Qt 的一种强大且灵活的回调（callback）系统，用于实现对象间的通信。
动态属性（Dynamic Properties）：允许在运行时向 QObject 添加自定义的属性值。

Q_OBJECT 宏的主要作用是为类声明扩展的 Qt 功能，包括信号、槽以及元对象特性。同时，它还确保类与 Qt 元对象编译器 (Meta-Object Compiler, MOC) 协同工作。MOC 用于生成与类相关的元对象代码，以实现动态类型信息和信号槽机制等功能。

当在自定义类中使用 Qt 提供的 QObject 特性时，如信号和槽等，就需要在该类中加入 Q_OBJECT 宏。但需要注意，只有继承自 QObject 的类以及符合 Qt 对象模型的类才能使用 Q_OBJECT 宏。

1.2 Qt 元对象系统简介 (Introduction to Qt Meta-Object System)

Qt 元对象系统 (Meta-Object System) 是 Qt 框架的基石，它为 QObject 类（以及其子类）提供了一些独特的功能。以下是元对象系统所提供的主要功能：

信号与槽机制：信号槽机制是 Qt 的核心特性之一，为组件之间的通信提供了一种安全且灵活的方法。这种机制使得组件可以在不必了解对方实现细节的情况下，实现解耦式的通信。
对象自省 (Introspection)：元对象系统允许在运行时查询关于对象的信息，例如类名、属性、信号和槽等。这使得 Qt 能够实现更加灵活的动态行为和强大的工具集成。
动态属性：元对象系统支持在运行时为 QObject 添加和修改动态属性。这些属性的值可以在没有改变类定义的情况下被设置和读取。

要使用 Qt 元对象系统，首先需要在自定义类声明中添加 Q_OBJECT 宏。此外，该类需要继承自 QObject（直接或间接继承）。Q_OBJECT 宏告诉 Qt 元对象编译器 (MOC) 为类生成所需的元对象代码，以支持信号槽机制、动态属性等特性。不包含 Q_OBJECT 宏的类将无法使用元对象系统提供的功能。

1.3 Q_OBJECT 宏与信号槽机制 (Q_OBJECT Macro and Signal-Slot Mechanism)

信号槽机制是 Qt 对象模型中一种用于在组件间传递事件和数据的核心机制。它允许开发者更加轻松地将组件的动作和响应分离，从而提高代码的可维护性和可读性。信号槽机制要求对象必须是 QObject 的直接或间接子类，并且类定义中必须包含 Q_OBJECT 宏，才能使用全部功能。

Q_OBJECT 宏在信号槽机制中的作用如下：

为信号槽连接提供支持：Q_OBJECT 宏确保元对象编译器 (MOC) 为类生成必要的元对象代码，从而支持信号和槽的连接。
支持信号的声明：Q_OBJECT 宏允许开发者在类定义中使用 signals 部分来声明信号。同时, MOC 将负责生成信号的实际实现代码。
支持槽的声明：Q_OBJECT 宏使得开发者可以在类定义的 public、protected 或 private 部分使用 slots 关键字声明槽。槽是普通的 C++ 成员函数，但它们可以与信号建立连接，从而在信号被发射时被调用。
支持运行时类型检查：Q_OBJECT 宏确保类与 Qt 元对象系统的集成，从而允许在运行时检查信号和槽的兼容性。这种检查机制有助于确保应用程序的稳定性，并在编程中避免一些常见的错误。

为了使用信号槽机制，开发者需要在 QObject 子类中至少包含 Q_OBJECT 宏。没有 Q_OBJECT 宏的类可能会无法正常地使用信号槽机制，甚至会导致应用程序出现不稳定的行为。

二、Q_OBJECT 宏的底层原理解析 (Underlying Principles of the Q_OBJECT Macro)

2.1 元对象编译器 (MOC) 的作用 (Role of the Meta-Object Compiler (MOC))

元对象编译器（Meta-Object Compiler，简称 MOC）是 Qt 框架中一个独特的工具，负责生成 QObject 子类的元信息。MOC 是一个预处理程序，它在 C++ 编译器处理源代码之前，扫描包含 Q_OBJECT 宏的 QObject 子类源文件，并输出额外的 C++ 代码。这些生成的代码用于实现信号槽机制、动态属性等元对象系统提供的功能。

MOC 的主要作用如下：

提供信号槽的实现：元对象编译器为信号槽机制生成底层实现代码。当两个 QObject 子类通过信号和槽连接时，MOC 生成的代码能够将信号与槽关联起来并在需要时执行槽函数。
支持运行时类型信息：MOC 生成的代码包含对象的运行时类型信息。这些信息可以用于实现对象自省，例如查询对象的类名、属性、信号和槽等。
支持动态属性：元对象编译器生成的代码允许 QObject 子类在运行时添加、修改和访问动态属性。

MOC 作为一个预处理工具，是 Qt 开发过程中不可或缺的一环。它允许开发者为 QObject 子类添加元数据，从而支持信号槽机制等功能。开发者需要确保 QObject 子类中包含 Q_OBJECT 宏，使得 MOC 能够正确地扫描并生成所需的元信息。

2.2 生成的元对象代码剖析 (Analysis of the Generated Meta-Object Code)

当元对象编译器（MOC）处理包含 Q_OBJECT 宏的 QObject 子类时，它会生成一些附加的 C++ 代码，提供运行时类型信息，实现信号槽机制等功能。以下是 MOC 生成的元对象代码所包含的主要组成部分：

静态元对象 (Static Meta-Object)：MOC 生成一个静态元对象实例，它包含了类的元数据，如类名、属性、信号和槽等信息。静态元对象用于支持运行时类型信息查询和信号槽机制。
信号函数实现：MOC 生成信号函数的代码实现。在 Qt 中，信号函数是空函数，它们仅用于激发信号发射状态。当信号发射时，MOC 生成的代码会遍历与信号关联的槽，并调用槽函数。
qt_metacall 函数：MOC 生成的 qt_metacall 函数负责实现槽函数的调用。它根据槽函数在元对象中的索引，以及传递给槽函数的参数，来执行相应的槽函数。
qt_metacast 函数：MOC 提供的 qt_metacast 函数用于执行 QObject 的动态类型转换。当使用 qobject_cast，如果类型之间存在继承关系，qt_metacast 函数可以在运行时将指针转换为正确的类型。
qt_static_metacall 函数：用于处理静态类型信号和槽的连接。此函数负责为静态类型的连接管理槽函数调用。

通过以上生成的代码，MOC 支持 QObject 子类的信号槽机制、动态属性、运行时类型信息等功能。正是由于 MOC 扫描包含 Q_OBJECT 宏的类并自动生成必要的代码，使得 Qt 能够实现这些强大的功能。在 Qt 项目的构建过程中，MOC 的运行是自动完成的，开发者无需手动运行 MOC。然而，了解 MOC 生成的代码及其工作原理有助于更好地理解 Qt 信号槽机制和元对象系统的运作。

2.3 Q_OBJECT 宏与静态类型信号槽 (Q_OBJECT Macro and Static Type Signal-Slot)

在 Qt 5 之后的版本，引入了基于模板的静态类型信号槽连接机制，这种类型的连接不再依赖 MOC 生成的元对象代码。尽管静态类型信号槽连接在一定程度上减少了对 Q_OBJECT 宏的依赖，但在 QObject 和子类中使用 Q_OBJECT 宏依然具有重要意义，以下是原因：

兼容性：虽然静态类型信号槽连接提供了类型安全和编译时检查的优势，但对于遗留代码和 Qt 的旧版本，仍然需要使用 Q_OBJECT 宏，以支持旧式的动态类型信号槽连接。
动态特性：静态类型信号槽连接虽然能完成信号槽的基本功能，但 Q_OBJECT 宏所支持的动态特性如动态属性、运行时类型信息查询等仍然是必要的。这些特性使 Qt 更加强大且灵活，而 Q_OBJECT 宏在此过程中发挥着关键作用。
信号槽连接类型：静态类型信号槽连接只适用于普通成员函数和 C++11 的 lambda 表达式。而对于使用 slots 关键字声明的槽函数以及用于 QT += core5-compat 模块支持的 Qt::UniqueConnection 和 Qt::DirectConnection 连接类型，仍然需要使用 Q_OBJECT 宏。

所以，在 QObject 子类中仍然建议使用 Q_OBJECT 宏，以确保 Qt 各项功能正常运行。静态类型信号槽连接可以作为连接方式的优化和补充，并不意味着 Q_OBJECT 宏已经失去了作用。在继承自 QObject 的类中，使用 Q_OBJECT 宏依然具有很高的实用性。

三、Q_OBJECT 宏的常见应用 (Common Applications of the Q_OBJECT Macro)

3.1 在自定义控件中使用 Q_OBJECT 宏 (Using the Q_OBJECT Macro in Custom Widgets)

当你创建一个自定义控件时，通常需要继承自一个 Qt 提供的控件类（如 QLabel、QPushButton 等），这些类都间接或直接继承自 QObject。在自定义控件中，使用 Q_OBJECT 宏可以为控件提供信号槽机制、动态属性等功能，从而使得自定义控件更加灵活且功能强大。

以下是在自定义控件中使用 Q_OBJECT 宏的一些建议：

声明信号：在自定义控件中，你可能需要创建信号以向外界发送控件的状态或事件信息。通过在类声明中使用 signals 部分声明信号，Q_OBJECT 宏确保 MOC 为信号生成正确的实现代码。
声明槽：在自定义控件中，你可能需要实现槽来响应外部信号。你可以在类声明的 public、protected 或 private 部分使用 slots 关键字声明槽。这些槽可以用于处理外部信号，例如父窗口的信号或者其他控件的信号。
添加动态属性：在自定义控件中，可能需要为控件添加额外的属性，例如自定义样式或自定义行为。你可以使用 QObject 提供的 setProperty 和 property 方法动态添加或修改属性，从而在运行时自定义控件的外观和行为。
多线程和并发处理：如果你的控件需要进行多线程或并发处理，Q_OBJECT 宏能够确保信号槽机制适应多线程环境。例如，你可以在子线程中发射信号，并在主线程中的槽函数中处理这个信号，避免主线程被阻塞。

在创建自定义控件时，确保在类声明中包含 Q_OBJECT 宏，并按照需要使用信号槽机制和动态属性等功能。这将帮助你创建功能丰富、灵活易用的自定义控件。

3.2 为自定义控件添加自定义信号和槽 (Adding Custom Signals and Slots to Custom Widgets)

在自定义控件中，你可能需要添加自定义的信号和槽来实现控件的特定功能。通过使用信号槽机制，你可以实现扩展控件功能的同时保持代码的可读性和可维护性。

以下是为自定义控件添加自定义信号和槽的步骤：

添加 Q_OBJECT 宏：首先，在自定义控件类的声明中添加 Q_OBJECT 宏。这将确保元对象编译器 (MOC) 为类生成元对象代码，支持信号槽机制。

class CustomWidget : public QWidget
{
    Q_OBJECT
public:
    CustomWidget(QWidget *parent = nullptr);
    ...
};

声明自定义信号：在自定义控件类中声明自定义信号。将信号声明在类声明中的 signals 部分。

class CustomWidget : public QWidget
{
    Q_OBJECT
public:
    CustomWidget(QWidget *parent = nullptr);
    ...
signals:
    void customSignal();
};

发射自定义信号：在自定义控件类的实现中，通过调用 emit 关键字并跟随信号名称来发射自定义信号。通常，你会在某个事件发生时发射信号，例如鼠标点击、键盘按下等。

void CustomWidget::mousePressEvent(QMouseEvent *event)
{
    ...
    emit customSignal();
}

声明自定义槽：在自定义控件类的声明中，使用 slots 关键字声明自定义槽。槽可以声明在 public、protected 或 private 部分。

class CustomWidget : public QWidget
{
    Q_OBJECT
public:
    CustomWidget(QWidget *parent = nullptr);
    ...
signals:
    void customSignal();
public slots:
    void customSlot();
};

实现自定义槽：在自定义控件类的实现中，编写自定义槽的具体实现。此槽将在与之连接的信号被发射时执行。

void CustomWidget::customSlot()
{
    ...
}

连接自定义信号和槽：在需要的地方（例如构造函数或其他初始化代码中），使用 QObject::connect 方法将自定义信号连接到自定义槽或其他 QObject 子类的槽。

connect(this, &CustomWidget::customSignal, this, &CustomWidget::customSlot);

通过以上步骤，你可以为自定义控件添加自定义信号和槽，实现控件功能的扩展和对象间的通信。使用信号槽机制有助于保持代码的可读性和可维护性。

3.3 在自定义控件中使用动态属性 (Using Dynamic Properties in Custom Widgets)

动态属性允许在运行时为 QObject 子类添加、修改和访问自定义属性。在自定义控件中使用动态属性可以实现控件属性的灵活管理，从而满足特定的外观和行为需求。以下是在自定义控件中使用动态属性的方法：

添加 Q_OBJECT 宏：首先，在自定义控件类的声明中添加 Q_OBJECT 宏。这将确保元对象编译器 (MOC) 为类生成元对象代码，支持动态属性功能。

class CustomWidget : public QWidget
{
    Q_OBJECT
public:
    CustomWidget(QWidget *parent = nullptr);
    ...
};

设置动态属性：在自定义控件类的实现中，你可以使用 QObject::setProperty 方法为控件添加或修改动态属性。你需要提供属性名（类型为 QByteArray 或 QLatin1String）和属性值（类型为 QVariant）。

void CustomWidget::setCustomProperty(const QString &value)
{
    setProperty("customProperty", value);
}

访问动态属性：要访问自定义控件的动态属性，你可以使用 QObject::property 方法。此方法接受属性名（类型为 QByteArray 或 QLatin1String），并返回属性值（类型为 QVariant）。

QString CustomWidget::customProperty() const
{
    return property("customProperty").toString();
}

监听动态属性更改：要监听自定义控件动态属性的更改，可以重写 QObject::event 方法，并在其中捕获 QDynamicPropertyChangeEvent 类型的事件。通过检查事件的属性名和新值，你可以根据需要执行相应的操作。

bool CustomWidget::event(QEvent *event)
{
    if (event->type() == QEvent::DynamicPropertyChange)
    {
        QDynamicPropertyChangeEvent *propertyEvent = static_cast<QDynamicPropertyChangeEvent *>(event);
        if (propertyEvent->propertyName() == "customProperty")
        {
            // Perform actions based on the changed customProperty.
        }
    }
    return QWidget::event(event);
}

通过以上步骤，你可以在自定义控件中使用动态属性来管理控件的自定义外观和行为。动态属性为自定义控件提供了更高的灵活性，可以根据需要在运行时调整属性值，使控件更加可定制。

四、Q_OBJECT 宏的常见用途

4.1 使用 Qt 的多线程类 (Using Qt’s Multithreading Classes)

Qt 提供了一系列多线程类，让开发者能够轻松地在项目中实现多线程功能。这些类包括 QThread、QThreadPool、QRunnable 和 QMutex 等。以下是使用 Qt 多线程类的简要指南：

QThread：QThread 类表示一个操作系统线程。要在单独的线程中运行任务，可以通过子类化 QThread 类并重写 run() 方法来创建自定义线程。将要在新线程中运行的代码放置在 run() 方法中。

class CustomThread : public QThread
{
    Q_OBJECT
protected:
    void run() override
    {
        // Place the code to run in a separate thread here
    }
};

创建自定义线程对象后，调用 start() 方法来开始线程。

CustomThread customThread;
customThread.start();
customThread.wait(); // Optionally, wait for the thread to finish

QThreadPool：QThreadPool 类管理一个线程池，可以用于运行多个并发任务。为了使用线程池，需要创建一个 QRunnable 子类并重写 run() 方法。将要在新线程中运行的代码放置在 run() 方法中。

class CustomRunnable : public QRunnable
{
public:
    void run() override
    {
        // Place the code to run in a separate thread here
    }
};

创建自定义 QRunnable 对象后，将其提交给 QThreadPool 的全局实例，以便在可用线程中运行。

CustomRunnable *customRunnable = new CustomRunnable();
QThreadPool::globalInstance()->start(customRunnable);

QMutex：QMutex 类用于同步对共享资源的访问。当多个线程需要访问共享资源时，可以使用 QMutex 来确保同一时间只有一个线程能访问资源。要使用 QMutex，请在需要保护的代码段周围使用 QMutexLocker 类，它将自动锁定和解锁互斥量。

QMutex mutex;
...
{
    QMutexLocker locker(&mutex);
    // Access shared resource
}

通过使用 Qt 的多线程类，可以轻松地在项目中实现多线程功能，从而提高应用程序的性能和响应速度。需要注意的是，在使用多线程时，应确保正确同步共享资源和信号槽连接，以避免出现竞争条件和不一致的数据。

4.2 使用 Qt 的信号槽机制进行线程间通信 (Using Qt’s Signal-Slot Mechanism for Inter-Thread Communication)

Qt 的信号槽机制在多线程环境下表现良好，可以方便地在不同线程之间传递数据和同步操作。以下是使用 Qt 信号槽进行线程间通信的方法：

创建自定义类：首先，需要创建一个自定义 QObject 子类，该类将在新的线程中运行。在类中定义槽和信号，以实现线程间通信。

class CustomWorker : public QObject
{
    Q_OBJECT
public:
    explicit CustomWorker(QObject *parent = nullptr);
public slots:
    void doWork();
signals:
    void resultReady();
};

子类化 QThread：创建一个 QThread 子类，以便将自定义 QObject 类移动到新线程中。

class CustomThread : public QThread
{
public:
    explicit CustomThread(QObject *parent = nullptr);
private:
    void run() override;
};

实现 QThread 子类的 run() 方法：在 QThread 子类的 run() 方法中，创建自定义 QObject 子类的实例，并将其移动到新线程。

void CustomThread::run()
{
    CustomWorker worker;
    worker.moveToThread(this);
    // Connect signals and slots as needed
    exec(); // Start the event loop for the thread
}

在新线程和主线程之间连接信号和槽：使用 QObject::connect 方法将新线程中的自定义 QObject 类实例的信号和槽连接到主线程的信号和槽。设置连接类型为 Qt::QueuedConnection，以便在信号发生时将调用放入事件队列，然后在接收者所在的线程中执行槽。

CustomThread customThread;
CustomWorker   worker;
worker.moveToThread(&customThread);
connect(&customThread, &CustomThread::started, &worker, &CustomWorker::doWork, Qt::QueuedConnection);
connect(&worker, &CustomWorker::resultReady, this, &MainWindow::handleResult, Qt::QueuedConnection);

开始新线程：调用 QThread::start 方法开始新线程。

customThread.start();

通过遵循上述步骤，您可以在 Qt 应用程序中使用信号槽机制实现线程间通信。这种方法具有良好的解耦性和可扩展性，可以轻松地在多个线程之间传递数据和同步操作。

Qt之Q_OBJECT 宏的神奇之旅（二）https://developer.aliyun.com/article/1464187

Qt之Q_OBJECT 宏的神奇之旅（一）

前言