--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/flowlayout.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,159 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+ \example layouts/flowlayout
+ \title Flow Layout Example
+
+ The Flow Layout example demonstrates a custom layout that arranges child
+ widgets from left to right and top to bottom in a top-level widget.
+
+ \image flowlayout-example.png Screenshot of the Flow Layout example
+
+ The items are first laid out horizontally and then vertically when each line
+ in the layout runs out of space.
+
+ The Flowlayout class mainly uses QLayout and QWidgetItem, while the
+ Window uses QWidget and QLabel. We will only document the definition
+ and implementation of \c FlowLayout below.
+
+ \section1 FlowLayout Class Definition
+
+ The \c FlowLayout class inherits QLayout. It is a custom layout class
+ that arranges its child widgets horizontally and vertically.
+
+ \snippet examples/layouts/flowlayout/flowlayout.h 0
+
+ We reimplement functions inherited from QLayout. These functions add items to
+ the layout and handle their orientation and geometry.
+
+ We also declare two private methods, \c doLayout() and \c smartSpacing().
+ \c doLayout() lays out the layout items, while the \c
+ smartSpacing() function calculates the spacing between them.
+
+ \section1 FlowLayout Class Implementation
+
+ We start off by looking at the constructor:
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 1
+
+ In the constructor we call \c setContentsMargins() to set the left, top,
+ right and bottom margin. By default, QLayout uses values provided by
+ the current style (see QStyle::PixelMetric).
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 2
+
+ In this example we reimplement \c addItem(), which is a pure virtual
+ function. When using \c addItem() the ownership of the layout items is
+ transferred to the layout, and it is therefore the layout's
+ responsibility to delete them.
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 3
+
+ \c addItem() is implemented to add items to the layout.
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 4
+
+ We implement \c horizontalSpacing() and \c verticalSpacing() to get
+ hold of the spacing between the widgets inside the layout. If the value
+ is less than or equal to 0, this value will be used. If not,
+ \c smartSpacing() will be called to calculate the spacing.
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 5
+
+ We then implement \c count() to return the number of items in the
+ layout. To navigate the list of items we use \c itemAt() and
+ takeAt() to remove and return items from the list. If an item is
+ removed, the remaining items will be renumbered. All three
+ functions are pure virtual functions from QLayout.
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 6
+
+ \c expandingDirections() returns the \l{Qt::Orientation}s in which the
+ layout can make use of more space than its \c sizeHint().
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 7
+
+ To adjust to widgets of which height is dependent on width, we implement \c
+ heightForWidth(). The function \c hasHeightForWidth() is used to test for this
+ dependency, and \c heightForWidth() passes the width on to \c doLayout() which
+ in turn uses the width as an argument for the layout rect, i.e., the bounds in
+ which the items are laid out. This rect does not include the layout margin().
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 8
+
+ \c setGeometry() is normally used to do the actual layout, i.e., calculate
+ the geometry of the layout's items. In this example, it calls \c doLayout()
+ and passes the layout rect.
+
+ \c sizeHint() returns the preferred size of the layout and \c minimumSize()
+ returns the minimum size of the layout.
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 9
+
+ \c doLayout() handles the layout if \c horizontalSpacing() or \c
+ verticalSpacing() don't return the default value. It uses
+ \c getContentsMargins() to calculate the area available to the
+ layout items.
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 10
+
+ It then sets the proper amount of spacing for each widget in the
+ layout, based on the current style.
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 11
+
+ The position of each item in the layout is then calculated by
+ adding the items width and the line height to the initial x and y
+ coordinates. This in turn lets us find out whether the next item
+ will fit on the current line or if it must be moved down to the next.
+ We also find the height of the current line based on the widgets height.
+
+ \snippet examples/layouts/flowlayout/flowlayout.cpp 12
+
+ \c smartSpacing() is designed to get the default spacing for either
+ the top-level layouts or the sublayouts. The default spacing for
+ top-level layouts, when the parent is a QWidget, will be determined
+ by querying the style. The default spacing for sublayouts, when
+ the parent is a QLayout, will be determined by querying the spacing
+ of the parent layout.
+
+*/