diff options
Diffstat (limited to 'examples/designer/doc/src/customwidgetplugin.qdoc')
| -rw-r--r-- | examples/designer/doc/src/customwidgetplugin.qdoc | 126 |
1 files changed, 58 insertions, 68 deletions
diff --git a/examples/designer/doc/src/customwidgetplugin.qdoc b/examples/designer/doc/src/customwidgetplugin.qdoc index 82b70cea3..dd8faf6a5 100644 --- a/examples/designer/doc/src/customwidgetplugin.qdoc +++ b/examples/designer/doc/src/customwidgetplugin.qdoc @@ -1,38 +1,16 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \example customwidgetplugin + \examplecategory {Desktop} + \meta tags {widgets,designer} \ingroup examples-designer - \title Custom Widget Plugin Example + \title Custom Widget Plugin - \brief Creating a custom widget plugin for Qt Designer. + \brief Creating a custom widget plugin for \QD. - \image customwidgetplugin-example.png + \image customwidgetplugin-example.webp In this example, the custom widget used is based on the \l{widgets/analogclock}{Analog Clock example}, and does not provide any custom @@ -45,59 +23,68 @@ example, we reuse the \l{widgets/analogclock}{Analog Clock example} for convenience. - Since custom widgets plugins rely on components supplied with \QD, the - project file that we use needs to contain information about \QD's - library components: + \section1 Project files - \snippet customwidgetplugin/customwidgetplugin.pro 2 - \snippet customwidgetplugin/customwidgetplugin.pro 0 + \section2 CMake - The \c TEMPLATE variable's value makes \c qmake create the custom - widget as a library. Later, we will ensure that the widget will be - recognized as a plugin by Qt by using the Q_PLUGIN_METADATA() macro - to export the relevant widget information. + The project files need to state that a plugin linking + to the \QD libraries is to be built: + \snippet customwidgetplugin/CMakeLists.txt 0 + \codeline + \snippet customwidgetplugin/CMakeLists.txt 2 - The \c CONFIG variable is set to \c plugin, which ensures that \c qmake - considers the custom widget a plugin library. + The link libraries list specifies \c Qt::UiPlugin. This 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. - 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 following example shows how to add the header and source files of the + widget: - 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 - use the custom widget: + \snippet customwidgetplugin/CMakeLists.txt 1 - \snippet customwidgetplugin/customwidgetplugin.pro 3 + We provide an implementation of the plugin interface so that \QD + can use the custom widget. It is also important to ensure that the plugin is installed in a location that is searched by \QD. We do this by specifying a target path for the project and adding it to the list of items to install: - \snippet doc/snippets/doc_src_examples_customwidgetplugin.pro 0 + \snippet customwidgetplugin/CMakeLists.txt 3 + \snippet customwidgetplugin/CMakeLists.txt 4 + + The custom widget is created as a library. It will be + installed alongside the other \QD plugins when the project is + installed (using \c{ninja install} or an equivalent installation + procedure). + + For more information about plugins, see the + \l {How to Create Qt Plugins} documentation. + + \section2 qmake + + The following example shows how to link a plugin to the \QD libraries: - The custom widget is created as a library, and will be installed - alongside the other \QD plugins when the project is installed - (using \c{make install} or an equivalent installation procedure). - Later, we will ensure that it is recognized as a plugin by \QD by - using the Q_PLUGIN_METADATA() macro to export the relevant widget - information. + \snippet customwidgetplugin/customwidgetplugin.pro 0 + \codeline + \snippet customwidgetplugin/customwidgetplugin.pro 1 + + The \c QT variable contains the keyword \c uiplugin, which is + the equivalent of the \c Qt::UiPlugin library. - Note that if you want the plugins to appear in a Visual Studio - integration, the plugins must be built in release mode and their - libraries must be copied into the plugin directory in the install - path of the integration (for an example, see \c {C:/program - files/trolltech as/visual studio integration/plugins}). + The following example shows how to add the header and source files of the + widget: + + \snippet customwidgetplugin/customwidgetplugin.pro 2 - For more information about plugins, see the \l {How to - Create Qt Plugins} documentation. + The following example shows how to install a plugin to the \QD's plugin path: + + \snippet customwidgetplugin/customwidgetplugin.pro 3 \section1 AnalogClock Class Definition and Implementation @@ -112,12 +99,15 @@ The \c AnalogClock class is exposed to \QD through the \c AnalogClockPlugin class. This class inherits from both QObject and the QDesignerCustomWidgetInterface class, and implements an - interface defined by QDesignerCustomWidgetInterface: + interface defined by QDesignerCustomWidgetInterface. + + To ensure that Qt recognizes the widget as a plugin, export relevant + information about the widget by adding the \c Q_PLUGIN_METADATA() macro: \snippet customwidgetplugin/customwidgetplugin.h 0 The functions provide information about the widget that \QD can use in - the \l{Getting to Know Qt Designer#WidgetBox}{widget box}. + the \l{Getting to Know Qt Widgets Designer#WidgetBox}{widget box}. The \c initialized private member variable is used to record whether the plugin has been initialized by \QD. |