From 2dc1b3809943e3d294e2363a2b0d185607b8854f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomi=20Korpip=C3=A4=C3=A4?= Date: Thu, 12 Sep 2013 07:58:26 +0300 Subject: QML documentation Task-number: QTRD-2133 Change-Id: I2568b3cd6e83ee933536d7fec2e48f9f121b213e Reviewed-by: Miikka Heikkinen --- src/datavisualization/engine/q3dbars.cpp | 147 +++++++++++++++++++ src/datavisualization/engine/q3dscatter.cpp | 117 +++++++++++++++ src/datavisualization/engine/q3dsurface.cpp | 214 ++++++++++++++++++++++++++-- src/datavisualization/engine/q3dsurface.h | 12 +- 4 files changed, 471 insertions(+), 19 deletions(-) (limited to 'src/datavisualization/engine') 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 @@ -88,6 +88,153 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE * \sa Q3DScatter, Q3DSurface, {Qt Data Visualization C++ Classes} */ +/*! + * \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. */ 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 @@ -80,6 +80,123 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE * \sa Q3DBars, Q3DSurface, {Qt Data Visualization C++ Classes} */ +/*! + * \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. */ 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 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(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 Q3DSurface::dataProxies() const { QList retList; @@ -309,6 +494,9 @@ QList 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); -- cgit v1.2.3