--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/basicgraphicslayouts.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,178 @@
+/****************************************************************************
+**
+** 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 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 {QGraphicsItem::boundingRect()}{boundingRect()}
+ will set the top left corner at (0,0), and the size of it will be
+ the size of the layout items
+ {QGraphicsLayoutItem::geometry()}{geometry()}. This is the area that
+ we paint within.
+
+ \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 3
+
+
+ The reimplementation of {QGraphicsLayoutItem::setGeometry()}{setGeometry()}
+ simply calls its baseclass implementation. However, since this will change
+ the boundingRect we must also call
+ {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