Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example graphicsview/basicgraphicslayouts
++ \title Basic Graphics Layouts Example
++ \examplecategory {Graphics}
++ \ingroup examples-graphicsview-layout
++ \brief Demonstrates how to create basic graphics layout.
++
++ 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 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 graphicsview/basicgraphicslayouts/window.cpp 0
++
++ We repeat the process:
++
++ \list
++ \li create a new \c LayoutItem,
++ \li add the item \c linear, and
++ \li provide a stretch factor.
++ \endlist
++
++ \snippet 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 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 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 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 graphicsview/basicgraphicslayouts/layoutitem.cpp 0
++
++ We use the Q_UNUSED() macro to prevent the compiler from generating
++ warnings regarding unused parameters.
++
++ \snippet 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 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 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 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 graphicsview/basicgraphicslayouts/layoutitem.cpp 5
++
++ */