Long live Qt!

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 0000000000..31ad65b505
--- /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}.
+*/