Macros(中文版)

QT_NO_NARROWING_CONVERSIONS_IN_CONNECT [since 5.8]

Defining this macro will disable narrowing and floating-point-to-integral conversions between the arguments carried by a signal and the arguments accepted by a slot, when the signal and the slot are connected using the PMF-based syntax.
This function was introduced in Qt 5.8.

See also **QObject::connect.

QCLASSINFO(_Name, Value)

This macro associates extra information to the class, which is available using QObject::metaObject(). Qt makes only limited use of this feature in Qt D-Bus and Qt QML modules.
The extra information takes the form of a Name string and a Value literal string.
Example:

class MyClass : public QObject
{
    Q_OBJECT
    Q_CLASSINFO("Author", "Pierre Gendron")
    Q_CLASSINFO("URL", "http://www.my-organization.qc.ca")
public:
    ...
};

See also **QMetaObject::classInfo(), Using Qt D-Bus Adaptors, and Extending QML.

QDISABLE_COPY(_Class)

Disables the use of copy constructors and assignment operators for the given Class.
Instances of subclasses of QObject should not be thought of as values that can be copied or assigned, but as unique identities. This means that when you create your own subclass of QObject (director or indirect), you should not give it a copy constructor or an assignment operator. However, it may not enough to simply omit them from your class, because, if you mistakenly write some code that requires a copy constructor or an assignment operator (it’s easy to do), your compiler will thoughtfully create it for you. You must do more.
The curious user will have seen that the Qt classes derived from QObject typically include this macro in a private section:

class MyClass : public QObject
{
private:
    Q_DISABLE_COPY(MyClass)
};

It declares a copy constructor and an assignment operator in the private section, so that if you use them by mistake, the compiler will report an error.

class MyClass : public QObject
{
private:
    MyClass(const MyClass &) = delete;
    MyClass &operator=(const MyClass &) = delete;
};

But even this might not catch absolutely every case. You might be tempted to do something like this:

QWidget w = QWidget();

First of all, don’t do that. Most compilers will generate code that uses the copy constructor, so the privacy violation error will be reported, but your C++ compiler is not required to generate code for this statement in a specific way. It could generate code using neither the copy constructor nor the assignment operator we made private. In that case, no error would be reported, but your application would probably crash when you called a member function of w.

See also Q_DISABLE_COPY_MOVE and Q_DISABLE_MOVE.

QDISABLE_COPY_MOVE(_Class) [since 5.13]

A convenience macro that disables the use of copy constructors, assignment operators, move constructors and move assignment operators for the given Class, combining Q_DISABLE_COPY and Q_DISABLE_MOVE.
This function was introduced in Qt 5.13.

See also Q_DISABLE_COPY and Q_DISABLE_MOVE.

QDISABLE_MOVE(_Class) [since 5.13]

Disables the use of move constructors and move assignment operators for the given Class.
This function was introduced in Qt 5.13.

See also Q_DISABLE_COPY and Q_DISABLE_COPY_MOVE.

Q_EMIT

Use this macro to replace the emit keyword for emitting signals, when you want to use Qt Signals and Slots with a 3rd party signal/slot mechanism.
The macro is normally used when no_keywords is specified with the CONFIG variable in the .pro file, but it can be used even when no_keywords is not specified.

Q_ENUM(…) [since 5.5]

This macro registers an enum type with the meta-object system. It must be placed after the enum declaration in a class that has the Q_OBJECT or the Q_GADGET macro. For namespaces use Q_ENUM_NS() instead.
For example:

class MyClass : public QObject
{
    Q_OBJECT
public:
    MyClass(QObject *parent = nullptr);
    ~MyClass();
    enum Priority { High, Low, VeryHigh, VeryLow };
    Q_ENUM(Priority)
    void setPriority(Priority priority);
    Priority priority() const;
};

Enumerations that are declared with Q_ENUM have their QMetaEnum registered in the enclosing QMetaObject. You can also use QMetaEnum::fromType() to get the QMetaEnum.
Registered enumerations are automatically registered also to the Qt meta type system, making them known to QMetaType without the need to use Q_DECLARE_METATYPE(). This will enable useful features; for example, if used in a QVariant, you can convert them to strings. Likewise, passing them to QDebug will print out their names.
Mind that the enum values are stored as signed int in the meta object system. Registering enumerations with values outside the range of values valid for int will lead to overflows and potentially undefined behavior when accessing them through the meta object system. QML, for example, does access registered enumerations through the meta object system.
This function was introduced in Qt 5.5.

See also Qt’s Property System.

Q_ENUM_NS(…) [since 5.8]

This macro registers an enum type with the meta-object system. It must be placed after the enum declaration in a namespace that has the Q_NAMESPACE macro. It is the same as Q_ENUM but in a namespace.
Enumerations that are declared with Q_ENUM_NS have their QMetaEnum registered in the enclosing QMetaObject. You can also use QMetaEnum::fromType() to get the QMetaEnum.
Registered enumerations are automatically registered also to the Qt meta type system, making them known to QMetaType without the need to use Q_DECLARE_METATYPE(). This will enable useful features; for example, if used in a QVariant, you can convert them to strings. Likewise, passing them to QDebug will print out their names.
Mind that the enum values are stored as signed int in the meta object system. Registering enumerations with values outside the range of values valid for int will lead to overflows and potentially undefined behavior when accessing them through the meta object system. QML, for example, does access registered enumerations through the meta object system.
This function was introduced in Qt 5.8.

See also Qt’s Property System.

Q_FLAG(…) [since 5.5]

This macro registers a single flags type with the meta-object system. It is typically used in a class definition to declare that values of a given enum can be used as flags and combined using the bitwise OR operator. For namespaces use Q_FLAG_NS() instead.
The macro must be placed after the enum declaration. The declaration of the flags type is done using the Q_DECLARE_FLAGS() macro.
For example, in QItemSelectionModel, the SelectionFlags flag is declared in the following way:

class QItemSelectionModel : public QObject
{
    Q_OBJECT
public:
    ...
    enum SelectionFlag {
        NoUpdate       = 0x0000,
        Clear          = 0x0001,
        Select         = 0x0002,
        Deselect       = 0x0004,
        Toggle         = 0x0008,
        Current        = 0x0010,
        Rows           = 0x0020,
        Columns        = 0x0040,
        SelectCurrent  = Select | Current,
        ToggleCurrent  = Toggle | Current,
        ClearAndSelect = Clear | Select
    };
    Q_DECLARE_FLAGS(SelectionFlags, SelectionFlag)
    Q_FLAG(SelectionFlags)
    ...
}

Note: The Q_FLAG macro takes care of registering individual flag values with the meta-object system, so it is unnecessary to use Q_ENUM() in addition to this macro.
This function was introduced in Qt 5.5.

See also Qt’s Property System.

Q_FLAG_NS(…) [since 5.8]

This macro registers a single flags type with the meta-object system. It is used in a namespace that has the Q_NAMESPACE macro, to declare that values of a given enum can be used as flags and combined using the bitwise OR operator. It is the same as Q_FLAG but in a namespace.
The macro must be placed after the enum declaration.
Note: The Q_FLAG_NS macro takes care of registering individual flag values with the meta-object system, so it is unnecessary to use Q_ENUM_NS() in addition to this macro.
This function was introduced in Qt 5.8.

See also Qt’s Property System.

Q_GADGET

The Q_GADGET macro is a lighter version of the Q_OBJECT macro for classes that do not inherit from QObject but still want to use some of the reflection capabilities offered by QMetaObject. Just like the Q_OBJECT macro, it must appear in the private section of a class definition.
Q_GADGETs can have Q_ENUM, Q_PROPERTY and Q_INVOKABLE, but they cannot have signals or slots.
Q_GADGET makes a class member, staticMetaObject, available. staticMetaObject is of type QMetaObject and provides access to the enums declared with Q_ENUMS.

Q_INTERFACES(…)

This macro tells Qt which interfaces the class implements. This is used when implementing plugins.
Example:

class BasicToolsPlugin : public QObject,
                         public BrushInterface,
                         public ShapeInterface,
                         public FilterInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.Examples.PlugAndPaint.BrushInterface" FILE "basictools.json")
    Q_INTERFACES(BrushInterface ShapeInterface FilterInterface)
public:
    ...
};

See the Plug & Paint Basic Tools example for details.

See also Q_DECLARE_INTERFACE(), Q_PLUGIN_METADATA(), and How to Create Qt Plugins.

Q_INVOKABLE

Apply this macro to declarations of member functions to allow them to be invoked via the meta-object system. The macro is written before the return type, as shown in the following example:

class Window : public QWidget
{
    Q_OBJECT
public:
    Window();
    void normalMethod();
    Q_INVOKABLE void invokableMethod();
};

The invokableMethod() function is marked up using Q_INVOKABLE, causing it to be registered with the meta-object system and enabling it to be invoked using QMetaObject::invokeMethod(). Since normalMethod() function is not registered in this way, it cannot be invoked using QMetaObject::invokeMethod().
If an invokable member function returns a pointer to a QObject or a subclass of QObject and it is invoked from QML, special ownership rules apply. See Data Type Conversion Between QML and C++ for more information.

Q_MOC_INCLUDE [since 6.0]

The Q_MOC_INCLUDE macro can be used within or outside a class, and tell the Meta Object Compiler to add an include.

// Put this in your code and the generated code will include this header.
Q_MOC_INCLUDE("myheader.h")

This is useful if the types you use as properties or signal/slots arguments are forward declared.
This function was introduced in Qt 6.0.

Q_NAMESPACE [since 5.8]

The Q_NAMESPACE macro can be used to add QMetaObject capabilities to a namespace.
Q_NAMESPACEs can have Q_CLASSINFO, Q_ENUM_NS, Q_FLAG_NS, but they cannot have Q_ENUM, Q_FLAG, Q_PROPERTY, Q_INVOKABLE, signals nor slots.
Q_NAMESPACE makes an external variable, staticMetaObject, available. staticMetaObject is of type QMetaObject and provides access to the enums declared with Q_ENUM_NS/Q_FLAG_NS.
For example:

namespace test {
Q_NAMESPACE
...

This function was introduced in Qt 5.8.

See also Q_NAMESPACE_EXPORT.

QNAMESPACE_EXPORT(_EXPORT_MACRO) [since 5.14]

The QNAMESPACE_EXPORT macro can be used to add QMetaObject capabilities to a namespace.
It works exactly like the Q_NAMESPACE macro. However, the external staticMetaObject variable that gets defined in the namespace is declared with the supplied _EXPORT_MACRO qualifier. This is useful if the object needs to be exported from a dynamic library.
For example:

namespace test {
Q_NAMESPACE_EXPORT(EXPORT_MACRO)
...

This function was introduced in Qt 5.14.

See also Q_NAMESPACE and Creating Shared Libraries.

Q_OBJECT

The Q_OBJECT macro must appear in the private section of a class definition that declares its own signals and slots or that uses other services provided by Qt’s meta-object system.
For example:

#include <QObject>
class Counter : public QObject
{
    Q_OBJECT
public:
    Counter() { m_value = 0; }
    int value() const { return m_value; }
public slots:
    void setValue(int value);
signals:
    void valueChanged(int newValue);
private:
    int m_value;
};

Note: This macro requires the class to be a subclass of QObject. Use Q_GADGET instead of Q_OBJECT to enable the meta object system’s support for enums in a class that is not a QObject subclass.

See also Meta-Object System, Signals and Slots, and Qt’s Property System.

Q_PROPERTY(…)

This macro is used for declaring properties in classes that inherit QObject. Properties behave like class data members, but they have additional features accessible through the Meta-Object System.

Q_PROPERTY(type name
           (READ getFunction [WRITE setFunction] |
            MEMBER memberName [(READ getFunction | WRITE setFunction)])
           [RESET resetFunction]
           [NOTIFY notifySignal]
           [REVISION int | REVISION(int[, int])]
           [DESIGNABLE bool]
           [SCRIPTABLE bool]
           [STORED bool]
           [USER bool]
           [BINDABLE bindableProperty]
           [CONSTANT]
           [FINAL]
           [REQUIRED])

The property name and type and the READ function are required. The type can be any type supported by QVariant, or it can be a user-defined type. The other items are optional, but a WRITE function is common. The attributes default to true except USER, which defaults to false.
For example:

Q_PROPERTY(QString title READ title WRITE setTitle USER true)

For more details about how to use this macro, and a more detailed example of its use, see the discussion on Qt’s Property System.

See also Qt’s Property System.

Q_REVISION

Apply this macro to declarations of member functions to tag them with a revision number in the meta-object system. The macro is written before the return type, as shown in the following example:

class Window : public QWidget
{
    Q_OBJECT
    Q_PROPERTY(int normalProperty READ normalProperty)
    Q_PROPERTY(int newProperty READ newProperty REVISION(2, 1))
public:
    Window();
    int normalProperty();
    int newProperty();
public slots:
    void normalMethod();
    Q_REVISION(2, 1) void newMethod();
};

This is useful when using the meta-object system to dynamically expose objects to another API, as you can match the version expected by multiple versions of the other API. Consider the following simplified example:

    Window window;
    int expectedRevision = 0;
    const QMetaObject *windowMetaObject = window.metaObject();
    for (int i=0; i < windowMetaObject->methodCount(); i++)
        if (windowMetaObject->method(i).revision() <= expectedRevision)
            exposeMethod(windowMetaObject->method(i));
    for (int i=0; i < windowMetaObject->propertyCount(); i++)
        if (windowMetaObject->property(i).revision() <= expectedRevision)
            exposeProperty(windowMetaObject->property(i));

Using the same Window class as the previous example, the newProperty and newMethod would only be exposed in this code when the expected version is 2.1 or greater.
Since all methods are considered to be in revision 0 if untagged, a tag of Q_REVISION(0) or Q_REVISION(0, 0) is invalid and ignored.
You can pass one or two integer parameters to Q_REVISION. If you pass one parameter, it denotes the minor version only. This means that the major version is unspecified. If you pass two, the first parameter is the major version and the second parameter is the minor version.
This tag is not used by the meta-object system itself. Currently this is only used by the QtQml module.
For a more generic string tag, see QMetaMethod::tag()

See also QMetaMethod::revision().

QSET_OBJECT_NAME(_Object) [since 5.0]

This macro assigns Object the objectName “Object”.
It doesn’t matter whether Object is a pointer or not, the macro figures that out by itself.
This function was introduced in Qt 5.0.

See also QObject::objectName().

Q_SIGNAL

This is an additional macro that allows you to mark a single function as a signal. It can be quite useful, especially when you use a 3rd-party source code parser which doesn’t understand a signals or Q_SIGNALS groups.
Use this macro to replace the signals keyword in class declarations, when you want to use Qt Signals and Slots with a 3rd party signal/slot mechanism.
The macro is normally used when no_keywords is specified with the CONFIG variable in the .pro file, but it can be used even when no_keywords is not specified.

Q_SIGNALS

Use this macro to replace the signals keyword in class declarations, when you want to use Qt Signals and Slots with a 3rd party signal/slot mechanism.
The macro is normally used when no_keywords is specified with the CONFIG variable in the .pro file, but it can be used even when no_keywords is not specified.

Q_SLOT

This is an additional macro that allows you to mark a single function as a slot. It can be quite useful, especially when you use a 3rd-party source code parser which doesn’t understand a slots or Q_SLOTS groups.
Use this macro to replace the slots keyword in class declarations, when you want to use Qt Signals and Slots with a 3rd party signal/slot mechanism.
The macro is normally used when no_keywords is specified with the CONFIG variable in the .pro file, but it can be used even when no_keywords is not specified.

Q_SLOTS

Use this macro to replace the slots keyword in class declarations, when you want to use Qt Signals and Slots with a 3rd party signal/slot mechanism.
The macro is normally used when no_keywords is specified with the CONFIG variable in the .pro file, but it can be used even when no_keywords is not specified.