From 4a79ed90f130e48b0a3237de9d8ebb6896b4567c Mon Sep 17 00:00:00 2001 From: Fabian Kosmale Date: Thu, 20 Mar 2025 11:42:27 +0100 Subject: [PATCH] Q_DECLARE_OPAQUE_POINTER: Document footgun Using Q_DECLARE_OPAQUE_POINTER means that the metatype system won't have any knowledge about the type, beyond it being a pointer. That leads to all kinds of unexpected errors in code that needs to introspect the meta-type information to handle QObject's and gadgets, notably but not limited to QML. Warn about using Q_DECLARE_OPAQUE_POINTER for gadgets and QObject's, and offer Q_MOC_INCLUDE as a potential alternative for some use cases. Pick-to: 6.8 6.5 Task-number: QTBUG-127012 Task-number: QTBUG-134883 Change-Id: I4fe53f277d0aa51ef552d04f642364aa6613ef7c Reviewed-by: Marc Mutz Reviewed-by: Leena Miettinen (cherry picked from commit 0a567a7f926f433cbd1294131aac0e80dcfd7943) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/kernel/qmetatype.cpp | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/corelib/kernel/qmetatype.cpp b/src/corelib/kernel/qmetatype.cpp index 66dec2979c4..ccf863b566e 100644 --- a/src/corelib/kernel/qmetatype.cpp +++ b/src/corelib/kernel/qmetatype.cpp @@ -220,6 +220,16 @@ const char *QtMetaTypePrivate::typedefNameForType(const QtPrivate::QMetaTypeInte to be registered with QMetaType using either Q_DECLARE_METATYPE() or qRegisterMetaType(). + Do not use this macro to avoid complaints or errors from \l moc about + incomplete property types when the pointee type is used as a complete type in + other contexts in the program. Use \l{Q_MOC_INCLUDE} instead when + the full definition of the type is available, but you prefer a forward + declaration in the header to reduce compilation times. + + \warning Don't use Q_DECLARE_OPAQUE_POINTER with pointers to a Q_OBJECT or + a gadget class, as that risks introducing inconsistent information in the + meta-type system. + \sa Q_DECLARE_METATYPE(), qRegisterMetaType() */