/****************************************************************************
**
** Copyright (C) 2004-2008 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License versions 2.0 or 3.0 as published by the Free Software
** Foundation and appearing in the files LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file.  Alternatively you may (at
** your option) use any later version of the GNU General Public
** License if such license has been publicly approved by Trolltech ASA
** (or its successors, if any) and the KDE Free Qt Foundation.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/. If
** you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech, as the sole
** copyright holder for Qt Designer, grants users of the Qt/Eclipse
** Integration plug-in the right for the Qt/Eclipse Integration to
** link to functionality provided by Qt Designer and its related
** libraries.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not expressly
** granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \page layout.html

    \title Layout Classes
    \ingroup architecture
    \ingroup classlists
    \brief A tour of the standard layout managers and an introduction
    to custom layouts.

    The Qt layout system provides a simple and powerful way of
    automatically arranging child widgets within a widget to ensure
    that they make good use of the available space.

    \tableofcontents

    \section1 Introduction

    Qt includes a set of layout management classes that are used to describe
    how widgets are laid out in an application's user interface. These layouts
    automatically position and resize widgets when the available space for
    them changes, ensuring that they are consistently arranged and that the
    user interface as a whole remains usable.

    All QWidget subclasses can use layouts to manage their children. The
    QWidget::setLayout() function applies a layout to a widget. When a layout
    is set on a widget in this way, it takes charge of the following tasks:

    \list
    \o Positioning of child widgets.
    \o Sensible default sizes for windows.
    \o Sensible minimum sizes for windows.
    \o Resize handling.
    \o Automatic updates when contents change:
        \list
        \o Font size, text or other contents of child widgets.
        \o Hiding or showing a child widget.
        \o Removal of child widgets.
        \endlist
    \endlist

    Qt's layout classes were designed for hand-written C++ code, allowing
    measurements to be specified in pixels for simplicity, so they're easy
    to understand and use. The code generated for forms created using
    \l{Qt Designer} also uses the layout classes. \QD is also useful to
    use when experimenting with the design of a form since it avoids the
    compile, link and run cycle usually involved in user interface
    development.

    \section1 Horizontal, Vertical, and Grid Layouts

    The easiest way to give your widgets a good layout is to use the
    built-in layout managers: QHBoxLayout, QVBoxLayout, and
    QGridLayout. These classes inherit from QLayout, which in turn
    derives from QObject (not QWidget). They take care of geometry
    management for a set of widgets. To create more complex layouts,
    you can nest layout managers inside each other.

    \list
    \o A QHBoxLayout lays out widgets in a horizontal row,
       from left to right (or right to left for right-to-left
       languages).

       \image qhboxlayout-with-5-children.png A QHBoxLayout with five child widgets

    \o A QVBoxLayout lays out widgets in a vertical column, from top
       to bottom.

       \image qvboxlayout-with-5-children.png A QVBoxLayout with five child widgets

    \o A QGridLayout lays out widgets in a two-dimensional grid.
       Widgets can occupy multiple cells.

       \image qgridlayout-with-5-children.png A QGridLayout with five child widgets
    \endlist

    The following code creates a QHBoxLayout that manages the
    geometry of five \l{QPushButton}s, as shown on the first
    screenshot above:

    \snippet doc/src/snippets/layouts/layouts.cpp 0
    \snippet doc/src/snippets/layouts/layouts.cpp 1
    \snippet doc/src/snippets/layouts/layouts.cpp 2
    \codeline
    \snippet doc/src/snippets/layouts/layouts.cpp 3
    \snippet doc/src/snippets/layouts/layouts.cpp 4
    \snippet doc/src/snippets/layouts/layouts.cpp 5

    The code for QVBoxLayout is identical, except the line where the
    layout is created. The code for QGridLayout is a bit different,
    because we need to specify the row and column position of the
    child widget:

    \snippet doc/src/snippets/layouts/layouts.cpp 12
    \snippet doc/src/snippets/layouts/layouts.cpp 13
    \snippet doc/src/snippets/layouts/layouts.cpp 14
    \codeline
    \snippet doc/src/snippets/layouts/layouts.cpp 15
    \snippet doc/src/snippets/layouts/layouts.cpp 16
    \snippet doc/src/snippets/layouts/layouts.cpp 17

    The third QPushButton spans 2 columns. This is possible by
    specifying 2 as the fifth argument to QGridLayout::addWidget().

    When you use a layout, you don't need to pass a parent when
    constructing the child widgets. The layout will automatically
    reparent the widgets (using QWidget::setParent()) so that they
    are children of the widget on which the layout is installed.

    \bold{Important:} Widgets in a layout are children of the widget
    on which the layout is installed, \e not of the layout itself.
    Widgets can only have other widgets as parent, not layouts.

    You can nest layouts using \c addLayout() on a layout; the inner
    layout then becomes a child of the layout it is inserted into.
    The \l{layouts/basiclayouts}{Basic Layouts} example uses this
    feature to create a complex dialog.

    \section1 Adding Widgets to a Layout

    When you add widgets to a layout, the layout process works as
    follows:

    \list 1
    \o All the widgets will initially be allocated an amount of space in
       accordance with their QWidget::sizePolicy(). 

    \o If any of the widgets have stretch factors set, with a value
       greater than zero, then they are allocated space in proportion
       to their stretch factor (explained below).

    \o If any of the widgets have stretch factors set to zero they
       will only get more space if no other widgets want the space.
       Of these, space is allocated to widgets with an
       \l{QSizePolicy::Expanding}{Expanding} size policy first.

    \o Any widgets that are allocated less space than their minimum size
       (or minimum size hint if no minimum size is specified) are allocated
       this minimum size they require. (Widgets don't have to have a minimum
       size or minimum size hint in which case the strech factor is their
       determining factor.)

    \o Any widgets that are allocated more space than their maximum size
       are allocated the maximum size space they require. (Widgets don't have
       to have a maximum size in which case the strech factor is their
       determining factor.)
    \endlist

    \section2 Stretch Factors
    \keyword stretch factor

    Widgets are normally created without any stretch factor set. When
    they are laid out in a layout the widgets are given a share of
    space in accordance with their QWidget::sizePolicy() or their
    minimum size hint whichever is the greater. Stretch factors are
    used to change how much space widgets are given in proportion to
    one another.

    If we have three widgets laid out using a QHBoxLayout with no
    stretch factors set we will get a layout like this:

    \img layout1.png Three widgets in a row

    If we apply stretch factors to each widget, they will be laid out in
    proportion (but never less than their minimum size hint), e.g.

    \img layout2.png Three widgets with different stretch factors in a row

    \section1 Custom Widgets in Layouts

    When you make your own widget class, you should also communicate its
    layout properties. If the widget has a QLayout, this is already taken
    care of. If the widget does not have any child widgets, or uses manual
    layout, you can change the behavior of the widget using any or all of
    the following mechanisms:

    \list
    \o Reimplement QWidget::sizeHint() to return the preferred size of the
       widget.
    \o Reimplement QWidget::minimumSizeHint() to return the smallest size the
       widget can have.
    \o Call QWidget::setSizePolicy() to specify the space requirements of the
       widget.
    \endlist

    Call QWidget::updateGeometry() whenever the size hint, minimum
    size hint or size policy changes. This will cause a layout
    recalculation. Multiple consecutive calls to
    QWidget::updateGeometry() will only cause one recalculation.

    If the preferred height of your widget depends on its actual
    width (e.g., a label with automatic word-breaking), set the
    \l{QSizePolicy::hasHeightForWidth()}{height-for-width} flag in
    the widget's \l{QWidget::sizePolicy}{size policy} and reimplement
    QWidget::heightForWidth().

    Even if you implement QWidget::heightForWidth(), it is still a
    good idea to provide a reasonable sizeHint().

    For further guidance when implementing these functions, see the
    \l{http://doc.trolltech.com/qq/qq04-height-for-width.html}{Trading
    Height for Width} article in \e{Qt Quarterly}.

    \section1 Layout Issues

    The use of rich text in a label widget can introduce some
    problems to the layout of its parent widget. Problems occur due
    to the way rich text is handled by Qt's layout managers when the
    label is word wrapped.

    In certain cases the parent layout is put into
    QLayout::FreeResize mode, meaning that it will not adapt the
    layout of its contents to fit inside small sized windows, or even
    prevent the user from making the window too small to be usable.
    This can be overcome by subclassing the problematic widgets, and
    implementing suitable sizeHint() and minimumSizeHint() functions.

    In some cases, it is relevant when a layout is added to a widget.
    When you set the widget of a QDockWidget or a QScrollArea (with
    QDockWidget::setWidget() and QScrollArea::setWidget()), the layout
    must already have been set on the widget. If not, the widget will
    not be visible.

    \section1 Manual Layout

    If you are making a one-of-a-kind special layout, you can also
    make a custom widget as described above. Reimplement
    QWidget::resizeEvent() to calculate the required distribution of
    sizes and call \l{QWidget::setGeometry()}{setGeometry()} on each
    child.

    The widget will get an event of type QEvent::LayoutRequest when
    the layout needs to be recalculated. Reimplement QWidget::event()
    to handle QEvent::LayoutRequest events.

    \section1 Writing Custom Layout Managers

    An alternative to manual layout is to write your own layout
    manager by subclassing QLayout. The
    \l{layouts/borderlayout}{Border Layout} and
    \l{layouts/flowlayout}{Flow Layout} examples show how to do this.

    Here we present an example in detail. The class CardLayout is
    inspired by the Java layout manager of the same name. It lays out
    the items (widgets or nested layouts) on top of each other, each
    item offset by QLayout::spacing().

    To write your own layout class, you must define the following:
    \list
    \o A data structure to store the items handled by the layout. Each
    item is a \link QLayoutItem QLayoutItem\endlink. We will use a
    QList in this example.
    \o \link QLayout::addItem() addItem() \endlink, how to add items to
    the layout.
    \o \link QLayout::setGeometry() setGeometry() \endlink, how to perform
    the layout.
    \o \link QLayout::sizeHint() sizeHint() \endlink, the preferred size
    of the layout.
    \o \link QLayout::itemAt() itemAt() \endlink, how to iterate over
    the layout.
    \o \link QLayout::takeAt() takeAt() \endlink, how to remove items
     from the layout.
    \endlist

    In most cases, you will also implement \link QLayout::minimumSize()
    minimumSize\endlink().

    \section2 The Header File (\c card.h)

    \snippet doc/src/snippets/code/doc_src_layout.qdoc 0

    \section2 The Implementation File (\c card.cpp)

    \snippet doc/src/snippets/code/doc_src_layout.qdoc 1

    First we define two functions that iterate over the layout: 
    itemAt() and takeAt(). These functions are used internally by the
    layout system to handle deletion of widgets. They are also available
    for application programmers. 

    ItemAt() returns the item at the given index. takeAt() removes the
    item at the given index, and returns it. In this case we use the list
    index as the layout index. In other cases where we have a more complex
    data structure, we may have to spend more effort defining a linear
    order for the items.

    \snippet doc/src/snippets/code/doc_src_layout.qdoc 2

    addItem() implements the default placement strategy for layout items.
    It must be implemented. It is used by QLayout::add(), by the QLayout
    constructor that takes a layout as parent. If your layout
    has advanced placement options that require parameters, you must
    provide extra access functions such as the row and column spanning
    overloads of \l QGridLayout::addItem(), addWidget(), and addLayout().

    \snippet doc/src/snippets/code/doc_src_layout.qdoc 3

    The layout takes over responsibility of the items added. Since
    QLayoutItem does not inherit QObject, we must delete the items
    manually. The function QLayout::deleteAllItems() uses takeAt()
    defined above to delete all the items in the layout.

    \snippet doc/src/snippets/code/doc_src_layout.qdoc 4

    The setGeometry() function actually performs the layout. The rectangle
    supplied as an argument does not include margin(). If relevant, use
    spacing() as the distance between items.

    \snippet doc/src/snippets/code/doc_src_layout.qdoc 5

    sizeHint() and minimumSize() are normally very similar in
    implementation. The sizes returned by both functions should include
    spacing(), but not margin().

    \snippet doc/src/snippets/code/doc_src_layout.qdoc 6

    \section2 Further Notes

    This layout does not handle height for width.

    We ignore QLayoutItem::isEmpty(), this means that the layout will
    treat hidden widgets as visible.

    For complex layouts, speed can be greatly increased by caching
    calculated values. In that case, implement QLayoutItem::invalidate()
    to mark the cached data as dirty.

    Calling QLayoutItem::sizeHint(), etc. may be expensive, so you should
    store the value in a local variable if you need it again later in the
    same function.

    You should not call QLayoutItem::setGeometry() twice on the same item
    in the same function. That can be very expensive if the item has
    several child widgets, because it must do a complete layout
    every time. Instead, calculate the geometry and then set it. (This
    doesn't only apply to layouts, you should do the same if you implement
    your own resizeEvent().)
*/
