/****************************************************************************

**

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

** All rights reserved.

** 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 Technology Preview License Agreement accompanying

** this package.

**

** 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.

**

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

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

**

**

**

**

**

**

**

**

** $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.