Add TextBalloon QML Scene Grpah example with documentation. I moved an old example over to a subfolder.

Reviewed-by: Gunnar Sletta

12 files changed, 459 insertions, 5 deletions

diff --git a/doc/src/declarative/example-textballoons.qdoc b/doc/src/declarative/example-textballoons.qdoc
new file mode 100644
index 0000000000..90de999265
--- /dev/null
+++ b/doc/src/declarative/example-textballoons.qdoc
@@ -0,0 +1,104 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \title Scenegraph Painted Item Example
+    \example declarative/painteditem/textballoons
+
+    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 QSGPaintedItem class is a class derived from QSGItem 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 QSGPaintedItem, the \c TextBalloonPlugin class
+    represents the skeleton code for a QtQuick 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 QtQuick
+    plugin please look at \l{declarative/tutorials/extending/chapter6-plugins}
+    {Writing an Extension Plugin}
+
+    \section1 TextBalloon Class Declaration
+
+    The \c TextBalloon class inherits from QSGPaintedItem. QSGPaintedItem class
+    is the base class for all QPainter based items in the QML Scene Graph
+    framework.
+
+    \snippet examples/declarative/painteditem/textballoons/textballoonplugin/textballoon.h 0
+
+    To implement a QSGPaintedItem you must implement QSGPaintedIem's pure
+    virtual function \l {QSGPaintedItem::}{paint()} which implements the
+    painting of the element.
+
+    \section1 TextBalloon Class Definition
+
+    We have to be sure to initialize the rightAligned property for a
+    TextBalloon item.
+
+    \snippet examples/declarative/painteditem/textballoons/textballoonplugin/textballoon.cpp 0
+
+    Then we implement the \c paint() function which is automatically called by
+    the Scenegraph framework to paint the contents of the item. The function
+    paints the item in local coordinates.
+
+    \snippet examples/declarative/painteditem/textballoons/textballoonplugin/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 {QSGPaintedItem::}{boundingRect()}
+    item is called to draw depending on the size of the item. The rectangle
+    returned by the \l {QSGPaintedItem::}{boundingRect()} 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 examples/declarative/painteditem/textballoons/textballoons.qml 0
+
+    The balloonModel contains two elements 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 examples/declarative/painteditem/textballoons/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 element to the end of the model with a random width.
+
+ */
diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc
index b7420e011b..e230d9f951 100644
--- a/doc/src/declarative/examples.qdoc
+++ b/doc/src/declarative/examples.qdoc
@@ -229,6 +229,10 @@ The examples can be found in Qt's \c examples/declarative directory.
 \o \l{declarative/cppextensions/networkaccessmanagerfactory}{Network access manager factory}
 \endlist
 
+\section2 Scenegraph
+\list
+\o \l{declarative/painteditem/textballoons}{Painted Item}
+\endlist
 
 \section1 Labs
 
diff --git a/doc/src/images/declarative-textballoons_example.png b/doc/src/images/declarative-textballoons_example.png
new file mode 100644
index 0000000000..d572de597c
--- /dev/null
+++ b/doc/src/images/declarative-textballoons_example.png
diff --git a/examples/declarative/painteditem/main.cpp b/examples/declarative/painteditem/smile/main.cpp
index 85028600be..e26c1b47e7 100644
--- a/examples/declarative/painteditem/main.cpp
+++ b/examples/declarative/painteditem/smile/main.cpp
@@ -67,10 +67,6 @@ public:
 
 int main(int argc, char ** argv)
 {
-#ifdef Q_WS_X11
-    QApplication::setAttribute(Qt::AA_X11InitThreads);
-#endif
-
     QApplication app(argc, argv);
 
     qmlRegisterType<MyPaintItem>("MyModule", 1, 0, "MyPaintItem");
@@ -79,7 +75,7 @@ int main(int argc, char ** argv)
     f.setSampleBuffers(true);
     QSGView view(f);
     view.setResizeMode(QSGView::SizeRootObjectToView);
-    view.setSource(QUrl::fromLocalFile("myfile.qml"));
+    view.setSource(QUrl::fromLocalFile("smile.qml"));
     view.show();
     view.raise();
 
diff --git a/examples/declarative/painteditem/painteditem.pro b/examples/declarative/painteditem/smile/smile.pro
index 5d7b9df074..5d7b9df074 100644
--- a/examples/declarative/painteditem/painteditem.pro
+++ b/examples/declarative/painteditem/smile/smile.pro
diff --git a/examples/declarative/painteditem/myfile.qml b/examples/declarative/painteditem/smile/smile.qml
index bc4bd2664b..bc4bd2664b 100644
--- a/examples/declarative/painteditem/myfile.qml
+++ b/examples/declarative/painteditem/smile/smile.qml
diff --git a/examples/declarative/painteditem/textballoons/textballoonplugin/plugin.h b/examples/declarative/painteditem/textballoons/textballoonplugin/plugin.h
new file mode 100644
index 0000000000..ec519a5de8
--- /dev/null
+++ b/examples/declarative/painteditem/textballoons/textballoonplugin/plugin.h
@@ -0,0 +1,56 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the demonstration applications of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Nokia.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QDeclarativeExtensionPlugin>
+
+#include "textballoon.h"
+
+class TextBalloonPlugin : public QDeclarativeExtensionPlugin
+{
+    Q_OBJECT
+public:
+    void registerTypes(const char *uri)
+    {
+        qmlRegisterType<TextBalloon>(uri, 1, 0, "TextBalloon");
+    }
+};
+
+Q_EXPORT_PLUGIN2(qmltextballoonplugin, TextBalloonPlugin);
diff --git a/examples/declarative/painteditem/textballoons/textballoonplugin/qmldir b/examples/declarative/painteditem/textballoons/textballoonplugin/qmldir
new file mode 100644
index 0000000000..e8a08ae9d3
--- /dev/null
+++ b/examples/declarative/painteditem/textballoons/textballoonplugin/qmldir
@@ -0,0 +1 @@
+plugin qmltextballoonplugin
diff --git a/examples/declarative/painteditem/textballoons/textballoonplugin/textballoon.cpp b/examples/declarative/painteditem/textballoons/textballoonplugin/textballoon.cpp
new file mode 100644
index 0000000000..0fc56c7a74
--- /dev/null
+++ b/examples/declarative/painteditem/textballoons/textballoonplugin/textballoon.cpp
@@ -0,0 +1,92 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the demonstration applications of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Nokia.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "textballoon.h"
+
+//! [0]
+TextBalloon::TextBalloon(QSGItem *parent)
+    : QSGPaintedItem(parent)
+    , rightAligned(false)
+{
+}
+//! [0]
+
+//! [1]
+void TextBalloon::paint(QPainter *painter)
+{
+    QBrush brush(QColor("#007430"));
+
+    painter->setBrush(brush);
+    painter->setPen(Qt::NoPen);
+    painter->setRenderHint(QPainter::Antialiasing);
+
+    painter->drawRoundedRect(0, 0, boundingRect().width(), boundingRect().height() - 10, 10, 10);
+
+    if (rightAligned)
+    {
+        const QPointF points[3] = {
+            QPointF(boundingRect().width() - 10.0, boundingRect().height() - 10.0),
+            QPointF(boundingRect().width() - 20.0, boundingRect().height()),
+            QPointF(boundingRect().width() - 30.0, boundingRect().height() - 10.0),
+        };
+        painter->drawConvexPolygon(points, 3);
+    }
+    else
+    {
+        const QPointF points[3] = {
+            QPointF(10.0, boundingRect().height() - 10.0),
+            QPointF(20.0, boundingRect().height()),
+            QPointF(30.0, boundingRect().height() - 10.0),
+        };
+        painter->drawConvexPolygon(points, 3);
+    }
+}
+//! [1]
+
+bool TextBalloon::isRightAligned()
+{
+    return this->rightAligned;
+}
+
+void TextBalloon::setRightAligned(bool rightAligned)
+{
+    this->rightAligned = rightAligned;
+}
diff --git a/examples/declarative/painteditem/textballoons/textballoonplugin/textballoon.h b/examples/declarative/painteditem/textballoons/textballoonplugin/textballoon.h
new file mode 100644
index 0000000000..1b630f4011
--- /dev/null
+++ b/examples/declarative/painteditem/textballoons/textballoonplugin/textballoon.h
@@ -0,0 +1,68 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the demonstration applications of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Nokia.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef TEXTBALLOON_H
+#define TEXTBALLOON_H
+
+#include <QtDeclarative>
+
+//! [0]
+class TextBalloon : public QSGPaintedItem
+{
+    Q_OBJECT
+    Q_PROPERTY(bool rightAligned READ isRightAligned WRITE setRightAligned NOTIFY rightAlignedChanged)
+
+    public:
+        TextBalloon(QSGItem *parent = 0);
+        void paint(QPainter *painter);
+
+        bool isRightAligned();
+        void setRightAligned(bool rightAligned);
+
+    private:
+        bool rightAligned;
+
+    signals:
+        void rightAlignedChanged();
+};
+//! [0]
+
+#endif
diff --git a/examples/declarative/painteditem/textballoons/textballoons.pro b/examples/declarative/painteditem/textballoons/textballoons.pro
new file mode 100644
index 0000000000..186581f9d5
--- /dev/null
+++ b/examples/declarative/painteditem/textballoons/textballoons.pro
@@ -0,0 +1,23 @@
+TEMPLATE = lib
+CONFIG += qt plugin
+QT += declarative
+
+TARGET = qmltextballoonplugin
+
+HEADERS += textballoonplugin/plugin.h \
+    textballoonplugin/textballoon.h
+
+SOURCES += textballoonplugin/textballoon.cpp
+
+DESTDIR = textballoonplugin
+
+qdeclarativesources.files += \
+    textballoonplugin/qmldir
+
+qdeclarativesources.path += $$[QT_INSTALL_EXAMPLES]/qtdeclarative/declarative/painteditem/textballoons/textballoonplugin
+ 
+sources.files = textballoons.qml
+sources.path += $$[QT_INSTALL_EXAMPLES]/qtdeclarative/declarative/painteditem/textballoons
+target.path += $$[QT_INSTALL_EXAMPLES]/qtdeclarative/declarative/painteditem/textballoons/textballoonplugin
+
+INSTALLS = qdeclarativesources sources target
diff --git a/examples/declarative/painteditem/textballoons/textballoons.qml b/examples/declarative/painteditem/textballoons/textballoons.qml
new file mode 100644
index 0000000000..b786a2c601
--- /dev/null
+++ b/examples/declarative/painteditem/textballoons/textballoons.qml
@@ -0,0 +1,110 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the demonstration applications of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial Usage
+** Licensees holding valid Qt Commercial licenses may use this file in
+** accordance with the Qt Commercial License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Nokia.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+import TextBalloonPlugin 1.0
+
+Item {
+    height: 480
+    width: 640
+
+    //! [0]
+    ListModel {
+        id: balloonModel
+        ListElement {
+            balloonWidth: 200
+        }
+        ListElement {
+            balloonWidth: 350
+        }
+    }
+
+    ListView {
+        anchors.bottom: controls.top
+        anchors.bottomMargin: 2
+        anchors.top: parent.top
+        id: balloonView
+        delegate: TextBalloon {
+            anchors.right: index % 2 == 0 ? undefined : parent.right
+            height: 60
+            rightAligned: index % 2 == 0 ? false : true
+            width: balloonWidth
+        }
+        model: balloonModel
+        spacing: 5
+        width: parent.width
+    }
+    //! [0]
+
+    //! [1]
+    Rectangle {
+        id: controls
+ 
+        anchors.bottom: parent.bottom
+        anchors.left: parent.left
+        anchors.margins: 1
+        anchors.right: parent.right
+        border.width: 2
+        color: "white"
+        height: parent.height * 0.15
+
+        Text {
+            anchors.centerIn: parent
+            text: "Add another balloon"
+        }
+
+        MouseArea {
+            anchors.fill: parent
+            hoverEnabled: true
+            onClicked: {
+                balloonModel.append({"balloonWidth": Math.floor(Math.random() * 300 + 100)})
+                balloonView.positionViewAtIndex(balloonView.count -1, ListView.End)
+            }
+            onEntered: {
+                parent.color = "#8ac953"
+            }
+            onExited: {
+                parent.color = "white"
+            }
+        }
+    }
+    //! [1]
+}