Doc: move a Qt Designer howto to qttools

One more file was missing from the modularization:
Creating and Using Components for Qt Designer. The links to
images in the file were consequently broken.

Change-Id: I7ae9f7efd74acc3dc030999796afcbaa48110696
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

diff --git a/src/designer/src/designer/doc/src/designer-custom-widgets.qdoc b/src/designer/src/designer/doc/src/designer-custom-widgets.qdoc
new file mode 100644 (file)
index 0000000..6966b88
--- /dev/null
+++ b/src/designer/src/designer/doc/src/designer-custom-widgets.qdoc
@@ -0,0 +1,131 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtdesigner-components.html
+    \title Creating and Using Components for Qt Designer
+    \brief How to create and use custom widget plugins.
+    \ingroup best-practices
+
+    \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
+    \li QDesignerActionEditorInterface
+    \li QDesignerObjectInspectorInterface
+    \li QDesignerPropertyEditorInterface
+    \li 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}
+*/