Examples: Moved example documentation.

-inline \example pages into separate .qdoc files
-fixed broken links to paths
-moved ui-components under examples/quick

Change-Id: I6e009b9213be3e1f4bed51bdbeb76a7a2142c80b
Reviewed-by: Martin Smith <martin.smith@digia.com>

1 files changed, 201 insertions, 0 deletions

diff --git a/examples/quick/scenegraph/customgeometry/doc/src/customgeometry.qdoc b/examples/quick/scenegraph/customgeometry/doc/src/customgeometry.qdoc
new file mode 100644
index 0000000000..e17990cc56
--- /dev/null
+++ b/examples/quick/scenegraph/customgeometry/doc/src/customgeometry.qdoc
@@ -0,0 +1,201 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example quick/scenegraph/customgeometry
+    \title Custom Geometry Example
+    \ingroup examples
+
+    The custom geometry example shows how to create a QQuickItem which
+    uses the scene graph API to build a custom geometry for the scene
+    graph. It does this by creating a BezierCurve item which is made
+    part of the CustomGeometry module and makes use of this in a QML
+    file.
+
+    \image custom-geometry-example.png
+
+    \section1 BezierCurve Declaration
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.h 1
+
+    The item declaration subclasses the QQuickItem class and adds five
+    properties. One for each of the four control points in the bezier
+    curve and a parameter to control the number of segments the curve
+    is subdivided into. For each of the properties we have
+    corresponding getter and setter functions. Since these properties
+    can be bound to in QML, it is also preferable to have notifier
+    signals for each of them so changes will be picked up the QML
+    engine and used accordingly.
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.h 2
+
+    The synchronization point between the QML scene and the rendering
+    scene graph is the virtual function \l
+    QQuickItem::updatePaintNode() which all items with custom scene
+    graph logic must implement.
+
+    \e { The scene graph will on many hardware configurations be
+    rendering on a separate thread. It is therefore crucial that
+    interaction with the scene graph happens in a controlled
+    manner, first and foremost through the \l
+    QQuickItem::updatePaintNode() function. }
+
+    \section1 BezierCurve Implementation
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.cpp 1
+
+    The BezierCurve constructor sets up default values for the
+    control points and the number of segments. The bezier curve
+    is specified in normalized coordinates relative to the item's
+    bounding rectangle.
+
+    The constructor also sets the flag \l
+    QQuickItem::ItemHasContents. This flags tells the canvas that this
+    item provides visual content and will call \l
+    QQuickItem::updatePaintNode() when it is time for the QML scene to
+    be synchronized with the rendering scene graph.
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.cpp 2
+
+    The BezierCurve class has no data members that need to be cleaned
+    up so the destructor does nothing. It is worth mentioning that the
+    rendering scene graph is managed by the scene graph it self,
+    potentially in a different thread, so one should never retain
+    QSGNode references in the QQuickItem class nor try to clean them
+    up explicitly.
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.cpp 3
+
+    The setter function for the p1 property checks if the value is
+    unchanged and exits early if this is the case. Then it updates the
+    internal value and emits the changed signal. It then proceeds to
+    call the \l QQuickItem::update() function which will notify the
+    rendering scene graph, that the state of this object has changed
+    and needs to be synchronized with the rendering scene graph.
+    A call to update() will result in a call to
+    QQuickItem::updatePaintNode() at a later time.
+
+    The other property setters are equivalent, and are omitted from
+    this example.
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.cpp 4
+
+    The updatePaintNode() function is the primary integration point
+    for synchronizing the state of the QML scene with the rendering
+    scene graph. The function gets passed a QSGNode which is the
+    instance that was returned on the last call to the function. It
+    will be null the first time the function gets called and we create
+    our QSGGeometryNode which we will fill with geometry and a
+    material.
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.cpp 5
+
+    We then create the geometry and add it to the node. The first
+    argument to the QSGGeometry constructor is a definition of the
+    vertex type, called an "attribute set". Since the graphics often
+    used in QML centers around a few common standard attribute sets,
+    these are provided by default. Here we use the Point2D attribute
+    set which has two floats, one for x coordinates and one for y
+    coordinates. The second argument is the vertex count.
+
+    \e {Custom attribute sets can also created, but that is not
+    covered in this example}.
+
+    Since we do not have any special needs for memory managing the
+    geometry, we specify that the QSGGeometryNode should own the
+    geometry.
+
+    \e {To minimize allocations, reduce memory fragmentation and
+    improve performance, it would also be possible to make the
+    geometry a member of a QSGGeometryNode subclass, in which case, we
+    would not have set the QSGGeometryNode::OwnsGeometry flag}.
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.cpp 6
+
+    The scene graph API provides a few commonly used used material
+    implementations. In this example we use the QSGFlatColorMaterial
+    which will fill the shape defined by the geometry with a solid
+    color. Again we pass the ownership of the material to the node, so
+    it can be cleaned up by the scene graph.
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.cpp 7
+
+    In the case where the QML item has changed and we only want to
+    modify the existing node's geometry, we cast the \c oldNode to a
+    QSGGeometryNode instance and extract it's geometry. In case the
+    segment count has changed, we call QSGGeometry::allocate() to make
+    sure it has the right number of vertices.
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.cpp 8
+
+    To fill the geometry, we first extract the vertex array from
+    it. Since we are using one of the default attribute sets, we can
+    use the convenience function QSGGeometry::vertexDataAsPoint2D().
+    Then we go through each segment and calculate its position and
+    write that value to the vertex.
+
+    \snippet quick/scenegraph/customgeometry/beziercurve.cpp 9
+
+    In the end of the function, we return the node so the scene graph
+    can render it.
+
+    \section1 Application Entry-Point
+
+    \snippet quick/scenegraph/customgeometry/main.cpp 1
+
+    The application is a straightforward QML application, with a
+    QGuiApplication and a QQuickView that we pass a .qml file. To make
+    use of the BezierCurve item, we need to register it in the QML
+    engine, using the qmlRegisterType function. We give it the name
+    BezierCurve and make it part of the \c {CustomGeometry 1.0}
+    module.
+
+    \section1 Using the Item
+
+    \snippet quick/scenegraph/customgeometry/LineTester.qml 1
+
+    Our .qml file imports the \c {QtQuick 2.0} module to get the
+    standard elements and also our own \c {CustomGeometry 1.0} module
+    which contains our newly created BezierCurve element.
+
+    \snippet quick/scenegraph/customgeometry/LineTester.qml 2
+
+    Then we create the our root item and an instance of the
+    BezierCurve which we anchor to fill the root.
+
+    \snippet quick/scenegraph/customgeometry/LineTester.qml 3
+
+    To make the example a bit more interesting we add an animation to
+    change the two control points in the curve. The end points stay
+    unchanged.
+
+    \snippet quick/scenegraph/customgeometry/LineTester.qml 4
+
+    Finally we overlay a short text outlining what the example shows.
+
+ */
+