Add type name to singleton (module api) implementations.

This change renames the previous module api implementation
to singleton types.

When a singleton type is registered, a type name must be provided
that is used when accessing the API from QML. This makes the
implementation more consistent with the rest of QML.

Task-number: QTBUG-26549
Change-Id: Iab0bb1ccf516bd3ae20aee562a64d22976e0aecd
Reviewed-by: Chris Adams <christopher.adams@nokia.com>

8 files changed, 75 insertions, 76 deletions

diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc
index 3ecd1de442..fd03cfc758 100644
--- a/src/qml/doc/src/cppintegration/definetypes.qdoc
+++ b/src/qml/doc/src/cppintegration/definetypes.qdoc
@@ -146,7 +146,7 @@ type name.
 instantiable but should be identifiable as a type to the QML type system. This
 is useful if a type's enums or attached properties should be accessible from QML
 but the type itself should not be instantiable.
-\li qmlRegisterModuleApi() registers a singleton instance that can be imported
+\li qmlRegisterSingletonType() registers a singleton type that can be imported
 from QML, as discussed below.
 \endlist
 
@@ -154,29 +154,30 @@ Note that all C++ types registered with the QML type system must be
 QObject-derived, even if they are non-instantiable.
 
 
-\section3 Registering Singleton Objects with a Module API
+\section3 Registering Singleton Objects with a Singleton Type
 
-A Module API enables properties, signals and methods to be exposed in
+A singleton type enables properties, signals and methods to be exposed in
 a namespace without requiring the client to manually instantiate an
-object instance. QObject module APIs in particular are an efficient and
+object instance. QObject singleton types in particular are an efficient and
 convenient way to provide functionality or global property values.
 
-Note that module APIs do not have an associated QQmlContext as they are
-shared across all contexts in an engine.  QObject module API instances
+Note that singleton types do not have an associated QQmlContext as they are
+shared across all contexts in an engine.  QObject singleton type instances
 are constructed and owned by the QQmlEngine, and will be destroyed when
 the engine is destroyed.
 
-A QObject module API can be interacted with in a manner simlar to any
-other QObject or instantiated element.  That is, Q_PROPERTYs of QObject
-module APIs may be bound to, and Q_INVOKABLE functions of QObject module
-APIs may be used in signal handler expressions.  This makes module APIs
-an ideal way to implement styling or theming, and they can also be used
-instead of ".pragma library" script imports to store global state or to
-provide global functionality.
+A QObject singleton type can be interacted with in a manner simlar to any
+other QObject or instantiated element, except that only one (engine constructed
+and owned) instance will exist, and it must be referenced by type name rather
+than id.  Q_PROPERTYs of QObject singleton types may be bound to, and Q_INVOKABLE
+functions of QObject module APIs may be used in signal handler expressions.
+This makes singleton types an ideal way to implement styling or theming, and
+they can also be used instead of ".pragma library" script imports to store global
+state or to provide global functionality.
 
-Once registered, a QObject module API may be imported and used like any
+Once registered, a QObject singleton type may be imported and used like any
 other QObject instance exposed to QML.  The following example assumes that
-a QObject module API was registered into the "MyThemeModule" namespace
+a QObject singleton type was registered into the "MyThemeModule" namespace
 with version 1.0, where that QObject has a QColor "color" Q_PROPERTY:
 
 \qml
@@ -187,11 +188,11 @@ Rectangle {
 }
 \endqml
 
-A QJSValue may also be exposed as a module API, however clients should
-be aware that properties of such a module API cannot be bound to.
+A QJSValue may also be exposed as a singleton type, however clients should
+be aware that properties of such a singleton type cannot be bound to.
 
-See \l{qmlRegisterModuleApi()} for more information on how implement and
-register a new module API, and how to use an existing module API.
+See \l{qmlRegisterSingletonType()} for more information on how implement and
+register a new singleton type, and how to use an existing singleton type.
 
 
 \section2 Type Revisions and Versions
diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc
index 49b1aa0e0c..fc7c626502 100644
--- a/src/qml/doc/src/cppintegration/topic.qdoc
+++ b/src/qml/doc/src/cppintegration/topic.qdoc
@@ -61,8 +61,8 @@ required functionality is provided by such a class, it can be exposed to QML in
 registered as an instantiable QML type}, so that it can be instantiated and used like any ordinary
 \l{qtqml-typesystem-objecttypes.html}{QML object type} from QML code
 \li The class can be registered as a
-\l{qtqml-cppintegration-definetypes.html#registering-singleton-objects-with-a-module-api}
-{Module API} so that a single instance of the class may be imported from QML code, allowing the
+\l{qtqml-cppintegration-definetypes.html#registering-singleton-objects-with-a-singleton-type}
+{Singleton Type} so that a single instance of the class may be imported from QML code, allowing the
 instance's properties, methods and signals to be accessed from QML
 \li An instance of the class can be \l{qtqml-cppintegration-contextproperties.html}{embedded into
 QML code} as a \e {context property} or \e {context object}, allowing the instance's properties,
@@ -100,7 +100,7 @@ more information.
 QML types can be defined in C++ and then registered with the \l{qtqml-typesystem-topic.html}{QML
 type system}. This allows a C++ class to be instantiated as a \l {QML object type}, enabling custom
 object types to be implemented in C++ and integrated into existing QML code. A C++ class may be also
-registered for other purposes: for example, it could be registered as a \e {Module API} to enable a
+registered for other purposes: for example, it could be registered as a \e {Singleton Type} to enable a
 single class instance to be imported by QML code, or it could be registered to enable the
 enumeration values of a non-instantiable class to be accessible from QML.
 
diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc
index df8141dec5..08acccbe21 100644
--- a/src/qml/doc/src/javascript/imports.qdoc
+++ b/src/qml/doc/src/javascript/imports.qdoc
@@ -74,7 +74,7 @@ For example:
 \endcode
 
 In particular, this may be useful in order to access functionality provided
-via a module API; see qmlRegisterModuleApi() for more information.
+via a singleton type; see qmlRegisterSingletonType() for more information.
 
 Due to the ability of a JavaScript file to import another script or QML module
 in this fashion in QtQuick 2.0, some extra semantics are defined:
diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc
index 0e23db3bf4..790ef5d371 100644
--- a/src/qml/doc/src/qmlfunctions.qdoc
+++ b/src/qml/doc/src/qmlfunctions.qdoc
@@ -205,25 +205,25 @@
 */
 
 /*!
-   \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QJSValue (*callback)(QQmlEngine *, QJSEngine *))
+   \fn int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, 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.
+   This function may be used to register a singleton type provider \a callback in a particular \a uri
+   and \a typeName 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.
+   Installing a singleton type allows developers to provide arbitrary functionality
+   (methods and properties) to a client without requiring individual instances of the type to
+   be instantiated by the client.
 
-   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.
+   A singleton type may be either a QObject or a QJSValue.
+   This function should be used to register a singleton type provider function which returns a QJSValue as a singleton type.
 
-   \b{NOTE:} QJSValue module API properties will \b{not} trigger binding re-evaluation if changed.
+   \b{NOTE:} QJSValue singleton type 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)
+   // first, define the singleton type provider function (callback).
+   static QJSValue *example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
    {
        Q_UNUSED(engine)
 
@@ -233,19 +233,19 @@
        return example;
    }
 
-   // second, register the module API provider with QML by calling this function in an initialization function.
+   // second, register the singleton type provider with QML by calling this function in an initialization function.
    ...
-   qmlRegisterModuleApi("Qt.example.qjsvalueApi", 1, 0, example_qjsvalue_module_api_provider);
+   qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);
    ...
    \endcode
 
-   In order to use the registered module API in QML, you must import the module API.
+   In order to use the registered singleton type in QML, you must import the singleton type.
    \qml
    import QtQuick 2.0
    import Qt.example.qjsvalueApi 1.0 as ExampleApi
    Item {
        id: root
-       property int someValue: ExampleApi.someProperty
+       property int someValue: ExampleApi.MyApi.someProperty
    }
    \endqml
   */
@@ -274,44 +274,44 @@
 */
 
 /*!
-   \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *))
+   \fn int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, 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.
+   This function may be used to register a singleton type provider \a callback in a particular \a uri
+   and \a typeName 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.
+   Installing a singleton type into a uri allows developers to provide arbitrary functionality
+   (methods and properties) to clients without requiring individual instances ot the type to be
+   instantiated by the client.
 
-   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 singleton type may be either a QObject or a QJSValue.
+   This function should be used to register a singleton type provider function which returns a QObject
+   of the given type T as a singleton type.
 
-   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).
+   A QObject singleton type may be referenced via the type name with which it was registered, and this
+   typename 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 singleton type property may not be aliased (because the
+   singleton type name 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
+   \b{NOTE:} A QObject singleton type instance returned from a singleton type provider is owned by the QML
+   engine.  For this reason, the singleton type 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
+   class SingletonTypeExample : public QObject
    {
        Q_OBJECT
        Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)
 
    public:
-       ModuleApiExample(QObject* parent = 0)
+       SingletonTypeExample(QObject* parent = 0)
            : QObject(parent), m_someProperty(0)
        {
        }
 
-       ~ModuleApiExample() {}
+       ~SingletonTypeExample() {}
 
        Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }
 
@@ -325,45 +325,45 @@
        int m_someProperty;
    };
 
-   // second, define the module API provider function (callback).
-   static QObject *example_qobject_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
+   // second, define the singleton type provider function (callback).
+   static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
    {
        Q_UNUSED(engine)
        Q_UNUSED(scriptEngine)
 
-       ModuleApiExample *example = new ModuleApiExample();
+       SingletonTypeExample *example = new SingletonTypeExample();
        return example;
    }
 
-   // third, register the module API provider with QML by calling this function in an initialization function.
+   // third, register the singleton type provider with QML by calling this function in an initialization function.
    ...
-   qmlRegisterModuleApi<ModuleApiExample>("Qt.example.qobjectApi", 1, 0, example_qobject_module_api_provider);
+   qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);
    ...
    \endcode
 
-   In order to use the registered module API in QML, you must import the module API.
+   In order to use the registered singleton type in QML, you must import the singleton type.
    \qml
    import QtQuick 2.0
-   import Qt.example.qobjectApi 1.0 as ExampleApi
+   import Qt.example.qobjectSingleton 1.0
    Item {
        id: root
-       property int someValue: ExampleApi.someProperty
+       property int someValue: MyApi.someProperty
 
        Component.onCompleted: {
-           someValue = ExampleApi.doSomething()
+           someValue = MyApi.doSomething()
        }
    }
    \endqml
 
-   Since Module APIs do not have an associated QQmlContext object, then within the functions of a QObject-derived
-   type that is registered as a module API implementation the QML context and engine information is not available.
+   Since singleton types do not have an associated QQmlContext object, then within the functions of a QObject-derived
+   type that is registered as a singleton type implementation the QML context and engine information is not available.
    The QQmlEngine::contextForObject() function returns NULL when supplied with a pointer to an QObject that
-   implements a module API.
+   implements a singleton type.
 
    Extending the above example:
 
    \code
-   class ModuleApiExample : public QObject
+   class SingletonTypeExample : public QObject
    {
        ...
 
diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc
index 5ec2982cad..715b866b47 100644
--- a/src/qml/doc/src/qtqml.qdoc
+++ b/src/qml/doc/src/qtqml.qdoc
@@ -175,7 +175,7 @@ types, animation classes, and canvas integration) for the QML language.
 
 More information about the Qt QML module is contained within the class and
 function documentation of the \l{QtQml}
-{Qt QML Module API Reference}.  The QML types provided by the Qt QML module
+{Qt QML Singleton Type Reference}.  The QML types provided by the Qt QML module
 are listed in the \l{qtqml-typereference-topic.html}
 {Qt QML Module QML Type Reference} page.
 
diff --git a/src/qml/doc/src/syntax/basics.qdoc b/src/qml/doc/src/syntax/basics.qdoc
index 786d208653..4c3e475f36 100644
--- a/src/qml/doc/src/syntax/basics.qdoc
+++ b/src/qml/doc/src/syntax/basics.qdoc
@@ -43,18 +43,16 @@ An import can be any one of:
 
 \list
 \li a versioned namespace into which types have been registered (e.g., by a plugin)
-\li a versioned namespace which provides a module API
 \li a relative directory which contains type-definitions as QML documents
 \li a JavaScript file
 \endlist
 
-Module API imports and JavaScript file imports must be qualified when
-imported, so that the properties and methods they provide can be accessed.
+JavaScript file imports must be qualified when imported, so that the properties and methods they provide can be accessed.
 
 The generic form of the various imports are as follows:
 \list
 \li \tt{import Namespace VersionMajor.VersionMinor}
-\li \tt{import Namespace VersionMajor.VersionMinor as ModuleApiIdentifier}
+\li \tt{import Namespace VersionMajor.VersionMinor as SingletonTypeIdentifier}
 \li \tt{import "directory"}
 \li \tt{import "file.js" as ScriptIdentifier}
 \endlist
diff --git a/src/qml/doc/src/typesystem/objecttypes.qdoc b/src/qml/doc/src/typesystem/objecttypes.qdoc
index a73d723f26..faa76b4ce7 100644
--- a/src/qml/doc/src/typesystem/objecttypes.qdoc
+++ b/src/qml/doc/src/typesystem/objecttypes.qdoc
@@ -126,7 +126,7 @@ functions which each allow different use-cases to be fulfilled.
 \li qmlRegisterExtendedType
 \li qmlRegisterInterface
 \li qmlRegisterCustomType
-\li qmlRegisterModuleApi
+\li qmlRegisterSingletonType
 \endlist
 
 For more information on this topic, see the documentation regarding
diff --git a/src/qml/doc/src/whatsnew.qdoc b/src/qml/doc/src/whatsnew.qdoc
index cf8f396024..b9961571b3 100644
--- a/src/qml/doc/src/whatsnew.qdoc
+++ b/src/qml/doc/src/whatsnew.qdoc
@@ -87,7 +87,7 @@ has now been replaced by the new QtQml and QtQuick C++ modules. See the
 \section2 Modules and Imports
 
 \list
-\li Arbitrary functionality may be provided in a namespace through a Module API.  See qmlRegisterModuleApi() for more information.
+\li Arbitrary functionality may be provided in a namespace through a singleton type.  See qmlRegisterSingletonType() for more information.
 \li JavaScript (.js) files may now import QML modules and other JavaScript files using the ".import" syntax.
 \endlist