1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \title Scenegraph Painted Item Example
30 \example declarative/painteditem/textballoons
32 The Painted Item example shows how to use the QML Scene Graph framework to
33 implement custom scenegraph items using QPainter.
35 \image declarative-textballoons_example.png
37 The QQuickPaintedItem class is a class derived from QQuickItem for implementing
38 custom QML Scene Graph items using the QPainter interfaces.
40 The example consists of an item class, a plugin class and a QML file
41 to use this plugin. The \c TextBalloon class represents the individual
42 text balloons extending QQuickPaintedItem, the \c TextBalloonPlugin class
43 represents the skeleton code for a QtQuick plugin and the
44 \c textballoons.qml file is used to load the plugin and display the text
47 We will focus on the \c TextBalloon class first and continue with the
48 \c textballoons.qml file. For an example on how to implement a QtQuick
49 plugin please look at \l{declarative/tutorials/extending/chapter6-plugins}
50 {Writing an Extension Plugin}
52 \section1 TextBalloon Class Declaration
54 The \c TextBalloon class inherits from QQuickPaintedItem. QQuickPaintedItem
55 is the base class for all QPainter based items in the QML Scene Graph
58 \snippet examples/declarative/painteditem/textballoons/textballoon.h 0
60 To implement a QQuickPaintedItem you must implement QQuickPaintedIem's pure
61 virtual function \l {QQuickPaintedItem::}{paint()} which implements the
62 painting of the element.
64 \section1 TextBalloon Class Definition
66 We have to be sure to initialize the rightAligned property for a
69 \snippet examples/declarative/painteditem/textballoons/textballoon.cpp 0
71 Then we implement the \c paint() function which is automatically called by
72 the Scenegraph framework to paint the contents of the item. The function
73 paints the item in local coordinates.
75 \snippet examples/declarative/painteditem/textballoons/textballoon.cpp 1
77 We start with setting the pen and brush on the item to define the look of
78 the item. After that we start drawing. Note that the \l {QQuickPaintedItem::}{boundingRect()}
79 item is called to draw depending on the size of the item. The rectangle
80 returned by the \l {QQuickPaintedItem::}{boundingRect()} function is the size
81 of the item as defined in the QML file.
83 \section1 textballoons.qml file
85 The Interface consists of two main parts. The scrollable area with the
86 textballoons and the controls button to add new balloons.
90 \snippet examples/declarative/painteditem/textballoons/textballoons.qml 0
92 The balloonModel contains two elements at application start which will be
93 displayed by the balloonView. The balloonView alernates the TextBalloon
94 delegate items between left-aligned and right-aligned.
98 \snippet examples/declarative/painteditem/textballoons/textballoons.qml 1
100 The controls part of the UI contains a rectangle with a MouseArea which
101 changes color when the mouse hovers over it. This control 'button' adds
102 a new element to the end of the model with a random width.