Fix Audiolevels and Bars examples & documentation for TP2

Task-number: QTRD-2635

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

5 files changed, 58 insertions, 50 deletions

diff --git a/examples/audiolevels/doc/src/audiolevels.qdoc b/examples/audiolevels/doc/src/audiolevels.qdoc
index 1aef9174..d52b2e25 100644
--- a/examples/audiolevels/doc/src/audiolevels.qdoc
+++ b/examples/audiolevels/doc/src/audiolevels.qdoc
@@ -30,14 +30,14 @@
 
     \image audiolevels-example.png
 
-    The interesting stuff happens in AudioLevels and AudioLevelsIODevice classes, so we
+    The interesting stuff happens in \c AudioLevels and \c AudioLevelsIODevice classes, so we
     concentrate on those and skip explaining the basic Q3DBars functionality - for that see
     \l{Bars Example}.
 
-    AudioLevelsIODevice subclasses QIODevice and is given as input device for QAudioInput
+    \c AudioLevelsIODevice subclasses QIODevice and is given as input device for QAudioInput
     class, so it receives microphone data.
 
-    In the header file for QAudioInput class we declare necessary members:
+    In the header file for \c AudioLevels class we declare necessary members:
 
     \snippet ../examples/audiolevels/audiolevels.h 0
 
@@ -45,7 +45,7 @@
 
     \snippet ../examples/audiolevels/audiolevels.cpp 0
 
-    In the header file for AudioLevelsIODevice class we store pointers to the data proxy and
+    In the header file for \c AudioLevelsIODevice class we store pointers to the data proxy and
     also the data array we give to the proxy, because we reuse the same array to keep memory
     reallocations to the minimum:
 
@@ -61,11 +61,11 @@
     byte from audio input is visualized. This is necessary to make the data readable, as it would
     otherwise make the graph scroll too fast.
 
-    In the AudioLevelsIODevice class constructor we initialize the data array:
+    In the \c AudioLevelsIODevice class constructor we initialize the data array:
 
     \snippet ../examples/audiolevels/audiolevelsiodevice.cpp 0
 
-    The AudioLevelsIODevice::writeData function is called whenever there is new audio data
+    The \c AudioLevelsIODevice::writeData function is called whenever there is new audio data
     available to be visualized. There we move the old data along the rows and insert new
     data in the beginning of the rows:
 
@@ -75,11 +75,11 @@
     the existing data array, as this allows us to avoid any extra memory allocations in our
     application code. This also means the data array dimensions do not change, which further
     improves efficiency in the bar graph renderer.
-    Secondly, since the rows are QVectors of QBarDataItems, which do not allocate any data that needs
-    deletion, we can utilize memmove and memcpy functions to quickly move and copy data around.
+    Secondly, since each row is a QVector of bar data items, which do not allocate any data that needs
+    deletion, we can utilize \c memmove and \c memcpy functions to quickly move and copy data around.
 
     \note In the future versions of Qt Data Visualization, QBarDataItem might get extended so that
     it does allocate some memory to store other optional bar properties besides the value.
-    In use cases where those optional properties are used, using memmove and memcpy would lead to
+    In use cases where those optional properties are used, using \c memmove and \c memcpy would lead to
     memory leaks, so use them with care.
 */
diff --git a/examples/bars/doc/src/bars.qdoc b/examples/bars/doc/src/bars.qdoc
index e24b4d0f..79cfb270 100644
--- a/examples/bars/doc/src/bars.qdoc
+++ b/examples/bars/doc/src/bars.qdoc
@@ -27,8 +27,8 @@
 
     \list
         \li Create an application with Q3DBars and some widgets
-        \li Use QBarDataProxy to set data to the graph
-        \li Adjust some graph properties using widget controls
+        \li Use QBar3DSeries and QBarDataProxy to set data to the graph
+        \li Adjust some graph and series properties using widget controls
     \endlist
 
     It also demonstrates how having negative bar values affects the graph.
@@ -57,7 +57,7 @@
     \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 GraphModifier (See \l {Setting up the graph} and
+    graph. Let's call it \c GraphModifier (See \l {Setting up the graph} and
     \l {Adding data to the graph} for details):
 
     \snippet ../examples/bars/main.cpp 2
@@ -68,7 +68,7 @@
 
     \section1 Setting up the graph
 
-    Let's set up the graph in the constructor of the GraphModifier class we instantiated in the
+    Let's set up the graph in the constructor of the \c GraphModifier class we instantiated in the
     application main:
 
     \snippet ../examples/bars/graphmodifier.cpp 0
@@ -84,56 +84,65 @@
 
     \snippet ../examples/bars/graphmodifier.cpp 2
 
-    We're also setting up the axes and adding them to the graph. Notice that we're not setting them
-    active yet:
+    We're also setting up the axes and setting them to the graph as active axes:
 
     \snippet ../examples/bars/graphmodifier.cpp 3
 
-    And add the proxy. Note that we're not setting it active yet, but just adding it:
+    Next we create two series for the graph, giving each one a data proxy. Here we also initialize
+    some of the visual properties of the series. Note that the second series is initially not visible:
+
+    \snippet ../examples/bars/graphmodifier.cpp 8
+
+    The series need to be added to the graph to show them:
 
     \snippet ../examples/bars/graphmodifier.cpp 4
 
+    Finally, we set the camera angle by calling the same method the camera angle change button
+    in the UI uses to cycle through various camera angles:
+
+    \snippet ../examples/bars/graphmodifier.cpp 6
+
+    There you can see that the camera is controlled via the scene object of the graph:
+
+    \snippet ../examples/bars/graphmodifier.cpp 10
+
+    For more information about using scene and cameras, see Q3DScene and Q3DCamera.
+
     That concludes setting up the graph.
 
     \section1 Adding data to the graph
 
     At the end of the constructor there's a call:
 
-    \code resetTemperatureData(); \endcode
+    \snippet ../examples/bars/graphmodifier.cpp 9
 
-    The method is used to add data to the proxy:
+    This method is used to add data to the proxies of the two series:
 
     \snippet ../examples/bars/graphmodifier.cpp 5
 
-    Now the data is in the proxy, but not in the graph. We have not set the proxy active yet.
-
-    In application main, we called \c {modifier->start()} after constructing all the necessary
-    objects. This is what is done in it:
-
-    \snippet ../examples/bars/graphmodifier.cpp 6
-
-    Finally we set the proxy and the axes active. Now our graph has the data and is ready to be
-    used.
+    Now the series have data to show.
 
     \section1 Using widgets to control the graph
 
     There isn't much interaction yet, so let's continue by adding some widgets back in the
-    application main. Let's just focus on two:
+    application main. Let's just focus on two as an example:
 
     \snippet ../examples/bars/main.cpp 4
 
-    We can use these to rotate the graph using slider widgets instead of just using the mouse or
+    We can use these slider widgets to rotate the graph instead of just using the mouse or
     touch.
 
     Let's add them to the vertical layout we created earlier:
 
     \snippet ../examples/bars/main.cpp 5
 
-    Then we'll connect them to methods in GraphModifier:
+    Then we'll connect them to methods in \c GraphModifier:
 
     \snippet ../examples/bars/main.cpp 6
 
-    Here are the methods in GraphModifier the signals were connected to:
+    Here are the methods in \c GraphModifier the signals were connected to. The camera
+    is controlled via the scene object. This time we specify the actual camera position
+    along the orbit around the center point, instead of specifying a preset camera angle:
 
     \snippet ../examples/bars/graphmodifier.cpp 7
 
@@ -148,6 +157,7 @@
         \li Background visibility
         \li Grid visibility
         \li Bar shading smoothness
+        \li Visibility of the second bar series
         \li Bar style
         \li Selection mode
         \li Theme
diff --git a/examples/bars/graphmodifier.cpp b/examples/bars/graphmodifier.cpp
index ff7a8032..13e4d3e7 100644
--- a/examples/bars/graphmodifier.cpp
+++ b/examples/bars/graphmodifier.cpp
@@ -72,29 +72,36 @@ GraphModifier::GraphModifier(Q3DBars *bargraph)
     m_yearAxis->setTitle("Year");
     m_monthAxis->setTitle("Month");
 
-    m_graph->addAxis(m_temperatureAxis);
-    m_graph->addAxis(m_yearAxis);
-    m_graph->addAxis(m_monthAxis);
+    m_graph->setValueAxis(m_temperatureAxis);
+    m_graph->setRowAxis(m_yearAxis);
+    m_graph->setColumnAxis(m_monthAxis);
     //! [3]
 
+    //! [8]
     QBar3DSeries *series = new QBar3DSeries(m_primaryData);
     series->setItemLabelFormat(QStringLiteral("Oulu - @colLabel @rowLabel: @valueLabel"));
-    series->setMesh(m_primaryStyle);
-    series->setMeshSmooth(m_smooth);
+    series->setMesh(QAbstract3DSeries::MeshBevelBar);
+    series->setMeshSmooth(false);
 
     QBar3DSeries *series2 = new QBar3DSeries(m_secondaryData);
     series2->setItemLabelFormat(QStringLiteral("Helsinki - @colLabel @rowLabel: @valueLabel"));
-    series2->setMesh(m_secondaryStyle);
-    series2->setMeshSmooth(m_smooth);
+    series2->setMesh(QAbstract3DSeries::MeshSphere);
+    series2->setMeshSmooth(false);
     series2->setVisible(false);
+    //! [8]
 
     //! [4]
     m_graph->addSeries(series);
     m_graph->addSeries(series2);
     //! [4]
 
+    //! [6]
     changePresetCamera();
+    //! [6]
+
+    //! [9]
     resetTemperatureData();
+    //! [9]
 }
 //! [0]
 
@@ -103,15 +110,6 @@ GraphModifier::~GraphModifier()
     delete m_graph;
 }
 
-void GraphModifier::start()
-{
-    //! [6]
-    m_graph->setValueAxis(m_temperatureAxis);
-    m_graph->setRowAxis(m_yearAxis);
-    m_graph->setColumnAxis(m_monthAxis);
-    //! [6]
-}
-
 void GraphModifier::resetTemperatureData()
 {
     //! [5]
@@ -175,12 +173,14 @@ void GraphModifier::changeStyle(int style)
 
 void GraphModifier::changePresetCamera()
 {
+    //! [10]
     static int preset = Q3DCamera::CameraPresetFront;
 
     m_graph->scene()->activeCamera()->setCameraPreset((Q3DCamera::CameraPreset)preset);
 
     if (++preset > Q3DCamera::CameraPresetDirectlyBelow)
         preset = Q3DCamera::CameraPresetFrontLow;
+    //! [10]
 }
 
 void GraphModifier::changeTheme(int theme)
@@ -194,7 +194,7 @@ void GraphModifier::changeTheme(int theme)
 
 void GraphModifier::changeLabelBackground()
 {
-    m_graph->theme()->setLabelBackgroundEnabled(!m_graph->theme()->isBackgroundEnabled());
+    m_graph->theme()->setLabelBackgroundEnabled(!m_graph->theme()->isLabelBackgroundEnabled());
 }
 
 void GraphModifier::changeSelectionMode(int selectionMode)
diff --git a/examples/bars/graphmodifier.h b/examples/bars/graphmodifier.h
index e361bb87..f7c0acaf 100644
--- a/examples/bars/graphmodifier.h
+++ b/examples/bars/graphmodifier.h
@@ -48,7 +48,6 @@ public:
     void setGridEnabled(int enabled);
     void setSmoothBars(int smooth);
     void setSeriesVisibility(int enabled);
-    void start();
 
 public slots:
     void changeStyle(int style);
diff --git a/examples/bars/main.cpp b/examples/bars/main.cpp
index e4a05401..21a4e0e6 100644
--- a/examples/bars/main.cpp
+++ b/examples/bars/main.cpp
@@ -249,7 +249,6 @@ int main(int argc, char **argv)
 
     //! [3]
     widget->show();
-    modifier->start();
     return app.exec();
     //! [3]
 }