Improve error messages, especially on embedded.

With embedded, it is often the case that some QT_NO_* features are
turned off (eg. QT_NO_XMLPATTERNS), which in turn leads to QML types not
being available.

1 files changed, 54 insertions, 1 deletions

diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index b4d8a2e..a986fbc 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -79,7 +79,7 @@
   \relates QDeclarativeEngine
 
   This template function registers the C++ type in the QML system with
-  the name \a qmlName. in the library imported from \a uri having the
+  the name \a qmlName, in the library imported from \a uri having the
   version number composed from \a versionMajor and \a versionMinor.
 
   Returns the QML type id.
@@ -94,6 +94,59 @@
 */
 
 /*!
+  \fn int qmlRegisterTypeUncreatable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
+  \relates QDeclarativeEngine
+
+  This template function registers the C++ type in the QML system with
+  the name \a qmlName, in the library imported from \a uri having the
+  version number composed from \a versionMajor and \a versionMinor.
+
+  While the type has a name and a type, it cannot be created, and the
+  given error \a message will result if creation is attempted.
+
+  This is useful where the type is only intended for providing attached properties or enum values.
+
+  Returns the QML type id.
+
+  \sa qmlRegisterTypeNotAvailable
+*/
+
+/*!
+  \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
+  \relates QDeclarativeEngine
+
+  This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the
+  version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type
+  will produce the given error \a message.
+
+  Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should
+  at least "reserve" the QML type name, and give the user of your module a meaningful error message.
+
+  Returns the QML type id.
+
+  Example:
+
+  \code
+  #ifdef NO_GAMES_ALLOWED
+  qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
+  #else
+  qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
+  #endif
+  \endcode
+
+  This will cause any QML which uses this module and attempts to use the type to produce an error message:
+  \code
+fun.qml: Get back to work, slacker!
+     Game {
+     ^
+  \endcode
+
+  Without this, a generic "Game is not a type" message would be given.
+
+  \sa qmlRegisterTypeUncreatable
+*/
+
+/*!
   \fn int qmlRegisterType()
   \relates QDeclarativeEngine
   \overload