QML documentation

Task-number: QTRD-2133

Change-Id: I2568b3cd6e83ee933536d7fec2e48f9f121b213e
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@digia.com>

4 files changed, 471 insertions, 19 deletions

diff --git a/src/datavisualization/engine/q3dbars.cpp b/src/datavisualization/engine/q3dbars.cpp
index ee741aed..8e281339 100644
--- a/src/datavisualization/engine/q3dbars.cpp
+++ b/src/datavisualization/engine/q3dbars.cpp
@@ -89,6 +89,153 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  */
 
 /*!
+ * \qmltype Bars3D
+ * \instantiates Q3DBars
+ *
+ * This type enables developers to render bar graphs in 3D with Qt Quick 2.
+ *
+ * You will need to import data visualization module to use this type:
+ *
+ * \snippet doc_src_qmldatavisualization.cpp 0
+ *
+ * After that you can use Bars3D in your qml files:
+ *
+ * \snippet doc_src_qmldatavisualization.cpp 1
+ *
+ * See \l{Qt Quick 2 Barchart Example} for more thorough usage example.
+ *
+ * \sa ItemModelBarDataProxy, Scatter3D, Surface3D, {Qt Data Visualization C++ Classes}
+ */
+
+/*!
+ * \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.
+ */
+
+/*!
+ * \qmlproperty CategoryAxis3D Bars3D::rowAxis
+ * A user-defined row axis.
+ *
+ * If an axis is not given, a temporary default axis with no labels is created.
+ * This temporary axis is destroyed if another axis is explicitly set to same orientation.
+ */
+
+/*!
+ * \qmlproperty ValueAxis3D Bars3D::valueAxis
+ * A user-defined value axis.
+ *
+ * If an axis is not given, a temporary default axis with no labels and automatically adjusting
+ * range is created.
+ * This temporary axis is destroyed if another axis is explicitly set to same orientation.
+ */
+
+/*!
+ * \qmlproperty CategoryAxis3D Bars3D::columnAxis
+ * A user-defined column axis.
+ *
+ * If an axis is not given, a temporary default axis with no labels is created.
+ * This temporary axis is destroyed if another axis is explicitly set to same orientation.
+ */
+
+/*!
+ * \qmlproperty Bars3D.SelectionMode Bars3D::selectionMode
+ * Bar selection mode.
+ */
+
+/*!
+ * \qmlproperty Bars3D.LabelTransparency Bars3D::labelTransparency
+ * Label transparency.
+ */
+
+/*!
+ * \qmlproperty Bars3D.ShadowQuality Bars3D::shadowQuality
+ * Shadow quality.
+ */
+
+/*!
+ * \qmlproperty Bars3D.MeshStyle Bars3D::barType
+ * Bar object type.
+ */
+
+/*!
+ * \qmlproperty Bars3D.CameraPreset Bars3D::cameraPreset
+ * Camera preset.
+ */
+
+/*!
+ * \qmlproperty Bars3D.ColorTheme Bars3D::theme
+ * Theme of the graph. Theme affects bar colors, label colors, text color, background color, window
+ * color and grid color. Lighting is also adjusted by themes.
+ */
+
+/*!
+ * \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.
+ */
+
+/*!
+ * \qmlproperty size Bars3D::barSpacing
+ * Bar spacing in X and Z dimensions.
+ */
+
+/*!
+ * \qmlproperty bool Bars3D::barSpacingRelative
+ * Relative or absolute bar spacing.
+ */
+
+/*!
+ * \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 font Bars3D::font
+ * Font used for labels.
+ */
+
+/*!
+ * \qmlproperty bool Bars3D::gridVisible
+ * Grid visibility. If false, grid lines are not drawn.
+ */
+
+/*!
+ * \qmlproperty bool Bars3D::backgroundVisible
+ * Background visibility. If false, background is not drawn.
+ */
+
+/*!
+ * \qmlproperty int Bars3D::rows
+ * Row count of data window.
+ */
+
+/*!
+ * \qmlproperty int Bars3D::columns
+ * Column count of data window.
+ */
+
+/*!
+ * \qmlproperty string Bars3D::itemLabelFormat
+ * Label format of single item labels, e.g. a selected bar.
+ */
+
+/*!
+ * \qmlproperty point Bars3D::selectedBarPos
+ * Position of the selected bar, if any. Only one bar can be selected at a time.
+ * To clear selection, specify an illegal position, e.g. Qt.point(-1.0, -1.0).
+ */
+
+/*!
  * Constructs a new 3D bar window.
  */
 Q3DBars::Q3DBars()
diff --git a/src/datavisualization/engine/q3dscatter.cpp b/src/datavisualization/engine/q3dscatter.cpp
index e9f467f6..f034b816 100644
--- a/src/datavisualization/engine/q3dscatter.cpp
+++ b/src/datavisualization/engine/q3dscatter.cpp
@@ -81,6 +81,123 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  */
 
 /*!
+ * \qmltype Scatter3D
+ * \instantiates Q3DScatter
+ *
+ * This type enables developers to render scatter graphs in 3D with Qt Quick 2.
+ *
+ * You will need to import data visualization module to use this type:
+ *
+ * \snippet doc_src_qmldatavisualization.cpp 0
+ *
+ * After that you can use Scatter3D in your qml files:
+ *
+ * \snippet doc_src_qmldatavisualization.cpp 2
+ *
+ * See \l{Qt Quick 2 Scatter Example} for more thorough usage example.
+ *
+ * \sa ItemModelScatterDataProxy, Bars3D, Surface3D, {Qt Data Visualization C++ Classes}
+ */
+
+/*!
+ * \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.
+ */
+
+/*!
+ * \qmlproperty ValueAxis3D Scatter3D::axisX
+ * A user-defined X axis.
+ *
+ * If an axis is not given, a temporary default axis with no labels and automatically adjusting
+ * range is created.
+ * This temporary axis is destroyed if another axis is explicitly set to same orientation.
+ */
+
+/*!
+ * \qmlproperty ValueAxis3D Scatter3D::axisY
+ * A user-defined Y axis.
+ *
+ * If an axis is not given, a temporary default axis with no labels and automatically adjusting
+ * range is created.
+ * This temporary axis is destroyed if another axis is explicitly set to same orientation.
+ */
+
+/*!
+ * \qmlproperty ValueAxis3D Scatter3D::axisZ
+ * A user-defined Z axis.
+ *
+ * If an axis is not given, a temporary default axis with no labels and automatically adjusting
+ * range is created.
+ * This temporary axis is destroyed if another axis is explicitly set to same orientation.
+ */
+
+/*!
+ * \qmlproperty Scatter3D.SelectionMode Scatter3D::selectionMode
+ * Dot selection mode.
+ */
+
+/*!
+ * \qmlproperty Scatter3D.LabelTransparency Scatter3D::labelTransparency
+ * Label transparency.
+ */
+
+/*!
+ * \qmlproperty Scatter3D.ShadowQuality Scatter3D::shadowQuality
+ * Shadow quality.
+ */
+
+/*!
+ * \qmlproperty Scatter3D.MeshStyle Scatter3D::objectType
+ * Dot object type.
+ */
+
+/*!
+ * \qmlproperty Scatter3D.CameraPreset Scatter3D::cameraPreset
+ * Camera preset.
+ */
+
+/*!
+ * \qmlproperty Scatter3D.ColorTheme Scatter3D::theme
+ * Theme of the graph. Theme affects bar colors, label colors, text color, background color, window
+ * color and grid color. Lighting is also adjusted by themes.
+ */
+
+/*!
+ * \qmlproperty bool Scatter3D::objectSmoothingEnabled
+ * Dot smoothing. If false, dot shading is flat.
+ */
+
+/*!
+ * \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.
+ */
+
+/*!
+ * \qmlproperty font Scatter3D::font
+ * Font used for labels.
+ */
+
+/*!
+ * \qmlproperty bool Scatter3D::gridVisible
+ * Grid visibility. If false, grid lines are not drawn.
+ */
+
+/*!
+ * \qmlproperty bool Scatter3D::backgroundVisible
+ * Background visibility. If false, background is not drawn.
+ */
+
+/*!
+ * \qmlproperty string Scatter3D::itemLabelFormat
+ * Label format of single item labels, e.g. a selected bar.
+ */
+
+/*!
  * Constructs a new 3D scatter window.
  */
 Q3DScatter::Q3DScatter()
diff --git a/src/datavisualization/engine/q3dsurface.cpp b/src/datavisualization/engine/q3dsurface.cpp
index 647d761a..41d025b3 100644
--- a/src/datavisualization/engine/q3dsurface.cpp
+++ b/src/datavisualization/engine/q3dsurface.cpp
@@ -36,6 +36,119 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * \sa Q3DBars, Q3DScatter, {Qt Data Visualization C++ Classes}
  */
 
+/*!
+ * \qmltype Surface3D
+ * \instantiates Q3DSurface
+ *
+ * This type enables developers to render surface plots in 3D with Qt Quick 2.
+ *
+ * You will need to import data visualization module to use this type:
+ *
+ * \snippet doc_src_qmldatavisualization.cpp 0
+ *
+ * After that you can use Surface3D in your qml files:
+ *
+ * \snippet doc_src_qmldatavisualization.cpp 3
+ *
+ * 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.
+ */
+
+/*!
+ * \qmlproperty ValueAxis3D Surface3D::axisX
+ * A user-defined X axis.
+ *
+ * If an axis is not given, a temporary default axis with no labels and automatically adjusting
+ * range is created.
+ * This temporary axis is destroyed if another axis is explicitly set to same orientation.
+ */
+
+/*!
+ * \qmlproperty ValueAxis3D Surface3D::axisY
+ * A user-defined Y axis.
+ *
+ * If an axis is not given, a temporary default axis with no labels and automatically adjusting
+ * range is created.
+ * This temporary axis is destroyed if another axis is explicitly set to same orientation.
+ */
+
+/*!
+ * \qmlproperty ValueAxis3D Surface3D::axisZ
+ * A user-defined Z axis.
+ *
+ * If an axis is not given, a temporary default axis with no labels and automatically adjusting
+ * range is created.
+ * This temporary axis is destroyed if another axis is explicitly set to same orientation.
+ */
+
+/*!
+ * \qmlproperty Surface3D.SelectionMode Surface3D::selectionMode
+ * Bar selection mode.
+ */
+
+/*!
+ * \qmlproperty Surface3D.LabelTransparency Surface3D::labelTransparency
+ * Label transparency.
+ */
+
+/*!
+ * \qmlproperty Surface3D.ShadowQuality Surface3D::shadowQuality
+ * Shadow quality.
+ */
+
+/*!
+ * \qmlproperty Surface3D.CameraPreset Surface3D::cameraPreset
+ * Camera preset.
+ */
+
+/*!
+ * \qmlproperty Surface3D.ColorTheme Surface3D::theme
+ * Theme of the graph. Theme affects bar colors, label colors, text color, background color, window
+ * color and grid color. Lighting is also adjusted by themes.
+ */
+
+/*!
+ * \qmlproperty font Surface3D::font
+ * Font used for labels.
+ */
+
+/*!
+ * \qmlproperty bool Surface3D::gridVisible
+ * Axis grid visibility. If false, grid lines are not drawn.
+ */
+
+/*!
+ * \qmlproperty bool Surface3D::backgroundVisible
+ * Background visibility. If false, background is not drawn.
+ */
+
+/*!
+ * \qmlproperty bool Surface3D::smoothSurfaceEnabled
+ * Smoothing of surface. If false, shading of the surface is flat.
+ */
+
+/*!
+ * \qmlproperty bool Surface3D::surfaceGridEnabled
+ * Surface grid visibility. If false, no surface grid is drawn.
+ */
+
+/*!
+ * \qmlproperty string Surface3D::itemLabelFormat
+ * Label format of single item labels, e.g. a selected bar.
+ */
+
+/*!
+ * Constructs a new 3D surface window.
+ */
 Q3DSurface::Q3DSurface()
     : d_ptr(new Q3DSurfacePrivate(this, geometry()))
 {
@@ -44,10 +157,16 @@ Q3DSurface::Q3DSurface()
                      &Q3DWindow::renderLater);
 }
 
+/*!
+ *  Destroys the 3D surface window.
+ */
 Q3DSurface::~Q3DSurface()
 {
 }
 
+/*!
+ * \internal
+ */
 void Q3DSurface::render()
 {
     d_ptr->m_shared->synchDataToRenderer();
@@ -55,36 +174,58 @@ void Q3DSurface::render()
 }
 
 #if defined(Q_OS_ANDROID)
+/*!
+ * \internal
+ */
 void Q3DSurface::mouseDoubleClickEvent(QMouseEvent *event)
 {
     Q_UNUSED(event)
 }
+
+/*!
+ * \internal
+ */
 void Q3DSurface::touchEvent(QTouchEvent *event)
 {
     Q_UNUSED(event)
 }
 #endif
 
+/*!
+ * \internal
+ */
 void Q3DSurface::mousePressEvent(QMouseEvent *event)
 {
     d_ptr->m_shared->mousePressEvent(event, event->pos());
 }
 
+/*!
+ * \internal
+ */
 void Q3DSurface::mouseReleaseEvent(QMouseEvent *event)
 {
     d_ptr->m_shared->mouseReleaseEvent(event, event->pos());
 }
 
+/*!
+ * \internal
+ */
 void Q3DSurface::mouseMoveEvent(QMouseEvent *event)
 {
     d_ptr->m_shared->mouseMoveEvent(event, event->pos());
 }
 
+/*!
+ * \internal
+ */
 void Q3DSurface::wheelEvent(QWheelEvent *event)
 {
     Q_UNUSED(event)
 }
 
+/*!
+ * \internal
+ */
 void Q3DSurface::resizeEvent(QResizeEvent *event)
 {
     Q_UNUSED(event);
@@ -95,9 +236,7 @@ void Q3DSurface::resizeEvent(QResizeEvent *event)
 /*!
  * \property Q3DSurface::gridVisible
  *
- * \a visible Flag to enable or disable grid. \c true by default.
- *
- * Sets grid drawing on or off.
+ * Sets grid visibility to \a visible. It is preset to \c true by default.
  */
 void Q3DSurface::setGridVisible(bool visible)
 {
@@ -112,9 +251,7 @@ bool Q3DSurface::isGridVisible() const
 /*!
  * \property Q3DSurface::backgroundVisible
  *
- * \a visible Flag to enable or disable background. \c true by default.
- *
- * Sets backround rendering on or off.
+ * Sets background visibility to \a visible. It is preset to \c true by default.
  */
 void Q3DSurface::setBackgroundVisible(bool visible)
 {
@@ -126,41 +263,60 @@ bool Q3DSurface::isBackgroundVisible() const
     return d_ptr->m_shared->backgroundEnabled();
 }
 
-void Q3DSurface::setSmoothSurface(bool enable)
+/*!
+ * \property Q3DSurface::smoothSurfaceEnabled
+ *
+ * Sets surface smoothing to \a enabled. It is preset to \c false by default.
+ */
+void Q3DSurface::setSmoothSurfaceEnabled(bool enabled)
 {
-    d_ptr->m_shared->setSmoothSurface(enable);
+    d_ptr->m_shared->setSmoothSurface(enabled);
 }
 
-bool Q3DSurface::smoothSurface() const
+bool Q3DSurface::isSmoothSurfaceEnabled() const
 {
     return d_ptr->m_shared->smoothSurface();
 }
 
-void Q3DSurface::setSurfaceGrid(bool enable)
+/*!
+ * \property Q3DSurface::surfaceGridEnabled
+ *
+ * Sets surface grid to \a enabled. It is preset to \c true by default.
+ */
+void Q3DSurface::setSurfaceGridEnabled(bool enabled)
 {
-    d_ptr->m_shared->setSurfaceGrid(enable);
+    d_ptr->m_shared->setSurfaceGrid(enabled);
 }
 
-bool Q3DSurface::surfaceGrid() const
+bool Q3DSurface::isSurfaceGridEnabled() const
 {
     return d_ptr->m_shared->surfaceGrid();
 }
 
+/*!
+ * Sets window \a width.
+ */
 void Q3DSurface::setWidth(const int width)
 {
     d_ptr->m_shared->setWidth(width);
     QWindow::setWidth(width);
 }
 
+/*!
+ * Sets window \a height.
+ */
 void Q3DSurface::setHeight(const int height)
 {
     d_ptr->m_shared->setHeight(height);
     QWindow::setHeight(height);
 }
 
-/*!
+/*
   TODO: REMOVE
  */
+/*!
+ * \internal
+ */
 void Q3DSurface::setSegmentCount(int segmentCount, qreal step, qreal minimum)
 {
     d_ptr->m_shared->setSegmentCount(GLint(segmentCount), GLfloat(step), GLfloat(minimum));
@@ -275,6 +431,15 @@ QList<Q3DValueAxis *> Q3DSurface::axes() const
     return retList;
 }
 
+/*!
+ * Sets the active data \a proxy. Implicitly calls addDataProxy() to transfer ownership of
+ * the \a proxy to this graph.
+ *
+ * If the \a proxy is null, a temporary default proxy is created and activated.
+ * This temporary proxy is destroyed if another \a proxy is explicitly set active via this method.
+ *
+ * \sa addDataProxy(), releaseDataProxy()
+ */
 void Q3DSurface::setActiveDataProxy(QSurfaceDataProxy *proxy)
 {
     d_ptr->m_shared->setActiveDataProxy(proxy);
@@ -288,16 +453,36 @@ QSurfaceDataProxy *Q3DSurface::activeDataProxy() const
     return static_cast<QSurfaceDataProxy *>(d_ptr->m_shared->activeDataProxy());
 }
 
+/*!
+ * Adds data \a proxy to the graph. The proxies added via addDataProxy are not yet taken to use,
+ * addDataProxy is simply used to give the ownership of the data \a proxy to the graph.
+ * The \a proxy must not be null or added to another graph.
+ *
+ * \sa releaseDataProxy(), setActiveDataProxy()
+ */
 void Q3DSurface::addDataProxy(QSurfaceDataProxy *proxy)
 {
     d_ptr->m_shared->addDataProxy(proxy);
 }
 
+/*!
+ * Releases the ownership of the data \a proxy back to the caller, if it is added to this graph.
+ * If the released \a proxy is in use, a new empty default proxy is created and taken to use.
+ *
+ * If the default \a proxy is released and added back later, it behaves as any other proxy would.
+ *
+ * \sa addDataProxy(), setActiveDataProxy()
+ */
 void Q3DSurface::releaseDataProxy(QSurfaceDataProxy *proxy)
 {
     d_ptr->m_shared->releaseDataProxy(proxy);
 }
 
+/*!
+ * \return list of all added data proxies.
+ *
+ * \sa addDataProxy()
+ */
 QList<QSurfaceDataProxy *> Q3DSurface::dataProxies() const
 {
     QList<QSurfaceDataProxy *> retList;
@@ -309,6 +494,9 @@ QList<QSurfaceDataProxy *> Q3DSurface::dataProxies() const
 }
 
 
+/*!
+ * Sets gradient color to \a color at \a pos.
+ */
 void Q3DSurface::setGradientColorAt(qreal pos, const QColor &color)
 {
     d_ptr->m_shared->setGradientColorAt(pos, color);
diff --git a/src/datavisualization/engine/q3dsurface.h b/src/datavisualization/engine/q3dsurface.h
index 5a458b67..79d03e36 100644
--- a/src/datavisualization/engine/q3dsurface.h
+++ b/src/datavisualization/engine/q3dsurface.h
@@ -33,8 +33,8 @@ class QT_DATAVISUALIZATION_EXPORT Q3DSurface : public Q3DWindow
     Q_OBJECT
     Q_PROPERTY(bool gridVisible READ isGridVisible WRITE setGridVisible)
     Q_PROPERTY(bool backgroundVisible READ isBackgroundVisible WRITE setBackgroundVisible)
-    Q_PROPERTY(bool smoothSurface READ smoothSurface WRITE setSmoothSurface)
-    Q_PROPERTY(bool surfaceGrid READ surfaceGrid WRITE setSurfaceGrid)
+    Q_PROPERTY(bool smoothSurfaceEnabled READ isSmoothSurfaceEnabled WRITE setSmoothSurfaceEnabled)
+    Q_PROPERTY(bool surfaceGridEnabled READ isSurfaceGridEnabled WRITE setSurfaceGridEnabled)
 
 public:
     explicit Q3DSurface();
@@ -49,12 +49,12 @@ public:
     bool isBackgroundVisible() const;
 
     // Enable or disable the smoothes of the surface
-    void setSmoothSurface(bool enable);
-    bool smoothSurface() const;
+    void setSmoothSurfaceEnabled(bool enabled);
+    bool isSmoothSurfaceEnabled() const;
 
     // Enable or disable the grid on the surface
-    void setSurfaceGrid(bool enable);
-    bool surfaceGrid() const;
+    void setSurfaceGridEnabled(bool enabled);
+    bool isSurfaceGridEnabled() const;
 
     void setGradientColorAt(qreal pos, const QColor &color);