diff options
Diffstat (limited to 'examples/designer/doc/src/worldtimeclockplugin.qdoc')
| -rw-r--r-- | examples/designer/doc/src/worldtimeclockplugin.qdoc | 182 |
1 files changed, 0 insertions, 182 deletions
diff --git a/examples/designer/doc/src/worldtimeclockplugin.qdoc b/examples/designer/doc/src/worldtimeclockplugin.qdoc deleted file mode 100644 index 25198f261..000000000 --- a/examples/designer/doc/src/worldtimeclockplugin.qdoc +++ /dev/null @@ -1,182 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \example worldtimeclockplugin - \ingroup examples-designer - \title World Time Clock Plugin Example - - \brief Creating a custom widget plugin for \QD that uses signals and slots. - - \image worldtimeclockplugin-example.png - - In this example, we simply extend the \l - {customwidgetplugin}{Custom Widget Plugin} example and - its custom widget (based on the \l{widgets/analogclock}{Analog - Clock} example), by introducing the concept of signals and slots. - - The World Time Clock Plugin example consists of two classes: - - \list - \li \c WorldTimeClock is a custom clock widget with hour and - minute hands that is automatically updated every few seconds. - \li \c WorldTimeClockPlugin exposes the \c WorldTimeClock class to \QD. - \endlist - - First we will take a look at the \c WorldTimeClock class which - extends the \l {customwidgetplugin}{Custom Widget Plugin} - example's \c AnalogClock class by providing a signal and a - slot. Then we will take a quick look at the \c - WorldTimeClockPlugin class, but this class is in most parts - identical to the \l {customwidgetplugin}{Custom Widget - Plugin} example's implementation. - - Finally we take a look at the plugin's project file. The project - file for custom widget plugins needs some additional information - to ensure that they will work within \QD. This is also covered in - the \l {customwidgetplugin}{Custom Widget Plugin} example, - but due to its importance (custom widget plugins rely on - components supplied with \QD which must be specified in the - project file that we use) we will repeat it here. - - \section1 WorldTimeClock Class - - The \c WorldTimeClock class inherits QWidget, and is a custom - clock widget with hour and minute hands that is automatically - updated every few seconds. What makes this example different from - the \l {customwidgetplugin}{Custom Widget Plugin} - example, is the introduction of the signal and slot in the custom - widget class: - - \snippet worldtimeclockplugin/worldtimeclock.h 1 - - Note the use of the QDESIGNER_WIDGET_EXPORT macro. This is needed - to ensure that \QD can create instances of the widget on some - platforms, but it is a good idea to use it on all platforms. - - We declare the \c setTimeZone() slot with an associated \c - timeZoneOffset variable, and we declare an \c updated() signal - which takes the current time as argument and is emitted whenever - the widget is repainted. - - \image worldtimeclock-connection.png - - In \QD's workspace we can then, for example, connect the \c - WorldTimeClock widget's \c updated() signal to a QTimeEdit's \l - {QDateTimeEdit::setTime()}{setTime()} slot using \QD's mode - for editing signal and slots. - - \image worldtimeclock-signalandslot.png - - We can also connect a QSpinBox's \l - {QSpinBox::valueChanged()}{valueChanged()} signal to the \c - WorldTimeClock's \c setTimeZone() slot. - - \section1 WorldTimeClockPlugin Class - - The \c WorldTimeClockPlugin class exposes the \c WorldTimeClock - class to \QD. Its definition is equivalent to the \l - {customwidgetplugin}{Custom Widget Plugin} example's - plugin class which is explained in detail. The only part of the - class definition that is specific to this particular custom widget - is the class name. - - 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 worldtimeclockplugin/worldtimeclockplugin.h 0 - - The plugin class provides \QD with basic information about our - plugin, such as its class name and its include file. Furthermore - it knows how to create instances of the \c WorldTimeClockPlugin - widget. \c WorldTimeClockPlugin also defines the \l - {QDesignerCustomWidgetInterface::initialize()}{initialize()} - function which is called after the plugin is loaded into \QD. The - function's QDesignerFormEditorInterface parameter provides the - plugin with a gateway to all of \QD's API's. - - The \c WorldTimeClockPlugin class inherits from both QObject and - QDesignerCustomWidgetInterface. It is important to remember, when - using multiple inheritance, to ensure that all the interfaces - (i.e. the classes that doesn't inherit Q_OBJECT) are made known to - the meta object system using the Q_INTERFACES() macro. This - enables \QD to use qobject_cast() to query for supported - interfaces using nothing but a QObject pointer. - - The implementation of the \c WorldTimeClockPlugin is also - equivalent to the plugin interface implementation in the \l - {customwidgetplugin}{Custom Widget Plugin} example (only - the class name and the implementation of - QDesignerCustomWidgetInterface::domXml() differ). The main thing - to remember is to use the Q_PLUGIN_METADATA() macro to export the \c - WorldTimeClockPlugin class for use with \QD: - - \snippet worldtimeclockplugin/worldtimeclockplugin.h 1 - - Without this macro, there is no way for Qt Designer to use the - widget. - - \section1 Project files - \section2 CMake - - The project files need to state that a plugin linking - to the \QD libraries is to be built: - - \snippet worldtimeclockplugin/CMakeLists.txt 0 - \codeline - \snippet worldtimeclockplugin/CMakeLists.txt 2 - - 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 header and source files for the widget are declared in the - usual way: - - \snippet worldtimeclockplugin/CMakeLists.txt 1 - - We provide an implementation of the plugin interface so that \QD - can use the custom widget. In this particular example we also - provide implementations of the container extension interface and - the extension factory. - - It is 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 worldtimeclockplugin/CMakeLists.txt 3 - \snippet worldtimeclockplugin/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: - - \snippet worldtimeclockplugin/worldtimeclockplugin.pro 0 - \codeline - \snippet worldtimeclockplugin/worldtimeclockplugin.pro 1 - - The \c QT variable contains the keyword \c uiplugin, which is - the equivalent of the \c Qt::UiPlugin library. - - The following example shows how to add the header and source files of the - widget: - - \snippet worldtimeclockplugin/worldtimeclockplugin.pro 2 - - The following example shows how to install a plugin to the \QD's plugin path: - - \snippet worldtimeclockplugin/worldtimeclockplugin.pro 3 -*/ |