diff options
-rw-r--r-- | examples/designer/doc/src/containerextension.qdoc | 22 | ||||
-rw-r--r-- | examples/designer/doc/src/customwidgetplugin.qdoc | 31 | ||||
-rw-r--r-- | examples/designer/doc/src/taskmenuextension.qdoc | 23 | ||||
-rw-r--r-- | examples/designer/doc/src/worldtimeclockplugin.qdoc | 32 | ||||
-rw-r--r-- | src/designer/src/designer/doc/src/designer-manual.qdoc | 71 |
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 |