diff options
Diffstat (limited to 'doc/src/examples/customwidgetplugin.qdoc')
| -rw-r--r-- | doc/src/examples/customwidgetplugin.qdoc | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/doc/src/examples/customwidgetplugin.qdoc b/doc/src/examples/customwidgetplugin.qdoc new file mode 100644 index 0000000..31ad65b --- /dev/null +++ b/doc/src/examples/customwidgetplugin.qdoc @@ -0,0 +1,252 @@ +/**************************************************************************** +** +** 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/customwidgetplugin + \title Custom Widget Plugin Example + + The Custom Widget example shows how to create a custom widget plugin for \QD. + + \image customwidgetplugin-example.png + + In this example, the custom widget used is based on the + \l{widgets/analogclock}{Analog Clock example}, and does not provide any custom + signals or slots. + + \section1 Preparation + + To provide a custom widget that can be used with \QD, we need to supply a + self-contained implementation and provide a plugin interface. In this + 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: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.pro 2 + \snippet examples/designer/customwidgetplugin/customwidgetplugin.pro 0 + + 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_EXPORT_PLUGIN2() macro + to export the relevant widget information. + + 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 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 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 examples/designer/customwidgetplugin/customwidgetplugin.pro 3 + + 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/src/snippets/code/doc_src_examples_customwidgetplugin.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} documentation. + + \section1 AnalogClock Class Definition and Implementation + + The \c AnalogClock class is defined and implemented in exactly the same + way as described in the \l{widgets/analogclock}{Analog Clock example}. + Since the class is self-contained, and does not require any external + configuration, it can be used without modification as a custom widget in + \QD. + + \section1 AnalogClockPlugin Class Definition + + 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: + + \snippet examples/designer/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 \c initialized private member variable is used to record whether + the plugin has been initialized by \QD. + + Note that the only part of the class definition that is specific to + this particular custom widget is the class name. + + \section1 AnalogClockPlugin Implementation + + The class constructor simply calls the QObject base class constructor + and sets the \c initialized variable to \c false. + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 0 + + \QD will initialize the plugin when it is required by calling the + \c initialize() function: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 1 + + In this example, the \c initialized private variable is tested, and only + set to \c true if the plugin is not already initialized. Although, this + plugin does not require any special code to be executed when it is + initialized, we could include such code after the test for initialization. + + The \c isInitialized() function lets \QD know whether the plugin is + ready for use: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 2 + + Instances of the custom widget are supplied by the \c createWidget() + function. The implementation for the analog clock is straightforward: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 3 + + In this case, the custom widget only requires a \c parent to be specified. + If other arguments need to be supplied to the widget, they can be + introduced here. + + The following functions provide information for \QD to use to represent + the widget in the widget box. + The \c name() function returns the name of class that provides the + custom widget: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 4 + + The \c group() function is used to describe the type of widget that the + custom widget belongs to: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 5 + + The widget plugin will be placed in a section identified by its + group name in \QD's widget box. The icon used to represent the + widget in the widget box is returned by the \c icon() function: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 6 + + In this case, we return a null icon to indicate that we have no icon + that can be used to represent the widget. + + A tool tip and "What's This?" help can be supplied for the custom widget's + entry in the widget box. The \c toolTip() function should return a short + message describing the widget: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 7 + + The \c whatsThis() function can return a longer description: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 8 + + The \c isContainer() function tells \QD whether the widget is supposed to + be used as a container for other widgets. If not, \QD will not allow the + user to place widgets inside it. + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 9 + + Most widgets in Qt can contain child widgets, but it only makes sense + to use dedicated container widgets for this purpose in \QD. By returning + \c false, we indicate that the custom widget cannot hold other widgets; + if we returned true, \QD would allow other widgets to be placed inside + the analog clock and a layout to be defined. + + The \c domXml() function provides a way to include default settings for + the widget in the standard XML format used by \QD. In this case, we only + specify the widget's geometry: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 10 + + If the widget provides a reasonable size hint, it is not necessary to + define it here. In addition, returning an empty string instead of a + \c{<widget>} element will tell \QD not to install the widget in the + widget box. + + To make the analog clock widget usable by applications, we implement + the \c includeFile() function to return the name of the header file + containing the custom widget class definition: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 12 + + Finally, we use the Q_EXPORT_PLUGIN2() macro to export the \c + AnalogClockPlugin class for use with \QD: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 13 + + This macro ensures that \QD can access and construct the custom widget. + Without this macro, there is no way for \QD to use the widget. + + It is important to note that you can only use the Q_EXPORT_PLUGIN2() + macro once in any implementation. If you have several custom widgets in + an implementation that you wish to make available to \QD, you will need + to implement \l{QDesignerCustomWidgetCollectionInterface}. +*/ |