1 files changed, 89 insertions, 0 deletions
diff --git a/examples/datavisualization/qmlspectrogram/doc/src/qmlspectrogram.qdoc b/examples/datavisualization/qmlspectrogram/doc/src/qmlspectrogram.qdoc
new file mode 100644
index 00000000..0aebdde0
--- /dev/null
+++ b/examples/datavisualization/qmlspectrogram/doc/src/qmlspectrogram.qdoc
@@ -0,0 +1,89 @@
+/****************************************************************************
+**
+** 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 qmlspectrogram
+    \title Qt Quick 2 Spectrogram Example
+    \ingroup qtdatavisualization_examples
+    \brief Showing spectrogram graph in a QML application.
+
+    The Qt Quick 2 Spectrogram example demonstrates how to show a polar and cartesian spectrograms
+    and how to utilize orthographic projection to show them in 2D.
+
+    \image qmlspectrogram-example.png
+
+    Spectrogram is simply a surface graph with a range gradient used to emphasize the different
+    values. Typically spectrograms are shown with two dimensional surfaces, which we simulate
+    with a top down orthographic view of the graph. To enforce the 2D effect, we disable the
+    graph rotation via mouse or touch when in the orthographic mode.
+
+    The focus in this example is on showing how to display spectrograms, so the basic
+    functionality is not explained. For more detailed QML example documentation,
+    see \l{Qt Quick 2 Scatter Example}.
+
+    \section1 Creating a spectrogram
+
+    To create a 2D spectrogram, we define a Surface3D item:
+
+    \snippet qmlspectrogram/qml/qmlspectrogram/main.qml 0
+
+    The key properties for enabling the 2D effect are
+    \l{AbstractGraph3D::orthoProjection}{orthoProjection} and
+    \l{Camera3D::cameraPreset}{scene.activeCamera.cameraPreset}. We remove the perspective by
+    enabling orthographic projection for the graph, and then we eliminate the Y-dimension by
+    viewing the graph directly from above:
+
+    \snippet qmlspectrogram/qml/qmlspectrogram/main.qml 1
+
+    Since this viewpoint causes the horizontal axis grid to be mostly obscured by the surface,
+    we also specify that the horizontal grid should be drawn on top of the graph:
+
+    \snippet qmlspectrogram/qml/qmlspectrogram/main.qml 2
+
+    \section1 Polar spectrogram
+
+    Depending on the data, it is sometimes more natural to use a polar graph instead of a cartesian
+    one. Qt Data Visualization supports this via \l{AbstractGraph3D::polar}{polar} property.
+    In this example we provide a button to switch between polar and cartesian modes:
+
+    \snippet qmlspectrogram/qml/qmlspectrogram/main.qml 3
+
+    In the polar mode, the X-axis is converted into the angular polar axis, and the Z-axis is
+    converted into the radial polar axis. The surface points are recalculated according to new axes.
+
+    The radial axis labels are drawn outside the graph by default, but in this example we want to
+    draw them right next to the 0 degree angular axis inside the graph, so we define only a tiny
+    offset for them:
+
+    \snippet qmlspectrogram/qml/qmlspectrogram/main.qml 4
+
+    To enforce the 2D effect, graph rotation via user input is disabled when in orthographic mode.
+    We do this by specifying a new input handler:
+
+    \snippet qmlspectrogram/qml/qmlspectrogram/main.qml 5
+    \snippet qmlspectrogram/qml/qmlspectrogram/main.qml 7
+    \dots 0
+    \snippet qmlspectrogram/qml/qmlspectrogram/main.qml 6
+    \dots 0
+
+    When the projection mode changes, we adjust the value of the
+    \l{InputHandler3D::rotationEnabled}{rotationEnabled} property of the \c{customInputHandler}
+    to control the rotation.
+
+    \section1 Example contents
+*/