1 files changed, 115 insertions, 0 deletions
diff --git a/examples/datavisualization/qmlaxisformatter/doc/src/qmlaxisformatter.qdoc b/examples/datavisualization/qmlaxisformatter/doc/src/qmlaxisformatter.qdoc
new file mode 100644
index 00000000..3568e507
--- /dev/null
+++ b/examples/datavisualization/qmlaxisformatter/doc/src/qmlaxisformatter.qdoc
@@ -0,0 +1,115 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+/*!
+    \example qmlaxisformatter
+    \title Qt Quick 2 Axis Formatter Example
+    \ingroup qtdatavisualization_examples
+    \brief Example of a hybrid C++ and QML application demonstrating different axis formatters.
+    \since QtDataVisualization 1.1
+
+    The Qt Quick axis formatter example shows how to use predefined axis formatters and how to
+    create a custom one.
+
+    \image qmlaxisformatter-example.png
+
+    The interesting thing about this example is axis formatters, so we'll concentrate on
+    that and skip explaining the basic functionality - for
+    more detailed QML example documentation, see \l{Qt Quick 2 Scatter Example}.
+
+    \section1 Custom axis formatter
+
+    Customizing axis formatters requires subclassing the QValue3DAxisFormatter, which cannot be
+    done in QML code alone. In this example we want an axis that interprets the float values as
+    a timestamp and shows the date in the axis labels. To achieve this, we introduce a new class
+    called \c CustomFormatter, which subclasses the QValue3DAxisFormatter:
+
+    \snippet qmlaxisformatter/customformatter.h 2
+    \dots 0
+
+    Since float values of a QScatter3DSeries cannot be directly cast into QDateTime values due to
+    difference in data width, we need some sort of mapping between the two. We chose to do the
+    mapping by specifying an origin date for the formatter and interpreting the float values
+    from the QScatter3DSeries as date offsets to that origin value. The origin date is given as
+    a property:
+
+    \snippet qmlaxisformatter/customformatter.h 1
+
+    The mapping from value to QDateTime is done using \c valueToDateTime() method:
+
+    \snippet qmlaxisformatter/customformatter.cpp 0
+
+    To function as an axis formatter, our \c CustomFormatter needs to reimplement some virtual
+    methods:
+
+    \snippet qmlaxisformatter/customformatter.h 0
+
+    The first two are simple, we just create a new instance of \c CustomFormatter and copy the
+    necessary data over to it. These two methods are used to create and update a cache of formatter for
+    rendering purposes. It is important to remember to call the superclass implementation
+    of \c populateCopy():
+
+    \snippet qmlaxisformatter/customformatter.cpp 1
+
+    Bulk of the work done by \c CustomFormatter is done in the \c recalculate() method, where
+    our formatter calculates the grid, subgrid, and label positions, as well as formats the label
+    strings.
+    In our custom formatter we ignore the segment count of the axis and draw a grid line always at
+    midnight. Subsegment count and label positioning is handled normally:
+
+    \snippet qmlaxisformatter/customformatter.cpp 2
+
+    The axis labels are formatted to show only the date, but for selection label we want little more
+    resolution for the timestamp, so we specify another property for our custom formatter to allow
+    user to customize it:
+
+    \snippet qmlaxisformatter/customformatter.h 3
+
+    This selection format property is used in the reimplemented \c stringToValue method, where we
+    ignore the submitted format and substitute the custom selection format for it:
+
+    \snippet qmlaxisformatter/customformatter.cpp 3
+
+    To expose our new custom formatter to the QML, we must declare and register it:
+
+    \snippet qmlaxisformatter/main.cpp 0
+    \dots 0
+    \snippet qmlaxisformatter/main.cpp 1
+
+    \section1 QML
+
+    In the QML codes, we define a different axis for each dimension:
+
+    \snippet qmlaxisformatter/qml/qmlaxisformatter/main.qml 3
+
+    Z-axis is just a regular ValueAxis3D:
+
+    \snippet qmlaxisformatter/qml/qmlaxisformatter/main.qml 0
+
+    For the Y-axis we define a logarithmic axis. ValueAxis3D can be made to show logarithmic scale
+    by specifying LogValueAxis3DFormatter for \c formatter property of the axis:
+
+    \snippet qmlaxisformatter/qml/qmlaxisformatter/main.qml 2
+
+    And finally, for the X-axis we use our new \c CustomFormatter:
+
+    \snippet qmlaxisformatter/qml/qmlaxisformatter/main.qml 1
+
+    Rest of the application consists of fairly self-explanatory logic for modifying the axes and
+    showing the graph.
+*/