doc/src/qtquick1/example-textballoons.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   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
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \title Scenegraph Painted Item Example
  30     \example declarative/painteditem/textballoons
  31
  32     The Painted Item example shows how to use the QML Scene Graph framework to
  33     implement custom scenegraph items using QPainter.
  34
  35     \image declarative-textballoons_example.png
  36
  37     The QQuickPaintedItem class is a class derived from QQuickItem for implementing
  38     custom QML Scene Graph items using the QPainter interfaces.
  39
  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
  45     balloons.
  46
  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}
  51
  52     \section1 TextBalloon Class Declaration
  53
  54     The \c TextBalloon class inherits from QQuickPaintedItem. QQuickPaintedItem
  55     is the base class for all QPainter based items in the QML Scene Graph
  56     framework.
  57
  58     \snippet examples/declarative/painteditem/textballoons/textballoon.h 0
  59
  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.
  63
  64     \section1 TextBalloon Class Definition
  65
  66     We have to be sure to initialize the rightAligned property for a
  67     TextBalloon item.
  68
  69     \snippet examples/declarative/painteditem/textballoons/textballoon.cpp 0
  70
  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.
  74
  75     \snippet examples/declarative/painteditem/textballoons/textballoon.cpp 1
  76
  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.
  82
  83     \section1 textballoons.qml file
  84
  85     The Interface consists of two main parts. The scrollable area with the
  86     textballoons and the controls button to add new balloons.
  87
  88     \section2 BalloonView
  89
  90     \snippet examples/declarative/painteditem/textballoons/textballoons.qml 0
  91
  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.
  95
  96     \section2 Controls
  97
  98     \snippet examples/declarative/painteditem/textballoons/textballoons.qml 1
  99
 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.
 103
 104  */