diff options
Diffstat (limited to 'doc/src/examples/worldtimeclockplugin.qdoc')
| -rw-r--r-- | doc/src/examples/worldtimeclockplugin.qdoc | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/doc/src/examples/worldtimeclockplugin.qdoc b/doc/src/examples/worldtimeclockplugin.qdoc new file mode 100644 index 0000000..072b1f0 --- /dev/null +++ b/doc/src/examples/worldtimeclockplugin.qdoc @@ -0,0 +1,210 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example designer/worldtimeclockplugin + \title World Time Clock Plugin Example + + The World Time Clock Plugin example shows how to create a custom + widget plugin for \QD that uses signals and slots. + + \image worldtimeclockplugin-example.png + + In this example, we simply extend the \l + {designer/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 + \o \c WorldTimeClock is a custom clock widget with hour and + minute hands that is automatically updated every few seconds. + \o \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 {designer/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 {designer/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 {designer/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 {designer/customwidgetplugin}{Custom Widget Plugin} + example, is the introduction of the signal and slot in the custom + widget class: + + \snippet examples/designer/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 + {designer/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 examples/designer/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 \l 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 + {designer/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_EXPORT_PLUGIN2() macro to export the \c + WorldTimeClockPlugin class for use with \QD: + + \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.cpp 0 + + 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 examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 0 + \snippet examples/designer/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 + \o \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). + + \o \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 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 examples/designer/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/src/snippets/code/doc_src_examples_worldtimeclockplugin.qdoc 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_EXPORT_PLUGIN2() 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. +*/ |