/**************************************************************************** ** ** Copyright (C) 2013 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 ** ****************************************************************************/ /*! \module QtDataVisualization \title Qt Data Visualization C++ Classes \ingroup modules \brief C++ classes for the Qt Data Visualization API. Qt Data Visualization functionality can be accessed via these C++ classes. */ /*! \qmlmodule com.digia.QtDataVisualization 1.0 \title Qt Data Visualization QML Types \ingroup qmlmodules \brief QML types for the Qt Data Visualization API. Qt Data Visualization functionality can be accessed via these QML types. \section1 QML Types */ /*! \group datavisualization_examples \title Qt Data Visualization Examples \brief Examples for the Qt Data Visualization. For some code examples, see one of the Qt Data Visualization examples: \section1 Examples \annotatedlist qtdatavisualization_examples */ /*! \page qtdatavisualization_getting_started.html \title Qt Data Visualization Getting Started \section1 Building Qt Data Visualization To build Qt Data Visualization module, set up a command prompt with an environment for building Qt applications, navigate to the directory containing \c qtdatavisualization.pro, and configure the project with qmake: \code qmake \endcode After running qmake, build the project with make: \table \header \li OS \li Make command \row \li Linux \li make \row \li Windows (MinGw) \li mingw32-make \row \li Windows (MSVC) \li nmake \row \li OSX \li make \endtable The above generates the default makefiles for your configuration, which is typically the release build if you are using precompiled binary Qt distribution. To build both debug and release, or one specifically, use one of the following qmake lines instead. For debug builds: \code qmake CONFIG+=debug; make \endcode or \code qmake CONFIG+=debug_and_release; make debug \endcode For release builds: \code qmake CONFIG+=release ; make \endcode or \code qmake CONFIG+=debug_and_release; make release \endcode For both builds \code qmake CONFIG+="debug_and_release build_all"; make \endcode If you want to install the module to your Qt directory use: \code make install \endcode If you want to uninstall the module \code make uninstall \endcode To build a statically linked version of the Qt Data Visualization module, give the following commands: \snippet doc_src_qtdatavisualization.cpp 7 \section1 Running examples Qt Data Visualization examples are found under \c examples subdirectory. To build and run a single example, e.g. the qmlsurface example, navigate to the example directory and give the following commands: \snippet doc_src_qtdatavisualization.cpp 8 \note On some platforms, such as Windows, the executable can be generated under debug or release folders, depending on your build. \section1 Creating a simple application To create a simple application, start by creating a new Qt Gui Application project in Qt Creator and add this line to the \c .pro file of the project: \snippet doc_src_qtdatavisualization.pro 0 In the \c main.cpp file, include the module headers and declare namespace usage: \snippet doc_src_qtdatavisualization.cpp 0 Then, add the sample code found in one of the following pages, depending on what kind of visualization you are interested in: \l{How to construct a minimal Q3DBars graph}, \l{How to construct a minimal Q3DScatter graph}, or \l{How to construct a minimal Q3DSurface graph}. To use Qt Data Visualization graphs in widget based applications, you can use QWidget::createWindowContainer() function to wrap the graph into a widget: \snippet doc_src_qtdatavisualization.cpp 9 For further code examples, see one of the Qt Data Visualization examples: \annotatedlist qtdatavisualization_examples */ /*! \page qtdatavisualization_data_handling.html \title Qt Data Visualization Data Handling \section1 Data proxies 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 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{Custom Proxy Example}{Custom Proxy} 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. */ /*! \page qtdatavisualization_interacting_with_data.html \title Qt Data Visualization Interacting with Data \section1 Interacting with data You can interact with the rendered graph with either mouse or touch to rotate, zoom, or select data. For the mouse controls, see Q3DInputHandler documentation, and for the touch controls, see QTouch3DInputHandler documentation. \note In the technology preview version, default input handlers cannot be replaced or even accessed via public API. This feature is planned for the final release. \section1 Data selection modes All visualization types support selecting single data item - a bar, a scatter item, or a surface vertex - using mouse, touch, and programmatically via the graph APIs. The selected item is highlighted in the rendered graph, and selecting causes emission of a graph specific signal for this purpose, e.g. Q3DBars::selectedBarPosChanged(), which the application can handle. \note Surface graph doesn't have fully implemented selection API yet, it only supports selection with mouse and touch in the technology preview version. Bar and surface graphs support slice selection modes, where the selected row or column is drawn in a separate viewport as a pseudo-2D graph. This makes it easier to see the actual values of single row or column. Bar graph additionally supports simply highlighting the whole row and/or column of the selected bar without opening the slice view. */