Update Qt Designer documentation.

- Document new QUiPlugin module.
- Fix example documentation to reflect the changes in
  the qmake variables (QT/CONFIG).

Task-number: QTBUG-44724
Change-Id: Idd85d601295af25d634c3186e993abc7090fe002
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@theqtcompany.com>

5 files changed, 74 insertions, 105 deletions

diff --git a/examples/designer/doc/src/containerextension.qdoc b/examples/designer/doc/src/containerextension.qdoc
index 4329d90a5..f82e1c042 100644
--- a/examples/designer/doc/src/containerextension.qdoc
+++ b/examples/designer/doc/src/containerextension.qdoc
@@ -107,24 +107,12 @@
     recognized as a plugin by Qt by using the Q_PLUGIN_METADATA() macro
     to export the relevant widget information.
 
-    The \c CONFIG variable contains two values, \c designer and \c
-    plugin:
+    The \c CONFIG variable is set to \c plugin, which ensures that \c qmake
+    considers the custom widget a plugin library.
 
-    \list
-        \li \c designer: Since custom widgets plugins rely on components
-           supplied with \QD, this value ensures that our plugin links against
-           \QD's library (\c libQtDesigner.so).
-
-        \li \c plugin: We also need to ensure that \c qmake considers the
-           custom widget a \e plugin library.
-    \endlist
-
-    When Qt is configured to build in both debug and release modes,
-    \QD will be built in release mode.  When this occurs, it is
-    necessary to ensure that plugins are also built in release
-    mode. For that reason we add a \c debug_and_release value to the
-    \c CONFIG variable. Otherwise, if a plugin is built in a mode that
-    is incompatible with \QD, it won't be loaded and installed.
+    The \c QT variable contains the value \c designer. Since the plugin uses
+    components supplied with \QD that require linkage, this value ensures
+    that our plugin links against \QD's library (\c libQtDesigner.so).
 
     The header and source files for the widget are declared in the
     usual way:
diff --git a/examples/designer/doc/src/customwidgetplugin.qdoc b/examples/designer/doc/src/customwidgetplugin.qdoc
index 84da3c495..2c3c9c6df 100644
--- a/examples/designer/doc/src/customwidgetplugin.qdoc
+++ b/examples/designer/doc/src/customwidgetplugin.qdoc
@@ -57,27 +57,18 @@
     recognized as a plugin by Qt by using the Q_PLUGIN_METADATA() macro
     to export the relevant widget information.
 
-    The \c CONFIG variable contains two values, \c designer and \c
-    plugin:
 
-    \list
-
-    \li \c designer: Since custom widgets plugins rely on components
-    supplied with \QD, this value ensures that our plugin links
-    against \QD's library (\c libQtDesigner.so).
-
-    \li \c plugin: We also need to ensure that \c qmake considers the
-    custom widget a plugin library.
-
-    \endlist
-
-    When Qt is configured to build in both debug and release modes,
-    \QD will be built in release mode. When this occurs, it is
-    necessary to ensure that plugins are also built in release
-    mode. For that reason we add the \c debug_and_release value to the
-    \c CONFIG variable. Otherwise, if a plugin is built in a mode that
-    is incompatible with \QD, it won't be loaded and
-    installed.
+    The \c CONFIG variable is set to \c plugin, which ensures that \c qmake
+    considers the custom widget a plugin library.
+
+    The \c QT variable contains the keyword \c uiplugin. This plugin type
+    provides a factory function for custom widget creation by implementing
+    the abstract interfaces QDesignerCustomWidgetInterface or
+    QDesignerCustomWidgetCollectionInterface, suitable for use with
+    QUiLoader. It does not have a dependency on the \QD libraries.
+    Plugins accessing other interfaces of \QD to implement container extensions
+    or other \QD specific functionality follow different rules and are covered
+    by other examples.
 
     The header and source files for the widget are declared in the usual way,
     and we provide an implementation of the plugin interface so that \QD can
diff --git a/examples/designer/doc/src/taskmenuextension.qdoc b/examples/designer/doc/src/taskmenuextension.qdoc
index 541e2a3ed..5f223f353 100644
--- a/examples/designer/doc/src/taskmenuextension.qdoc
+++ b/examples/designer/doc/src/taskmenuextension.qdoc
@@ -108,25 +108,12 @@
     recognized as a plugin by Qt by using the Q_PLUGIN_METADATA() macro to
     export the relevant widget information.
 
-    The \c CONFIG variable contains two values, \c designer and \c
-    plugin:
+    The \c CONFIG variable is set to \c plugin, which ensures that \c qmake
+    considers the custom widget a plugin library.
 
-    \list
-        \li \c designer: Since custom widgets plugins rely on components
-           supplied with \QD, this value ensures that our plugin links against
-           \QD's library (\c libQtDesigner.so).
-
-        \li \c plugin: We also need to ensure that \c qmake considers the
-           custom widget a \e plugin library.
-    \endlist
-
-    When Qt is configured to build in both debug and release modes,
-    \QD will be built in release mode.  When this occurs, it is
-    necessary to ensure that plugins are also built in release
-    mode. For that reason we add the \c debug_and_release value to
-    the \c CONFIG variable. Otherwise, if a plugin is built in a mode
-    that is incompatible with \QD, it won't be loaded and
-    installed.
+    The \c QT variable contains the value \c designer. Since the plugin uses
+    components supplied with \QD that require linkage, this value ensures
+    that our plugin links against \QD's library (\c libQtDesigner.so).
 
     The header and source files for the widget are declared in the
     usual way:
diff --git a/examples/designer/doc/src/worldtimeclockplugin.qdoc b/examples/designer/doc/src/worldtimeclockplugin.qdoc
index bc45a751a..917ab8bda 100644
--- a/examples/designer/doc/src/worldtimeclockplugin.qdoc
+++ b/examples/designer/doc/src/worldtimeclockplugin.qdoc
@@ -145,26 +145,18 @@
     \snippet worldtimeclockplugin/worldtimeclockplugin.pro 0
     \snippet worldtimeclockplugin/worldtimeclockplugin.pro 1
 
-    The \c TEMPLATE variable's value make \c qmake create the custom
-    widget as a library. The \c CONFIG variable contains two values,
-    \c designer and \c plugin:
-
-    \list
-        \li \c designer: Since custom widgets plugins rely on components
-           supplied with \QD, this value ensures that our plugin links against
-           \QD's library (\c libQtDesigner.so).
-
-        \li \c plugin: We also need to ensure that \c qmake considers the
-           custom widget a \e plugin library.
-    \endlist
-
-    When Qt is configured to build in both debug and release modes,
-    \QD will be built in release mode.  When this occurs, it is
-    necessary to ensure that plugins are also built in release
-    mode. For that reason you might have to add a \c release value to
-    your \c CONFIG variable. Otherwise, if a plugin is built in a mode
-    that is incompatible with \QD, it won't be loaded and
-    installed.
+    The \c TEMPLATE variable's value in conjunction with the keyword
+    \c plugin in the \c CONFIG variable make \c qmake create the custom
+    widget as a plugin library.
+
+    The \c QT variable contains the keyword \c uiplugin. This plugin type
+    provides a factory function for custom widget creation by implementing
+    the abstract interfaces QDesignerCustomWidgetInterface or
+    QDesignerCustomWidgetCollectionInterface, suitable for use with
+    QUiLoader. It does not have a dependency on the \QD libraries.
+    Plugins accessing other interfaces of \QD to implement container extensions
+    or other \QD specific functionality follow different rules and are covered
+    by other examples.
 
     The header and source files for the widget are declared in the
     usual way, and in addition we provide an implementation of the
diff --git a/src/designer/src/designer/doc/src/designer-manual.qdoc b/src/designer/src/designer/doc/src/designer-manual.qdoc
index e13e5d106..665456468 100644
--- a/src/designer/src/designer/doc/src/designer-manual.qdoc
+++ b/src/designer/src/designer/doc/src/designer-manual.qdoc
@@ -2534,14 +2534,16 @@ pixmap property in the property editor.
     with specific plugin support for \QD. This is done with the following
     declarations:
 
-    \snippet customwidgetplugin/customwidgetplugin.pro 3
+    \snippet customwidgetplugin/customwidgetplugin.pro 0
+    \snippet customwidgetplugin/customwidgetplugin.pro 2
 
-    If Qt is configured to build in both debug and release modes, \QD will be
-    built in release mode. When this occurs, it is necessary to ensure that
-    plugins are also built in release mode. To do this, include the following
-    declaration in the plugin's \c{.pro} file:
-
-    \snippet manual/doc_src_designer-manual.pro 3
+    The \c QT variable contains the keyword \c uiplugin. It indicates that
+    the plugin uses the abstract interfaces QDesignerCustomWidgetInterface
+    and QDesignerCustomWidgetCollectionInterface only and has no linkage
+    to the \QD libraries. When accessing other interfaces of \QD that have
+    linkage, \c designer should be used instead; this ensures that the plugin
+    dynamically links to the \QD libraries and has a run-time dependency on
+    them.
 
     If plugins are built in a mode that is incompatible with \QD, they will
     not be loaded and installed. For more information about plugins, see the
@@ -2568,36 +2570,45 @@ pixmap property in the property editor.
     application making use of the custom widgets to the \QD headers and
     libraries as introduced by the simple approach explained above.
 
-    There are two ways to resolve this:
+    The following sections describe how to resolve this.
 
-    \list
-        \li Create a \c{.pri} file that contains the headers sources and sources
-           of the custom widget:
+    \section3 Linking the Widget into the Application
 
-           \code
-           INCLUDEPATH += $$PWD
-           HEADERS += $$PWD/analogclock.h
-           SOURCES += $$PWD/analogclock.cpp
-           \endcode
+     The source and header file of the custom widget can be shared
+     between the application and \QD by creating a \c{.pri} file for
+     inclusion:
 
-           This file would then be included by the \c{.pro} file of the plugin and
-           the application:
+     \code
+     INCLUDEPATH += $$PWD
+     HEADERS += $$PWD/analogclock.h
+     SOURCES += $$PWD/analogclock.cpp
+     \endcode
 
-           \code
-           include(customwidget.pri)
-           \endcode
+     This file would then be included by the \c{.pro} file of the plugin and
+     the application:
 
-           Running \c{qmake -Wall} on the \c{.pro} files causes a warning to be
-           printed if an included \c{.pri} file cannot be found.
+     \code
+     include(customwidget.pri)
+     \endcode
 
-        \li Create a standalone shared library containing the custom widgets only
-           as described in
-           \l{sharedlibrary.html}{Creating Shared Libraries}.
+    \section3 Sharing the Widget Using a Library
 
-           This library would then be used by the application as well as by the
-           \QD plugin. Care must be taken to ensure that the plugin can locate
-          the library at run-time.
-    \endlist
+    Another approach is to put the widget into a library that is linked to
+    the \QD plugin as well as to the application. It is recommended to
+    use static libraries to avoid problems locating the library at run-time.
+
+    For shared libraries, see \l{sharedlibrary.html}{Creating Shared Libraries}.
+
+    \section3 Using the Plugin with QUiLoader
+
+    The preferred way of adding custom widgets to QUiLoader is to subclass it
+    reimplementing QUiLoader::createWidget().
+
+    However, it is also possible to use \QD custom widget plugins
+    (see QUiLoader::pluginPaths() and related functions). To avoid having
+    to deploy the \QD libraries onto the target device, those plugins should
+    have no linkage to the \QD libraries (\c {QT = uiplugin}, see
+    \l{Creating Custom Widgets for Qt Designer#BuildingandInstallingthePlugin}).
 
     \section1 Related Examples