Axis formatter customization example

Also refactored the formatter api somewhat:

- Removed virtual from allowNegatives and allowZero and added a
setter function for those. This will make it cleaner if we need to
add similar properties to the axis formatter in the future, as
no new virtual methods can be added without breaking BC.

- Changed the labelValues array to labelStrings list, as it makes
more sense to directly format the strings in recalculate.

Change-Id: I3ea005afa984bb756845ca356b999762e0807415
Reviewed-by: Tomi Korpipää <tomi.korpipaa@digia.com>

1 files changed, 114 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..b990c490
--- /dev/null
+++ b/examples/datavisualization/qmlaxisformatter/doc/src/qmlaxisformatter.qdoc
@@ -0,0 +1,114 @@
+/****************************************************************************
+**
+** 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.
+
+    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.
+*/