/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example layouts/flowlayout
    \title Flow Layout Example
    \ingroup examples-layout
    \brief Shows how to arrange widgets for different window sizes.

    \e{Flow Layout} implements a layout that handles different window sizes. The
    widget placement changes depending on the width of the application window.

    \image flowlayout-example.png Screenshot of the Flow Layout example

    The Flowlayout class mainly uses QLayout and QWidgetItem, while the
    Window uses QWidget and QLabel.

    For more information, visit the \l{Layout Management} page.

    \include examples-run.qdocinc

    \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 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 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 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 layouts/flowlayout/flowlayout.cpp 3

    \c addItem() is implemented to add items to the layout.

    \snippet 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 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 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 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 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 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 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 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 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.

*/