Document - and use - the qmlRegisterXXX template functions

This commit removes the obsolete QML_REGISTER_TYPE macros.

3 files changed, 83 insertions, 31 deletions

diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc
index 4b61bd9..ed63367 100644
--- a/doc/src/declarative/declarativeui.qdoc
+++ b/doc/src/declarative/declarativeui.qdoc
@@ -68,7 +68,7 @@ internet-enabled applications like a \l {http://www.flickr.com}{Flickr} photo br
 
 Qt Declarative builds on \l {QML for Qt programmers}{Qt's existing strengths}.
 QML can be be used to incrementally extend an existing application or to build
-completely new applications.  QML is fully \l {Extending QML}{extensible from C++}.
+completely new applications.  QML is fully \l {Extending QML in C++}{extensible from C++}.
 
 \section1 Getting Started:
 \list
@@ -100,7 +100,7 @@ completely new applications.  QML is fully \l {Extending QML}{extensible from C+
 \list
 \o \l {QML Elements}
 \o \l {QML Global Object}
-\o \l {Extending QML}
+\o \l {Extending QML in C++}
 \o \l {QML Internationalization}
 \o \l {QtDeclarative Module}
 \o \l {Debugging QML}
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 5aaa7bd..0ae4f7d 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -41,7 +41,7 @@
 
 /*!
 \page qml-extending.html
-\title Extending QML
+\title Extending QML in C++
 
 The QML syntax declaratively describes how to construct an in memory object
 tree.  In Qt, QML is mainly used to describe a visual scene graph, but it is
@@ -67,21 +67,23 @@ that derive from QObject.
 The QML engine has no intrinsic knowledge of any class types.  Instead the
 programmer must define the C++ types, and their corresponding QML name.
 
-Custom C++ types are made available to QML using these two macros:
+Custom C++ types are declared QML types using a macro and a template function:
 
 \quotation
+
 \code
 #define QML_DECLARE_TYPE(T)
-#define QML_REGISTER_TYPE(URI,VMAJ,VMIN,QDeclarativeName,T)
+template<typename T>
+int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
 \endcode
 
-Register the C++ type \a T with the QML system, and make it available in QML
-under the name \a QDeclarativeName in library URI version VMAJ.VMIN.
-\a T and \a QDeclarativeName may be the same.
+Calling qmlRegisterType() registers the C++ type \a T with the QML system, and makes it available in QML
+under the name \a qmlName in library \a uri version \a versionMajor.versionMinor.
+The \a qmlName can be the same as the C++ type name.
 
 Generally the QML_DECLARE_TYPE() macro should be included immediately following
-the type declaration (usually in its header file), and the QML_REGISTER_TYPE()
-macro called by the implementation.
+the type declaration (usually in its header file), and the template function qmlRegisterType()
+called by the implementation.
 
 Type \a T must be a concrete type that inherits QObject and has a default
 constructor.
@@ -147,19 +149,20 @@ property can be assigned.
 QML also supports assigning Qt interfaces.  To assign to a property whose type
 is a Qt interface pointer, the interface must also be registered with QML.  As
 they cannot be instantiated directly, registering a Qt interface is different
-from registering a new QML type.  The following macros are used instead:
+from registering a new QML type.  The following macro and function are used instead:
 
 \quotation
 \code
-    #define QML_DECLARE_INTERFACE(T)
-    #define QML_REGISTER_INTERFACE(T)
+#define QML_DECLARE_INTERFACE(T)
+template<typename T>
+int qmlRegisterInterface(const char *typeName)
 \endcode
 
-Register the C++ interface \a T with the QML system.
+Registers the C++ interface \a T with the QML system as \a typeName.
 
 Generally the QML_DECLARE_INTERFACE() macro should be included immediately
 following the interface declaration (usually in its header file), and the
-QML_REGISTER_INTERFACE() macro called by the implementation.
+qmlRegisterInterface() template function called by the implementation.
 
 Following registration, QML can coerce objects that implement this interface
 for assignment to appropriately typed properties.
@@ -174,7 +177,7 @@ The guest property declaration looks like this:
 
 \snippet examples/declarative/extending/properties/birthdayparty.h 2
 
-\l {Extending QML - Object and List Property Types Example} shows the complete
+\l {Extending QML in C++ - Object and List Property Types Example} shows the complete
 code used to create the \c BirthdayParty type.
 
 \section1 Inheritance and Coercion
@@ -192,25 +195,26 @@ type used in the previous section, but the assignment is valid as both the Boy
 and Girl objects inherit from Person.
 
 To assign to a property, the property's type must have been registered with QML.
-Both the QML_REGISTER_TYPE() and QML_REGISTER_INTERFACE() macros already shown can
-be used to register a type with QML.  Additionally, if a type that acts purely
+Both the qmlRegisterType() and qmlRegisterInterface() template functions already
+shown can be used to register a type with QML.  Additionally, if a type that acts purely
 as a base class that cannot be instantiated from QML needs to be
-registered these macros can be used:
+registered these macro and function can be used:
 
 \quotation
 \code
     #define QML_DECLARE_TYPE(T)
-    #define QML_REGISTER_NOCREATE_TYPE(T)
+    template<typename T>
+    int qmlRegisterType()
 \endcode
 
-Register the C++ type \a T with the QML system. QML_REGISTER_NOCREATE_TYPE()
-differs from QML_REGISTER_TYPE() in that it does not define a mapping between the
+Registers the C++ type \a T with the QML system. The parameterless call to the template
+function qmlRegisterType() does not define a mapping between the
 C++ class and a QML element name, so the type is not instantiable from QML, but
 it is available for type coercion.
 
 Generally the QML_DECLARE_TYPE() macro should be included immediately following
 the type declaration (usually in its header file), and the
-QML_REGISTER_NOCREATE_TYPE() macro called from the implementation.
+qmlRegisterType() template function called from the implementation.
 
 Type \a T must inherit QObject, but there are no restrictions on whether it is
 concrete or the signature of its constructor.
@@ -220,7 +224,7 @@ QML will automatically coerce C++ types when assigning to either an object
 property, or to a list property.  Only if coercion fails does an assignment
 error occur.
 
-\l {Extending QML - Inheritance and Coercion Example} shows the complete
+\l {Extending QML in C++ - Inheritance and Coercion Example} shows the complete
 code used to create the \c Boy and \c Girl types.
 
 \section1 Default Property
@@ -252,7 +256,7 @@ refer to a property declared in the class itself, or a property inherited from a
 base class.
 \endquotation
 
-\l {Extending QML - Default Property Example} shows the complete code used to
+\l {Extending QML in C++ - Default Property Example} shows the complete code used to
 specify a default property.
 
 \section1 Grouped Properties
@@ -277,7 +281,7 @@ property block - in this case the size, color, brand and price properties.
 
 Grouped property blocks may declared and accessed be recusively.
 
-\l {Extending QML - Grouped Properties Example} shows the complete code used to
+\l {Extending QML in C++ - Grouped Properties Example} shows the complete code used to
 implement the \c shoe property grouping.
 
 \section1 Attached Properties
@@ -369,7 +373,7 @@ creating it if it does not already exist.  If \a create is false, the attachment
 object will only be returned if it has previously been created.
 \endquotation
 
-\l {Extending QML - Attached Properties Example} shows the complete code used to
+\l {Extending QML in C++ - Attached Properties Example} shows the complete code used to
 implement the rsvp attached property.
 
 \section1 Memory Management and QVariant types
@@ -431,7 +435,7 @@ listed in \l {Adding Types}, as well registered object types are permitted as
 signal parameter types.  Using other types is not an error, but the parameter
 value will not be accessible from script.
 
-\l {Extending QML - Signal Support Example} shows the complete code used to
+\l {Extending QML in C++ - Signal Support Example} shows the complete code used to
 implement the onPartyStarted signal property.
 
 \section1 Property Value Sources
@@ -478,7 +482,7 @@ to assign it normally, as though it were a regular QML type.  Only if this
 assignment fails does the engine call the setTarget() method.  This allows
 the type to also be used in contexts other than just as a value source.
 
-\l {Extending QML -  Property Value Source Example} shows the complete code used
+\l {Extending QML in C++ -  Property Value Source Example} shows the complete code used
 implement the HappyBirthday property value source.
 
 \section1 Property Binding
@@ -550,7 +554,7 @@ The CONSTANT attribute should only be used for properties whose value is set,
 and finalized, only in the class constructor.  All other properties that want
 to be used in bindings should have a NOTIFY signal instead.
 
-\l {Extending QML -  Binding Example} shows the BirthdayParty example updated to
+\l {Extending QML in C++ -  Binding Example} shows the BirthdayParty example updated to
 include NOTIFY signals for use in binding.
 
 \section1 Extension Objects
@@ -623,7 +627,7 @@ public:
 \title Extending types from QML
 
 Many of the elements available for use in QML are implemented in
-\l {Extending QML}{C++}.  These types are know as "core types".  QML
+\l {Extending QML in C++}{C++}.  These types are know as "core types".  QML
 allows programmers to build new, fully functional elements without using C++.
 Existing core types can be extended, and new types defined entirely in the QML
 language.
diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index 41d6338..b43d0ec 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -65,3 +65,51 @@ For more information on the Qt Declarative module, see the
 \l{declarativeui.html}{Declarative UI} documentation.
 
 */
+
+
+/*!
+    \macro QML_DECLARE_TYPE(T)
+    \relates QDeclarativeEngine
+
+    yada yada yada
+
+*/
+
+
+/*!
+    \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
+    \relates QDeclarativeEngine
+
+    This template function registers the C++ type \a T with the QML system, and make it available in
+    QML under the name \a qmlName in the import library \a uri version \a versionMajor.versionMajor.
+
+    Returns the QML type id.
+
+    Example: Register the C++ class \c MinehuntGame as QML type \c Game version 0.1 in the import
+    library \c MinehuntCore:
+
+    \code
+        qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
+    \endcode
+
+*/
+
+/*!
+    \fn int qmlRegisterType()
+    \relates QDeclarativeEngine
+    \overload
+
+    This template function registers the C++ type \a T with the QML system. Instances of this type cannot
+    be created from the QML system.
+
+    Returns the QML type id.
+*/
+
+/*! \fn int qmlRegisterInterface(const char *typeName)
+    \relates QDeclarativeEngine
+
+    This template function registers the C++ type \a T as interface with the QML system, under the name
+    \a typeName.
+
+    Returns the QML type id.
+  */