// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
    \title Scene Graph - Painted Item
    \brief Shows how to implement QPainter-based custom scenegraph items.
    \example customitems/painteditem
    \ingroup qtquickexamples
    \examplecategory {Graphics}

    The Painted Item example shows how to use the QML Scene Graph framework to
    implement custom scenegraph items using QPainter.

    \image declarative-textballoons_example.png

    The QQuickPaintedItem class is a class derived from QQuickItem for implementing
    custom QML Scene Graph items using the QPainter interfaces.

    The example consists of an item class and a QML file to use the item. The
    \c TextBalloon class represents the individual text balloons extending
    QQuickPaintedItem and the \c textballoons.qml file is used to load the module
    containing the TextBalloon QML type and display the text balloons.

    We will focus on the \c TextBalloon class first and continue with the
    \c textballoons.qml file. For an example on how to implement a plugin for a
    QML module please look at \l{Chapter 6: Writing an Extension Plugin}
    {Writing an Extension Plugin}

    \section1 TextBalloon Class Declaration

    The \c TextBalloon class inherits from QQuickPaintedItem. QQuickPaintedItem
    is the base class for all QPainter based items in the QML Scene Graph
    framework.

    \snippet customitems/painteditem/TextBalloon/textballoon.h 0

    To implement a QQuickPaintedItem you must implement QQuickPaintedIem's pure
    virtual function \l {QQuickPaintedItem::}{paint()} which implements the
    painting of the type.

    \section1 TextBalloon Class Definition

    We have to be sure to initialize the rightAligned property for a
    TextBalloon item.

    \snippet customitems/painteditem/TextBalloon/textballoon.cpp 0

    Then we implement the \c paint() function which is automatically called by
    the Scene Graph framework to paint the contents of the item. The function
    paints the item in local coordinates.

    \snippet customitems/painteditem/TextBalloon/textballoon.cpp 1

    We start with setting the pen and brush on the item to define the look of
    the item. After that we start drawing. Note that the \l {QQuickPaintedItem::}{contentsBoundingRect()}
    item is called to draw depending on the size of the item. The rectangle
    returned by the \l {QQuickPaintedItem::}{contentsBoundingRect()} function is the size
    of the item as defined in the QML file.

    \section1 textballoons.qml File

    The Interface consists of two main parts. The scrollable area with the
    textballoons and the controls button to add new balloons.

    \section2 BalloonView

    \snippet customitems/painteditem/textballoons.qml 0

    The balloonModel contains two types at application start which will be
    displayed by the balloonView. The balloonView alernates the TextBalloon
    delegate items between left-aligned and right-aligned.

    \section2 Controls

    \snippet customitems/painteditem/textballoons.qml 1

    The controls part of the UI contains a rectangle with a MouseArea which
    changes color when the mouse hovers over it. This control 'button' adds
    a new object to the end of the model with a random width.

 */
