--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/customwidgetplugin.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,252 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@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}.
+*/