source: branches/4.5.1/doc/src/qtdesigner.qdoc@ 1044

/****************************************************************************
**
** 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$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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$
**
****************************************************************************/

/*!
    \module QtDesigner
    \title QtDesigner Module
    \contentspage Qt's Modules
    \previouspage Qt3Support
    \nextpage QtUiTools
    \ingroup modules

    \brief The QtDesigner module provides classes that allow you to
    create your own custom widget plugins for Qt Designer, and classes
    that enable you to access Qt Designer's components.

    In addition, the QFormBuilder class provides the possibility of
    constructing user interfaces from \c .ui files at run-time.

    To include the definitions of the module's classes, use the
    following directive:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 0

    To link against the module, add this line to your \c qmake .pro
    file:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 1

    \note These classes are part of the \l{Open Source Versions of Qt} and
    \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial
    users.

    \tableofcontents

    \section1 Creating Custom Widget Plugins

    When implementing a custom widget plugin for \QD, you must
    subclass QDesignerCustomWidgetInterface to expose your custom
    widget to \QD. A single custom widget plugin is built as a
    separate library. If you want to include several custom widget
    plugins in the same library, you must in addition subclass
    QDesignerCustomWidgetCollectionInterface.

    To provide your custom widget plugin with the expected behavior
    and functionality within \QD's workspace you can subclass the
    associated extension classes:

    The QDesignerContainerExtension class allows you to add pages to a
    custom multi-page container. The QDesignerTaskMenuExtension class
    allows you to add custom menu entries to \QD's task menu. The
    QDesignerMemberSheetExtension class allows you to manipulate a
    widget's member functions which is displayed when configuring
    connections using \QD's mode for editing signals and slots. And
    finally, the QDesignerPropertySheetExtension class allows you to
    manipulate a widget's properties which is displayed in \QD's
    property editor.

    \image qtdesignerextensions.png

    In \QD the extensions are not created until they are required. For
    that reason, when implementing extensions, you must also subclass
    QExtensionFactory, i.e create a class that is able to make
    instances of your extensions. In addition, you must make \QD's
    extension manager register your factory; the extension manager
    controls the construction of extensions as they are required, and
    you can access it through QDesignerFormEditorInterface and
    QExtensionManager.

    For a complete example creating a custom widget plugin with an
    extension, see the \l {designer/taskmenuextension}{Task Menu
    Extension} or \l {designer/containerextension}{Container
    Extension} examples.

    \section1 Retrieving Access to \QD Components

    The purpose of the classes mentioned in this section is to provide
    access to \QD's components, managers and workspace, and they are
    not intended to be instantiated directly.

    \QD is composed by several components. It has an action editor, a
    property editor, widget box and object inspector which you can
    view in its workspace.

    \image qtdesignerscreenshot.png

    \QD also has an object that works behind the scene; it contains
    the logic that integrates all of \QD's components into a coherent
    application. You can access this object, using the
    QDesignerFormEditorInterface, to retrieve interfaces to \QD's
    components:

    \list
    \o QDesignerActionEditorInterface
    \o QDesignerObjectInspectorInterface
    \o QDesignerPropertyEditorInterface
    \o QDesignerWidgetBoxInterface
    \endlist

    In addition, you can use QDesignerFormEditorInterface to retrieve
    interfaces to \QD's extension manager (QExtensionManager) and form
    window manager (QDesignerFormWindowManagerInterface). The
    extension manager controls the construction of extensions as they
    are required, while the form window manager controls the form
    windows appearing in \QD's workspace.

    Once you have an interface to \QD's form window manager
    (QDesignerFormWindowManagerInterface), you also have access to all
    the form windows currently appearing in \QD's workspace: The
    QDesignerFormWindowInterface class allows you to query and
    manipulate the form windows, and it provides an interface to the
    form windows' cursors. QDesignerFormWindowCursorInterface is a
    convenience class allowing you to query and modify a given form
    window's widget selection, and in addition modify the properties
    of all the form's widgets.

    \section1 Creating User Interfaces at Run-Time

    The \c QtDesigner module contains the QFormBuilder class that
    provides a mechanism for dynamically creating user interfaces at
    run-time, based on \c .ui files created with \QD. This class is
    typically used by custom components and applications that embed
    \QD. Standalone applications that need to dynamically generate
    user interfaces at run-time use the QUiLoader class, found in
    the QtUiTools module.

    For a complete example using QUiLoader, see
    the \l {designer/calculatorbuilder}{Calculator Builder example}.

    \sa {Qt Designer Manual}, {QtUiTools Module}
*/

/*!
    \class QDesignerMemberSheetExtension

    \brief The QDesignerMemberSheetExtension class allows you to
    manipulate a widget's member functions which is displayed when
    configuring connections using Qt Designer's mode for editing
    signals and slots.

    \inmodule QtDesigner

    QDesignerMemberSheetExtension is a collection of functions that is
    typically used to query a widget's member functions, and to
    manipulate the member functions' appearance in \QD's signals and
    slots editing mode. For example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 2

    When implementing a custom widget plugin, a pointer to \QD's
    current QDesignerFormEditorInterface object (\c formEditor in the
    example above) is provided by the
    QDesignerCustomWidgetInterface::initialize() function's parameter.

    The member sheet (and any other extension), can be retrieved by
    querying \QD's extension manager using the qt_extension()
    function. When you want to release the extension, you only need to
    delete the pointer.

    All widgets have a default member sheet used in \QD's signals and
    slots editing mode with the widget's member functions. But
    QDesignerMemberSheetExtension also provides an interface for
    creating custom member sheet extensions.

    \warning \QD uses the QDesignerMemberSheetExtension to facilitate
    the signal and slot editing mode. Whenever a connection between
    two widgets is requested, \QD will query for the widgets' member
    sheet extensions. If a widget has an implemented member sheet
    extension, this extension will override the default member sheet.

    To create a member sheet extension, your extension class must
    inherit from both QObject and QDesignerMemberSheetExtension. Then,
    since we are implementing an interface, we must ensure that it's
    made known to the meta object system using the Q_INTERFACES()
    macro:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 3

    This enables \QD to use qobject_cast() to query for
    supported interfaces using nothing but a QObject pointer.

    In \QD the extensions are not created until they are
    required. For that reason, when implementing a member sheet
    extension, you must also create a QExtensionFactory, i.e a class
    that is able to make an instance of your extension, and register
    it using \QD's \l {QExtensionManager}{extension manager}.

    When a widget's member sheet extension is required, \QD's \l
    {QExtensionManager}{extension manager} will run through all its
    registered factories calling QExtensionFactory::createExtension()
    for each until the first one that is able to create a member sheet
    extension for that widget, is found. This factory will then make
    an instance of the extension. If no such factory is found, \QD
    will use the default member sheet.

    There are four available types of extensions in \QD:
    QDesignerContainerExtension, QDesignerMemberSheetExtension,
    QDesignerPropertySheetExtension and
    QDesignerTaskMenuExtension. \QD's behavior is the same whether the
    requested extension is associated with a multi page container, a
    member sheet, a property sheet or a task menu.

    The QExtensionFactory class provides a standard extension
    factory, and can also be used as an interface for custom
    extension factories. You can either create a new
    QExtensionFactory and reimplement the
    QExtensionFactory::createExtension() function. For example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 4

    Or you can use an existing factory, expanding the
    QExtensionFactory::createExtension() function to make the factory
    able to create a member sheet extension as well. For example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 5

    For a complete example using an extension class, see \l
    {designer/taskmenuextension}{Task Menu Extension example}. The
    example shows how to create a custom widget plugin for Qt
    Designer, and how to to use the QDesignerTaskMenuExtension class
    to add custom items to \QD's task menu.

    \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget
    Extensions}
*/

/*!
    \fn QDesignerMemberSheetExtension::~QDesignerMemberSheetExtension()

    Destroys the member sheet extension.
*/

/*!
    \fn int QDesignerMemberSheetExtension::count() const

    Returns the extension's number of member functions.
*/

/*!
    \fn int QDesignerMemberSheetExtension::indexOf(const QString &name) const

    Returns the index of the member function specified by the given \a
    name.

    \sa memberName()
*/

/*!
    \fn QString QDesignerMemberSheetExtension::memberName(int index) const

    Returns the name of the member function with the given \a index.

    \sa indexOf()
*/

/*!
    \fn QString QDesignerMemberSheetExtension::memberGroup(int index) const

    Returns the name of the member group specified for the function
    with the given \a index.

    \sa indexOf(), setMemberGroup()
*/

/*!
    \fn void QDesignerMemberSheetExtension::setMemberGroup(int index, const QString &group)

    Sets the member group of the member function with the given \a
    index, to \a group.

    \sa indexOf(), memberGroup()
*/

/*!
    \fn bool QDesignerMemberSheetExtension::isVisible(int index) const

    Returns true if the member function with the given \a index is
    visible in \QD's signal and slot editor, otherwise false.

    \sa indexOf(), setVisible()
*/

/*!
    \fn void QDesignerMemberSheetExtension::setVisible(int index, bool visible)

    If \a visible is true, the member function with the given \a index
    is visible in \QD's signals and slots editing mode; otherwise the
    member function is hidden.

    \sa indexOf(), isVisible()
*/

/*!
    \fn virtual bool QDesignerMemberSheetExtension::isSignal(int index) const

    Returns true if the member function with the given \a index is a
    signal, otherwise false.

    \sa indexOf()
*/

/*!
    \fn bool QDesignerMemberSheetExtension::isSlot(int index) const

    Returns true if the member function with the given \a index is a
    slot, otherwise false.

    \sa indexOf()
*/

/*!
    \fn bool QDesignerMemberSheetExtension::inheritedFromWidget(int index) const

    Returns true if the member function with the given \a index is
    inherited from QWidget, otherwise false.

    \sa indexOf()
*/

/*!
    \fn QString QDesignerMemberSheetExtension::declaredInClass(int index) const

    Returns the name of the class in which the member function with
    the given \a index is declared.

    \sa indexOf()
*/

/*!
    \fn QString QDesignerMemberSheetExtension::signature(int index) const

    Returns the signature of the member function with the given \a
    index.

    \sa indexOf()
*/

/*!
    \fn QList<QByteArray> QDesignerMemberSheetExtension::parameterTypes(int index) const

    Returns the parameter types of the member function with the given
    \a index, as a QByteArray list.

    \sa indexOf(), parameterNames()
*/

/*!
    \fn QList<QByteArray> QDesignerMemberSheetExtension::parameterNames(int index) const

    Returns the parameter names of the member function with the given
    \a index, as a QByteArray list.

    \sa indexOf(), parameterTypes()
*/


// Doc: Interface only

/*!
    \class QDesignerLayoutDecorationExtension
    \brief The QDesignerLayoutDecorationExtension class provides an extension to a layout in \QD.
    \inmodule QtDesigner
    \internal
*/

/*!
    \enum QDesignerLayoutDecorationExtension::InsertMode

    This enum describes the modes that are used to insert items into a layout.

    \value InsertWidgetMode Widgets are inserted into empty cells in a layout.
    \value InsertRowMode    Whole rows are inserted into a vertical or grid layout.
    \value InsertColumnMode Whole columns are inserted into a horizontal or grid layout.
*/

/*!
    \fn virtual QDesignerLayoutDecorationExtension::~QDesignerLayoutDecorationExtension()

    Destroys the extension.
*/

/*!
    \fn virtual QList<QWidget*> QDesignerLayoutDecorationExtension::widgets(QLayout *layout) const

    Returns the widgets that are managed by the given \a layout.

    \sa insertWidget(), removeWidget()
*/

/*!
    \fn QRect QDesignerLayoutDecorationExtension::itemInfo(int index) const

    Returns the rectangle covered by the item at the given \a index in the layout.
*/

/*!
    \fn int QDesignerLayoutDecorationExtension::indexOf(QWidget *widget) const

    Returns the index of the specified \a widget in the layout.
*/

/*!
    \fn int QDesignerLayoutDecorationExtension::indexOf(QLayoutItem *item) const

    Returns the index of the specified layout \a item.
*/

/*!
    \fn QDesignerLayoutDecorationExtension::InsertMode QDesignerLayoutDecorationExtension::currentInsertMode() const

    Returns the current insertion mode.
*/

/*!
    \fn int QDesignerLayoutDecorationExtension::currentIndex() const

    Returns the current index in the layout.
*/

/*!
    \fn QPair<int, int> QDesignerLayoutDecorationExtension::currentCell() const

    Returns a pair containing the row and column of the current cell in the layout.
*/

/*!
    \fn void QDesignerLayoutDecorationExtension::insertWidget(QWidget *widget, const QPair<int, int> &cell)

    Inserts the given \a widget into the specified \a cell in the layout.

    \sa removeWidget()
*/

/*!
    \fn void QDesignerLayoutDecorationExtension::removeWidget(QWidget *widget)

    Removes the specified \a widget from the layout.

    \sa insertWidget()
*/

/*!
    \fn void QDesignerLayoutDecorationExtension::insertRow(int row)

    Inserts a new row into the form at the position specified by \a row.
*/

/*!
    \fn void QDesignerLayoutDecorationExtension::insertColumn(int column)

    Inserts a new column into the form at the position specified by \a column.
*/

/*!
    \fn void QDesignerLayoutDecorationExtension::simplify()

    Simplifies the layout by removing unnecessary empty rows and columns, and by changing the
    number of rows or columns spanned by widgets.
*/

/*!
    \fn int QDesignerLayoutDecorationExtension::findItemAt(const QPoint &position) const

    Returns the index of the item in the layout that covers the given \a position.
*/

/*!
    \fn int QDesignerLayoutDecorationExtension::findItemAt(int row, int column) const

    Returns the item in the layout that occupies the specified \a row and \a column in the layout.

    Currently, this only applies to grid layouts.
*/

/*!
    \fn void QDesignerLayoutDecorationExtension::adjustIndicator(const QPoint &position, int index)

    Adjusts the indicator for the item specified by \a index so that
    it lies at the given \a position on the form.
*/


// Doc: Interface only

/*!
    \class QDesignerContainerExtension
    \brief The QDesignerContainerExtension class allows you to add pages to
    a custom multi-page container in Qt Designer's workspace.
    \inmodule QtDesigner

    QDesignerContainerExtension provide an interface for creating
    custom container extensions. A container extension consists of a
    collection of functions that \QD needs to manage a multi-page
    container plugin, and a list of the container's pages.

    \image containerextension-example.png

    \warning This is \e not an extension for container plugins in
    general, only custom \e multi-page containers.

    To create a container extension, your extension class must inherit
    from both QObject and QDesignerContainerExtension. For example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 6

    Since we are implementing an interface, we must ensure that it's
    made known to the meta object system using the Q_INTERFACES()
    macro. This enables \QD to use the qobject_cast() function to
    query for supported interfaces using nothing but a QObject
    pointer.

    You must reimplement several functions to enable \QD to manage a
    custom multi-page container widget: \QD uses count() to keep track
    of the number pages in your container, widget() to return the page
    at a given index in the list of the container's pages, and
    currentIndex() to return the list index of the selected page. \QD
    uses the addWidget() function to add a given page to the
    container, expecting it to be appended to the list of pages, while
    it expects the insertWidget() function to add a given page to the
    container by inserting it at a given index.

    In \QD the extensions are not created until they are
    required. For that reason you must also create a
    QExtensionFactory, i.e a class that is able to make an instance of
    your extension, and register it using \QD's \l
    {QExtensionManager}{extension manager}.

    When a container extension is required, \QD's \l
    {QExtensionManager}{extension manager} will run through all its
    registered factories calling QExtensionFactory::createExtension()
    for each until the first one that is able to create a container
    extension, is found. This factory will then create the extension
    for the plugin.

    There are four available types of extensions in \QD:
    QDesignerContainerExtension , QDesignerMemberSheetExtension,
    QDesignerPropertySheetExtension and QDesignerTaskMenuExtension.
    \QD's behavior is the same whether the requested extension is
    associated with a multi page container, a member sheet, a property
    sheet or a task menu.

    The QExtensionFactory class provides a standard extension factory,
    and can also be used as an interface for custom extension
    factories. You can either create a new QExtensionFactory and
    reimplement the QExtensionFactory::createExtension() function. For
    example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 7

    Or you can use an existing factory, expanding the
    QExtensionFactory::createExtension() function to make the factory
    able to create a container extension as well. For example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 8

    For a complete example using the QDesignerContainerExtension
    class, see the \l {designer/containerextension}{Container
    Extension example}. The example shows how to create a custom
    multi-page plugin for \QD.

    \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget
    Extensions}
*/

/*!
    \fn QDesignerContainerExtension::~QDesignerContainerExtension()

    Destroys the extension.
*/

/*!
    \fn int QDesignerContainerExtension::count() const

    Returns the number of pages in the container.
*/

/*!
    \fn QWidget *QDesignerContainerExtension::widget(int index) const

    Returns the page at the given \a index in the extension's list of
    pages.

    \sa addWidget(), insertWidget()
*/

/*!
    \fn int QDesignerContainerExtension::currentIndex() const

    Returns the index of the currently selected page in the
    container.

    \sa setCurrentIndex()
*/

/*!
    \fn void QDesignerContainerExtension::setCurrentIndex(int index)

    Sets the the currently selected page in the container to be the
    page at the given \a index in the extension's list of pages.

    \sa currentIndex()
*/

/*!
    \fn void QDesignerContainerExtension::addWidget(QWidget *page)

    Adds the given \a page to the container by appending it to the
    extension's list of pages.

    \sa insertWidget(), remove(), widget()
*/

/*!
    \fn void QDesignerContainerExtension::insertWidget(int index, QWidget *page)

    Adds the given \a page to the container by inserting it at the
    given \a index in the extension's list of pages.

    \sa addWidget(), remove(), widget()
*/

/*!
    \fn void QDesignerContainerExtension::remove(int index)

    Removes the page at the given \a index from the extension's list
    of pages.

    \sa addWidget(), insertWidget()
*/


// Doc: Interface only

/*!
    \class QDesignerTaskMenuExtension
    \brief The QDesignerTaskMenuExtension class allows you to add custom
    menu entries to Qt Designer's task menu.
    \inmodule QtDesigner

    QDesignerTaskMenuExtension provides an interface for creating
    custom task menu extensions. It is typically used to create task
    menu entries that are specific to a plugin in \QD.

    \QD uses the QDesignerTaskMenuExtension to feed its task
    menu. Whenever a task menu is requested, \QD will query
    for the selected widget's task menu extension.

    \image taskmenuextension-example-faded.png

    A task menu extension is a collection of QActions. The actions
    appear as entries in the task menu when the plugin with the
    specified extension is selected. The image above shows the custom
    \gui {Edit State...} action which appears in addition to \QD's
    default task menu entries: \gui Cut, \gui Copy, \gui Paste etc.

    To create a custom task menu extension, your extension class must
    inherit from both QObject and QDesignerTaskMenuExtension. For
    example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 9

    Since we are implementing an interface, we must ensure that it
    is made known to the meta-object system using the Q_INTERFACES()
    macro. This enables \QD to use the qobject_cast() function to
    query for supported interfaces using nothing but a QObject
    pointer.

    You must reimplement the taskActions() function to return a list
    of actions that will be included in \QD task menu. Optionally, you
    can reimplement the preferredEditAction() function to set the
    action that is invoked when selecting your plugin and pressing
    \key F2. The preferred edit action must be one of the actions
    returned by taskActions() and, if it's not defined, pressing the
    \key F2 key will simply be ignored.

    In \QD, extensions are not created until they are required. A
    task menu extension, for example, is created when you click the
    right mouse button over a widget in \QD's workspace. For that
    reason you must also construct an extension factory, using either
    QExtensionFactory or a subclass, and register it using \QD's
    \l {QExtensionManager}{extension manager}.

    When a task menu extension is required, \QD's \l
    {QExtensionManager}{extension manager} will run through all its
    registered factories calling QExtensionFactory::createExtension()
    for each until it finds one that is able to create a task menu
    extension for the selected widget. This factory will then make an
    instance of the extension.

    There are four available types of extensions in \QD:
    QDesignerContainerExtension, QDesignerMemberSheetExtension,
    QDesignerPropertySheetExtension, and QDesignerTaskMenuExtension.
    \QD's behavior is the same whether the requested extension is
    associated with a container, a member sheet, a property sheet or a
    task menu.

    The QExtensionFactory class provides a standard extension factory,
    and can also be used as an interface for custom extension
    factories. You can either create a new QExtensionFactory and
    reimplement the QExtensionFactory::createExtension() function. For
    example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 10

    Or you can use an existing factory, expanding the
    QExtensionFactory::createExtension() function to make the factory
    able to create a task menu extension as well. For example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 11

    For a complete example using the QDesignerTaskMenuExtension class,
    see the \l {designer/taskmenuextension}{Task Menu Extension
    example}. The example shows how to create a custom widget plugin
    for \QD, and how to to use the QDesignerTaskMenuExtension
    class to add custom items to \QD's task menu.

    \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget
    Extensions}
*/

/*!
    \fn QDesignerTaskMenuExtension::~QDesignerTaskMenuExtension()

    Destroys the task menu extension.
*/

/*!
    \fn QAction *QDesignerTaskMenuExtension::preferredEditAction() const

    Returns the action that is invoked when selecting a plugin with
    the specified extension and pressing \key F2.

    The action must be one of the actions returned by taskActions().
*/

/*!
    \fn QList<QAction*> QDesignerTaskMenuExtension::taskActions() const

    Returns the task menu extension as a list of actions which will be
    included in \QD's task menu when a plugin with the specified
    extension is selected.

    The function must be reimplemented to add actions to the list.
*/


// Doc: Interface only

/*!
    \class QDesignerCustomWidgetCollectionInterface

    \brief The QDesignerCustomWidgetCollectionInterface class allows
    you to include several custom widgets in one single library.

    \inmodule QtDesigner

    When implementing a custom widget plugin, you build it as a
    separate library. If you want to include several custom widget
    plugins in the same library, you must in addition subclass
    QDesignerCustomWidgetCollectionInterface.

    QDesignerCustomWidgetCollectionInterface contains one single
    function returning a list of the collection's
    QDesignerCustomWidgetInterface objects. For example, if you have
    several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and
    \c CustomWidgetThree, the class definition may look like this:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 12

    In the class constructor you add the interfaces to your custom
    widgets to the list which you return in the customWidgets()
    function:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 13

    Note that instead of exporting each custom widget plugin using the
    Q_EXPORT_PLUGIN2() macro, you export the entire collection. The
    Q_EXPORT_PLUGIN2() macro ensures that \QD can access and construct
    the custom widgets. Without this macro, there is no way for \QD to
    use them.

    \sa QDesignerCustomWidgetInterface, {Creating Custom Widgets for
    Qt Designer}
*/

/*!
    \fn QDesignerCustomWidgetCollectionInterface::~QDesignerCustomWidgetCollectionInterface() {

    Destroys the custom widget collection interface.
*/

/*!
    \fn QList<QDesignerCustomWidgetInterface*> QDesignerCustomWidgetCollectionInterface::customWidgets() const

    Returns a list of interfaces to the collection's custom widgets.
*/


// Doc: Interface only

/*!
    \class QDesignerCustomWidgetInterface

    \brief The QDesignerCustomWidgetInterface class enables Qt Designer
    to access and construct custom widgets.

    \inmodule QtDesigner

    QDesignerCustomWidgetInterface provides a custom widget with an
    interface. The class contains a set of functions that must be subclassed
    to return basic information about the widget, such as its class name and
    the name of its header file. Other functions must be implemented to
    initialize the plugin when it is loaded, and to construct instances of
    the custom widget for \QD to use.

    When implementing a custom widget you must subclass
    QDesignerCustomWidgetInterface to expose your widget to \QD. For
    example, this is the declaration for the plugin used in the
    \l{Custom Widget Plugin Example}{Custom Widget Plugin example} that
    enables an analog clock custom widget to be used by \QD:

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

    Note that the only part of the class definition that is specific
    to this particular custom widget is the class name. In addition,
    since we are implementing an interface, we must ensure that it's
    made known to the meta object system using the Q_INTERFACES()
    macro. This enables \QD to use the qobject_cast() function to
    query for supported interfaces using nothing but a QObject
    pointer.

    After \QD loads a custom widget plugin, it calls the interface's
    initialize() function to enable it to set up any resources that it
    may need. This function is called with a QDesignerFormEditorInterface
    parameter that provides the plugin with a gateway to all of \QD's API.

    \QD constructs instances of the custom widget by calling the plugin's
    createWidget() function with a suitable parent widget. Plugins must
    construct and return an instance of a custom widget with the specified
    parent widget. 

    In the implementation of the class you must remember to export
    your custom widget plugin to \QD using the Q_EXPORT_PLUGIN2()
    macro. For example, if a library called \c libcustomwidgetplugin.so
    (on Unix) or \c libcustomwidget.dll (on Windows) contains a widget
    class called \c MyCustomWidget, we can export it by adding the
    following line to the file containing the plugin implementation:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 14

    This macro ensures that \QD can access and construct the custom widget.
    Without this macro, there is no way for \QD to use it.

    When implementing a custom widget plugin, you build it as a
    separate library. If you want to include several custom widget
    plugins in the same library, you must in addition subclass
    QDesignerCustomWidgetCollectionInterface.

    \warning If your custom widget plugin contains QVariant
    properties, be aware that only the following \l
    {QVariant::Type}{types} are supported:

    \list
    \o QVariant::ByteArray
    \o QVariant::Bool
    \o QVariant::Color
    \o QVariant::Cursor
    \o QVariant::Date
    \o QVariant::DateTime
    \o QVariant::Double
    \o QVariant::Int
    \o QVariant::Point
    \o QVariant::Rect
    \o QVariant::Size
    \o QVariant::SizePolicy
    \o QVariant::String
    \o QVariant::Time
    \o QVariant::UInt
    \endlist

    For a complete example using the QDesignerCustomWidgetInterface
    class, see the \l {designer/customwidgetplugin}{Custom Widget
    Example}. The example shows how to create a custom widget plugin
    for \QD.

    \sa QDesignerCustomWidgetCollectionInterface {Creating Custom
    Widgets for Qt Designer}
*/

/*!
    \fn QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface()

    Destroys the custom widget interface.
*/

/*!
    \fn QString QDesignerCustomWidgetInterface::name() const

    Returns the class name of the custom widget supplied by the interface.

    The name returned \e must be identical to the class name used for the
    custom widget.
*/

/*!
    \fn QString QDesignerCustomWidgetInterface::group() const

    Returns the name of the group to which the custom widget belongs.
*/

/*!
    \fn QString QDesignerCustomWidgetInterface::toolTip() const

    Returns a short description of the widget that can be used by \QD
    in a tool tip.
*/

/*!
    \fn QString QDesignerCustomWidgetInterface::whatsThis() const

    Returns a description of the widget that can be used by \QD in
    "What's This?" help for the widget.
*/

/*!
    \fn QString QDesignerCustomWidgetInterface::includeFile() const

    Returns the path to the include file that \l uic uses when
    creating code for the custom widget.
*/

/*!
    \fn QIcon QDesignerCustomWidgetInterface::icon() const

    Returns the icon used to represent the custom widget in \QD's
    widget box.
*/

/*!
    \fn bool QDesignerCustomWidgetInterface::isContainer() const

    Returns true if the custom widget is intended to be used as a
    container; otherwise returns false.

    Most custom widgets are not used to hold other widgets, so their
    implementations of this function will return false, but custom
    containers will return true to ensure that they behave correctly
    in \QD.
*/

/*!
    \fn QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent)

    Returns a new instance of the custom widget, with the given \a
    parent.
*/

/*!
    \fn bool QDesignerCustomWidgetInterface::isInitialized() const

    Returns true if the widget has been initialized; otherwise returns
    false.

    \sa initialize()
*/

/*!
    \fn void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor)

    Initializes the widget for use with the specified \a formEditor
    interface.

    \sa isInitialized()
*/

/*!
    \fn QString QDesignerCustomWidgetInterface::domXml() const

    Returns the XML that is used to describe the custom widget's
    properties to \QD.
*/

/*!
    \fn QString QDesignerCustomWidgetInterface::codeTemplate() const

    This function is reserved for future use by \QD.

    \omit
    Returns the code template that \QD includes in forms that contain
    the custom widget when they are saved.
    \endomit
*/

/*!
    \macro QDESIGNER_WIDGET_EXPORT
    \relates QDesignerCustomWidgetInterface
    \since 4.1

    This macro is used when defining custom widgets to ensure that they are
    correctly exported from plugins for use with \QD.

    On some platforms, the symbols required by \QD to create new widgets
    are removed from plugins by the build system, making them unusable.
    Using this macro ensures that the symbols are retained on those platforms,
    and has no side effects on other platforms.

    For example, the \l{designer/worldtimeclockplugin}{World Time Clock Plugin}
    example exports a custom widget class with the following declaration:

    \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 0
    \dots
    \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 2

    \sa {Creating Custom Widgets for Qt Designer}
*/


// Doc: Abstract class

/*!
    \class QDesignerDnDItemInterface
    \brief The QDesignerDnDItemInterface class provides an interface that is used to manage items
    during a drag and drop operation.
    \inmodule QtDesigner
    \internal
*/

/*!
    \enum QDesignerDnDItemInterface::DropType

    This enum describes the result of a drag and drop operation.

    \value MoveDrop The item was moved.
    \value CopyDrop The item was copied.
*/

/*!
    \fn QDesignerDnDItemInterface::QDesignerDnDItemInterface()

    Constructs a new interface to a drag and drop item.
*/

/*!
    \fn QDesignerDnDItemInterface::~QDesignerDnDItemInterface()

    Destroys the interface to the item.
*/

/*!
    \fn DomUI *QDesignerDnDItemInterface::domUi() const

    Returns a user interface object for the item.
*/

/*!
    \fn QWidget *QDesignerDnDItemInterface::widget() const

    Returns the widget being copied or moved in the drag and drop operation.

    \sa source()
*/

/*!
    \fn QWidget *QDesignerDnDItemInterface::decoration() const

    Returns the widget used to represent the item.
*/

/*!
    \fn QPoint QDesignerDnDItemInterface::hotSpot() const

    Returns the cursor's hotspot.

    \sa QDrag::hotSpot()
*/

/*!
    \fn DropType QDesignerDnDItemInterface::type() const

    Returns the type of drag and drop operation in progress.
*/

/*!
    \fn QWidget *QDesignerDnDItemInterface::source() const

    Returns the widget that is the source of the drag and drop operation; i.e. the original
    container of the widget being dragged.

    \sa widget()
*/


// Doc: Abstract class

/*!
    \class QDesignerIconCacheInterface
    \brief The QDesignerIconCacheInterface class provides an interface to \QD's icon cache.
    \inmodule QtDesigner
    \internal
*/

/*!
    \fn QDesignerIconCacheInterface::QDesignerIconCacheInterface(QObject *parent)

    Constructs a new interface with the given \a parent.
*/

/*!
    \fn QIcon QDesignerIconCacheInterface::nameToIcon(const QString &filePath, const QString &qrcPath)

    Returns the icon associated with the name specified by \a filePath in the resource
    file specified by \a qrcPath.

    If \a qrcPath refers to a valid resource file, the name used for the file path is a path
    within those resources; otherwise the file path refers to a local file.

    \sa {The Qt Resource System}, nameToPixmap()
*/

/*!
    \fn QPixmap QDesignerIconCacheInterface::nameToPixmap(const QString &filePath, const QString &qrcPath)

    Returns the pixmap associated with the name specified by \a filePath in the resource
    file specified by \a qrcPath.

    If \a qrcPath refers to a valid resource file, the name used for the file path is a path
    within those resources; otherwise the file path refers to a local file.

    \sa {The Qt Resource System}, nameToIcon()
*/

/*!
    \fn QString QDesignerIconCacheInterface::iconToFilePath(const QIcon &icon) const

    Returns the file path associated with the given \a icon. The file path is a path within
    an application resources.
*/

/*!
    \fn QString QDesignerIconCacheInterface::iconToQrcPath(const QIcon &icon) const

    Returns the path to the resource file that refers to the specified \a icon. The resource
    path refers to a local file.
*/

/*!
    \fn QString QDesignerIconCacheInterface::pixmapToFilePath(const QPixmap &pixmap) const

    Returns the file path associated with the given \a pixmap. The file path is a path within
    an application resources.
*/

/*!
    \fn QString QDesignerIconCacheInterface::pixmapToQrcPath(const QPixmap &pixmap) const

    Returns the path to the resource file that refers to the specified \a pixmap. The resource
    path refers to a local file.
*/

/*!
    \fn QList<QPixmap> QDesignerIconCacheInterface::pixmapList() const

    Returns a list of pixmaps for the icons provided by the icon cache.
*/

/*!
    \fn QList<QIcon> QDesignerIconCacheInterface::iconList() const

    Returns a list of icons provided by the icon cache.
*/

/*!
    \fn QString QDesignerIconCacheInterface::resolveQrcPath(const QString &filePath, const QString &qrcPath, const QString &workingDirectory) const

    Returns a path to a resource specified by the \a filePath within
    the resource file located at \a qrcPath. If \a workingDirectory is
    a valid path to a directory, the path returned will be relative to
    that directory; otherwise an absolute path is returned.

    \omit
    ### Needs checking
    \endomit
*/


// Doc: Interface only

/*!
    \class QDesignerPropertySheetExtension

    \brief The QDesignerPropertySheetExtension class allows you to
    manipulate a widget's properties which is displayed in Qt
    Designer's property editor.

    \sa QDesignerDynamicPropertySheetExtension

    \inmodule QtDesigner

    QDesignerPropertySheetExtension provides a collection of functions that
    are typically used to query a widget's properties, and to
    manipulate the properties' appearance in the property editor. For
    example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 15

    Note that if you change the value of a property using the
    QDesignerPropertySheetExtension::setProperty() function, the undo
    stack is not updated. To ensure that a property's value can be
    reverted using the undo stack, you must use the
    QDesignerFormWindowCursorInterface::setProperty() function, or its
    buddy \l
    {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()},
    instead.

    When implementing a custom widget plugin, a pointer to \QD's
    current QDesignerFormEditorInterface object (\c formEditor in the
    example above) is provided by the
    QDesignerCustomWidgetInterface::initialize() function's parameter.

    The property sheet, or any other extension, can be retrieved by
    querying \QD's extension manager using the qt_extension()
    function. When you want to release the extension, you only need to
    delete the pointer.

    All widgets have a default property sheet which populates \QD's
    property editor with the widget's properties (i.e the ones defined
    with the Q_PROPERTY() macro). But QDesignerPropertySheetExtension
    also provides an interface for creating custom property sheet
    extensions.

    \warning \QD uses the QDesignerPropertySheetExtension to feed its
    property editor. Whenever a widget is selected in its workspace,
    \QD will query for the widget's property sheet extension. If the
    selected widget has an implemented property sheet extension, this
    extension will override the default property sheet.

    To create a property sheet extension, your extension class must
    inherit from both QObject and
    QDesignerPropertySheetExtension. Then, since we are implementing
    an interface, we must ensure that it's made known to the meta
    object system using the Q_INTERFACES() macro:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 16

    This enables \QD to use qobject_cast() to query for supported
    interfaces using nothing but a QObject pointer.

    In \QD the extensions are not created until they are
    required. For that reason, when implementing a property sheet
    extension, you must also create a QExtensionFactory, i.e a class
    that is able to make an instance of your extension, and register
    it using \QD's \l {QExtensionManager}{extension manager}.

    When a property sheet extension is required, \QD's \l
    {QExtensionManager}{extension manager} will run through all its
    registered factories calling QExtensionFactory::createExtension()
    for each until the first one that is able to create a property
    sheet extension for the selected widget, is found. This factory
    will then make an instance of the extension. If no such factory
    can be found, \QD will use the default property sheet.

    There are four available types of extensions in \QD:
    QDesignerContainerExtension, QDesignerMemberSheetExtension,
    QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. Qt
    Designer's behavior is the same whether the requested extension is
    associated with a multi page container, a member sheet, a property
    sheet or a task menu.

    The QExtensionFactory class provides a standard extension factory,
    and can also be used as an interface for custom extension
    factories. You can either create a new QExtensionFactory and
    reimplement the QExtensionFactory::createExtension() function. For
    example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 17

    Or you can use an existing factory, expanding the
    QExtensionFactory::createExtension() function to make the factory
    able to create a property sheet extension extension as well. For
    example:

    \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 18

    For a complete example using an extension class, see the \l
    {designer/taskmenuextension}{Task Menu Extension example}. The
    example shows how to create a custom widget plugin for Qt
    Designer, and how to to use the QDesignerTaskMenuExtension class
    to add custom items to \QD's task menu.

    \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget
    Extensions}
*/

/*!
    \fn QDesignerPropertySheetExtension::~QDesignerPropertySheetExtension()

    Destroys the property sheet extension.
*/

/*!
    \fn int QDesignerPropertySheetExtension::count() const

    Returns the selected widget's number of properties.
*/

/*!
    \fn int QDesignerPropertySheetExtension::indexOf(const QString &name) const

    Returns the index for a given property \a name.

    \sa propertyName()
*/

/*!
    \fn QString QDesignerPropertySheetExtension::propertyName(int index) const

    Returns the name of the property at the given \a index.

    \sa indexOf()
*/

/*!
    \fn QString QDesignerPropertySheetExtension::propertyGroup(int index) const

    Returns the property group for the property at the given \a index.

    \QD's property editor supports property groups, i.e. sections of
    related properties. A property can be related to a group using the
    setPropertyGroup() function. The default group of any property is
    the name of the class that defines it. For example, the
    QObject::objectName property appears within the QObject property
    group.

    \sa indexOf(), setPropertyGroup()
*/

/*!
    \fn void QDesignerPropertySheetExtension::setPropertyGroup(int index, const QString &group)

    Sets the property group for the property at the given \a index to
    \a group.

    Relating a property to a group makes it appear within that group's
    section in the property editor. The default property group of any
    property is the name of the class that defines it. For example,
    the QObject::objectName property appears within the QObject
    property group.

    \sa indexOf(), property(), propertyGroup()
*/

/*!
    \fn bool QDesignerPropertySheetExtension::hasReset(int index) const

    Returns true if the property at the given \a index has a reset
    button in \QD's property editor, otherwise false.

    \sa indexOf(), reset()
*/

/*!
    \fn bool QDesignerPropertySheetExtension::reset(int index)

    Resets the value of the property at the given \a index, to the
    default value. Returns true if a default value could be found, otherwise false.

    \sa indexOf(), hasReset(), isChanged()
*/

/*!
    \fn bool QDesignerPropertySheetExtension::isVisible(int index) const

    Returns true if the property at the given \a index is visible in
    \QD's property editor, otherwise false.

    \sa indexOf(), setVisible()
*/

/*!
    \fn void QDesignerPropertySheetExtension::setVisible(int index, bool visible)

    If \a visible is true, the property at the given \a index is
    visible in \QD's property editor; otherwise the property is
    hidden.

    \sa indexOf(), isVisible()
*/

/*!
    \fn bool QDesignerPropertySheetExtension::isAttribute(int index) const

    Returns true if the property at the given \a index is an attribute,
    which will be \e excluded from the .ui file, otherwise false.

    \sa indexOf(), setAttribute()
*/

/*!
    \fn void QDesignerPropertySheetExtension::setAttribute(int index, bool attribute)

    If \a attribute is true, the property at the given \a index is
    made an attribute which will be \e excluded from the .ui file;
    otherwise it will be included.

    \sa indexOf(), isAttribute()
*/

/*!
    \fn QVariant QDesignerPropertySheetExtension::property(int index) const

    Returns the value of the property at the given \a index.

    \sa indexOf(), setProperty(), propertyGroup()
*/

/*!
    \fn void QDesignerPropertySheetExtension::setProperty(int index, const QVariant &value)

    Sets the \a value of the property at the given \a index.

    \warning If you change the value of a property using this
    function, the undo stack is not updated. To ensure that a
    property's value can be reverted using the undo stack, you must
    use the QDesignerFormWindowCursorInterface::setProperty()
    function, or its buddy \l
    {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()},
    instead.

    \sa indexOf(), property(), propertyGroup()
*/

/*!
    \fn bool QDesignerPropertySheetExtension::isChanged(int index) const

    Returns true if the value of the property at the given \a index
    differs from the property's default value, otherwise false.

    \sa indexOf(), setChanged(), reset()
*/

/*!
    \fn void QDesignerPropertySheetExtension::setChanged(int index, bool changed)

    Sets whether the property at the given \a index is different from
    its default value, or not, depending on the \a changed parameter.

    \sa indexOf(), isChanged()
*/

// Doc: Interface only

/*!
    \class QDesignerDynamicPropertySheetExtension

    \brief The QDesignerDynamicPropertySheetExtension class allows you to
    manipulate a widget's dynamic properties in Qt Designer's property editor.

    \sa QDesignerPropertySheetExtension, {QObject#Dynamic Properties}{Dynamic Properties}

    \inmodule QtDesigner
    \since 4.3
*/

/*!
    \fn QDesignerDynamicPropertySheetExtension::~QDesignerDynamicPropertySheetExtension()

    Destroys the dynamic property sheet extension.
*/

/*!
    \fn bool QDesignerDynamicPropertySheetExtension::dynamicPropertiesAllowed() const

    Returns true if the widget supports dynamic properties; otherwise returns false.
*/

/*!
    \fn int QDesignerDynamicPropertySheetExtension::addDynamicProperty(const QString &propertyName, const QVariant &value)

    Adds a dynamic property named \a propertyName and sets its value to \a value.
    Returns the index of the property if it was added successfully; otherwise returns -1 to
    indicate failure.
*/

/*!
    \fn bool QDesignerDynamicPropertySheetExtension::removeDynamicProperty(int index)

    Removes the dynamic property at the given \a index.
    Returns true if the operation succeeds; otherwise returns false.
*/

/*!
    \fn bool QDesignerDynamicPropertySheetExtension::isDynamicProperty(int index) const

    Returns true if the property at the given \a index is a dynamic property; otherwise
    returns false.
*/

/*!
    \fn bool QDesignerDynamicPropertySheetExtension::canAddDynamicProperty(const QString &propertyName) const

    Returns true if \a propertyName is a valid, unique name for a dynamic
    property; otherwise returns false.

*/