Introduce Q_DECLARE_OPAQUE_POINTER

To hide the IsPointerToTypeDerivedFromQObject monstruosity :-)

Documentation for Q_DECLARE_METATYPE and qRegisterMetaType was updated
to mention requirements on registered types and how they can be
circumvented for pointer types with the new macro.

Change-Id: If83b037a8e2f28761eb903525e87008107298801
Reviewed-by: Harald Fernengel <harald.fernengel@nokia.com>
Reviewed-by: Stephen Kelly <stephen.kelly@kdab.com>

1 files changed, 20 insertions, 0 deletions

diff --git a/src/corelib/kernel/qmetatype.cpp b/src/corelib/kernel/qmetatype.cpp
index 6a7c5c2a34..d965c48255 100644
--- a/src/corelib/kernel/qmetatype.cpp
+++ b/src/corelib/kernel/qmetatype.cpp
@@ -116,6 +116,16 @@ template<> struct TypeDefinition<QRegExp> { static const bool IsAvailable = fals
 #endif
 } // namespace
 
+/*!
+    \macro Q_DECLARE_OPAQUE_POINTER(Pointer)
+    \relates QMetaType
+
+    This macro enables pointers to forward-declared types to be registered with
+    QMetaType using either Q_DECLARE_METATYPE() or qRegisterMetaType().
+
+    \sa Q_DECLARE_METATYPE(), qRegisterMetaType()
+
+*/
 
 /*!
     \macro Q_DECLARE_METATYPE(Type)
@@ -126,6 +136,11 @@ template<> struct TypeDefinition<QRegExp> { static const bool IsAvailable = fals
     a public destructor.
     It is needed to use the type \a Type as a custom type in QVariant.
 
+    This macro requires that \a Type is a fully defined type at the point where
+    it is used. For pointer types, it also requires that the pointed to type is
+    fully defined. Use in conjunction with Q_DECLARE_OPAQUE_POINTER() to
+    register pointers to forward declared types.
+
     Ideally, this macro should be placed below the declaration of
     the class or struct. If that is not possible, it can be put in
     a private header file which has to be included every time that
@@ -1630,6 +1645,11 @@ QMetaType::TypeFlags QMetaType::typeFlags(int type)
     public default constructor, a public copy constructor and a public
     destructor can be registered.
 
+    This function requires that \c{T} is a fully defined type at the point
+    where the function is called. For pointer types, it also requires that the
+    pointed to type is fully defined. Use Q_DECLARE_OPAQUE_POINTER() to be able
+    to register pointers to forward declared types.
+
     After a type has been registered, you can create and destroy
     objects of that type dynamically at run-time.