diff options
Diffstat (limited to 'examples/qmloscilloscope/doc/src/qmloscilloscope.qdoc')
-rw-r--r-- | examples/qmloscilloscope/doc/src/qmloscilloscope.qdoc | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/examples/qmloscilloscope/doc/src/qmloscilloscope.qdoc b/examples/qmloscilloscope/doc/src/qmloscilloscope.qdoc new file mode 100644 index 00000000..9fdcd8d2 --- /dev/null +++ b/examples/qmloscilloscope/doc/src/qmloscilloscope.qdoc @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** 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 qmloscilloscope + \title Qt Quick 2 Oscilloscope Example + \ingroup qtdatavisualization_examples + \brief Example of a hybrid C++ and QML application. + + The Qt Quick 2 oscilloscope example shows how to combine C++ and QML in an application, + as well as showing data that changes realtime. + + \image qmloscilloscope-example.png + + The interesting thing about this example is combining C++ and QML, so we'll concentrate on + that and skip explaining the basic functionality - for + more detailed QML example documentation, see \l{Qt Quick 2 Scatter Example}. + + \section1 Data source in C++ + + The item model based proxies are good for simple and/or static graphs, but to achieve + best performance when displaying data changing in realtime, the basic proxies should be used. + Those are not supported in QML, as the data items they store are not \l{QObject}s and + cannot therefore be directly manipulated from QML code. + To overcome this limitation, we implement a simple \c DataSource class in C++ to populate the + data proxy of the series. + + The \c DataSource class provides three methods that can be called from QML: + + \snippet ../examples/qmloscilloscope/datasource.h 0 + + The first method, \c generateData(), creates a cache of simulated oscilloscope data for us + to display. The data is cached in a format accepted by QSurfaceDataProxy: + + \snippet ../examples/qmloscilloscope/datasource.cpp 0 + + The secod method, \c update(), copies one set of the cached data into another array, which we + set to the data proxy of the series by calling QSurfaceDataProxy::resetArray(). + We reuse the same array if the array dimensions have not changed to minimize overhead: + + \snippet ../examples/qmloscilloscope/datasource.cpp 1 + + \note Even though we are operating on the array pointer we have previously set to the proxy + we still need to call QSurfaceDataProxy::resetArray() after changing the data in it to prompt + the graph to render the data. + + The final method, \c selectionLabel(), is used to generate a label string we can show on the + QML ui. This method utilizes the axis formats to format the label: + + \snippet ../examples/qmloscilloscope/datasource.cpp 2 + + To be able to access the \c DataSource methods from QML, we need to expose it. We do this by + defining a context property in application main: + + \snippet ../examples/qmloscilloscope/main.cpp 0 + + \section1 QML + + In the QML codes, we define a Surface3D graph normally and give it a Surface3DSeries: + + \snippet ../examples/qmloscilloscope/qml/qmloscilloscope/main.qml 0 + + One interesting detail is that we don't specify a proxy for the Surface3DSeries we attach + to the graph. This makes the series to utilize the default QSurfaceDataProxy. + + We also specify an empty string for \l{Abstract3DSeries::itemLabelFormat}{itemLabelFormat}, since we want to display + the selected item information in a \c Text element instead of a label above the selection pointer. + This is done because the selection pointer moves around a lot as the data changes, which makes + the regular selection label difficult to read. + When selection point changes, we update the label text using a helper function + \c updateSelectionLabel(), which calls one of the methods we defined for our \c DataSource class + to obtain the label: + + \snippet ../examples/qmloscilloscope/qml/qmloscilloscope/main.qml 1 + + We initialize the \c DataSource cache when the graph is complete by calling a helper function + \c generateData(), which calls the method with the same name on the \c DataSource: + + \snippet ../examples/qmloscilloscope/qml/qmloscilloscope/main.qml 2 + \dots 4 + \snippet ../examples/qmloscilloscope/qml/qmloscilloscope/main.qml 4 + + To trigger the updates in data, we define a \c Timer item which calls the \c update() method on the \c + DataSource at requested intervals. The label update is also triggered on each cycle: + + \snippet ../examples/qmloscilloscope/qml/qmloscilloscope/main.qml 3 +*/ |