FCL/sf/mw/qt: comparison doc/src/examples/customwidgetplugin.qdoc

equal deleted inserted replaced

--1:000000000000
+:1918ee327afb
+/****************************************************************************
+**
+** Copyright (C) 2009 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}.
+*/