Widget example documentation

Task-number: QTRD-2401

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

4 files changed, 188 insertions, 38 deletions

diff --git a/examples/widget/doc/images/widget-example.png b/examples/widget/doc/images/widget-example.png
index 4fb43b42..c2d4d598 100644
--- a/examples/widget/doc/images/widget-example.png
+++ b/examples/widget/doc/images/widget-example.png
diff --git a/examples/widget/doc/src/widget.qdoc b/examples/widget/doc/src/widget.qdoc
index 12d621fa..b67386c7 100644
--- a/examples/widget/doc/src/widget.qdoc
+++ b/examples/widget/doc/src/widget.qdoc
@@ -23,9 +23,137 @@
     \brief Using Q3DBars in a widget application.
 
     The widget example shows how to make a 3D bar graph using Q3DBars and combining the use of
-    widgets for adjusting several adjustable qualities.
+    widgets for adjusting several adjustable qualities. The example shows how to:
+
+    \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
+    \endlist
+
+    It also demonstrates how having negative bar values affects the graph.
 
     \image widget-example.png
 
-    TODO
+    \section1 Creating the application
+
+    First, in main.cpp, we create a QApplication, instantiate Q3DBars and a window container
+    for it:
+
+    \snippet ../examples/widget/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/widget/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 GraphModifier (See \l {Setting up the graph} and
+    \l {Adding data to the graph} for details):
+
+    \snippet ../examples/widget/main.cpp 2
+
+    The application main is done and we can show the graph and start the event loop:
+
+    \snippet ../examples/widget/main.cpp 3
+
+    \section1 Setting up the graph
+
+    Let's set up the graph in the constructor of the GraphModifier class we instantiated in the
+    application main:
+
+    \snippet ../examples/widget/graphmodifier.cpp 0
+
+    Let's take a closer look at parts of the code.
+
+    First we're creating the axes and the proxy into member variables to support changing them
+    easily later on, if we want to:
+
+    \snippet ../examples/widget/graphmodifier.cpp 1
+
+    Then we're setting some of the visual qualities for the graph:
+
+    \snippet ../examples/widget/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:
+
+    \snippet ../examples/widget/graphmodifier.cpp 3
+
+    And add the proxy. Note that we're not setting it active yet, but just adding it:
+
+    \snippet ../examples/widget/graphmodifier.cpp 4
+
+    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
+
+    The method is used to add data to the proxy:
+
+    \snippet ../examples/widget/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/widget/graphmodifier.cpp 6
+
+    Finally we set the proxy and the axes active. Now our graph has the data and is ready to be
+    used.
+
+    \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:
+
+    \snippet ../examples/widget/main.cpp 4
+
+    We can use these to rotate the graph using slider widgets instead of just using the mouse or
+    touch.
+
+    Let's add them to the vertical layout we created earlier:
+
+    \snippet ../examples/widget/main.cpp 5
+
+    Then we'll connect them to methods in GraphModifier:
+
+    \snippet ../examples/widget/main.cpp 6
+
+    Here are the methods in GraphModifier the signals were connected to:
+
+    \snippet ../examples/widget/graphmodifier.cpp 7
+
+    Now these two sliders can be used to rotate the graph.
+
+    And so we have an application in which we can control:
+
+    \list
+        \li Graph rotation
+        \li Label style
+        \li Camera preset
+        \li Background visibility
+        \li Grid visibility
+        \li Bar shading smoothness
+        \li Bar style
+        \li Selection mode
+        \li Theme
+        \li Shadow quality
+        \li Font
+        \li Font size
+    \endlist
+
+    \section1 Example contents
+
 */
diff --git a/examples/widget/graphmodifier.cpp b/examples/widget/graphmodifier.cpp
index c5b8be4a..0b33bde0 100644
--- a/examples/widget/graphmodifier.cpp
+++ b/examples/widget/graphmodifier.cpp
@@ -28,27 +28,36 @@ QT_DATAVISUALIZATION_USE_NAMESPACE
 
 const QString celsiusString = QString(QChar(0xB0)) + "C";
 
+//! [0]
 GraphModifier::GraphModifier(Q3DBars *bargraph)
     : m_graph(bargraph),
       m_xRotation(0.0),
       m_yRotation(0.0),
-      m_fontSize(20),
+      m_fontSize(30),
       m_segments(4),
       m_subSegments(3),
-      m_minval(-20.0), // TODO Bargraph Y-axis currently only properly supports zero-centered ranges
+      m_minval(-20.0),
       m_maxval(20.0),
+      //! [1]
       m_temperatureAxis(new Q3DValueAxis),
       m_yearAxis(new Q3DCategoryAxis),
       m_monthAxis(new Q3DCategoryAxis),
       m_temperatureData(new QBarDataProxy),
+      //! [1]
       m_style(QDataVis::MeshStyleBevelBars),
       m_smooth(false)
 {
+    //! [2]
+    m_graph->setBackgroundVisible(false);
+    m_graph->setShadowQuality(QDataVis::ShadowQualitySoftMedium);
+    m_graph->setFont(QFont("Times New Roman", m_fontSize));
+    m_graph->setLabelStyle(QDataVis::LabelStyleFromTheme);
+    //! [2]
+
     m_months << "January" << "February" << "March" << "April" << "May" << "June" << "July" << "August" << "September" << "October" << "November" << "December";
     m_years << "2006" << "2007" << "2008" << "2009" << "2010" << "2011" << "2012";
 
-    m_graph->setBackgroundVisible(false);
-
+    //! [3]
     m_temperatureAxis->setTitle("Average temperature");
     m_temperatureAxis->setSegmentCount(m_segments);
     m_temperatureAxis->setSubSegmentCount(m_subSegments);
@@ -56,26 +65,22 @@ GraphModifier::GraphModifier(Q3DBars *bargraph)
     m_temperatureAxis->setLabelFormat(QString(QStringLiteral("%d ") + celsiusString));
 
     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->setShadowQuality(QDataVis::ShadowQualitySoftMedium);
+    //! [3]
 
     m_temperatureData->setItemLabelFormat(QStringLiteral("@valueTitle for @colLabel @rowLabel: @valueLabel"));
 
+    //! [4]
     m_graph->addDataProxy(m_temperatureData);
-
-    m_graph->setFont(QFont("Times Roman", 20));
-
-    m_graph->setSelectionMode(QDataVis::SelectionModeItem);
+    //! [4]
 
     resetTemperatureData();
-    changeLabelStyle();
 }
+//! [0]
 
 GraphModifier::~GraphModifier()
 {
@@ -84,17 +89,18 @@ GraphModifier::~GraphModifier()
 
 void GraphModifier::start()
 {
+    //! [6]
     m_graph->setActiveDataProxy(m_temperatureData);
 
-    m_graph->setTitle(QStringLiteral("Average temperatures in Oulu, Finland (2006-2012)"));
-
     m_graph->setValueAxis(m_temperatureAxis);
     m_graph->setRowAxis(m_yearAxis);
     m_graph->setColumnAxis(m_monthAxis);
+    //! [6]
 }
 
 void GraphModifier::resetTemperatureData()
 {
+    //! [5]
     // Set up data
     static const qreal temp[7][12] = {
         {-6.7, -11.7, -9.7, 3.3, 9.2, 14.0, 16.3, 17.8, 10.2, 2.1, -2.6, -0.3},    // 2006
@@ -106,24 +112,25 @@ void GraphModifier::resetTemperatureData()
         {-8.7, -11.3, -2.3, 0.4, 7.5, 12.2, 16.4, 14.1, 9.2, 3.1, 0.3, -12.1}      // 2012
     };
 
-    // Create data rows
+    // Create data array
     QBarDataArray *dataSet = new QBarDataArray;
     QBarDataRow *dataRow;
 
     dataSet->reserve(m_years.size());
     for (int year = 0; year < m_years.size(); year++) {
+        // Create a data row
         dataRow = new QBarDataRow(m_months.size());
-        // Create data items
         for (int month = 0; month < m_months.size(); month++) {
-            // Add data to rows
+            // Add data to the row
             (*dataRow)[month].setValue(temp[year][month]);
         }
-        // Add row to set
+        // Add the row to the set
         dataSet->append(dataRow);
     }
 
-    // Add data to the graph (the graph assumes ownership)
+    // Add data to the graph (the graph assumes ownership of it)
     m_temperatureData->resetArray(dataSet, m_years, m_months);
+    //! [5]
 }
 
 void GraphModifier::changeStyle(int style)
@@ -191,6 +198,7 @@ void GraphModifier::changeShadowQuality(int quality)
     emit shadowQualityChanged(quality);
 }
 
+//! [7]
 void GraphModifier::rotateX(int rotation)
 {
     m_xRotation = rotation;
@@ -202,6 +210,7 @@ void GraphModifier::rotateY(int rotation)
     m_yRotation = rotation;
     m_graph->scene()->activeCamera()->setCameraPosition(m_xRotation, m_yRotation);
 }
+//! [7]
 
 void GraphModifier::setBackgroundEnabled(int enabled)
 {
diff --git a/examples/widget/main.cpp b/examples/widget/main.cpp
index c1bee4e5..158244b4 100644
--- a/examples/widget/main.cpp
+++ b/examples/widget/main.cpp
@@ -32,25 +32,27 @@
 
 int main(int argc, char **argv)
 {
+    //! [0]
     QApplication app(argc, argv);
-
-    QWidget *widget = new QWidget;
-    QHBoxLayout *hLayout = new QHBoxLayout(widget);
-    QVBoxLayout *vLayout = new QVBoxLayout();
-
     Q3DBars *widgetgraph = new Q3DBars();
-    QSize screenSize = widgetgraph->screen()->size();
-
     QWidget *container = QWidget::createWindowContainer(widgetgraph);
+    //! [0]
+
+    QSize screenSize = widgetgraph->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("Average temperatures in Oulu, Finland (2006-2012)"));
-
+    //! [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("Average temperatures in Oulu, Finland (2006-2012)"));
 
     QComboBox *themeList = new QComboBox(widget);
     themeList->addItem(QStringLiteral("Qt"));
@@ -99,25 +101,30 @@ int main(int argc, char **argv)
     gridCheckBox->setText(QStringLiteral("Show grid"));
     gridCheckBox->setChecked(true);
 
+    //! [4]
     QSlider *rotationSliderX = new QSlider(Qt::Horizontal, widget);
-    rotationSliderX->setTickInterval(1);
+    rotationSliderX->setTickInterval(30);
+    rotationSliderX->setTickPosition(QSlider::TicksBelow);
     rotationSliderX->setMinimum(-180);
     rotationSliderX->setValue(0);
     rotationSliderX->setMaximum(180);
     QSlider *rotationSliderY = new QSlider(Qt::Horizontal, widget);
-    rotationSliderY->setTickInterval(1);
+    rotationSliderY->setTickInterval(15);
+    rotationSliderY->setTickPosition(QSlider::TicksAbove);
     rotationSliderY->setMinimum(-90);
     rotationSliderY->setValue(0);
     rotationSliderY->setMaximum(90);
+    //! [4]
 
     QSlider *fontSizeSlider = new QSlider(Qt::Horizontal, widget);
-    fontSizeSlider->setTickInterval(1);
+    fontSizeSlider->setTickInterval(10);
+    fontSizeSlider->setTickPosition(QSlider::TicksBelow);
     fontSizeSlider->setMinimum(1);
-    fontSizeSlider->setValue(20);
+    fontSizeSlider->setValue(30);
     fontSizeSlider->setMaximum(100);
 
     QFontComboBox *fontList = new QFontComboBox(widget);
-    fontList->setCurrentFont(QFont("Arial"));
+    fontList->setCurrentFont(QFont("Times New Roman"));
 
     QComboBox *shadowQuality = new QComboBox(widget);
     shadowQuality->addItem(QStringLiteral("None"));
@@ -129,10 +136,12 @@ int main(int argc, char **argv)
     shadowQuality->addItem(QStringLiteral("High Soft"));
     shadowQuality->setCurrentIndex(5);
 
+    //! [5]
     vLayout->addWidget(new QLabel(QStringLiteral("Rotate horizontally")));
     vLayout->addWidget(rotationSliderX, 0, Qt::AlignTop);
     vLayout->addWidget(new QLabel(QStringLiteral("Rotate vertically")));
     vLayout->addWidget(rotationSliderY, 0, Qt::AlignTop);
+    //! [5]
     vLayout->addWidget(labelButton, 0, Qt::AlignTop);
     vLayout->addWidget(cameraButton, 0, Qt::AlignTop);
     vLayout->addWidget(backgroundCheckBox);
@@ -151,12 +160,14 @@ int main(int argc, char **argv)
     vLayout->addWidget(new QLabel(QStringLiteral("Adjust font size")));
     vLayout->addWidget(fontSizeSlider, 1, Qt::AlignTop);
 
-    widget->show();
-
+    //! [2]
     GraphModifier *modifier = new GraphModifier(widgetgraph);
+    //! [2]
 
+    //! [6]
     QObject::connect(rotationSliderX, &QSlider::valueChanged, modifier, &GraphModifier::rotateX);
     QObject::connect(rotationSliderY, &QSlider::valueChanged, modifier, &GraphModifier::rotateY);
+    //! [6]
 
     QObject::connect(labelButton, &QPushButton::clicked, modifier,
                      &GraphModifier::changeLabelStyle);
@@ -192,7 +203,9 @@ int main(int argc, char **argv)
     QObject::connect(fontList, &QFontComboBox::currentFontChanged, modifier,
                      &GraphModifier::changeFont);
 
+    //! [3]
+    widget->show();
     modifier->start();
-
     return app.exec();
+    //! [3]
 }