summaryrefslogtreecommitdiffstats
path: root/src/datavisualization/doc/src
diff options
context:
space:
mode:
authorMiikka Heikkinen <miikka.heikkinen@digia.com>2014-06-05 12:00:24 +0300
committerMiikka Heikkinen <miikka.heikkinen@digia.com>2014-06-05 12:03:16 +0300
commitcfbfbea7d932f98c3f541bb4fc3e975ffb7a5658 (patch)
treebed376368e9611c751cf1dd75b85de2827d67325 /src/datavisualization/doc/src
parent8435c15d224a4e9db0920ecd33c4bea3e70d83bf (diff)
parentc51e0f83ef6dd9e85db6953995585ba0cafb35d7 (diff)
Merge branch 'develop'
Diffstat (limited to 'src/datavisualization/doc/src')
-rw-r--r--src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc180
-rw-r--r--src/datavisualization/doc/src/qtdatavisualization-qml-color.qdoc35
-rw-r--r--src/datavisualization/doc/src/qtdatavisualization.qdoc59
3 files changed, 246 insertions, 28 deletions
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
index 891cc5c1..ba3173b0 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc
@@ -28,8 +28,9 @@
Note that this type is uncreatable, but contains properties that are shared between
the 3D visualizations.
- For AbstractGraph3D enums, see \l QAbstract3DGraph::SelectionFlag and
- \l QAbstract3DGraph::ShadowQuality
+ For AbstractGraph3D enums, see \l{QAbstract3DGraph::SelectionFlag},
+ \l{QAbstract3DGraph::ShadowQuality}, \l{QAbstract3DGraph::ElementType}, and
+ \l{QAbstract3DGraph::OptimizationHint}.
\sa Bars3D, Scatter3D, Surface3D, {Qt Data Visualization C++ Classes}
*/
@@ -57,7 +58,7 @@
/*!
\qmlproperty AbstractInputHandler3D AbstractGraph3D::inputHandler
- Input handler. You can disable default input handlers by setting this property to \c null.
+ Input handler. You can disable default input handlers by setting this property to \c {null}.
*/
/*!
@@ -119,13 +120,184 @@
When renderingMode is \c RenderDirectToBackground or \c RenderDirectToBackground_NoClear, this
property value is read-only and returns the number of samples specified by the window surface
format.
- Defaults to 4.
+ Defaults to \c{4}.
\sa renderingMode
*/
/*!
+ * \qmlproperty bool AbstractGraph3D::measureFps
+ * \since QtDataVisualization 1.1
+ *
+ * If \c {true}, the rendering is done continuously instead of on demand, and currentFps property
+ * is updated. Defaults to \c{false}.
+ *
+ * \sa currentFps
+ */
+
+/*!
+ * \qmlproperty int AbstractGraph3D::currentFps
+ * \since QtDataVisualization 1.1
+ *
+ * When fps measuring is enabled, the results for the last second are stored in this read-only
+ * property. It takes at least a second before this value updates after measurement is activated.
+ *
+ * \sa measureFps
+ */
+
+/*!
* \qmlmethod void AbstractGraph3D::clearSelection()
* Clears selection from all attached series.
*/
+/*!
+ * \qmlmethod int AbstractGraph3D::addCustomItem(Custom3DItem item)
+ *
+ * Adds a Custom3DItem \a item to the graph. Graph takes ownership of the added item.
+ *
+ * \return index to the added item if add was successful, -1 if trying to add a null item, and
+ * index of the item if trying to add an already added item.
+ *
+ * \sa removeCustomItems(), removeCustomItem(), removeCustomItemAt()
+ *
+ * \since QtDataVisualization 1.1
+ */
+
+/*!
+ * \qmlmethod void AbstractGraph3D::removeCustomItems()
+ *
+ * Removes all custom items. Deletes the resources allocated to them.
+ *
+ * \since QtDataVisualization 1.1
+ */
+
+/*!
+ * \qmlmethod void AbstractGraph3D::removeCustomItem(Custom3DItem item)
+ *
+ * Removes the custom \a {item}. Deletes the resources allocated to it.
+ *
+ * \since QtDataVisualization 1.1
+ */
+
+/*!
+ * \qmlmethod void AbstractGraph3D::removeCustomItemAt(vector3d position)
+ *
+ * Removes all custom items at \a {position}. Deletes the resources allocated to them.
+ *
+ * \since QtDataVisualization 1.1
+ */
+
+/*!
+ * \qmlmethod void AbstractGraph3D::releaseCustomItem(Custom3DItem item)
+ *
+ * Gets ownership of \a item back and removes the \a item from the graph.
+ *
+ * \since QtDataVisualization 1.1
+ *
+ * \note If the same item is added back to the graph, the texture file needs to be re-set.
+ *
+ * \sa Custom3DItem::textureFile
+ */
+
+/*!
+ * \qmlmethod int AbstractGraph3D::selectedLabelIndex()
+ *
+ * Can be used to query the index of the selected label after receiving \c selectedElementChanged
+ * signal with any label type. Selection is valid until the next \c selectedElementChanged signal.
+ *
+ * \return index of the selected label, or -1.
+ *
+ * \since QtDataVisualization 1.1
+ *
+ * \sa selectedElement
+ */
+
+/*!
+ * \qmlmethod Abstract3DAxis AbstractGraph3D::selectedAxis()
+ *
+ * Can be used to get the selected axis after receiving \c selectedElementChanged signal with any label
+ * type. Selection is valid until the next \c selectedElementChanged signal.
+ *
+ * \return the selected axis, or null.
+ *
+ * \since QtDataVisualization 1.1
+ *
+ * \sa selectedElement
+ */
+
+/*!
+ * \qmlmethod int AbstractGraph3D::selectedCustomItemIndex()
+ *
+ * Can be used to query the index of the selected custom item after receiving \c selectedElementChanged
+ * signal with \l{QAbstract3DGraph::ElementCustomItem}{ElementCustomItem} type. Selection is valid
+ * until the next \c selectedElementChanged signal.
+ *
+ * \return index of the selected custom item, or -1.
+ *
+ * \since QtDataVisualization 1.1
+ *
+ * \sa selectedElement
+ */
+
+/*!
+ * \qmlmethod Custom3DItem AbstractGraph3D::selectedCustomItem()
+ *
+ * Can be used to get the selected custom item after receiving \c selectedElementChanged signal with
+ * \l{QAbstract3DGraph::ElementCustomItem}{ElementCustomItem} type. Ownership of the item remains
+ * with the graph. Selection is valid until the next \c selectedElementChanged signal.
+ *
+ * \return the selected custom item, or null.
+ *
+ * \since QtDataVisualization 1.1
+ *
+ * \sa selectedElement
+ */
+
+/*!
+ * \qmlproperty AbstractGraph3D.ElementType AbstractGraph3D::selectedElement
+ *
+ * Can be used to query the selected element type.
+ * Type is valid until the next \c selectedElementChanged signal.
+ *
+ * \c selectedElementChanged signal is emitted when a selection is made in the graph.
+ *
+ * Signal can be used for example for implementing customized input handling, as demonstrated in
+ * this \l {Qt Quick 2 Axis Dragging Example}{example}.
+ *
+ * \sa selectedLabelIndex(), selectedAxis(), selectedCustomItemIndex(), selectedCustomItem(),
+ * Bars3D::selectedSeries, Scatter3D::selectedSeries, Scene3D::selectionQueryPosition
+ *
+ * \since QtDataVisualization 1.1
+ */
+
+/*!
+ * \qmlproperty bool AbstractGraph3D::orthoProjection
+ * \since QtDataVisualization 1.1
+ *
+ * If \c {true}, orthographic projection will be used for displaying the graph. Defaults to \c{false}.
+ * \note Shadows will be disabled when set to \c{true}.
+ */
+
+/*!
+ * \qmlproperty real AbstractGraph3D::aspectRatio
+ * \since QtDataVisualization 1.1
+ *
+ * Aspect ratio of the graph data. This is the ratio of data scaling between horizontal and
+ * vertical axes. Defaults to \c{2.0}.
+ *
+ * \note Has no effect on Bars3D.
+ */
+
+/*!
+ * \qmlproperty AbstractGraph3D.OptimizationHints AbstractGraph3D::optimizationHints
+ * \since Qt Data Visualization 1.1
+ *
+ * Defines if the rendering optimization is default or static. Default mode provides the full feature set at
+ * reasonable performance. Static is a beta level feature and currently supports only a subset of the
+ * features on the Scatter graph. Missing features are object gradient for mesh objects, both gradients
+ * for points, and diffuse and specular color on rotations. At this point static is intended just for
+ * introducing a new feature. It optimizes graph rendering and is ideal for large non-changing data
+ * sets. It is slower with dynamic data changes and item rotations. Selection is not optimized, so using it
+ * with massive data sets is not advisable.
+ * Defaults to \c{OptimizationDefault}
+ */
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-color.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-color.qdoc
new file mode 100644
index 00000000..e845adea
--- /dev/null
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-color.qdoc
@@ -0,0 +1,35 @@
+/****************************************************************************
+**
+** 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
+**
+****************************************************************************/
+
+/*!
+ \qmltype ThemeColor
+ \inqmlmodule QtDataVisualization
+ \since QtDataVisualization 1.0
+ \ingroup datavisualization_qml
+ \brief Defines the color in a Theme3D.
+
+ Defines a color in Theme3D::baseColors property of Theme3D.
+*/
+
+/*!
+ \qmlproperty color ThemeColor::color
+
+ The color property describes the color of this ThemeColor.
+
+ The default color is black.
+*/
diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc
index 836823e6..af419814 100644
--- a/src/datavisualization/doc/src/qtdatavisualization.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc
@@ -37,7 +37,7 @@
*/
/*!
- \qmlmodule QtDataVisualization 1.0
+ \qmlmodule QtDataVisualization 1.1
\title Qt Data Visualization QML Types
\ingroup qmlmodules
@@ -73,8 +73,8 @@
in the package manager.
After installation Qt Data Visualization documentation and examples are available in Qt Creator.
- You can find all Qt Data Visualization examples by typing \c visualization in the
- \c {Search in Examples...} field.
+ 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.
@@ -238,9 +238,18 @@
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
+ into bar graph rows and columns.
+
+ See individual proxy classes for more information and examples
about how to use them: QItemModelBarDataProxy, QItemModelScatterDataProxy, and
QItemModelSurfaceDataProxy.
@@ -257,28 +266,27 @@
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 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.
+ 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.
+ 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 do some optimization by making the assumption that the data in
- rows and columns is sorted along their respective axes, but it is nowhere near as efficient
- as in the 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.
+ 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.
*/
/*!
@@ -303,7 +311,8 @@
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.
+ 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.
@@ -322,10 +331,12 @@
\li Q3DLight class (and Light3D QML item) are currently not usable for anything.
\li Changing any of Q3DScene properties affecting subviewports currently has no effect.
\li The color style Q3DTheme::ColorStyleObjectGradient doesn't work for surface graphs.
- \li Scatter "point" meshes (QAbstract3DSeries::MeshPoint) do not support gradients, they
- always use the base color.
\li Widget based examples layout incorrectly in iOS.
\li Reparenting a graph to an item in another QQuickWindow is not supported.
+ \li There is a low-impact binary break between 1.0 and 1.1. The break is due to a QML type
+ registration conflict with QAbstractItemModel between QtDataVisualization and
+ QtCommercial.Charts. Introducing the binary break makes it possible to use both
+ Charts and Data Visualization in the same QML application.
\endlist
*/