diff options
Diffstat (limited to 'src/datavisualization/doc/src')
6 files changed, 91 insertions, 157 deletions
diff --git a/src/datavisualization/doc/src/qtdatavisualization-index.qdoc b/src/datavisualization/doc/src/qtdatavisualization-index.qdoc index 456f8ac5..c37d98a4 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-index.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-index.qdoc @@ -32,10 +32,10 @@ \li Uses OpenGL for rendering the data \li QML2 support \li Customizable axes for data - control viewable data window with axis ranges - \li Customizable input handling (upcoming feature - not supported in technology preview) - \li Customizable scene handling - full control of cameras and lights (upcoming feature - - not supported in technology preview) - \li Customizable themes (upcoming feature - not supported in technology preview) + \li Customizable input handling + \li Customizable scene handling - full control of viewports + (upcoming feature - not fully supported in alpha) + \li Customizable themes \endlist \section1 Getting Started @@ -62,8 +62,8 @@ \section1 Articles \list - \li \l{Qt Data Visualization Data Handling}{Data input} - \li \l{Qt Data Visualization Interacting with Data}{Interacting with visualized data} + \li \l{Qt Data Visualization Data Handling}{Data Handling} + \li \l{Qt Data Visualization Interacting with Data}{Interacting with Data} \endlist \section1 References diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc index 59331bf9..7493709f 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc @@ -35,10 +35,6 @@ \qmlproperty AbstractGraph3D.SelectionMode AbstractGraph3D::selectionMode Active selection mode in the visualization. */ -/*! - \qmlproperty AbstractGraph3D.LabelStyle AbstractGraph3D::labelStyle - Label style. - */ /*! \qmlproperty AbstractGraph3D.ShadowQuality AbstractGraph3D::shadowQuality @@ -46,32 +42,11 @@ */ /*! - \qmlproperty AbstractGraph3D.CameraPreset AbstractGraph3D::cameraPreset - Camera preset. - */ - -/*! - \qmlproperty AbstractGraph3D.Theme AbstractGraph3D::theme - Theme of the graph. Theme affects visualization colors, label colors, text color, background color, window - color and grid color. Lighting is also adjusted by themes. - */ - -/*! - \qmlproperty font AbstractGraph3D::font - Font used for labels. - */ - -/*! - \qmlproperty bool AbstractGraph3D::gridVisible - Grid visibility. If false, grid lines are not drawn. - */ - -/*! - \qmlproperty bool AbstractGraph3D::backgroundVisible - Background visibility. If false, background is not drawn. + \qmlproperty AbstractInputHandler3D AbstractGraph3D::inputHandler + Input handler. You can disable default input handlers by setting this property to \c null. */ /*! - \qmlproperty string AbstractGraph3D::itemLabelFormat - Label format of single item labels, e.g. a selected datapoint. + \qmlproperty Theme3D AbstractGraph3D::theme + Theme of the graph. */ diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc index 935662b3..fc1b732c 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc @@ -36,28 +36,7 @@ * * See \l{Qt Quick 2 Bars Example} for more thorough usage example. * - * \sa ItemModelBarDataProxy, Scatter3D, Surface3D, {Qt Data Visualization C++ Classes} - */ - -/*! - * \qmlmethod void Bars3D::setBarColor(const QColor &baseColor, bool uniform) - * Set bar color using your own color. \a baseColor sets the base color of a bar. The \a uniform - * -flag is used to define if color needs to be uniform throughout bar's length, or will the colors - * be applied by height, starting with dark at the bottom. It is \c true by default. - * - * Calling this method overrides colors from theme. - * - * \sa AbstractGraph3D::theme - * - * \warning This method is subject to change. - */ - -/*! - * \qmlproperty BarDataProxy Bars3D::dataProxy - * The active data proxy. - * - * If a proxy is not given, a temporary default proxy is created and activated. - * This temporary proxy is destroyed if another proxy is explicitly set active via this property. + * \sa Bar3DSeries, ItemModelBarDataProxy, Scatter3D, Surface3D, {Qt Data Visualization C++ Classes} */ /*! @@ -87,11 +66,6 @@ /*! - * \qmlproperty Bars3D.MeshStyle Bars3D::barType - * Bar object type. - */ - -/*! * \qmlproperty real Bars3D::barThickness * Bar thickness ratio between X and Z dimensions. 1.0 means bars are as wide as they are deep, 0.5 * makes them twice as deep as they are wide. @@ -108,29 +82,23 @@ */ /*! - * \qmlproperty bool Bars3D::barSmoothingEnabled - * Bar smoothing. If false, bar shading is flat. - */ - -/*! - * \qmlproperty string Bars3D::meshFileName - * Override bar type with a mesh object. - * \note Object needs to be in Wavefront obj format and include vertices, normals and UVs. - * It also needs to be in triangles. - */ - -/*! - * \qmlproperty int Bars3D::rows - * Row count of data window. + * \qmlproperty list<QBar3DSeries> Bars3D::seriesList + * This property holds the series of the graph. + * By default, this property contains an empty list. + * To set the series, either use the addSeries() function or define them as children of the graph. */ /*! - * \qmlproperty int Bars3D::columns - * Column count of data window. + * \qmlmethod void Bars3D::addSeries(QBar3DSeries *series) + * Adds the \a series to the graph. A graph can contain multiple series, but only one set of axes, + * so the rows and columns of all series must match for the visualized data to be meaningful. + * If the graph has multiple visible series, only the first one added will + * generate the row or column labels on the axes in cases where the labels are not explicitly set + * to the axes. If the newly added series has specified a selected bar, it will be highlighted and + * any existing selection will be cleared. Only one added series can have an active selection. */ /*! - * \qmlproperty point Bars3D::selectedBarPos - * Position of the selected bar in data window. Only one bar can be selected at a time. - * To clear selection, specify an illegal position, e.g. Qt.point(-1.0, -1.0). + * \qmlmethod void Bars3D::removeSeries(QBar3DSeries *series) + * Remove the \a series from the graph. */ diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc index db5c381d..1f04424f 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc @@ -36,28 +36,7 @@ See \l{Qt Quick 2 Scatter Example} for more thorough usage example. - \sa ItemModelScatterDataProxy, Bars3D, Surface3D, {Qt Data Visualization C++ Classes} - */ - -/*! - * \qmlmethod void Scatter3D::setObjectColor(const QColor &baseColor, bool uniform) - * Set item color using your own colors. \a baseColor sets the base color of a item. The \a uniform - * -flag is used to define if color needs to be uniform throughout item's length, or will the colors - * be applied by height. It is \c true by default. - * - * Calling this method overrides colors from theme. - * - * \sa AbstractGraph3D::theme - * - * \warning This method is subject to change. - */ - -/*! - \qmlproperty ScatterDataProxy Scatter3D::dataProxy - The active data proxy. - - If a proxy is not given, a temporary default proxy is created and activated. - This temporary proxy is destroyed if another proxy is explicitly set active via this property. + \sa Scatter3DSeries, ScatterDataProxy, Bars3D, Surface3D, {Qt Data Visualization C++ Classes} */ /*! @@ -88,18 +67,20 @@ */ /*! - \qmlproperty Scatter3D.MeshStyle Scatter3D::objectType - Dot object type. + * \qmlproperty list<QScatter3DSeries> Scatter3D::seriesList + * This property holds the series of the graph. + * By default, this property contains an empty list. + * To set the series, either use the addSeries() function or define them as children of the graph. */ /*! - \qmlproperty bool Scatter3D::objectSmoothingEnabled - Dot smoothing. If false, dot shading is flat. + * \qmlmethod void Scatter3D::addSeries(QScatter3DSeries *series) + * Adds the \a series to the graph. A graph can contain multiple series, but has only one set of + * axes. If the newly added series has specified a selected item, it will be highlighted and + * any existing selection will be cleared. Only one added series can have an active selection. */ /*! - \qmlproperty string Scatter3D::meshFileName - Override object type with a mesh object. - \note Object needs to be in Wavefront obj format and include vertices, normals and UVs. - It also needs to be in triangles. + * \qmlmethod void Scatter3D::removeSeries(QScatter3DSeries *series) + * Remove the \a series from the graph. */ diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc index 7d79a19e..a3886008 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc @@ -36,15 +36,7 @@ See \l{Qt Quick 2 Surface Example} for more thorough usage example. - \sa ItemModelSurfaceDataProxy, Bars3D, Scatter3D, {Qt Data Visualization C++ Classes} - */ - -/*! - \qmlproperty SurfaceDataProxy Surface3D::dataProxy - The active data proxy. - - If a proxy is not given, a temporary default proxy is created and activated. - This temporary proxy is destroyed if another proxy is explicitly set active via this property. + \sa Surface3DSeries, ItemModelSurfaceDataProxy, Bars3D, Scatter3D, {Qt Data Visualization C++ Classes} */ /*! @@ -75,16 +67,26 @@ */ /*! - \qmlproperty bool Surface3D::smoothSurfaceEnabled - The smoothing of surface. If false, the shading of the surface is flat. +/*! + \qmlproperty ColorGradient Surface3D::gradient + The current surface gradient. Setting this property replaces the previous gradient. + */ + +/*! + * \qmlproperty list<QSurface3DSeries> Surface3D::seriesList + * This property holds the series of the graph. + * By default, this property contains an empty list. + * To set the series, either use the addSeries() function or define them as children of the graph. + * \note The surface graph currently supports only a single series at a time. */ /*! - \qmlproperty bool Surface3D::surfaceGridEnabled - The surface grid visibility. If false, no surface grid is drawn. + * \qmlmethod void Surface3D::addSeries(QSurface3DSeries *series) + * Adds the \a series to the graph. + * \note The surface graph currently supports only a single series at a time. */ /*! - \qmlproperty ColorGradient Surface3D::gradient - The current surface gradient. Setting this property replaces the previous gradient. + * \qmlmethod void Surface3D::removeSeries(QSurface3DSeries *series) + * Remove the \a series from the graph. */ diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc index add1c252..9c951877 100644 --- a/src/datavisualization/doc/src/qtdatavisualization.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc @@ -167,47 +167,60 @@ \page qtdatavisualization_data_handling.html \title Qt Data Visualization Data Handling + \section1 Series + + Series is combination of 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. Bar and scatter graphs can have multiple series added simultaneously. + Surface graphs support only a single series at a time. + + 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 Q3DBars is QBarDataProxy, which stores rows of QBarDataItem + 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 - QBarDataArray and QBarDataRow containers. + \c QBarDataArray and \c QBarDataRow containers. - This code snipped shows how to use basic proxy when your data is stored in some hypothetical + 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 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 a different proxy and just change the active - proxy, rather than reset the data in one proxy every time you need to switch. + \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 and a corresponding mapping - class for this purpose, for example, QItemModelBarDataProxy and QItemModelBarDataMapping for Q3DBars. + 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 mapping object containing rules how to map the data into format the basic proxy can - digest. + data and the 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 + 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. - Depending on the visualization type, mapping classes may support other functionalities 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 - about how to use them: QItemModelBarDataMapping, QItemModelScatterDataMapping, and - QItemModelSurfaceDataMapping. + 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 @@ -244,8 +257,6 @@ 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. */ /*! @@ -255,21 +266,15 @@ \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 the public API. This feature is planned for the final release. + 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 graph APIs. The selected item is highlighted - in the rendered graph, and selecting causes emission of a graph specific signal for this purpose, - for example, Q3DBars::selectedBarPosChanged(), which the application can handle. - - \note The surface graph doesn't have a fully implemented selection API yet. It only supports - selection with mouse and touch in the technology preview version. + 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 @@ -277,4 +282,7 @@ Bar graph additionally supports simply highlighting the whole row and/or column of the selected bar without opening the slice view. + + When multiple series are added to a graph, selecting an item in one of them will clear the selection + on other series. */ |