diff options
Diffstat (limited to 'examples/designer/doc/src/worldtimeclockplugin.qdoc')
| -rw-r--r-- | examples/designer/doc/src/worldtimeclockplugin.qdoc | 188 |
1 files changed, 0 insertions, 188 deletions
diff --git a/examples/designer/doc/src/worldtimeclockplugin.qdoc b/examples/designer/doc/src/worldtimeclockplugin.qdoc deleted file mode 100644 index 19ec83f6b..000000000 --- a/examples/designer/doc/src/worldtimeclockplugin.qdoc +++ /dev/null @@ -1,188 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \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: - - \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 The Project File: worldtimeclockplugin.pro - - The project file for custom widget plugins needs some additional - information to ensure that they will work as expected within \QD: - - \snippet worldtimeclockplugin/worldtimeclockplugin.pro 0 - \snippet worldtimeclockplugin/worldtimeclockplugin.pro 1 - - 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 - plugin interface so that \QD can use the custom widget. - - \snippet worldtimeclockplugin/worldtimeclockplugin.pro 2 - - 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 doc/snippets/doc_src_examples_worldtimeclockplugin.pro 0 - - 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. - - 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}). - - For more information about plugins, see the \l {How to Create Qt - Plugins} document. -*/ |