source: trunk/doc/src/development/designer-manual.qdoc@ 788

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** 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.1, 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 have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page designer-manual.html

    \title Qt Designer Manual
    \ingroup qttools
    \keyword Qt Designer

    \QD is Qt's tool for designing and building graphical user
    interfaces (GUIs) from Qt components. You can compose and customize your
    widgets or dialogs in a what-you-see-is-what-you-get (WYSIWYG) manner, and
    test them using different styles and resolutions.

    Widgets and forms created with \QD integrated seamlessly with programmed
    code, using Qt's signals and slots mechanism, that lets you easily assign
    behavior to graphical elements. All properties set in \QD can be changed
    dynamically within the code. Furthermore, features like widget promotion
    and custom plugins allow you to use your own components with \QD.

    If you are new to \QD, you can take a look at the
    \l{Getting To Know Qt Designer} document. For a quick tutorial on how to
    use \QD, refer to \l{A Quick Start to Qt Designer}.

    \image designer-multiple-screenshot.png

    For more information on using \QD, you can take a look at the following
    links:

    \list
        \o  \l{Qt Designer's Editing Modes}
            \list
                \o  \l{Qt Designer's Widget Editing Mode}{Widget Editing Mode}
                \o  \l{Qt Designer's Signals and Slots Editing Mode}
                      {Signals and Slots Editing Mode}
                \o  \l{Qt Designer's Buddy Editing Mode}
                      {Buddy Editing Mode}
                \o  \l{Qt Designer's Tab Order Editing Mode}
                      {Tab Order Editing Mode}
            \endlist
        \o  \l{Using Layouts in Qt Designer}
        \o  \l{Saving, Previewing and Printing Forms in Qt Designer}
        \o  \l{Using Containers in Qt Designer}
        \o  \l{Creating Main Windows in Qt Designer}
        \o  \l{Editing Resources with Qt Designer}
        \o  \l{Using Stylesheets with Qt Designer}
        \o  \l{Using a Designer UI File in Your Application}
    \endlist

    For advanced usage of \QD, you can refer to these links:

    \list
        \o  \l{Customizing Qt Designer Forms}
        \o  \l{Using Custom Widgets with Qt Designer}
        \o  \l{Creating Custom Widgets for Qt Designer}
        \o  \l{Creating Custom Widget Extensions}
        \o  \l{Qt Designer's UI File Format}
    \endlist


    \section1 Legal Notices

    Some source code in \QD is licensed under specific highly permissive
    licenses from the original authors. The Qt team gratefully acknowledges
    these contributions to \QD and all uses of \QD should also acknowledge
    these contributions and quote the following license statements in an
    appendix to the documentation.

    \list
    \i \l{Implementation of the Recursive Shadow Casting Algorithm in Qt Designer}
    \endlist
*/


/*!
    \page designer-to-know.html
    \contentspage {Qt Designer Manual}{Contents}


    \title Getting to Know Qt Designer

    \tableofcontents

    \image designer-screenshot.png

    \section1 Launching Designer

    The way that you launch \QD depends on your platform:

    \list
        \i On Windows, click the Start button, under the \gui Programs submenu,
           open the \gui{Qt 4} submenu and click \gui Designer.
        \i On Unix or Linux, you might find a \QD icon on the desktop
           background or in the desktop start menu under the \gui Programming
           or \gui Development submenus. You can launch \QD from this icon.
           Alternatively, you can type \c{designer} in a terminal window.
        \i On Mac OS X, double click on \QD in \gui Finder.
    \endlist

    \section1 The User Interface

    When used as a standalone application, \QD's user interface can be
    configured to provide either a multi-window user interface (the default
    mode), or it can be used in docked window mode. When used from within an
    integrated development environment (IDE) only the multi-window user
    interface is available. You can switch modes in the \gui Preferences dialog
    from the \gui Edit menu.

    In multi-window mode, you can arrange each of the tool windows to suit your
    working style. The main window consists of a menu bar, a tool bar, and a
    widget box that contains the widgets you can use to create your user
    interface.

    \target MainWindow
    \table
        \row
            \i \inlineimage designer-main-window.png
            \i \bold{Qt Designer's Main Window}

        The menu bar provides all the standard actions for managing forms,
        using the clipboard, and accessing application-specific help.
        The current editing mode, the tool windows, and the forms in use can
        also be accessed via the menu bar.

        The tool bar displays common actions that are used when editing a form.
        These are also available via the main menu.

        The widget box provides common widgets and layouts that are used to
        design components. These are grouped into categories that reflect their
        uses or features.
    \endtable

    Most features of \QD are accessible via the menu bar, the tool bar, or the
    widget box. Some features are also available through context menus that can
    be opened over the form windows. On most platforms, the right mouse is used
    to open context menus.

    \target WidgetBox
    \table
        \row
            \i \inlineimage designer-widget-box.png
            \i \bold{Qt Designer's Widget Box}

        The widget box provides a selection of standard Qt widgets, layouts,
        and other objects that can be used to create user interfaces on forms.
        Each of the categories in the widget box contain widgets with similar
        uses or related features.

        \note Since Qt 4.4, new widgets have been included, e.g.,
        QPlainTextEdit, QCommandLinkButton, QScrollArea, QMdiArea, and
        QWebView.

        You can display all of the available objects in a category by clicking
        on the handle next to the category label. When in
        \l{Qt Designer's Widget Editing Mode}{Widget Editing
        Mode}, you can add objects to a form by dragging the appropriate items
        from the widget box onto the form, and dropping them in the required
        locations.

        \QD provides a scratch pad feature that allows you to collect
        frequently used objects in a separate category. The scratch pad
        category can be filled with any widget currently displayed in a form
        by dragging them from the form and dropping them onto the widget box.
        These widgets can be used in the same way as any other widgets, but
        they can also contain child widgets. Open a context menu over a widget
        to change its name or remove it from the scratch pad.
    \endtable


    \section1 The Concept of Layouts in Qt

    A layout is used to arrange and manage the elements that make up a user
    interface. Qt provides a number of classes to automatically handle layouts
    -- QHBoxLayout, QVBoxLayout, QGridLayout, and QFormLayout. These classes
    solve the challenge of laying out widgets automatically, providing a user
    interface that behaves predictably. Fortunately knowledge of the layout
    classes is not required to arrange widgets with \QD. Instead, select one of
    the \gui{Lay Out Horizontally}, \gui{Lay Out in a Grid}, etc., options from
    the context menu.

    Each Qt widget has a recommended size, known as \l{QWidget::}{sizeHint()}.
    The layout manager will attempt to resize a widget to meet its size hint.
    In some cases, there is no need to have a different size. For example, the
    height of a QLineEdit is always a fixed value, depending on font size and
    style. In other cases, you may require the size to change, e.g., the width
    of a QLineEdit or the width and height of item view widgets. This is where
    the widget size constraints -- \l{QWidget::minimumSize()}{minimumSize} and
    \l{QWidget::maximumSize()}{maximumSize} constraints come into play. These
    are properties you can set in the property editor. For example, to override
    the default \l{QWidget::}{sizeHint()}, simply set
    \l{QWidget::minimumSize()}{minimumSize} and \l{QWidget::maximumSize()}
    {maximumSize} to the same value. Alternatively, to use the current size as
    a size constraint value, choose one of the \gui{Size Constraint} options
    from the widget's context menu. The layout  will then ensure that those
    constraints are met. To control the size of your widgets via code, you can
    reimplement \l{QWidget::}{sizeHint()} in your code.

    The screenshot below shows the breakdown of a basic user interface designed
    using a grid. The coordinates on the screenshot show the position of each
    widget within the grid.

    \image addressbook-tutorial-part3-labeled-layout.png

    \note Inside the grid, the QPushButton objects are actually nested. The
    buttons on the right are first placed in a QVBoxLayout; the buttons at the
    bottom are first placed in a QHBoxLayout. Finally, they are put into
    coordinates (1,2) and (3,1) of the QGridLayout.

    To visualize, imagine the layout as a box that shrinks as much as possible,
    attempting to \e squeeze your widgets in a neat arrangement, and, at the
    same time, maximize the use of available space.

    Qt's layouts help when you:

    \list 1
        \i  Resize the user face to fit different window sizes.
        \i  Resize elements within the user interface to suit different
            localizations.
        \i  Arrange elements to adhere to layout guidelines for different
            platforms.
    \endlist

    So, you no longer have to worry about rearranging widgets for different
    platforms, settings, and languages.

    The example below shows how different localizations can affect the user
    interface. When a localization requires more space for longer text strings
    the Qt layout automatically scales to accommodate this, while ensuring that
    the user interface looks presentable and still matches the platform
    guidelines.

    \table
        \header
            \i  A Dialog in English
            \i  A Dialog in French
        \row
            \i  \image designer-english-dialog.png
            \i  \image designer-french-dialog.png
    \endtable

    The process of laying out widgets consists of creating the layout hierarchy
    while setting as few widget size constraints as possible.

    For a more technical perspective on Qt's layout classes, refer to the
    \l{Layout Management} documentation.
*/


/*!
    \page designer-quick-start.html
    \contentspage {Qt Designer Manual}{Contents}


    \title A Quick Start to Qt Designer

    Using \QD involves \bold four basic steps:

    \list 1
        \o  Choose your form and objects
        \o  Lay the objects out on the form
        \o  Connect the signals to the slots
        \o  Preview the form
    \endlist

    \image rgbController-screenshot.png

    Suppose you would like to design a small widget (see screenshot above) that
    contains the controls needed to manipulate Red, Green and Blue (RGB) values
    -- a type of widget that can be seen everywhere in image manipulation
    programs.

    \table
    \row
    \i \inlineimage designer-choosing-form.png
    \i \bold{Choosing a Form}

    You start by choosing \gui Widget from the \gui{New Form} dialog.
    \endtable


    \table
    \row
    \i  \inlineimage rgbController-arrangement.png
    \i  \bold{Placing Widgets on a Form}

    Drag three labels, three spin boxes and three vertical sliders on to your
    form. To change the label's default text, simply double-click on it. You
    can arrange them according to how you would like them to be laid out.
    \endtable

    To ensure that they are laid out exactly like this in your program, you
    need to place these widgets into a layout. We will do this in groups of
    three. Select the "RED" label. Then, hold down \key Ctrl while you select
    its corresponding spin box and slider. In the \gui{Form} menu, select
    \gui{Lay Out in a Grid}.

    \table
        \row
            \i \inlineimage rgbController-form-gridLayout.png
            \i \inlineimage rgbController-selectForLayout.png
    \endtable


    Repeat the step for the other two labels along with their corresponding
    spin boxes and sliders as well.

    The next step is to combine all three layouts into one \bold{main layout}.
    The main layout is the top level widget's (in this case, the QWidget)
    layout. It is important that your top level widget has a layout; otherwise,
    the widgets on your window will not resize when your window is resized. To
    set the layout, \gui{Right click} anywhere on your form, outside of the
    three separate layouts, and select \gui{Lay Out Horizontally}.
    Alternatively, you could also select \gui{Lay Out in a Grid} -- you will
    still see the same arrangement (shown below).

    \image rgbController-final-layout.png

    \note Main layouts cannot be seen on the form. To check if you have a main
    layout installed, try resizing your form; your widgets should resize
    accordingly. Alternatively, you can take a look at \QD's
    \gui{Object Inspector}. If your top level widget does not have a layout,
    you will see the broken layout icon next to it,
    \inlineimage rgbController-no-toplevel-layout.png
    .

    When you click on the slider and drag it to a certain value, you want the
    spin box to display the slider's position. To accomplish this behavior, you
    need to connect the slider's \l{QAbstractSlider::}{valueChanged()} signal
    to the spin box's \l{QSpinBox::}{setValue()} slot. You also need to make
    the reverse connections, e.g., connect the spin box's \l{QSpinBox::}
    {valueChanged()} signal to the slider's \l{QAbstractSlider::value()}
    {setValue()} slot.

    To do this, you have to switch to \gui{Edit Signals/Slots} mode, either by
    pressing \key{F4} or selecting \gui{Edit Signals/Slots} from the \gui{Edit}
    menu.

    \table
        \row
            \i \inlineimage rgbController-signalsAndSlots.png
            \i \bold{Connecting Signals to Slots}

        Click on the slider and drag the cursor towards the spin box. The
        \gui{Configure Connection} dialog, shown below, will pop up. Select the
        correct signal and slot and click \gui OK.
    \endtable

    \image rgbController-configure-connection1.png

    Repeat the step (in reverse order), clicking on the spin box and dragging
    the cursor towards the slider, to connect the spin box's
    \l{QSpinBox::}{valueChanged()} signal to the slider's
    \l{QAbstractSlider::value()}{setValue()} slot.

    You can use the screenshot below as a guide to selecting the correct signal
    and slot.

    \image rgbController-configure-connection2.png

    Now that you have successfully connected the objects for the "RED"
    component of the RGB Controller, do the same for the "GREEN" and "BLUE"
    components as well.

    Since RGB values range between 0 and 255, we need to limit the spin box
    and slider to that particular range.

    \table
        \row
            \i \inlineimage rgbController-property-editing.png
            \i \bold{Setting Widget Properties}

        Click on the first spin box. Within the \gui{Property Editor}, you will
        see \l{QSpinBox}'s properties. Enter "255" for the
        \l{QSpinBox::}{maximum} property. Then, click on the first vertical
        slider, you will see \l{QAbstractSlider}'s properties. Enter "255" for
        the \l{QAbstractSlider::}{maximum} property as well. Repeat this
        process for the remaining  spin boxes and sliders.
    \endtable

    Now, we preview your form to see how it would look in your application -
    press \key{Ctrl + R} or select \gui Preview from the \gui Form menu. Try
    dragging the slider - the spin box will mirror its value too (and vice
    versa). Also, you can resize it to see how the layouts that are used to
    manage the child widgets, respond to different window sizes.
*/


/*!
    \page designer-editing-mode.html
    \previouspage Getting to Know Qt Designer
    \contentspage {Qt Designer Manual}{Contents}
    \nextpage Using Layouts in Qt Designer

    \title Qt Designer's Editing Modes

    \QD provides four editing modes: \l{Qt Designer's Widget Editing Mode}
    {Widget Editing Mode}, \l{Qt Designer's Signals and Slots Editing Mode}
    {Signals and Slots Editing Mode}, \l{Qt Designer's Buddy Editing Mode}
    {Buddy Editing Mode} and \l{Qt Designer's Tab Order Editing Mode}
    {Tab Order Editing Mode}. When working with \QD, you will always be in one
    of these four modes. To switch between modes, simply select it from the
    \gui{Edit} menu or the toolbar. The table below describes these modes in
    further detail.

    \table
        \header \i  \i  \bold{Editing Modes}
        \row
            \i  \inlineimage designer-widget-tool.png
            \i  In \l{Qt Designer's Widget Editing Mode}{Edit} mode, we can
                change the appearance of the form, add layouts, and edit the
                properties of each widget. To switch to this mode, press
                \key{F3}. This is \QD's default mode.

        \row
            \i  \inlineimage designer-connection-tool.png
            \i  In \l{Qt Designer's Signals and Slots Editing Mode}
                {Signals and Slots} mode, we can connect widgets together using
                Qt's signals and slots mechanism. To switch to this mode, press
                \key{F4}.

        \row
            \i  \inlineimage designer-buddy-tool.png
            \i  In \l{Qt Designer's Buddy Editing Mode}{Buddy Editing Mode},
                buddy widgets can be assigned to label widgets to help them
                handle keyboard focus correctly.

        \row
            \i  \inlineimage designer-tab-order-tool.png
            \i  In \l{Qt Designer's Tab Order Editing Mode}
                {Tab Order Editing Mode}, we can set the order in which widgets
                receive the keyboard focus.
    \endtable

*/


/*!
    \page designer-widget-mode.html
    \previouspage Qt Designer's Editing Modes
    \contentspage {Qt Designer Manual}{Contents}
    \nextpage Qt Designer's Signals and Slots Editing Mode

    \title Qt Designer's Widget Editing Mode

    \image designer-editing-mode.png

    In the Widget Editing Mode, objects can be dragged from the main window's
    widget box to a form, edited, resized, dragged around on the form, and even
    dragged between forms. Object properties can be modified interactively, so
    that changes can be seen immediately. The editing interface is intuitive
    for simple operations, yet it still supports Qt's powerful layout
    facilities.


    \tableofcontents

    To create and edit new forms, open the \gui File menu and select
    \gui{New Form...} or press \key{Ctrl+N}. Existing forms can also be edited
    by selecting \gui{Open Form...} from the \gui File menu or pressing
    \key{Ctrl+O}.

    At any point, you can save your form by selecting the \gui{Save From As...}
    option from the \gui File menu. The UI files saved by \QD contain
    information about the objects used, and any details of signal and slot
    connections between them.


    \section1 Editing A Form

    By default, new forms are opened in widget editing mode. To switch to Edit
    mode from another mode, select \gui{Edit Widgets} from the \gui Edit menu
    or press the \key F3 key.

    Objects are added to the form by dragging them from the main widget box
    and dropping them in the desired location on the form. Once there, they
    can be moved around simply by dragging them, or using the cursor keys.
    Pressing the \key Ctrl key at the same time moves the selected widget
    pixel by pixel, while using the cursor keys alone make the selected widget
    snap to the grid when it is moved. Objects can be selected by clicking on
    them with the left mouse button. You can also use the \key Tab key to
    change the selection.

    ### Screenshot of widget box, again

    The widget box contains objects in a number of different categories, all of
    which can be placed on the form as required. The only objects that require
    a little more preparation are the \gui Container widgets. These are
    described in further detail in the \l{Using Containers in Qt Designer}
    chapter.


    \target SelectingObjects
    \table
        \row
            \i  \inlineimage designer-selecting-widget.png
            \i  \bold{Selecting Objects}

        Objects on the form are selected by clicking on them with the left
        mouse button. When an object is selected, resize handles are shown at
        each corner and the midpoint of each side, indicating that it can be
        resized.

        To select additional objects, hold down the \key Shift key and click on
        them. If more than one object is selected, the current object will be
        displayed with resize handles of a different color.

        To move a widget within a layout, hold down \key Shift and \key Control
        while dragging the widget. This extends the selection to the widget's
        parent layout.

        Alternatively, objects can be selected in the
        \l{The Object Inspector}{Object Inspector}.
    \endtable

    When a widget is selected, normal clipboard operations such as cut, copy,
    and paste can be performed on it. All of these operations can be done and
    undone, as necessary.

    The following shortcuts can be used:

    \target ShortcutsForEditing
    \table
        \header \i Action       \i Shortcut     \i Description
        \row
            \i Cut
            \i \key{Ctrl+X}
            \i Cuts the selected objects to the clipboard.
        \row
            \i Copy
            \i \key{Ctrl+C}
            \i Copies the selected objects to the clipboard.
        \row
            \i Paste
            \i \key{Ctrl+V}
            \i Pastes the objects in the clipboard onto the form.
        \row
            \i Delete
            \i \key Delete
            \i Deletes the selected objects.
        \row
            \i Clone object
            \i \key{Ctrl+drag} (leftmouse button)
            \i Makes a copy of the selected object or group of objects.
        \row
            \i Preview
            \i \key{Ctrl+R}
            \i Shows a preview of the form.
    \endtable

    All of the above actions (apart from cloning) can be accessed via both the
    \gui Edit menu and the form's context menu. These menus also provide
    funcitons for laying out objects as well as a \gui{Select All} function to
    select all the objects on the form.

    Widgets are not unique objects; you can make as many copies of them as you
    need. To quickly duplicate a widget, you can clone it by holding down the
    \key Ctrl key and dragging it. This allows widgets to be copied and placed
    on the form more quickly than with clipboard operations.


    \target DragAndDrop
    \table
        \row
            \i \inlineimage designer-dragging-onto-form.png
            \i \bold{Drag and Drop}

        \QD makes extensive use of the drag and drop facilities provided by Qt.
        Widgets can be dragged from the widget box and dropped onto the form.

        Widgets can also be "cloned" on the form: Holding down \key Ctrl and
        dragging the widget creates a copy of the widget that can be dragged to
        a new position.

        It is also possible to drop Widgets onto the \l {The Object Inspector}
        {Object Inspector} to handle nested layouts easily.
    \endtable

    \QD allows selections of objects to be copied, pasted, and dragged between
    forms. You can use this feature to create more than one copy of the same
    form, and experiment with different layouts in each of them.


    \section2 The Property Editor

    The Property Editor always displays properties of the currently selected
    object on the form. The available properties depend on the object being
    edited, but all of the widgets provided have common properties such as
    \l{QObject::}{objectName}, the object's internal name, and
    \l{QWidget::}{enabled}, the property that determines whether an
    object can be interacted with or not.


    \target EditingProperties
    \table
        \row
            \i \inlineimage designer-property-editor.png
            \i \bold{Editing Properties}

        The property editor uses standard Qt input widgets to manage the
        properties of jbects on the form. Textual properties are shown in line
        edits, integer properties are displayed in spinboxes, boolean
        properties are displayed in check boxes, and compound properties such
        as colors and sizes are presented in drop-down lists of input widgets.

        Modified properties are indicated with bold labels. To reset them, click
        the arrow button on the right.

        Changes in properties are applied to all selected objects that have the
        same property.
    \endtable

    Certain properties are treated specially by the property editor:

    \list
        \o Compound properties -- properties that are made up of more than one
           value -- are represented as nodes that can be expanded, allowing
           their values to be edited.
        \o Properties that contain a choice or selection of flags are edited
           via combo boxes with checkable items.
        \o Properties that allow access to rich data types, such as QPalette,
           are modified using dialogs that open when the properties are edited.
           QLabel and the widgets in the \gui Buttons section of the widget box
           have a \c text property that can also be edited by double-clicking
           on the widget or by pressing \gui F2. \QD interprets the backslash
           (\\) character specially, enabling newline (\\n) characters to be
           inserted into the text; the \\\\ character sequence is used to
           insert a single backslash into the text. A context menu can also be
           opened while editing, providing another way to insert special
           characters and newlines into the text.
    \endlist


    \section2 Dynamic Properties

    The property editor can also be used to add new
    \l{QObject#Dynamic Properties}{dynamic properties} to both standard Qt
    widgets and to forms themselves. Since Qt 4.4, dynamic properties are added
    and removed via the property editor's toolbar, shown below.

    \image designer-property-editor-toolbar.png

    To add a dynamic property, clcik on the \gui Add button
    \inlineimage designer-property-editor-add-dynamic.png
    . To remove it, click on the \gui Remove button
    \inlineimage designer-property-editor-remove-dynamic.png
     instead. You can also sort the properties alphabetically and change the
    color groups by clickinig on the \gui Configure button
    \inlineimage designer-property-editor-configure.png
    .

    \section2 The Object Inspector
    \table
        \row
            \i  \inlineimage designer-object-inspector.png
            \i  \bold{The Object Inspector}

        The \gui{Object Inspector} displays a hierarchical list of all the
        objects on the form that is currently being edited. To show the child
        objects of a container widget or a layout, click the handle next to the
        object label.

        Each object on a form can be selected by clicking on the corresponding
        item in the \gui{Object Inspector}. Right-clicking opens the form's
        context menu. These features can be useful if you have many overlapping
        objects. To locate an object in the \gui{Object Inspector}, use
        \key{Ctrl+F}.

        Since Qt 4.4, double-clicking on the object's name allows you to change
        the object's name with the in-place editor.

        Since Qt 4.5, the \gui{Object Inspector} displays the layout state of
        the containers. The broken layout icon ###ICON is displayed if there is
        something wrong with the layouts.

    \endtable
*/


/*!
    \page designer-layouts.html
    \previouspage Qt Designer's Widget Editing Mode
    \contentspage
    \nextpage Qt Designer's Signals and Slots Editing Mode

    \title Using Layouts in Qt Designer

    Before a form can be used, the objects on the form need to be placed into
    layouts. This ensures that the objects will be displayed properly when the
    form is previewed or used in an application. Placing objects in a layout
    also ensures that they will be resized correctly when the form is resized.


    \tableofcontents

    \section1 Applying and Breaking Layouts

    The simplest way to manage objects is to apply a layout to a group of
    existing objects. This is achieved by selecting the objects that you need
    to manage and applying one of the standard layouts using the main toolbar,
    the \gui Form menu, or the form's context menu.

    Once widgets have been inserted into a layout, it is not possible to move
    and resize them individually because the layout itself controls the
    geometry of each widget within it, taking account of the hints provided by
    spacers. Instead, you must either break the layout and adjust each object's
    geometry manually, or you can influence the widget's geometry by resizing
    the layout.

    To break the layout, press \key{Ctrl+0} or choose \gui{Break Layout} from
    the form's context menu, the \gui Form menu or the main toolbar. You can
    also add and remove spacers from the layout to influence the geometries of
    the widgets.


    \target InsertingObjectsIntoALayout
    \table
        \row
            \i  \inlineimage designer-layout-inserting.png
            \i  \bold{Inserting Objects into a Layout}

        Objects can be inserted into an existing layout by dragging them from
        their current positions and dropping them at the required location. A
        blue cursor is displayed in the layout as an object is dragged over
        it to indicate where the object will be added.
    \endtable


    \section2 Setting A Top Level Layout

    The form's top level layout can be set by clearing the slection (click the
    left mouse button on the form itself) and applying a layout. A top level
    layout is necessary to ensure that your widgets will resize correctly when
    its window is resized. To check if you have set a top level layout, preview
    your widget and attempt to resize the window by dragging the size grip.

    \table
        \row
            \i  \inlineimage designer-set-layout.png
            \i  \bold{Applying a Layout}

        To apply a layout, you can select your choice of layout from the
        toolbar shown on the left, or from the context menu shown below.
    \endtable

    \image designer-set-layout2.png


    \section2 Horizontal and Vertical Layouts

    The simplest way to arrange objects on a form is to place them in a
    horizontal or vertical layout. Horizontal layouts ensure that the widgets
    within are aligned horizontally; vertical layouts ensure that they are
    aligned vertically.

    Horizontal and vertical layouts can be combined and nested to any depth.
    However, if you need more control over the placement of objects, consider
    using the grid layout.


    \section3 The Grid Layout

    Complex form layouts can be created by placing objects in a grid layout.
    This kind of layout gives the form designer much more freedom to arrange
    widgets on the form, but can result in a much less flexible layout.
    However, for some kinds of form layout, a grid arrangement is much more
    suitable than a nested arrangement of horizontal and vertical layouts.


    \section3 Splitter Layouts

    Another common way to manage the layout of objects on a form is to place
    them in a splitter. These splitters arrange the objects horizontally or
    vertically in the same way as normal layouts, but also allow the user to
    adjust the amount of space allocated to each object.

    \image designer-splitter-layout.png

    Although QSplitter is a container widget, \QD treats splitter objects as
    layouts that are applied to existing widgets. To place a group of widgets
    into a splitter, select them
    \l{Qt Designer's Widget Editing Mode#SelectingObjects}{as described here}
    then apply the splitter layout by using the appropriate toolbar button,
    keyboard shortcut, or \gui{Lay out} context menu entry.


    \section3 The Form Layout

    Since Qt 4.4, another layout class has been included -- QFormLayout. This
    class manages widgets in a two-column form; the left column holds labels
    and the right column holds field widgets such as line edits, spin boxes,
    etc. The QFormLayout class adheres to various platform look and feel
    guidelines and supports wrapping for long rows.

    \image designer-form-layout.png

    The UI file above results in the previews shown below.

    \table
        \header
            \i  Windows XP
            \i  Mac OS X
            \i  Cleanlooks
        \row
            \i  \inlineimage designer-form-layout-windowsXP.png
            \i  \inlineimage designer-form-layout-macintosh.png
            \i  \inlineimage designer-form-layout-cleanlooks.png
    \endtable


    \section2 Shortcut Keys

    In addition to the standard toolbar and context menu entries, there is also
    a set of keyboard shortcuts to apply layouts on widgets.

    \target LayoutShortcuts
    \table
        \header
            \i  Layout
            \i  Shortcut
            \i  Description
        \row
            \i  Horizontal
            \i  \key{Ctrl+1}
            \i  Places the selected objects in a horizontal layout.
        \row
            \i  Vertical
            \i  \key{Ctrl+2}
            \i  Places the selected objects in a vertical layout.
        \row
            \i  Grid
            \i  \key{Ctrl+5}
            \i  Places the selected objects in a grid layout.
        \row
            \i  Form
            \i  \key{Ctrl+6}
            \i  Places the selected objects in a form layout.
        \row
            \i  Horizontal splitter
            \i  \key{Ctrl+3}
            \i  Creates a horizontal splitter and places the selected objects
                inside it.
        \row
            \i  Vertical splitter
            \i  \key{Ctrl+4}
            \i  Creates a vertical splitter and places the selected objects
                inside it.
        \row
            \i  Adjust size
            \i  \key{Ctrl+J}
            \i  Adjusts the size of the layout to ensure that each child object
                has sufficient space to display its contents. See
                QWidget::adjustSize() for more information.
    \endtable

    \note \key{Ctrl+0} is used to break a layout.

*/


/*!
    \page designer-preview.html
    \contentspage {Qt Designer Manual}{Contents}
    \previouspage Using Layouts in Qt Designer
    \nextpage Qt Designer's Buddy Editing Mode
    \title Saving, Previewing and Printing Forms in Qt Designer

    Although \QD's forms are accurate representations of the components being
    edited, it is useful to preview the final appearance while editing. This
    feature can be activated by opening the \gui Form menu and selecting
    \gui Preview, or by pressing \key{Ctrl+R} when in the form.

    \image designer-dialog-preview.png

    The preview shows exactly what the final component will look like when used
    in an application.

    Since Qt 4.4, it is possible to preview forms with various skins - default
    skins, skins created with Qt Style Sheets or device skins. This feature
    simulates the effect of calling \c{QApplication::setStyleSheet()} in the
    application.

    To preview your form with skins, open the \gui Edit menu and select
    \gui{Preferences...}

    You will see the dialog shown below:

    \image designer-preview-style.png

    The \gui{Print/Preview Configuration} checkbox must be checked to activate
    previews of skins. You can select the styles provided from the \gui{Style}
    drop-down box.

    \image designer-preview-style-selection.png

    Alternatively, you can preview custom style sheet created with Qt Style
    Sheets. The figure below shows an example of Qt Style Sheet syntax and the
    corresponding output.

    \image designer-preview-stylesheet.png

    Another option would be to preview your form with device skins. A list of
    generic device skins are available in \QD, however, you may also use
    other QVFB skins with the \gui{Browse...} option.

    \image designer-preview-deviceskin-selection.png


    \section1 Viewing the Form's Code

    Since Qt 4.4, it is possible to view code generated by the User Interface
    Compiler (uic) for the \QD form.

    \image designer-form-viewcode.png

    Select \gui{View Code...} from the \gui{Form} menu and a dialog with the
    generated code will be displayed. The screenshot below is an example of
    code generated by the \c{uic}.

    \image designer-code-viewer.png

    \section1 Saving and Printing the Form

    Forms created in \QD can be saved to an image or printed.

    \table
    \row
    \i \inlineimage designer-file-menu.png
    \i \bold{Saving Forms}

    To save a form as an image, choose the \gui{Save Image...} option. The file
    will be saved in \c{.png} format.

    \bold{Printing Forms}

    To print a form, select the \gui{Print...} option.

    \endtable
*/


/*!
    \page designer-connection-mode.html
    \contentspage {Qt Designer Manual}{Contents}
    \previouspage Using Layouts in Qt Designer
    \nextpage Qt Designer's Buddy Editing Mode


    \title Qt Designer's Signals and Slots Editing Mode

    \image designer-connection-mode.png

    In \QD's signals and slots editing mode, you can connect objects in a form
    together using Qt's signals and slots mechanism. Both widgets and layouts
    can be connected via an intuitive connection interface, using the menu of
    compatible signals and slots provided by \QD. When a form is saved, all
    connections are preserved so that they will be ready for use when your
    project is built.


    \tableofcontents

    For more information on Qt's signals and sltos mechanism, refer to the
    \l{Signals and Slots} document.


    \section1 Connecting Objects

    To begin connecting objects, enter the signals and slots editing mode by
    opening the \gui Edit menu and selecting \gui{Edit Signals/Slots}, or by
    pressing the \key F4 key.

    All widgets and layouts on the form can be connected together. However,
    spacers just provide spacing hints to layouts, so they cannot be connected
    to other objects.


    \target HighlightedObjects
    \table
        \row
            \i  \inlineimage designer-connection-highlight.png
            \i  \bold{Highlighted Objects}

        When the cursor is over an object that can be used in a connection, the
        object will be highlighted.
    \endtable

    To make a connectionn, press the left mouse button and drag the cursor
    towards the object you want to connect it to. As you do this, a line will
    extend from the source object to the cursor. If the cursor is over another
    object on the form, the line will end with an arrow head that points to the
    destination object. This indicates that a connection will be made between
    the two objects when you release the mouse button.

    You can abandon the connection at any point while you are dragging the
    connection path by pressing \key{Esc}.

    \target MakingAConnection
    \table
        \row
            \i  \inlineimage designer-connection-making.png
            \i  \bold{Making a Connection}

        The connection path will change its shape as the cursor moves around
        the form. As it passes over objects, they are highlighted, indicating
        that they can be used in a signal and slot connection. Release the
        mouse button to make the connection.
    \endtable

    The \gui{Configure Connection} dialog (below) is displayed, showing signals
    from the source object and slots from the destination object that you can
    use.

    \image designer-connection-dialog.png

    To complete the connection, select a signal from the source object and a
    slot from the destination object, then click \key OK. Click \key Cancel if
    you wish to abandon the connection.

    \note If the \gui{Show all signals and slots} checkbox is selected, all
    available signals from the source object will be shown. Otherwise, the
    signals and slots inherited from QWidget will be hidden.

    You can make as many connections as you like between objects on the form;
    it is possible to connect signals from objects to slots in the form itself.
    As a result, the signal and slot connections in many dialogs can be
    completely configured from within \QD.