/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** 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.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/


/*!
    \title Scene Graph - Painted Item
    \brief Shows how to implement QPainter-based custom scenegraph items.
    \example customitems/painteditem
    \ingroup qtquickexamples

    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, a plugin class and a QML file
    to use this plugin. The \c TextBalloon class represents the individual
    text balloons extending QQuickPaintedItem, the \c TextBalloonPlugin class
    represents the skeleton code for a \l {Qt Quick} plugin and the
    \c textballoons.qml file is used to load the plugin 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 \l {Qt Quick}
    plugin 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.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.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.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.

 */
