FCL/sf/mw/qt: comparison doc/src/widgets-and-layouts/layout.qdoc

equal deleted inserted replaced

--1:000000000000
+:1918ee327afb
+/****************************************************************************
+**
+** Copyright (C) 2009 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$
+**
+****************************************************************************/
+/*!
+\group geomanagement
+\title Layout Classes
+*/
+/*!
+\page layout.html
+\title Layout Management
+\brief A tour of the standard layout managers and an introduction to custom
+layouts.
+\previouspage Widget Classes
+\contentspage Widgets and Layouts
+\nextpage {Implementing Styles and Style Aware Widgets}{Styles}
+\ingroup frameworks-technologies
+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
+\section1 Qt's Layout Classes
+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.
+\annotatedlist geomanagement
+\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://qt.nokia.com/doc/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 \c{count()} to fetch the number of items in the list.
+\snippet doc/src/snippets/code/doc_src_layout.qdoc 2
+Then 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 3
+\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 4
+The layout takes over responsibility of the items added. Since QLayoutItem
+does not inherit QObject, we must delete the items manually. In the
+destructor, we remove each item from the list using \c{takeAt()}, and
+then delete it.
+\snippet doc/src/snippets/code/doc_src_layout.qdoc 5
+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 6
+\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 7
+\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 same 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
+*/