summaryrefslogtreecommitdiffstats
path: root/src/datavisualization/doc/src/qtdatavisualization.qdoc
blob: adfab9347e76a07de384f17308b1f2d45f9b4c7d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Data Visualization module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:GPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3 or (at your option) any later version
** approved by the KDE Free Qt Foundation. The licenses are as published by
** the Free Software Foundation and appearing in the file LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \namespace QtDataVisualization
    \inmodule QtDataVisualization
    \brief Contains the classes and enumerations in the Qt Data Visualization
    module.

    \generatelist{classesbymodule QtDataVisualization}
*/

/*!
    \module QtDataVisualization
    \title Qt Data Visualization C++ Classes
    \ingroup modules

    \brief C++ classes for the Qt Data Visualization API.

    The Qt Data Visualization functionality can be accessed via these C++ classes.
*/

/*!
    \qmlmodule QtDataVisualization 1.2
    \title Qt Data Visualization QML Types
    \ingroup qmlmodules

    \brief QML types for the Qt Data Visualization API.

    The Qt Data Visualization functionality can be accessed via these QML types.

    \section1 QML Types
*/

/*!
    \group datavisualization_examples
    \ingroup all-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
*/

/*!
    \group qtdatavisualization_getting_started
    \title Qt Data Visualization Getting Started

    \section1 Installing the Qt Data Visualization Module

    Use the \c {Package Manager} in \c {Maintenance Tool} or the \c {Online installer} to install
    the Qt Data Visualization module. The module can be found under \c {Qt Enterprise Add-Ons}
    in the package manager.

    After installation Qt Data Visualization documentation and examples are available in Qt Creator.
    Examples can be found on the examples page of Qt Creator by selecting the Qt Data Visualization
    component from the drop-down menu.

    The source code is installed into the QtDataVisualization folder under EnterpriseAddOns.

    \section1 Building Qt Data Visualization

    To build the Qt Data Visualization module from source code yourself, 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 OS X                     \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 (Windows/OS X only):
    \code
    qmake CONFIG+="debug_and_release build_all"
    make
    \endcode

    After building, install the module to your Qt directory:
    \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 the \c examples subdirectory. To build and run a
    single example, in this case qmlsurface, navigate to the example directory and enter 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
    the 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 Series

    A series is a combination of a logically connected set of data items (handled by a data proxy)
    and visual properties that describe how the data items should be rendered, such as item
    meshes and colors. Each visualization type has its own series type. For example, bar graphs
    use QBar3DSeries. All graphs can have multiple series added simultaneously.

    This code snippet shows how to use QBar3DSeries to render bars as cylinders and with a
    gradient instead of a uniform color:

    \snippet doc_src_qtdatavisualization.cpp 11

    \section1 Data Proxies

    The data that 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 QBar3DSeries is QBarDataProxy, which stores rows of QBarDataItem
    objects. Each QBarDataItem stores a single bar value. Additional typedefs are provided for
    \c QBarDataArray and \c QBarDataRow containers.

    This code snippet shows how to use basic proxy when your data is stored in some hypothetical
    \c myData object:

    \snippet doc_src_qtdatavisualization.cpp 10

    \note Series objects can own only a single proxy at a time. The existing proxy is deleted
    when another is set to the series. Graphs can contain multiple series, though.
    If you need to switch back and forth between two different sets of data,
    it is usually more efficient to store each set in a different series and just change the series,
    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 class for this purpose,
    for example, QItemModelBarDataProxy for QBar3DSeries.
    These proxies are simple to use: just give them a pointer to the item model containing the
    data and the rules how to map the data into format the basic proxy can digest.

    Mapping works with item model roles. Each data item in the model can have different
    values for different roles. For example, with QItemModelBarDataProxy 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.

    Often the item models will have a single role that contains information you want to map to
    multiple values. A typical example of this is a timestamp field when generating a bar graph
    with two time related axes, for example years and months. To enable mapping a single item
    model role to more than one data field, pattern matching and replacing mechanism is provided
    by item model proxies. You can also use this mechanism to reformat data even in one-to-one
    mapping cases.

    Depending on the visualization type, proxies may support other functionalities as well,
    such as QItemModelBarDataProxy optionally mapping QAbstractItemModel rows and columns directly
    into bar graph rows and columns.

    See individual proxy classes for more information and examples
    about how to use them: QItemModelBarDataProxy, QItemModelScatterDataProxy, and
    QItemModelSurfaceDataProxy.

    \section1 Other Custom Proxies

    QHeightMapSurfaceDataProxy is a specialized proxy for generating a surface graph from a
    heightmap image. See the 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 unnecessary 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 reuse 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 the 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. For the best performance with the scatter graphs, only keep
    the data you need in the proxy.

    Surface data, while on item level similar to scatter data, is already assigned into rows and
    columns, so the surface renderer can optimize drawing by making the assumption that
    the data in the rows and columns is sorted along their respective axes. It is not quite as
    efficient as in the bars case, but nearly so.
*/

/*!
    \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 default mouse controls, see Q3DInputHandler documentation, and for the default
    touch controls, see QTouch3DInputHandler documentation.

    \section1 Data Selection Modes

    All visualization types support selecting a single data item - a bar, a scatter item, or a surface
    vertex - using mouse, touch, and programmatically via the series APIs. The selected item is highlighted
    in the rendered graph, and selecting causes emission of a series specific signal for this purpose,
    for example, QBar3DSeries::selectedBarChanged(), which the application can handle.

    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
    a 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. Bar graph also supports selecting/slicing a whole row and/or
    column by clicking the axis label, based on selection mode.

    When multiple series are added to a graph, selecting an item in one of them will clear the selection
    on other series.
*/

/*!
    \page qtdatavisualization_known_issues.html
    \title Qt Data Visualization Known Issues

    \list
        \li Some platforms like Android and WinRT cannot handle multiple native windows properly,
            so only the Qt Quick 2 graphs are available in practice for those platforms.
        \li Shadows are not supported with OpenGL ES2 (including Angle builds in Windows).
        \li Anti-aliasing doesn't work with OpenGL ES2 (including Angle builds in Windows).
        \li QCustom3DVolume items are not supported with OpenGL ES2 (including Angle builds in
            Windows).
        \li Surfaces with non-straight rows and columns do not always render properly.
        \li Q3DLight class (and Light3D QML item) are currently not usable for anything.
        \li Changing most of Q3DScene properties affecting subviewports currently has no effect.
        \li Widget based examples layout incorrectly in iOS.
        \li Reparenting a graph to an item in another QQuickWindow is not supported.
        \li Android builds of QML applications importing QtDataVisualization also require
            "QT += datavisualization" in the pro file. This is because Qt Data Visualization
            QML plugin has a dependency to Qt Data Visualization C++ library, which Qt Creator
            doesn't automatically add to the deployment package.
        \li Only OpenGL ES2 emulation is available for software renderer (that is, when using
            QCoreApplication::setAttribute(Qt::AA_UseSoftwareOpenGL))
    \endlist
*/

/*!
 * \fn QSurfaceFormat QtDataVisualization::qDefaultSurfaceFormat(bool antialias = true)
 * \relates QAbstract3DGraph
 *
 * This convenience function can be used to create a custom surface format suitable for use by
 * Qt Data Visualization graphs.
 *
 * The \a antialias parameter specifies whether or not antialiasing is activated.
 *
 * Give the surface format returned by this function to the graph constructor (C++) or set
 * it as the window format for QQuickView (QML) before calling show on it.
 *
 * For example, disable antialiasing on C++ application:
 *
 * \code
 * #include <QtDataVisualization/qutils.h>
 *
 * // ...
 *
 * Q3DBars *graph = new Q3DBars(QtDataVisualization::qDefaultSurfaceFormat(false));
 * \endcode
 *
 * For example, enable antialiasing for direct rendering modes on QML application:
 *
 * \code
 * #include <QtDataVisualization/qutils.h>
 *
 * // ...
 *
 * QQuickView viewer;
 * viewer.setFormat(QtDataVisualization::qDefaultSurfaceFormat());
 * \endcode
 *
 * \note Antialiasing is not supported in OpenGL ES2 environments.
 */