Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 164 insertions, 0 deletions

diff --git a/doc/src/examples/basicgraphicslayouts.qdoc b/doc/src/examples/basicgraphicslayouts.qdoc
new file mode 100644
index 0000000000..0110e29951
--- /dev/null
+++ b/doc/src/examples/basicgraphicslayouts.qdoc
@@ -0,0 +1,164 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 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:FDL$
+** 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 Free Documentation License
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example graphicsview/basicgraphicslayouts
+    \title Basic Graphics Layouts Example
+
+    The Basic Graphics Layouts example shows how to use the layout classes
+    in QGraphicsView: QGraphicsLinearLayout and QGraphicsGridLayout.
+    In addition to that it shows how to write your own custom layout item.
+
+    \image basicgraphicslayouts-example.png Screenshot of the Basic Layouts Example
+
+    \section1 Window Class Definition
+
+    The \c Window class is a subclass of QGraphicsWidget. It has a
+    constructor with a QGraphicsWidget \a parent as its parameter.
+
+    \snippet examples/graphicsview/basicgraphicslayouts/window.h 0
+
+    \section1 Window Class Implementation
+
+    The constructor of \c Window instantiates a QGraphicsLinearLayout object,
+    \c windowLayout, with vertical orientation. We instantiate another
+    QGraphicsLinearLayout object, \c linear, whose parent is \c windowLayout.
+    Next, we create a \c LayoutItem object, \c item and add it to \c linear
+    with the \l{QGraphicsLinearLayout::}{addItem()} function. We also provide
+    \c item with a \l{QGraphicsLinearLayout::setStretchFactor()}
+    {stretchFactor}.
+
+    \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 0
+
+    We repeat the process:
+
+    \list
+        \o create a new \c LayoutItem,
+        \o add the item \c linear, and
+        \o provide a stretch factor.
+    \endlist
+
+    \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 1
+
+    We then add \c linear to \c windowLayout, nesting two
+    QGraphicsLinearLayout objects. Apart from the QGraphicsLinearLayout, we
+    also use a QGraphicsGridLayout object, \c grid, which is a 4x3 grid with
+    some cells spanning to other rows.
+
+    We create seven \c LayoutItem objects and place them into \c grid with
+    the \l{QGraphicsGridLayout::}{addItem()} function as shown in the code
+    snippet below:
+
+    \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 2
+
+    The first item we add to \c grid is placed in the top left cell,
+    spanning four rows. The next two items are placed in the second column,
+    and they span two rows. Each item's \l{QGraphicsWidget::}{maximumHeight()}
+    and \l{QGraphicsWidget::}{minimumHeight()} are set to be equal so that
+    they do not expand vertically. As a result, these items will not
+    fit vertically in their cells. So, we specify that they should be
+    vertically aligned in the center of the cell using Qt::AlignVCenter.
+
+    Finally, \c grid itself is added to \c windowLayout. Unlike
+    QGridLayout::addItem(), QGraphicsGridLayout::addItem() requires a row
+    and a column for its argument, specifying which cell the item should be
+    positioned in. Also, if the \c rowSpan and \c columnSpan arguments
+    are omitted, they will default to 1.
+
+    Note that we do not specify a parent for each \c LayoutItem that we
+    construct, as all these items will be added to \c windowLayout. When we
+    add an item to a layout, it will be automatically reparented to the widget
+    on which the layout is installed.
+
+    \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 3
+
+    Now that we have set up \c grid and added it to \c windowLayout, we
+    install \c windowLayout onto the window object using
+    QGraphicsWidget::setLayout() and we set the window title.
+
+    \section1 LayoutItem Class Definition
+
+    The \c LayoutItem class is a subclass of QGraphicsLayoutItem and
+    QGraphicsItem. It has a constructor, a destructor, and some required
+    reimplementations.
+    Since it inherits QGraphicsLayoutItem it must reimplement
+    {QGraphicsLayoutItem::setGeometry()}{setGeometry()} and
+    {QGraphicsLayoutItem::sizeHint()}{sizeHint()}.
+    In addition to that it inherits QGraphicsItem, so it must reimplement
+    {QGraphicsItem::boundingRect()}{boundingRect()} and
+    {QGraphicsItem::paint()}{paint()}.
+
+    \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.h 0
+
+    The \c LayoutItem class also has a private instance of QPixmap, \c m_pix.
+
+    \section1 LayoutItem Class Implementation
+
+    In \c{LayoutItem}'s constructor, \c m_pix is instantiated and the
+    \c{block.png} image is loaded into it.
+
+    \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 0
+
+    We use the Q_UNUSED() macro to prevent the compiler from generating
+    warnings regarding unused parameters.
+
+    \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 1
+
+    The idea behind the \c paint() function is to paint the
+    background rect then paint a rect around the pixmap.
+
+    \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 2
+
+    The reimplementation of \l{QGraphicsItem::}{boundingRect()}
+    will set the top left corner at (0,0), and the size of it will be
+    the size of the layout items
+    \l{QGraphicsLayoutItem::}{geometry()}. This is the area that
+    we paint within.
+
+    \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 3
+
+
+    The reimplementation of \l{QGraphicsLayoutItem::setGeometry()}{setGeometry()}
+    simply calls its baseclass implementation. However, since this will change
+    the boundingRect we must also call
+    \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()}.
+    Finally, we move the item according to \c geom.topLeft().
+
+    \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 4
+
+
+    Since we don't want the size of the item to be smaller than the pixmap, we
+    must make sure that we return a size hint that is larger than \c m_pix.
+    We also add some extra space around for borders that we will paint later.
+    Alternatively, you could scale the pixmap to prevent the item from
+    becoming smaller than the pixmap.
+    The preferred size is the same as the minimum size hint, while we set
+    maximum to be a large value
+
+    \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 5
+
+*/
\ No newline at end of file