1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \page qtdesigner-components.html

    44     \title Creating and Using Components for Qt Designer

    45     \ingroup best-practices

    46 

    47     \tableofcontents

    48 

    49     \section1 Creating Custom Widget Plugins

    50 

    51     When implementing a custom widget plugin for \QD, you must

    52     subclass QDesignerCustomWidgetInterface to expose your custom

    53     widget to \QD. A single custom widget plugin is built as a

    54     separate library. If you want to include several custom widget

    55     plugins in the same library, you must in addition subclass

    56     QDesignerCustomWidgetCollectionInterface.

    57 

    58     To provide your custom widget plugin with the expected behavior

    59     and functionality within \QD's workspace you can subclass the

    60     associated extension classes:

    61 

    62     The QDesignerContainerExtension class allows you to add pages to a

    63     custom multi-page container. The QDesignerTaskMenuExtension class

    64     allows you to add custom menu entries to \QD's task menu. The

    65     QDesignerMemberSheetExtension class allows you to manipulate a

    66     widget's member functions which is displayed when configuring

    67     connections using \QD's mode for editing signals and slots. And

    68     finally, the QDesignerPropertySheetExtension class allows you to

    69     manipulate a widget's properties which is displayed in \QD's

    70     property editor.

    71 

    72     \image qtdesignerextensions.png

    73 

    74     In \QD the extensions are not created until they are required. For

    75     that reason, when implementing extensions, you must also subclass

    76     QExtensionFactory, i.e create a class that is able to make

    77     instances of your extensions. In addition, you must make \QD's

    78     extension manager register your factory; the extension manager

    79     controls the construction of extensions as they are required, and

    80     you can access it through QDesignerFormEditorInterface and

    81     QExtensionManager.

    82 

    83     For a complete example creating a custom widget plugin with an

    84     extension, see the \l {designer/taskmenuextension}{Task Menu

    85     Extension} or \l {designer/containerextension}{Container

    86     Extension} examples.

    87 

    88     \section1 Retrieving Access to \QD Components

    89 

    90     The purpose of the classes mentioned in this section is to provide

    91     access to \QD's components, managers and workspace, and they are

    92     not intended to be instantiated directly.

    93 

    94     \QD is composed by several components. It has an action editor, a

    95     property editor, widget box and object inspector which you can

    96     view in its workspace.

    97 

    98     \image qtdesignerscreenshot.png

    99 

   100     \QD also has an object that works behind the scene; it contains

   101     the logic that integrates all of \QD's components into a coherent

   102     application. You can access this object, using the

   103     QDesignerFormEditorInterface, to retrieve interfaces to \QD's

   104     components:

   105 

   106     \list

   107     \o QDesignerActionEditorInterface

   108     \o QDesignerObjectInspectorInterface

   109     \o QDesignerPropertyEditorInterface

   110     \o QDesignerWidgetBoxInterface

   111     \endlist

   112 

   113     In addition, you can use QDesignerFormEditorInterface to retrieve

   114     interfaces to \QD's extension manager (QExtensionManager) and form

   115     window manager (QDesignerFormWindowManagerInterface). The

   116     extension manager controls the construction of extensions as they

   117     are required, while the form window manager controls the form

   118     windows appearing in \QD's workspace.

   119 

   120     Once you have an interface to \QD's form window manager

   121     (QDesignerFormWindowManagerInterface), you also have access to all

   122     the form windows currently appearing in \QD's workspace: The

   123     QDesignerFormWindowInterface class allows you to query and

   124     manipulate the form windows, and it provides an interface to the

   125     form windows' cursors. QDesignerFormWindowCursorInterface is a

   126     convenience class allowing you to query and modify a given form

   127     window's widget selection, and in addition modify the properties

   128     of all the form's widgets.

   129 

   130     \section1 Creating User Interfaces at Run-Time

   131 

   132     The \c QtDesigner module contains the QFormBuilder class that

   133     provides a mechanism for dynamically creating user interfaces at

   134     run-time, based on UI files created with \QD. This class is

   135     typically used by custom components and applications that embed

   136     \QD. Standalone applications that need to dynamically generate

   137     user interfaces at run-time use the QUiLoader class, found in

   138     the QtUiTools module.

   139 

   140     For a complete example using QUiLoader, see

   141     the \l {designer/calculatorbuilder}{Calculator Builder example}.

   142 

   143     \sa {Qt Designer Manual}, {QtUiTools Module}

   144 */