From ce26eaf1b9300a788f7c3caa18dd8a5eec23da23 Mon Sep 17 00:00:00 2001 From: Alexei Cazacov Date: Tue, 28 May 2024 14:45:14 +0300 Subject: [PATCH] Docs: Update the obsolete requirements for Q_OBJECT and Q_GADGET Since 6.5, you can declare the Q_OBJECT macro in any class section, not only in private. The docs are updated accordingly. The Q_OBJECT macro specifies a private section on its own, thus making private all the members declared after the macro. This is an important behavior change, so the note about it was rewritten for clarity & moved a little bit up. Fixes: QTBUG-125776 Pick-to: 6.5 6.6 6.7 Change-Id: Ifba063af7cf7fe7258b6183da5a4599784171052 Reviewed-by: Nicholas Bennett --- .../signalsandslots/signalsandslots.h | 2 + .../doc/src/objectmodel/metaobjects.qdoc | 3 +- .../doc/src/objectmodel/properties.qdoc | 25 ++++++----- src/corelib/kernel/qobject.cpp | 41 ++++++++++--------- 4 files changed, 36 insertions(+), 35 deletions(-) diff --git a/src/corelib/doc/snippets/signalsandslots/signalsandslots.h b/src/corelib/doc/snippets/signalsandslots/signalsandslots.h index 2f5a53231c8..a590e8fd5e6 100644 --- a/src/corelib/doc/snippets/signalsandslots/signalsandslots.h +++ b/src/corelib/doc/snippets/signalsandslots/signalsandslots.h @@ -33,6 +33,8 @@ class Counter : public QObject { Q_OBJECT +// Note. The Q_OBJECT macro starts a private section. +// To declare public members, use the 'public:' access modifier. public: Counter() { m_value = 0; } diff --git a/src/corelib/doc/src/objectmodel/metaobjects.qdoc b/src/corelib/doc/src/objectmodel/metaobjects.qdoc index 3d7685447fc..44f574816e1 100644 --- a/src/corelib/doc/src/objectmodel/metaobjects.qdoc +++ b/src/corelib/doc/src/objectmodel/metaobjects.qdoc @@ -19,8 +19,7 @@ \list 1 \li The \l QObject class provides a base class for objects that can take advantage of the meta-object system. - \li The Q_OBJECT macro inside the private section of the class - declaration is used to enable meta-object features, such as + \li The Q_OBJECT macro is used to enable meta-object features, such as dynamic properties, signals, and slots. \li The \l{moc}{Meta-Object Compiler} (\c moc) supplies each QObject subclass with the necessary code to implement diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc index 99a3e60d884..0e66c8445c2 100644 --- a/src/corelib/doc/src/objectmodel/properties.qdoc +++ b/src/corelib/doc/src/objectmodel/properties.qdoc @@ -186,12 +186,11 @@ \section1 A Simple Example - Suppose we have a class MyClass, which is derived from QObject and - which uses the Q_OBJECT macro in its private section. We want to - declare a property in MyClass to keep track of a priority - value. The name of the property will be \e priority, and its type - will be an enumeration type named \e Priority, which is defined in - MyClass. + Suppose we have a class \c MyClass, which is derived from QObject and which + uses the Q_OBJECT macro. We want to declare a property in \c MyClass to keep + track of a priority value. The name of the property will be \c priority, and + its type will be an enumeration type named \c Priority, which is defined in + \c MyClass. We declare the property with the Q_PROPERTY() macro in the private section of the class. The required \c READ function is named \c @@ -200,7 +199,7 @@ System} using the Q_ENUM() macro. Registering an enumeration type makes the enumerator names available for use in calls to QObject::setProperty(). We must also provide our own declarations - for the \c READ and \c WRITE functions. The declaration of MyClass + for the \c READ and \c WRITE functions. The declaration of \c MyClass then might look like this: \snippet code/doc_src_properties.cpp 5 @@ -213,24 +212,24 @@ potentially forcing re-evaluation in other places if nothing has changed. - Given a pointer to an instance of MyClass or a pointer to a - QObject that is an instance of MyClass, we have two ways to set + Given a pointer to an instance of \c MyClass or a pointer to a + QObject that is an instance of \c MyClass, we have two ways to set its priority property: \snippet code/doc_src_properties.cpp 6 In the example, the enumeration type that is the property type is - declared in MyClass and registered with the \l{Meta-Object System} + declared in \c MyClass and registered with the \l{Meta-Object System} using the Q_ENUM() macro. This makes the enumeration values - available as strings for use as in the call to \l{QObject::}{setProperty()}. Had - the enumeration type been declared in another class, its fully + available as strings for use as in the call to \l{QObject::}{setProperty()}. + Had the enumeration type been declared in another class, its fully qualified name (i.e., OtherClass::Priority) would be required, and that other class would also have to inherit QObject and register the enumeration type there using the Q_ENUM() macro. A similar macro, Q_FLAG(), is also available. Like Q_ENUM(), it registers an enumeration type, but it marks the type as being a - set of \e flags, i.e. values that can be OR'd together. An I/O + set of \e flags, i.e., values that can be OR'd together. An I/O class might have enumeration values \c Read and \c Write and then QObject::setProperty() could accept \c{Read | Write}. Q_FLAG() should be used to register this enumeration type. diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp index e1129c5d251..31b779dc9b3 100644 --- a/src/corelib/kernel/qobject.cpp +++ b/src/corelib/kernel/qobject.cpp @@ -4698,16 +4698,25 @@ QDebug operator<<(QDebug dbg, const QObject *o) \sa {Qt's Property System} */ - /*! \macro Q_OBJECT \relates QObject - 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. + The Q_OBJECT macro is used to enable meta-object features, such as dynamic + properties, signals, and slots. - For example: + You can add the Q_OBJECT macro to any section of a class definition that + declares its own signals and slots or that uses other services provided by + Qt's meta-object system. + +//! [qobject-macros-private-access-specifier] + \note This macro expansion ends with a \c private: access specifier. If you + declare members immediately after this macro, those members will also be + private. To add public (or protected) members right after the macro, use a + \c {public:} (or \c {protected:}) access specifier. +//! [qobject-macros-private-access-specifier] + + Example: \snippet signalsandslots/signalsandslots.h 1 \codeline @@ -4715,15 +4724,8 @@ QDebug operator<<(QDebug dbg, const QObject *o) \snippet signalsandslots/signalsandslots.h 3 \note This macro requires the class to be a subclass of QObject. Use - Q_GADGET or Q_GADGET_EXPORT instead of Q_OBJECT to enable the meta object system's support - for enums in a class that is not a QObject subclass. - -//! [qobject-macros-private-access-specifier] - \note This macro expansion ends with a \c private: access specifier, which makes member - declarations immediately after the macro private, too. If you want add public (or protected) - members immediately after the macro, you need to use a \c public: (or \c protected:) - access specifier. -//! [qobject-macros-private-access-specifier] + Q_GADGET or Q_GADGET_EXPORT instead of Q_OBJECT to enable the meta object + system's support for enums in a class that is not a QObject subclass. \sa {Meta-Object System}, {Signals and Slots}, {Qt's Property System} */ @@ -4734,8 +4736,9 @@ QDebug operator<<(QDebug dbg, const QObject *o) 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. + reflection capabilities offered by QMetaObject. + + \include qobject.cpp qobject-macros-private-access-specifier Q_GADGETs can have Q_ENUM, Q_PROPERTY and Q_INVOKABLE, but they cannot have signals or slots. @@ -4744,8 +4747,6 @@ QDebug operator<<(QDebug dbg, const QObject *o) \c{staticMetaObject} is of type QMetaObject and provides access to the enums declared with Q_ENUM. - \include qobject.cpp qobject-macros-private-access-specifier - \sa Q_GADGET_EXPORT */ @@ -4761,6 +4762,8 @@ QDebug operator<<(QDebug dbg, const QObject *o) enclosing class as a whole should not be (e.g. because it consists of mostly inline functions). + \include qobject.cpp qobject-macros-private-access-specifier + For example: \code @@ -4771,8 +4774,6 @@ QDebug operator<<(QDebug dbg, const QObject *o) ~~~ \endcode - \include qobject.cpp qobject-macros-private-access-specifier - \sa Q_GADGET, {Creating Shared Libraries} */