Merge remote-tracking branch 'origin/5.15' into dev

Change-Id: Ia15cd13ed7014db80e02ba8b7e0588e3c53f832c

3 files changed, 316 insertions, 37 deletions

diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc
index 8e26c4aadd..9227f0e604 100644
--- a/src/qml/doc/src/javascript/imports.qdoc
+++ b/src/qml/doc/src/javascript/imports.qdoc
@@ -154,7 +154,7 @@ var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3
 \endcode
 
 In particular, this may be useful in order to access functionality provided
-via a singleton type; see qmlRegisterSingletonType() for more information.
+via a singleton type; see QML_SINGLETON for more information.
 
 \note The .import syntax doesn't work for scripts used in the \l {WorkerScript}
 */
diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc
index 67c0f6bb25..63c28d7aa7 100644
--- a/src/qml/doc/src/qmlfunctions.qdoc
+++ b/src/qml/doc/src/qmlfunctions.qdoc
@@ -26,6 +26,273 @@
 ****************************************************************************/
 
 /*!
+  \macro QML_ELEMENT
+  \related QQmlEngine
+
+  Declares the enclosing type or namespace to be available in QML, using its
+  class or namespace name as the QML element name.
+
+  For example, this makes the C++ class \c Slider available as a QML type
+  named \c Slider.
+
+  \code
+  class Slider : public QObject
+  {
+      Q_OBJECT
+      QML_ELEMENT
+      ...
+  }
+  \endcode
+
+  You can use the build system to register the type in the type namespace
+  "com.mycompany.qmlcomponents" with major version \c 1 by specifying the
+  following in your project file:
+
+  \code
+  CONFIG += qmltypes
+  QML_IMPORT_NAME = com.mycompany.qmlcomponents
+  QML_IMPORT_MAJOR_VERSION = 1
+  \endcode
+
+  Once registered, the type can be used in QML by importing the
+  same type namespace and version number:
+
+  \qml
+  import com.mycompany.qmlcomponents 1.0
+
+  Slider {
+      // ...
+  }
+  \endqml
+
+  You can also make namespaces tagged with Q_NAMESPACE available this way, in
+  order to expose any enums tagged with Q_ENUM_NS they contain.
+
+  \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_NAMED_ELEMENT(),
+      Q_REVISION(), QML_ADDED_IN_MINOR_VERSION()
+*/
+
+/*!
+  \macro QML_NAMED_ELEMENT(name)
+  \related QQmlEngine
+
+  Declares the enclosing type or namespace to be available in QML, using \a name
+  as the element name. Otherwise behaves the same as QML_ELEMENT.
+
+  \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_ELEMENT
+*/
+
+/*!
+  \macro QML_ANONYMOUS
+  \relates QQmlEngine
+
+  Declares the enclosing type to be available, but anonymous in QML. The type
+  cannot be created or used as property type, but when passed from C++, it is
+  recognized.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_INTERFACE
+*/
+
+/*!
+  \macro QML_INTERFACE
+  \relates QQmlEngine
+
+  This macro registers the enclosing C++ type in the QML system as an interface.
+
+  Types registered as an interface in QML should also declare themselves as an
+  interface with the \l {The Meta-Object System}{meta object system}. For
+  example:
+
+  \code
+  struct FooInterface
+  {
+      QML_INTERFACE
+  public:
+      virtual ~FooInterface();
+      virtual void doSomething() = 0;
+  };
+
+  Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")
+  \endcode
+
+  When registered with QML in this way, they can be used as property types:
+
+  Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)
+
+  When you assign a \l QObject sub-class to this property, the QML engine does
+  the interface cast to \c FooInterface* automatically.
+
+  Interface types are implicitly anonymous and uncreatable in QML.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_ANONYMOUS
+*/
+
+/*!
+  \macro QML_UNCREATABLE(reason)
+  \relates QQmlEngine
+
+  Declares that the enclosing type shall not be creatable from QML. This takes
+  effect if the type is available in QML, by having a \l QML_ELEMENT or
+  \l QML_NAMED_ELEMENT() macro. The \a reason will be emitted as error message if an
+  attempt to create the type from QML is detected.
+
+  Some QML types are implicitly uncreatable, in particular types exposed with
+  \l QML_ANONYMOUS or namespaces exposed with \l QML_ELEMENT or
+  \l QML_NAMED_ELEMENT(). For such types, \l QML_UNCREATABLE() can be used to
+  provide a custom error message.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS
+*/
+
+/*!
+  \macro QML_SINGLETON
+  \relates QQmlEngine
+
+  Declares the enclosing type to be a singleton in QML. This only takes effect
+  if the type is available in QML, by having a \l QML_ELEMENT or
+  \l QML_NAMED_ELEMENT() macro. By default, each QQmlEngine will try to create a
+  singleton instance using the type's default constructor when the type is first
+  accessed. If there is no default constructor the singleton is initially
+  inaccessible. This behavior can be overridden by calling
+  \l qmlRegisterSingletonType() with a specific factory function or
+  \l qmlRegisterSingletonInstance() with a specific instance for the same class
+  and the same type namespace and version.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), qmlRegisterSingletonInstance().
+*/
+
+/*!
+  \macro QML_ADDED_IN_MINOR_VERSION(VERSION)
+  \relates QQmlEngine
+
+  Declares that the enclosing type or namespace was added in the specified minor
+  \a VERSION, relative to the module major version. The minor version is assumed
+  to be in line with any revisions given by \l Q_REVISION() macros on methods,
+  slots, or signals, and any REVISION tags on properties declared with
+  \l Q_PROPERTY().
+
+  \l QML_ADDED_IN_MINOR_VERSION() only takes effect if the type or namespace is
+  available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(),
+  \l QML_ANONYMOUS, or \l QML_INTERFACE macro.
+
+  If the QML module the type belongs to is imported with a lower version than
+  the one determined this way, the QML type is invisible.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT()
+*/
+
+/*!
+  \macro QML_REMOVED_IN_MINOR_VERSION(VERSION)
+  \relates QQmlEngine
+
+  Declares that the enclosing type or namespace was removed in the specified
+  minor \a VERSION, relative to the module major version. This is primarily
+  useful when replacing the implementation of a QML type. If a corresponding
+  \l QML_ADDED_IN_MINOR_VERSION() is present on a different type or namespace of
+  the same QML name, then the removed type is used when importing versions of
+  the module lower than \a VERSION, and the added type is used when importing
+  versions of the module greater or equal \a VERSION.
+
+  \l QML_REMOVED_IN_MINOR_VERSION() only takes effect if type or namespace is
+  available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(),
+  \l QML_ANONYMOUS, or \l QML_INTERFACE macro.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT()
+*/
+
+/*!
+  \macro QML_ATTACHED(ATTACHED_TYPE)
+  \relates QQmlEngine
+
+  Declares that the enclosing type attaches \a ATTACHED_TYPE as an
+  \l {Attached Properties and Attached Signal Handlers}
+  {attached property} to other types. This takes effect if the type
+  is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAtachedPropertiesObject(),
+      {Providing Attached Properties}
+*/
+
+/*!
+  \macro QML_EXTENDED(EXTENDED_TYPE)
+  \relates QQmlEngine
+
+  Declares that the enclosing type uses \a EXTENDED_TYPE as an extension to
+  provide further properties and methods in QML. This takes effect if the type
+  is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), {Registering Extension Objects}
+*/
+
+/*!
+  \macro QML_FOREIGN(FOREIGN_TYPE)
+  \relates QQmlEngine
+
+  Declares that any \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), \l QML_ANONYMOUS,
+  \l QML_INTERFACE, \l QML_UNCREATABLE(), \l QML_SINGLETON,
+  \l QML_ADDED_IN_MINOR_VERSION(), \l QML_REMOVED_IN_MINOR_VERSION(),
+  \l QML_ATTACHED(), or \l QML_EXTENDED() macros in the enclosing C++ type do
+  not apply to the enclosing type but instead to \a FOREIGN_TYPE. The enclosing
+  type still needs to be registered with the
+  \l {The Meta-Object System}{meta object system} using a \l G_GADGET or
+  \l Q_OBJECT macro.
+
+  This is useful for registering types that cannot be amended to add the macros,
+  for example because they belong to 3rdparty libraries.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT()
+*/
+
+/*!
+  \macro QML_UNAVAILABLE
+  \relates QQmlEngine
+
+  This macro declares the enclosing type to be unavailable in QML. It registers
+  an internal dummy type called \c QQmlTypeNotAvailable as \l QML_FOREIGN()
+  type, using any further QML macros you specify.
+
+  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 the unavailable type a meaningful error message.
+
+  Example:
+
+  \code
+  #ifdef NO_GAMES_ALLOWED
+  struct MinehuntGame
+  {
+      Q_GADGET
+      QML_NAMED_ELEMENT(Game)
+      QML_UNAVAILABLE
+      QML_UNCREATABLE("Get back to work, slacker!");
+  };
+  #else
+  class MinehuntGame : public QObject
+  {
+      Q_OBJECT
+      QML_NAMED_ELEMENT(Game)
+      // ...
+  };
+  #endif
+  \endcode
+
+  This will cause any QML which attempts to use the "Game" type to produce an
+  error message:
+  \code
+  fun.qml: Get back to work, slacker!
+     Game {
+     ^
+  \endcode
+
+  Using this technique, you only need a \l G_GADGET struct to customize the error
+  message, not a full-blown \l QObject. Without \l QML_UNCREATABLE(),
+  \l QML_UNAVAILABLE still results in a more specific error message than the usual
+  "is not a type" for completely unknown types.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_FOREIGN()
+*/
+
+/*!
   \macro QML_DECLARE_TYPE()
   \relates QQmlEngine
 
@@ -41,7 +308,8 @@
 
   Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which
   declares that the \a Type supports \l {Attached Properties and Attached Signal Handlers}
-  {attached properties}.
+  {attached properties}. QML_DECLARE_TYPEINFO() is not necessary if \a Type contains the
+  QML_ATTACHED macro.
 */
 
 /*!
@@ -106,7 +374,8 @@
   QML written to previous versions to continue to work, even if more advanced versions of
   some of its types are available.
 
-  \sa {Choosing the Correct Integration Method Between C++ and QML}
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT(),
+      {Choosing the Correct Integration Method Between C++ and QML}
 */
 
 /*!
@@ -143,7 +412,7 @@
 
   Returns the QML type id.
 
-  \sa qmlRegisterTypeNotAvailable(),
+  \sa QML_UNCREATABLE(), qmlRegisterTypeNotAvailable(),
       {Choosing the Correct Integration Method Between C++ and QML}
 */
 
@@ -158,7 +427,7 @@
 
   Returns the QML type id.
 
-  \sa qmlRegisterType(), {Registering Extension Objects}
+  \sa QML_EXTENDED(), qmlRegisterType(), {Registering Extension Objects}
 */
 
 
@@ -180,7 +449,7 @@
 
   Returns the QML type id.
 
-  \sa qmlRegisterUncreatableType()
+  \sa QML_EXTENDED(), QML_UNCREATABLE(), qmlRegisterUncreatableType()
 */
 
 /*!
@@ -220,6 +489,8 @@
   \code
   Component.onCompleted: console.log(MyNamespace.Key2)
   \endcode
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE()
 */
 
 /*!
@@ -235,6 +506,8 @@
   the \a parser provided.
 
   Returns the QML type id.
+
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED()
 */
 
 /*!
@@ -269,7 +542,7 @@
 
   Without this, a generic "Game is not a type" message would be given.
 
-  \sa qmlRegisterUncreatableType(),
+  \sa QML_UNAVAILABLE, qmlRegisterUncreatableType(),
       {Choosing the Correct Integration Method Between C++ and QML}
 */
 
@@ -353,7 +626,7 @@
   Returns the QML type id.
 
   \since 5.14
-  \sa {Choosing the Correct Integration Method Between C++ and QML}
+  \sa QML_ANONYMOUS, {Choosing the Correct Integration Method Between C++ and QML}
 */
 
 /*!
@@ -397,6 +670,8 @@
     the interface cast to \c FooInterface* automatically.
 
     Returns the QML type id.
+
+    \sa QML_INTERFACE
 */
 
 /*!
@@ -455,7 +730,7 @@
    }
    \endqml
 
-   \sa {Choosing the Correct Integration Method Between C++ and QML}
+   \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML}
 */
 
 /*!
@@ -477,8 +752,7 @@
     Returns 0 if type \e T is not a valid attaching type, or if \a create is false and no
     attachment object instance has previously been created for \a attachee.
 
-    \sa {Providing Attached Properties}
-
+    \sa QML_ATTACHED(), {Providing Attached Properties}
 */
 
 /*!
@@ -571,7 +845,7 @@
    }
    \endqml
 
-   \sa {Choosing the Correct Integration Method Between C++ and QML}
+   \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML}
 */
 
 
@@ -626,6 +900,8 @@
    That can be done by adding a pragma Singleton statement among the imports of the type's QML file. In addition
    the type must be defined in a qmldir file with a singleton keyword and the qmldir must be imported by the QML
    files using the singleton.
+
+   \sa QML_SINGLETON
 */
 
 /*!
@@ -718,7 +994,7 @@
     }
     \endqml
 
-   \sa qmlRegisterSingletonType
+   \sa QML_SINGLETON, qmlRegisterSingletonType
  */
 
 /*!
@@ -792,5 +1068,5 @@
   Returns -1 if no matching type was found or one of the given parameters
   was invalid.
 
-  \sa qmlRegisterType(), qmlRegisterSingletonType()
+  \sa QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON, qmlRegisterType(), qmlRegisterSingletonType()
 */
diff --git a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc
index 05447db627..496245820a 100644
--- a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc
+++ b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc
@@ -1,19 +1,22 @@
-QQmlExtensionPlugin is a plugin interface that makes it possible to
+\l QQmlEngineExtensionPlugin is a plugin interface that makes it possible to
 create QML extensions that can be loaded dynamically into QML applications.
 These extensions allow custom QML types to be made available to the
 QML engine.
 
 To write a QML extension plugin:
 \list 1
-\li Subclass QQmlExtensionPlugin
+\li Subclass \l QQmlEngineExtensionPlugin and use the Q_PLUGIN_METADATA() macro
+    to register the plugin with the Qt meta object system.
+\li Use the \l QML_ELEMENT and \l QML_NAMED_ELEMENT() macros to declare
+    QML types.
+\li Write a project file for the plugin. Add:
     \list
-        \li Use the Q_PLUGIN_METADATA() macro to register the plugin with
-            the Qt meta object system
-        \li Override the \l{QQmlExtensionPlugin::}{registerTypes()} method
-            and call qmlRegisterType() to register the types to be exported
-            by the plugin
+        \li \c {CONFIG += qmltypes} to instruct the build system to generate
+            QML types.
+        \li \c {QML_IMPORT_NAME = <my.import.name>} to specify the import name.
+        \li \c {QML_IMPORT_MAJOR_VERSION = <version>} to specify the import
+            major version.
     \endlist
-\li Write a project file for the plugin
 \li Create a \l{Module Definition qmldir Files}{qmldir file} to
     describe the plugin
 \endlist
@@ -27,26 +30,18 @@ issues in the library user's code.
 
 Suppose there is a new \c TimeModel C++ class that should be made available
 as a new QML type. It provides the current time through \c hour and \c minute
-properties.
+properties. It declares a QML type called \c Time via \l QML_NAMED_ELEMENT().
 
 \snippet qmlextensionplugins/timemodel.h 0
 \dots
 
 To make this type available, we create a plugin class named \c QExampleQmlPlugin
-which is a subclass of \l QQmlExtensionPlugin. It overrides the
-\l{QQmlExtensionPlugin::}{registerTypes()} method in order to register the \c TimeModel
-type using qmlRegisterType(). It also uses the Q_PLUGIN_METADATA() macro in the class
-definition to register the plugin with the Qt meta object system using a unique
-identifier for the plugin.
+which is a subclass of \l QQmlEngineExtensionPlugin. It uses the
+Q_PLUGIN_METADATA() macro in the class definition to register the plugin with the
+Qt meta object system using a unique identifier for the plugin.
 
 \snippet qmlextensionplugins/plugin.cpp plugin
 
-This registers the \c TimeModel class with version \c{1.0} of this plugin library, as
-a QML type called \c Time. The Q_ASSERT() macro can ensure the type namespace is
-imported correctly by any QML components that use this plugin. The
-\l{Defining QML Types from C++} article has more information about registering C++
-types into the runtime.
-
 \section1 Project settings for the plugin
 
 Additionally, the project file (\c .pro) defines the project as a plugin library,
@@ -55,14 +50,22 @@ the plugin target name and various other details:
 
 \code
 TEMPLATE = lib
-CONFIG += qt plugin
+CONFIG += qt plugin qmltypes
 QT += qml
 
-DESTDIR = imports/TimeExample
-TARGET = qmlqtimeexampleplugin
+QML_IMPORT_NAME = TimeExample
+QML_IMPORT_MAJOR_VERSION = 1
+
+DESTDIR = imports/$$QML_IMPORT_NAME
+TARGET  = qmlqtimeexampleplugin
+
 SOURCES += qexampleqmlplugin.cpp
 \endcode
 
+This registers the \c TimeModel class with the import \c{TimeExample 1.0}, as
+a QML type called \c Time. The \l{Defining QML Types from C++} article has more
+information about registering C++ types for usage in QML.
+
 \section1 Plugin definition in the qmldir
 
 Finally, a \l{Module Definition qmldir Files}{qmldir file} is required