Long live Qt 4.5!

1 files changed, 381 insertions, 0 deletions

diff --git a/doc/src/layout.qdoc b/doc/src/layout.qdoc
new file mode 100644
index 0000000..38163c8
--- /dev/null
+++ b/doc/src/layout.qdoc
@@ -0,0 +1,381 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, 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 are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \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 amount of space
+    available 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 are easy to
+    understand and use. The code generated for forms created using \QD also
+    uses the layout classes. \QD is 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, Grid, and Form Layouts
+
+    The easiest way to give your widgets a good layout is to use the built-in
+    layout managers: QHBoxLayout, QVBoxLayout, QGridLayout, and QFormLayout.
+    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
+
+        \o  A QVBoxLayout lays out widgets in a vertical column, from top to
+            bottom.
+            \image qvboxlayout-with-5-children.png
+
+        \o  A QGridLayout lays out widgets in a two-dimensional grid. Widgets
+            can occupy multiple cells.
+            \image qgridlayout-with-5-children.png
+
+        \o  A QFormLayout lays out widgets in a 2-column descriptive label-
+            field style.
+            \image qformlayout-with-6-children.png
+    \endlist
+
+
+    \section2 Laying Out Widgets in Code
+
+    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().
+
+    Finally, the code for QFormLayout is ..
+
+
+    \section2 Tips for Using Layouts
+
+    When you use a layout, you do not 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.
+
+    \note 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.
+
+
+    \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() and
+            QWidget::sizeHint().
+
+        \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 do not
+            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 one of Qt's layouts, 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 layout
+    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
+    \e{Qt Quarterly} article
+    \l{http://doc.trolltech.com/qq/qq04-height-for-width.html}
+    {Trading Height for Width}.
+
+
+    \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 \l{QWidget::}{sizeHint()} and
+    \l{QWidget::}{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()} 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 How to Write A Custom Layout Manager
+
+    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 \c CardLayout class 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  \l{QLayout::}{addItem()}, how to add items to the layout.
+        \o  \l{QLayout::}{setGeometry()}, how to perform the layout.
+        \o  \l{QLayout::}{sizeHint()}, the preferred size of the layout.
+        \o  \l{QLayout::}{itemAt()}, how to iterate over the layout.
+        \o  \l{QLayout::}{takeAt()}, how to remove items from the layout.
+    \endlist
+
+    In most cases, you will also implement \l{QLayout::}{minimumSize()}.
+
+
+    \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: \c{itemAt()}
+    and \c{takeAt()}. These functions are used internally by the layout system
+    to handle deletion of widgets. They are also available for application
+    programmers. 
+
+    \c{itemAt()} returns the item at the given index. \c{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
+
+    \c{addItem()} implements the default placement strategy for layout items.
+    This function 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
+    QGridLayout::addItem(), QGridLayout::addWidget(), and
+    QGridLayout::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 \c{takeAt()} defined above to delete all the
+    items in the layout.
+
+    \snippet doc/src/snippets/code/doc_src_layout.qdoc 4
+
+    The \c{setGeometry()} function actually performs the layout. The rectangle
+    supplied as an argument does not include \c{margin()}. If relevant, use
+    \c{spacing()} as the distance between items.
+
+    \snippet doc/src/snippets/code/doc_src_layout.qdoc 5
+
+    \c{sizeHint()} and \c{minimumSize()} are normally very similar in
+    implementation. The sizes returned by both functions should include
+    \c{spacing()}, but not \c{margin()}.
+
+    \snippet doc/src/snippets/code/doc_src_layout.qdoc 6
+
+
+    \section2 Further Notes
+
+    \list
+        \o  This custom layout does not handle height for width.
+        \o  We ignore QLayoutItem::isEmpty(); this means that the layout will
+            treat hidden widgets as visible.
+        \o  For complex layouts, speed can be greatly increased by caching
+            calculated values. In that case, implement
+            QLayoutItem::invalidate() to mark the cached data is dirty.
+        \o  Calling QLayoutItem::sizeHint(), etc. may be expensive. So, you
+            should store the value in a local variable if you need it again
+            later within in the same function.
+        \o  You should not call QLayoutItem::setGeometry() twice on the same
+            item in the smae function. This call can be very expensive if the
+            item has several child widgets, because the layout manager must do
+            a complete layout every time. Instead, calculate the geometry and
+            then set it. (This does not only apply to layouts, you should do
+            the same if you implement your own resizeEvent(), for example.)
+    \endlist
+*/
+