1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example designer/customwidgetplugin

    44     \title Custom Widget Plugin Example

    45 

    46     The Custom Widget example shows how to create a custom widget plugin for \QD.

    47 

    48     \image customwidgetplugin-example.png

    49 

    50     In this example, the custom widget used is based on the

    51     \l{widgets/analogclock}{Analog Clock example}, and does not provide any custom

    52     signals or slots.

    53 

    54     \section1 Preparation

    55 

    56     To provide a custom widget that can be used with \QD, we need to supply a

    57     self-contained implementation and provide a plugin interface. In this

    58     example, we reuse the \l{widgets/analogclock}{Analog Clock example} for

    59     convenience.

    60 

    61     Since custom widgets plugins rely on components supplied with \QD, the

    62     project file that we use needs to contain information about \QD's

    63     library components:

    64 

    65     \snippet examples/designer/customwidgetplugin/customwidgetplugin.pro 2

    66     \snippet examples/designer/customwidgetplugin/customwidgetplugin.pro 0

    67 

    68     The \c TEMPLATE variable's value makes \c qmake create the custom

    69     widget as a library. Later, we will ensure that the widget will be

    70     recognized as a plugin by Qt by using the Q_EXPORT_PLUGIN2() macro

    71     to export the relevant widget information.

    72 

    73     The \c CONFIG variable contains two values, \c designer and \c

    74     plugin:

    75 

    76     \list

    77 

    78     \o \c designer: Since custom widgets plugins rely on components

    79     supplied with \QD, this value ensures that our plugin links

    80     against \QD's library (\c libQtDesigner.so).

    81 

    82     \o \c plugin: We also need to ensure that \c qmake considers the

    83     custom widget a plugin library.

    84 

    85     \endlist

    86 

    87     When Qt is configured to build in both debug and release modes,

    88     \QD will be built in release mode. When this occurs, it is

    89     necessary to ensure that plugins are also built in release

    90     mode. For that reason we add the \c debug_and_release value to the

    91     \c CONFIG variable. Otherwise, if a plugin is built in a mode that

    92     is incompatible with \QD, it won't be loaded and

    93     installed.

    94 

    95     The header and source files for the widget are declared in the usual way,

    96     and we provide an implementation of the plugin interface so that \QD can

    97     use the custom widget:

    98 

    99     \snippet examples/designer/customwidgetplugin/customwidgetplugin.pro 3

   100 

   101     It is also important to ensure that the plugin is installed in a

   102     location that is searched by \QD. We do this by specifying a

   103     target path for the project and adding it to the list of items to

   104     install:

   105 

   106     \snippet doc/src/snippets/code/doc_src_examples_customwidgetplugin.qdoc 0

   107 

   108     The custom widget is created as a library, and will be installed

   109     alongside the other \QD plugins when the project is installed

   110     (using \c{make install} or an equivalent installation procedure).

   111     Later, we will ensure that it is recognized as a plugin by \QD by

   112     using the Q_EXPORT_PLUGIN2() macro to export the relevant widget

   113     information.

   114 

   115     Note that if you want the plugins to appear in a Visual Studio

   116     integration, the plugins must be built in release mode and their

   117     libraries must be copied into the plugin directory in the install

   118     path of the integration (for an example, see \c {C:/program

   119     files/trolltech as/visual studio integration/plugins}).

   120 

   121     For more information about plugins, see the \l {How to

   122     Create Qt Plugins} documentation.

   123 

   124     \section1 AnalogClock Class Definition and Implementation

   125 

   126     The \c AnalogClock class is defined and implemented in exactly the same

   127     way as described in the \l{widgets/analogclock}{Analog Clock example}.

   128     Since the class is self-contained, and does not require any external

   129     configuration, it can be used without modification as a custom widget in

   130     \QD.

   131 

   132     \section1 AnalogClockPlugin Class Definition

   133 

   134     The \c AnalogClock class is exposed to \QD through the \c

   135     AnalogClockPlugin class. This class inherits from both QObject and

   136     the QDesignerCustomWidgetInterface class, and implements an

   137     interface defined by QDesignerCustomWidgetInterface:

   138 

   139     \snippet examples/designer/customwidgetplugin/customwidgetplugin.h 0

   140 

   141     The functions provide information about the widget that \QD can use in

   142     the \l{Getting to Know Qt Designer#WidgetBox}{widget box}.

   143     The \c initialized private member variable is used to record whether

   144     the plugin has been initialized by \QD.

   145 

   146     Note that the only part of the class definition that is specific to

   147     this particular custom widget is the class name.

   148 

   149     \section1 AnalogClockPlugin Implementation

   150 

   151     The class constructor simply calls the QObject base class constructor

   152     and sets the \c initialized variable to \c false.

   153 

   154     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 0

   155 

   156     \QD will initialize the plugin when it is required by calling the

   157     \c initialize() function:

   158 

   159     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 1

   160 

   161     In this example, the \c initialized private variable is tested, and only

   162     set to \c true if the plugin is not already initialized. Although, this

   163     plugin does not require any special code to be executed when it is

   164     initialized, we could include such code after the test for initialization.

   165 

   166     The \c isInitialized() function lets \QD know whether the plugin is

   167     ready for use:

   168 

   169     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 2

   170 

   171     Instances of the custom widget are supplied by the \c createWidget()

   172     function. The implementation for the analog clock is straightforward:

   173 

   174     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 3

   175 

   176     In this case, the custom widget only requires a \c parent to be specified.

   177     If other arguments need to be supplied to the widget, they can be

   178     introduced here.

   179 

   180     The following functions provide information for \QD to use to represent

   181     the widget in the widget box.

   182     The \c name() function returns the name of class that provides the

   183     custom widget:

   184 

   185     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 4

   186 

   187     The \c group() function is used to describe the type of widget that the

   188     custom widget belongs to:

   189 

   190     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 5

   191 

   192     The widget plugin will be placed in a section identified by its

   193     group name in \QD's widget box. The icon used to represent the

   194     widget in the widget box is returned by the \c icon() function:

   195 

   196     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 6

   197 

   198     In this case, we return a null icon to indicate that we have no icon

   199     that can be used to represent the widget.

   200 

   201     A tool tip and "What's This?" help can be supplied for the custom widget's

   202     entry in the widget box. The \c toolTip() function should return a short

   203     message describing the widget:

   204 

   205     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 7

   206 

   207     The \c whatsThis() function can return a longer description:

   208 

   209     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 8

   210 

   211     The \c isContainer() function tells \QD whether the widget is supposed to

   212     be used as a container for other widgets. If not, \QD will not allow the

   213     user to place widgets inside it.

   214 

   215     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 9

   216 

   217     Most widgets in Qt can contain child widgets, but it only makes sense

   218     to use dedicated container widgets for this purpose in \QD. By returning

   219     \c false, we indicate that the custom widget cannot hold other widgets;

   220     if we returned true, \QD would allow other widgets to be placed inside

   221     the analog clock and a layout to be defined.

   222 

   223     The \c domXml() function provides a way to include default settings for

   224     the widget in the standard XML format used by \QD. In this case, we only

   225     specify the widget's geometry:

   226 

   227     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 10

   228 

   229     If the widget provides a reasonable size hint, it is not necessary to

   230     define it here. In addition, returning an empty string instead of a

   231     \c{<widget>} element will tell \QD not to install the widget in the

   232     widget box.

   233 

   234     To make the analog clock widget usable by applications, we implement

   235     the \c includeFile() function to return the name of the header file

   236     containing the custom widget class definition:

   237 

   238     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 12

   239 

   240     Finally, we use the Q_EXPORT_PLUGIN2() macro to export the \c

   241     AnalogClockPlugin class for use with \QD:

   242 

   243     \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 13

   244 

   245     This macro ensures that \QD can access and construct the custom widget.

   246     Without this macro, there is no way for \QD to use the widget.

   247 

   248     It is important to note that you can only use the Q_EXPORT_PLUGIN2()

   249     macro once in any implementation. If you have several custom widgets in

   250     an implementation that you wish to make available to \QD, you will need

   251     to implement \l{QDesignerCustomWidgetCollectionInterface}.

   252 */