/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** 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 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 http://qt.nokia.com/contact.
** $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 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 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}
*/