From d93981d49d0c4ac7dbc98e089387b4e483b19297 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomi=20Korpip=C3=A4=C3=A4?= Date: Tue, 8 Oct 2013 13:59:47 +0300 Subject: Scatter example documentation Task-number: QTRD-2400 Change-Id: Ic6e67298c493ac2b92ad03c6f3746a5481ae1e97 Reviewed-by: Miikka Heikkinen --- examples/scatter/doc/images/scatter-example.png | Bin 0 -> 489862 bytes examples/scatter/doc/src/scatter.qdoc | 127 +++++++++++++++++++++++- examples/scatter/main.cpp | 34 ++++--- examples/scatter/scatterdatamodifier.cpp | 27 ++++- 4 files changed, 169 insertions(+), 19 deletions(-) create mode 100644 examples/scatter/doc/images/scatter-example.png 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 Binary files /dev/null and b/examples/scatter/doc/images/scatter-example.png differ 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(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() { -- cgit v1.2.3