Scatter example documentation

Task-number: QTRD-2400

Change-Id: Ic6e67298c493ac2b92ad03c6f3746a5481ae1e97
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@digia.com>

4 files changed, 169 insertions, 19 deletions

diff --git a/examples/scatter/doc/images/scatter-example.png b/examples/scatter/doc/images/scatter-example.png
new file mode 100644
index 00000000..2384ffb5
--- /dev/null
+++ b/examples/scatter/doc/images/scatter-example.png
diff --git a/examples/scatter/doc/src/scatter.qdoc b/examples/scatter/doc/src/scatter.qdoc
index 5053d77a..90410bc6 100644
--- a/examples/scatter/doc/src/scatter.qdoc
+++ b/examples/scatter/doc/src/scatter.qdoc
@@ -23,9 +23,132 @@
     \brief Using Q3DScatter in a widget application.
 
     The scatter example shows how to make a simple 3D scatter graph using Q3DScatter and
-    combining the use of widgets for adjusting several adjustable qualities.
+    combining the use of widgets for adjusting several adjustable qualities. The example shows
+    how to:
+
+    \list
+        \li Create an application with Q3DScatter and some widgets
+        \li Use QScatterDataProxy to set data to the graph
+        \li Adjust some graph properties using widget controls
+    \endlist
 
     \image scatter-example.png
 
-    TODO
+    \section1 Creating the application
+
+    First, in main.cpp, we create a QApplication, instantiate Q3DScatter and a window container
+    for it:
+
+    \snippet ../examples/scatter/main.cpp 0
+
+    The call to QWidget::createWindowContainer is required, as all data visualization types
+    (Q3DBars, Q3DScatter, Q3DSurface) inherit QWindow. Any class inheriting QWindow cannot be used
+    as a widget any other way.
+
+    Then we'll create horizontal and vertical layouts. We'll add the graph and the vertical
+    layout into the horizontal one:
+
+    \snippet ../examples/scatter/main.cpp 1
+
+    We're not using the vertical layout for anything yet, but we'll get back to it in
+    \l {Using widgets to control the graph}
+
+    Next, let's create another class to handle the data addition and other interaction with the
+    graph. Let's call it ScatterDataModifier (See \l {Setting up the graph} and
+    \l {Adding data to the graph} for details):
+
+    \snippet ../examples/scatter/main.cpp 2
+
+    The application main is done and we can show the graph and start the event loop:
+
+    \snippet ../examples/scatter/main.cpp 3
+
+    \section1 Setting up the graph
+
+    Let's set up some visual qualities for the graph in the constructor of the ScatterDataModifier
+    class we instantiated in the application main:
+
+    \snippet ../examples/scatter/scatterdatamodifier.cpp 0
+
+    None of these are required, but are used to override graph defaults. You can try how it looks
+    with the preset defaults by commenting the block above out.
+
+    Then we'll set axes for the graph:
+
+    \snippet ../examples/scatter/scatterdatamodifier.cpp 1
+
+    And finally we create a QScatterDataProxy, set a label format for it and set it as the active
+    proxy for the graph:
+
+    \snippet ../examples/scatter/scatterdatamodifier.cpp 2
+
+    That concludes setting up the graph.
+
+    \section1 Adding data to the graph
+
+    In application main, we called \c {modifier->start()} after constructing all the necessary
+    objects. This is how it looks like:
+
+    \snippet ../examples/scatter/scatterdatamodifier.cpp 3
+
+    There is nothing in it except a call to another method. There is actually no need for a
+    separate \c start() method, but we keep it here in case we want to add some more functionality
+    in it that can be done only after all construction in application main is done.
+
+    The actual data addition is done in \c addData() method. First we configure the axes we created
+    in constructor:
+
+    \snippet ../examples/scatter/scatterdatamodifier.cpp 4
+
+    This could have been done in the ScatterDataModifier's constructor, but we added it here
+    to keep the constructor simpler and the axes configuration near the data.
+
+    Next we create a data array:
+
+    \snippet ../examples/scatter/scatterdatamodifier.cpp 5
+
+    And populate it:
+
+    \snippet ../examples/scatter/scatterdatamodifier.cpp 6
+
+    Finally we tell the proxy to start using the data we gave it:
+
+    \snippet ../examples/scatter/scatterdatamodifier.cpp 7
+
+    Now our graph has the data and is ready to be used. There isn't much interaction yet, though,
+    so let's continue by adding some widgets to play with.
+
+    \section1 Using widgets to control the graph
+
+    First, back in the application main, we'll create some widgets:
+
+    \snippet ../examples/scatter/main.cpp 4
+
+    And add them to the vertical layout we created earlier:
+
+    \snippet ../examples/scatter/main.cpp 5
+
+    Now, let's connect them to methods in ScatterDataModifier:
+
+    \snippet ../examples/scatter/main.cpp 6
+
+    Here are the methods in ScatterDataModifier the signals were connected to:
+
+    \snippet ../examples/scatter/scatterdatamodifier.cpp 8
+
+    And so we have an application in which we can control:
+
+    \list
+        \li Label style
+        \li Camera preset
+        \li Background visibility
+        \li Grid visibility
+        \li Dot shading smoothness
+        \li Dot style
+        \li Theme
+        \li Shadow quality
+        \li Font
+    \endlist
+
+    \section1 Example contents
 */
diff --git a/examples/scatter/main.cpp b/examples/scatter/main.cpp
index 961ed3db..ed0adc57 100644
--- a/examples/scatter/main.cpp
+++ b/examples/scatter/main.cpp
@@ -32,26 +32,29 @@
 
 int main(int argc, char **argv)
 {
+    //! [0]
     QApplication app(argc, argv);
-
-    QWidget *widget = new QWidget;
-    QHBoxLayout *hLayout = new QHBoxLayout(widget);
-    QVBoxLayout *vLayout = new QVBoxLayout();
-
     Q3DScatter *graph = new Q3DScatter();
-    QSize screenSize = graph->screen()->size();
-
     QWidget *container = QWidget::createWindowContainer(graph);
+    //! [0]
+
+    QSize screenSize = graph->screen()->size();
     container->setMinimumSize(QSize(screenSize.width() / 2, screenSize.height() / 1.5));
     container->setMaximumSize(screenSize);
     container->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
     container->setFocusPolicy(Qt::StrongFocus);
 
-    widget->setWindowTitle(QStringLiteral("values of some things in something"));
-
+    //! [1]
+    QWidget *widget = new QWidget;
+    QHBoxLayout *hLayout = new QHBoxLayout(widget);
+    QVBoxLayout *vLayout = new QVBoxLayout();
     hLayout->addWidget(container, 1);
     hLayout->addLayout(vLayout);
+    //! [1]
+
+    widget->setWindowTitle(QStringLiteral("A Cosine Wave"));
 
+    //! [4]
     QComboBox *themeList = new QComboBox(widget);
     themeList->addItem(QStringLiteral("Qt"));
     themeList->addItem(QStringLiteral("Primary Colors"));
@@ -98,7 +101,9 @@ int main(int argc, char **argv)
 
     QFontComboBox *fontList = new QFontComboBox(widget);
     fontList->setCurrentFont(QFont("Arial"));
+    //! [4]
 
+    //! [5]
     vLayout->addWidget(labelButton, 0, Qt::AlignTop);
     vLayout->addWidget(cameraButton, 0, Qt::AlignTop);
     vLayout->addWidget(backgroundCheckBox);
@@ -112,11 +117,13 @@ int main(int argc, char **argv)
     vLayout->addWidget(shadowQuality);
     vLayout->addWidget(new QLabel(QStringLiteral("Change font")));
     vLayout->addWidget(fontList, 1, Qt::AlignTop);
+    //! [5]
 
-    widget->show();
-
+    //! [2]
     ScatterDataModifier *modifier = new ScatterDataModifier(graph);
+    //! [2]
 
+    //! [6]
     QObject::connect(cameraButton, &QPushButton::clicked, modifier,
                      &ScatterDataModifier::changePresetCamera);
     QObject::connect(labelButton, &QPushButton::clicked, modifier,
@@ -145,8 +152,11 @@ int main(int argc, char **argv)
 
     QObject::connect(fontList, &QFontComboBox::currentFontChanged, modifier,
                      &ScatterDataModifier::changeFont);
+    //! [6]
 
+    //! [3]
+    widget->show();
     modifier->start();
-
     return app.exec();
+    //! [3]
 }
diff --git a/examples/scatter/scatterdatamodifier.cpp b/examples/scatter/scatterdatamodifier.cpp
index d9fc5bc3..1fb08c93 100644
--- a/examples/scatter/scatterdatamodifier.cpp
+++ b/examples/scatter/scatterdatamodifier.cpp
@@ -34,6 +34,7 @@ ScatterDataModifier::ScatterDataModifier(Q3DScatter *scatter)
       m_style(QDataVis::MeshStyleSpheres),
       m_smooth(true)
 {
+    //! [0]
     QFont font = m_graph->font();
     font.setPointSize(m_fontSize);
     m_graph->setFont(font);
@@ -41,13 +42,19 @@ ScatterDataModifier::ScatterDataModifier(Q3DScatter *scatter)
     m_graph->setTheme(QDataVis::ThemeEbony);
     m_graph->setShadowQuality(QDataVis::ShadowQualityHigh);
     m_graph->scene()->activeCamera()->setCameraPreset(QDataVis::CameraPresetFront);
+    //! [0]
+
+    //! [1]
     m_graph->setAxisX(new Q3DValueAxis);
     m_graph->setAxisY(new Q3DValueAxis);
     m_graph->setAxisZ(new Q3DValueAxis);
+    //! [1]
 
+    //! [2]
     QScatterDataProxy *proxy = new QScatterDataProxy;
     proxy->setItemLabelFormat("@xTitle: @xLabel @yTitle: @yLabel @zTitle: @zLabel");
     m_graph->setActiveDataProxy(proxy);
+    //! [2]
 
     changeLabelStyle();
 }
@@ -57,13 +64,16 @@ ScatterDataModifier::~ScatterDataModifier()
     delete m_graph;
 }
 
+//! [3]
 void ScatterDataModifier::start()
 {
     addData();
 }
+//! [3]
 
 void ScatterDataModifier::addData()
 {
+    //! [4]
     // Add labels
     m_graph->axisX()->setTitle("X");
     m_graph->axisY()->setTitle("Y");
@@ -71,10 +81,13 @@ void ScatterDataModifier::addData()
     m_graph->axisX()->setRange(-50.0, 50.0);
     m_graph->axisY()->setRange(-1.0, 1.0);
     m_graph->axisZ()->setRange(-50.0, 50.0);
+    //! [4]
 
+    //! [5]
     QScatterDataArray *dataArray = new QScatterDataArray;
     dataArray->resize(numberOfItems);
     QScatterDataItem *ptrToDataArray = &dataArray->first();
+    //! [5]
 
 #ifdef RANDOM_SCATTER
     for (int i = 0; i < numberOfItems; i++) {
@@ -82,6 +95,7 @@ void ScatterDataModifier::addData()
         ptrToDataArray++;
     }
 #else
+    //! [6]
     float limit = qSqrt(numberOfItems) / 2.0f;
     for (float i = -limit; i < limit; i++) {
         for (float j = -limit; j < limit; j++) {
@@ -89,11 +103,15 @@ void ScatterDataModifier::addData()
             ptrToDataArray++;
         }
     }
+    //! [6]
 #endif
 
-    static_cast<QScatterDataProxy *>(m_graph->activeDataProxy())->resetArray(dataArray);
+    //! [7]
+    m_graph->activeDataProxy()->resetArray(dataArray);
+    //! [7]
 }
 
+//! [8]
 void ScatterDataModifier::changeStyle(int style)
 {
     m_style = QDataVis::MeshStyle(style + 5); // skip unsupported mesh types
@@ -117,7 +135,7 @@ void ScatterDataModifier::changePresetCamera()
 
     m_graph->scene()->activeCamera()->setCameraPreset((QDataVis::CameraPreset)preset);
 
-    if (++preset > QDataVis::CameraPresetDirectlyAboveCCW45)
+    if (++preset > QDataVis::CameraPresetDirectlyBelow)
         preset = QDataVis::CameraPresetFrontLow;
 }
 
@@ -141,15 +159,13 @@ void ScatterDataModifier::changeFont(const QFont &font)
 void ScatterDataModifier::shadowQualityUpdatedByVisual(QDataVis::ShadowQuality sq)
 {
     int quality = int(sq);
-    // Updates the UI component to show correct shadow quality
-    emit shadowQualityChanged(quality);
+    emit shadowQualityChanged(quality); // connected to a checkbox in main.cpp
 }
 
 void ScatterDataModifier::changeShadowQuality(int quality)
 {
     QDataVis::ShadowQuality sq = QDataVis::ShadowQuality(quality);
     m_graph->setShadowQuality(sq);
-    emit shadowQualityChanged(quality);
 }
 
 void ScatterDataModifier::setBackgroundEnabled(int enabled)
@@ -161,6 +177,7 @@ void ScatterDataModifier::setGridEnabled(int enabled)
 {
     m_graph->setGridVisible((bool)enabled);
 }
+//! [8]
 
 QVector3D ScatterDataModifier::randVector()
 {