From 79ac7ce92c9651ce420a427f786f35af97dd8491 Mon Sep 17 00:00:00 2001 From: Miikka Heikkinen Date: Mon, 7 Oct 2013 13:50:23 +0300 Subject: Improve documentation on data handling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: Ie1acb5b12eeb9b59815b7482042edc8adc0250d8 Reviewed-by: Tomi Korpipää --- .../data/qitemmodelbardatamapping.cpp | 6 +- .../data/qitemmodelbardataproxy.cpp | 6 ++ .../data/qitemmodelscatterdataproxy.cpp | 6 ++ .../data/qitemmodelsurfacedatamapping.cpp | 6 +- .../data/qitemmodelsurfacedataproxy.cpp | 6 ++ .../doc/snippets/doc_src_qtdatavisualization.cpp | 17 +++++ .../doc/src/qtdatavisualization.qdoc | 76 +++++++++++++++++++++- 7 files changed, 117 insertions(+), 6 deletions(-) (limited to 'src/datavisualization') diff --git a/src/datavisualization/data/qitemmodelbardatamapping.cpp b/src/datavisualization/data/qitemmodelbardatamapping.cpp index 54cb0708..fc6f8f54 100644 --- a/src/datavisualization/data/qitemmodelbardatamapping.cpp +++ b/src/datavisualization/data/qitemmodelbardatamapping.cpp @@ -88,12 +88,14 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE /*! * \qmlproperty list BarDataMapping::rowCategories - * The row categories of the mapping. + * The row categories of the mapping. Only items with row roles that are found in this list are + * included when data is resolved. The rows are ordered in the same order as they are in this list. */ /*! * \qmlproperty list BarDataMapping::columnCategories - * The column categories of the mapping. + * The column categories of the mapping. Only items with column roles that are found in this list are + * included when data is resolved. The columns are ordered in the same order as they are in this list. */ /*! diff --git a/src/datavisualization/data/qitemmodelbardataproxy.cpp b/src/datavisualization/data/qitemmodelbardataproxy.cpp index 85fd8bf9..b0fa74b6 100644 --- a/src/datavisualization/data/qitemmodelbardataproxy.cpp +++ b/src/datavisualization/data/qitemmodelbardataproxy.cpp @@ -32,6 +32,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE * for Q3DBars. It uses QItemModelBarDataMapping instance to map data from the model to Q3DBars * graph. * + * Data is resolved asynchronously whenever the mapping or the model changes. + * QBarDataProxy::arrayReset() is emitted when the data has been resolved. + * * \sa QItemModelBarDataMapping, {Qt Data Visualization Data Handling} */ @@ -46,6 +49,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE * * This type allows you to use AbstractItemModel derived models as a data source for Bars3D. * + * Data is resolved asynchronously whenever the mapping or the model changes. + * QBarDataProxy::arrayReset() is emitted when the data has been resolved. + * * Usage example: * * \snippet doc_src_qmldatavisualization.cpp 7 diff --git a/src/datavisualization/data/qitemmodelscatterdataproxy.cpp b/src/datavisualization/data/qitemmodelscatterdataproxy.cpp index 7527f87e..b037d4d1 100644 --- a/src/datavisualization/data/qitemmodelscatterdataproxy.cpp +++ b/src/datavisualization/data/qitemmodelscatterdataproxy.cpp @@ -31,6 +31,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE * QItemModelScatterDataProxy allows you to use QAbstractItemModel derived models as a data source * for Q3DScatter. It maps roles defined in QItemModelScatterDataMapping to roles in the model. * + * Data is resolved asynchronously whenever the mapping or the model changes. + * QScatterDataProxy::arrayReset() is emitted when the data has been resolved. + * * /sa {Qt Data Visualization Data Handling} */ @@ -45,6 +48,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE * * This type allows you to use AbstractItemModel derived models as a data source for Scatter3D. * + * Data is resolved asynchronously whenever the mapping or the model changes. + * QScatterDataProxy::arrayReset() is emitted when the data has been resolved. + * * Usage example: * * \snippet doc_src_qmldatavisualization.cpp 8 diff --git a/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp b/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp index 0b7c74c9..5388ec18 100644 --- a/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp +++ b/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp @@ -89,12 +89,14 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE /*! * \qmlproperty list SurfaceDataMapping::rowCategories - * The row categories of the mapping. + * The row categories of the mapping. Only items with row roles that are found in this list are + * included when data is resolved. The rows are ordered in the same order as they are in this list. */ /*! * \qmlproperty list SurfaceDataMapping::columnCategories - * The column categories of the mapping. + * The column categories of the mapping. Only items with column roles that are found in this list are + * included when data is resolved. The columns are ordered in the same order as they are in this list. */ /*! diff --git a/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp b/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp index 22271c2e..f6403e9b 100644 --- a/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp +++ b/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp @@ -33,6 +33,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE * QItemModelSurfaceDataProxy allows you to use QAbstractItemModel derived models as a data source * for Q3DSurface. It maps roles defined in QItemModelSurfaceDataMapping to roles in the model. * + * Data is resolved asynchronously whenever the mapping or the model changes. + * QSurfaceDataProxy::arrayReset() is emitted when the data has been resolved. + * * /sa {Qt Data Visualization Data Handling} */ @@ -47,6 +50,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE * * This type allows you to use AbstractItemModel derived models as a data source for Surface3D. * + * Data is resolved asynchronously whenever the mapping or the model changes. + * QSurfaceDataProxy::arrayReset() is emitted when the data has been resolved. + * * Usage example: * * \snippet doc_src_qmldatavisualization.cpp 9 diff --git a/src/datavisualization/doc/snippets/doc_src_qtdatavisualization.cpp b/src/datavisualization/doc/snippets/doc_src_qtdatavisualization.cpp index b64755e1..2f3d6a98 100644 --- a/src/datavisualization/doc/snippets/doc_src_qtdatavisualization.cpp +++ b/src/datavisualization/doc/snippets/doc_src_qtdatavisualization.cpp @@ -99,3 +99,20 @@ make Q3DBars *graph = new Q3DBars(); QWidget *container = QWidget::createWindowContainer(graph); //! [9] + +//! [10] +Q3DBars graph; +QBarDataProxy *newProxy = new QBarDataProxy; + +QBarDataArray *dataArray = new QBarDataArray; +dataArray->reserve(10); +for (int i = 0; i < 10; i++) { + QBarDataRow *dataRow = new QBarDataRow(5); + for (int j = 0; j < 5; j++) + (*dataRow)[j].setValue(myData->getValue(i, j)); + dataArray->append(dataRow); +} + +newProxy->resetArray(dataArray); +graph->setActiveDataProxy(newProxy); +//! [10] diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc index ba158d27..7c4bcd2e 100644 --- a/src/datavisualization/doc/src/qtdatavisualization.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc @@ -98,11 +98,83 @@ \section1 Data proxies - TODO + The data users wish to visualize comes in many formats, all of which cannot obviously be + directly supported. Therefore Qt Data Visualization implements data proxies into which + user can feed their data in a known format. Each visualization type has a basic proxy type, + which takes data in a format suitable for that visualization. + For example, the basic proxy for Q3DBars is QBarDataProxy, which stores rows of QBarDataItem + objects. Each QBarDataItem stores a single bar value. Additional typedefs are provided for + QBarDataArray and QBarDataRow containers. + + This code snipped shows how to use basic proxy when your data is stored in some hypothetical + \c myData object: + + \snippet doc_src_qtdatavisualization.cpp 10 + + \note The graph objects can own more than one data proxy, but only one proxy can be + active at a time. If you need to switch back and forth between two different sets of data, + it may be more efficient to store each set in different proxy and just change the active + proxy, rather than reset the data in one proxy every time you need to switch. \section1 Item models and data mapping - TODO + For common use cases, Qt Data Visualization offers specialized proxies. One such case is having + data in an item model (QAbstractItemModel subclass), which is a common way to store data in + Qt applications. Each of the visualization types offers a special proxy and a corresponding mapping + class for this purpose, e.g. QItemModelBarDataProxy and QItemModelBarDataMapping for Q3DBars. + These proxies are simple to use - just give them a pointer to the item model containing the + data and the mapping object containing rules how to map the data into format the basic proxy can + digest. + + Mapping objects work with item model roles. Each data item in the model can have different + values for different roles. For example, with QItemModelBarDataMapping you can specify which + role is used to determine which row the item belongs to, which role does the same for columns, + and which role specifies the value of the item. When the proxy resolves the data from the model, + it uses these mappings to generate the rows and columns of the bar graph. + + Depending on the visualization type, mapping classes may support other functionality as well, + such as QItemModelBarDataMapping optionally mapping QAbstractItemModel rows and columns directly + into bar graph rows and columns. See individual mapping classes for more information and examples + how to use them: QItemModelBarDataMapping, QItemModelScatterDataMapping, and + QItemModelSurfaceDataMapping. + + \section1 Other custom proxies + + QHeightMapSurfaceDataProxy is a specialized proxy for generating a surface graph from a + heightmap image. See QHeightMapSurfaceDataProxy documentation for more information. + + The \l{Rainfall Example}{Rainfall} example shows how a custom proxy can be created. It defines + a custom data set based on variant lists and an extension of the basic proxy to resolve that + data with an associated mapper. + + \section1 Dealing with real-time data + + When you have a data set that updates rapidly, it is important to handle data properly to + ensure good performance. Since memory allocation is a costly operation, always use + QList::reserve() and QVector::resize() where possible to avoid reallocations when constructing + the array to give to the proxy. If you need to change the entire data set for each frame, + it is in most cases best to re-use the existing array - especially if the array dimensions do not + change. If you need to add, insert, remove, or change several rows or items for each frame, it + is always more efficient to do it with one method call instead of multiple calls affecting + a single row or item each. For example, adding ten rows with a single QBarDataProxy::addRows() call + is much more efficient than ten separate QBarDataProxy::addRow() calls. + + Bars renderer is optimized to access only data that is within data window and thus should not + suffer noticeable slowdown even if more data is continually added to the proxy. + + Due to the unsorted nature of the scatter data, any change in the data window ranges requires + all data points to be checked for visibility, which can cause increasing slowdown if data is + continually added to the proxy. + + Surface data, while on item level similar to scatter data, is already assigned into rows and + columns, so the surface renderer can do some optimization by making assumption that the data in + rows and columns is sorted along their respective axes, but it is nowhere near as efficient + as in bars case. Surface rendering can suffer significant slowdown if the data size grows unchecked. + + For the best performance with the scatter and surface graphs, only keep the data you need in the + proxy. + + \note Data handling is not yet fully optimized in the technology preview version. */ /*! -- cgit v1.2.3