Create new documentation structure

The documentation currently has no clear separation between Qt QML
and Qt Quick.  With recent commits like:
6c8378eaf1edbbefe6aaa3672b0127816a004fd7
and
ab1e510121c8a679fdaca12ccd30e0f7ac12a26b
the separation between the language definition and implementation,
provided by Qt QML, and the standard library for the QML language,
provided by Qt Quick, is clear.

This commit creates a new documentation structure that is more
navigable and separates concepts into logical categories, with
clear separation between QtQML and QtQuick.  It also provides a more
generic QML Application Developer Resources page which contains links
to information for QML application developers.

Change-Id: Ia807ccfbfd24ffa0e1c7f0a51ed9d2ed3aa6a733
Reviewed-by: Martin Jones <martin.jones@nokia.com>

1 files changed, 334 insertions, 0 deletions

diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc
new file mode 100644
index 0000000000..974d99c7f1
--- /dev/null
+++ b/src/qml/doc/src/qmlfunctions.qdoc
@@ -0,0 +1,334 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+  \macro QML_DECLARE_TYPE()
+  \relates QQmlEngine
+
+  Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)
+
+  #include <QtQml> to use this macro.
+*/
+
+/*!
+  \macro QML_DECLARE_TYPEINFO(Type,Flags)
+  \relates QQmlEngine
+
+  Declares additional properties of the given \a Type as described by the
+  specified \a Flags.
+
+  Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which
+  declares that the \a Type supports \l {Attached Properties}.
+
+  #include <QtQml> to use this macro.
+*/
+
+
+/*!
+  \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
+  \relates QQmlEngine
+
+  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.
+
+  Returns the QML type id.
+
+  There are two forms of this template function:
+
+  \code
+  template<typename T>
+  int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
+
+  template<typename T, int metaObjectRevision>
+  int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
+  \endcode
+
+  The former is the standard form which registers the type \e T as a new type.
+  The latter allows a particular revision of a class to be registered in
+  a specified version (see \l {QML Type Versioning}).
+
+
+  For example, this registers a C++ class \c MySliderItem as a QML type
+  named \c Slider for version 1.0 of a \l{QML Modules}{module} called
+  "com.mycompany.qmlcomponents":
+
+  \code
+  #include <QtQml>
+
+  ...
+
+  qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");
+  \endcode
+
+  Once this is registered, the type can be used in QML by importing the
+  specified module name and version number:
+
+  \qml
+  import com.mycompany.qmlcomponents 1.0
+
+  Slider {
+      // ...
+  }
+  \endqml
+
+  Note that it's perfectly reasonable for a library to register types to older versions
+  than the actual version of the library. Indeed, it is normal for the new library to allow
+  QML written to previous versions to continue to work, even if more advanced versions of
+  some of its types are available.
+*/
+
+/*!
+  \fn int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
+  \relates QQmlEngine
+
+  This template function registers the specified revision of a C++ type in the QML system with
+  the library imported from \a uri having the version number composed
+  from \a versionMajor and \a versionMinor.
+
+  Returns the QML type id.
+
+  \code
+  template<typename T, int metaObjectRevision>
+  int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);
+  \endcode
+
+  This function is typically used to register the revision of a base class to
+  use for the specified module version (see \l {QML Type Versioning}).
+*/
+
+/*!
+  \fn int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
+  \relates QQmlEngine
+
+  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.
+
+  #include <QtQml> to use this function.
+
+  \sa qmlRegisterTypeNotAvailable()
+*/
+
+/*!
+  \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
+  \relates QQmlEngine
+
+  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.
+
+  #include <QtQml> to use this function.
+
+  \sa qmlRegisterUncreatableType()
+*/
+
+/*!
+  \fn int qmlRegisterType()
+  \relates QQmlEngine
+  \overload
+
+  This template function registers the C++ type in the QML
+  system. Instances of this type cannot be created from the QML
+  system.
+
+  #include <QtQml> to use this function.
+
+  Returns the QML type id.
+*/
+
+/*!
+  \fn int qmlRegisterInterface(const char *typeName)
+  \relates QQmlEngine
+
+  This template function registers the C++ type in the QML system
+  under the name \a typeName.
+
+  #include <QtQml> to use this function.
+
+  Returns the QML type id.
+*/
+
+/*!
+   \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QJSValue (*callback)(QQmlEngine *, QJSEngine *))
+   \relates QQmlEngine
+
+   This function may be used to register a module API provider \a callback in a particular \a uri
+   with a version specified in \a versionMajor and \a versionMinor.
+
+   Installing a module API into a uri allows developers to provide arbitrary functionality
+   (methods and properties) in a namespace that doesn't necessarily contain elements.
+
+   A module API may be either a QObject or a QJSValue.  Only one module API provider
+   may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor).
+   This function should be used to register a module API provider function which returns a QJSValue as a module API.
+
+   \b{NOTE:} QJSValue module API properties will \b{not} trigger binding re-evaluation if changed.
+
+   Usage:
+   \code
+   // first, define the module API provider function (callback).
+   static QJSValue *example_qjsvalue_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
+   {
+       Q_UNUSED(engine)
+
+       static int seedValue = 5;
+       QJSValue example = scriptEngine->newObject();
+       example.setProperty("someProperty", seedValue++);
+       return example;
+   }
+
+   // second, register the module API provider with QML by calling this function in an initialization function.
+   ...
+   qmlRegisterModuleApi("Qt.example.qjsvalueApi", 1, 0, example_qjsvalue_module_api_provider);
+   ...
+   \endcode
+
+   In order to use the registered module API in QML, you must import the module API.
+   \qml
+   import QtQuick 2.0
+   import Qt.example.qjsvalueApi 1.0 as ExampleApi
+   Item {
+       id: root
+       property int someValue: ExampleApi.someProperty
+   }
+   \endqml
+  */
+
+/*!
+   \fn template<typename T> int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *))
+   \relates QQmlEngine
+
+   This function may be used to register a module API provider \a callback in a particular \a uri
+   with a version specified in \a versionMajor and \a versionMinor.
+
+   Installing a module API into a uri allows developers to provide arbitrary functionality
+   (methods and properties) in a namespace that doesn't necessarily contain elements.
+
+   A module API may be either a QObject or a QJSValue.  Only one module API provider
+   may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor).
+   This function should be used to register a module API provider function which returns a QObject
+   of the given type T as a module API.
+
+   A QObject module API must be imported with a qualifier, and that qualifier may be used as
+   the target in a \l Connections element or otherwise used as any other element id would.
+   One exception to this is that a QObject module API property may not be aliased (because the
+   module API qualifier does not identify an object within the same component as any other item).
+
+   \b{NOTE:} A QObject module API instance returned from a module API provider is owned by the QML
+   engine.  For this reason, the module API provider function should \b{not} be implemented as a
+   singleton factory.
+
+   Usage:
+   \code
+   // first, define your QObject which provides the functionality.
+   class ModuleApiExample : public QObject
+   {
+       Q_OBJECT
+       Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)
+
+   public:
+       ModuleApiExample(QObject* parent = 0)
+           : QObject(parent), m_someProperty(0)
+       {
+       }
+
+       ~ModuleApiExample() {}
+
+       Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }
+
+       int someProperty() const { return m_someProperty; }
+       void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }
+
+   signals:
+       void somePropertyChanged(int newValue);
+
+   private:
+       int m_someProperty;
+   };
+
+   // second, define the module API provider function (callback).
+   static QObject *example_qobject_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
+   {
+       Q_UNUSED(engine)
+       Q_UNUSED(scriptEngine)
+
+       ModuleApiExample *example = new ModuleApiExample();
+       return example;
+   }
+
+   // third, register the module API provider with QML by calling this function in an initialization function.
+   ...
+   qmlRegisterModuleApi<ModuleApiExample>("Qt.example.qobjectApi", 1, 0, example_qobject_module_api_provider);
+   ...
+   \endcode
+
+   In order to use the registered module API in QML, you must import the module API.
+   \qml
+   import QtQuick 2.0
+   import Qt.example.qobjectApi 1.0 as ExampleApi
+   Item {
+       id: root
+       property int someValue: ExampleApi.someProperty
+
+       Component.onCompleted: {
+           someValue = ExampleApi.doSomething()
+       }
+   }
+   \endqml
+  */