diff options
Diffstat (limited to 'doc/src/examples/basicgraphicslayouts.qdoc')
| -rw-r--r-- | doc/src/examples/basicgraphicslayouts.qdoc | 164 |
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 |