diff options
Diffstat (limited to 'src/datavisualization/data')
17 files changed, 808 insertions, 612 deletions
diff --git a/src/datavisualization/data/qabstract3dseries.cpp b/src/datavisualization/data/qabstract3dseries.cpp index c24ece86..42579f62 100644 --- a/src/datavisualization/data/qabstract3dseries.cpp +++ b/src/datavisualization/data/qabstract3dseries.cpp @@ -36,11 +36,13 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QAbstract3DSeries * \inmodule QtDataVisualization - * \brief Base class for all QtDataVisualization series. + * \brief The QAbstract3DSeries class is a base class for all data series. * \since QtDataVisualization 1.0 * - * You use the visualization type specific inherited classes instead of the base class. - * \sa QBar3DSeries, QScatter3DSeries, QSurface3DSeries, {Qt Data Visualization Data Handling} + * There are inherited classes for each supported series type: QBar3DSeries, + * QScatter3DSeries, and QSurface3DSeries. + * + * For more information, see \l{Qt Data Visualization Data Handling}. */ /*! @@ -59,13 +61,12 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \since QtDataVisualization 1.0 * \ingroup datavisualization_qml * \instantiates QAbstract3DSeries - * \brief Base type for all QtDataVisualization series. - * - * This type is uncreatable, but contains properties that are exposed via subtypes. + * \brief A base type for all data series. * - * For Abstract3DSeries enums, see \l QAbstract3DSeries::SeriesType and \l{QAbstract3DSeries::Mesh}. + * This type is uncreatable, but contains properties that are exposed via the + * following subtypes: Bar3DSeries, Scatter3DSeries, and Surface3DSeries. * - * \sa Bar3DSeries, Scatter3DSeries, Surface3DSeries, {Qt Data Visualization Data Handling} + * For more information, see \l{Qt Data Visualization Data Handling}. */ /*! @@ -112,21 +113,22 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * Arrow pointing upwards. * \value MeshPoint * 2D point. Usable only with Q3DScatter. - * \b Note: Shadows do not affect this style. Color style Q3DTheme::ColorStyleObjectGradient + * Shadows do not affect this style. Color style Q3DTheme::ColorStyleObjectGradient * is not supported by this style. */ /*! * \qmlproperty Abstract3DSeries.SeriesType Abstract3DSeries::type - * The type of the series. + * The type of the series. One of the QAbstract3DSeries::SeriesType values. + * */ /*! * \qmlproperty string Abstract3DSeries::itemLabelFormat * * The label format for data items in this series. This format is used for single item labels, - * for example, when an item is selected. How the format is interpreted depends on series type. See - * each series class documentation for more information. + * for example, when an item is selected. How the format is interpreted depends + * on series type: Bar3DSeries, Scatter3DSeries, Surface3DSeries. */ /*! @@ -141,13 +143,15 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * Surface3DSeries. If the mesh is \l{QAbstract3DSeries::MeshUserDefined}{Abstract3DSeries.MeshUserDefined}, * then the userDefinedMesh property must also be set for items to render properly. * The default value depends on the graph type. + * + * \sa QAbstract3DSeries::Mesh */ /*! * \qmlproperty bool Abstract3DSeries::meshSmooth * * If \c true, smooth versions of predefined meshes set via the \l mesh property are used. - * This property doesn't affect custom meshes used when mesh is + * This property does not affect custom meshes used when the mesh is set to * \l{QAbstract3DSeries::MeshUserDefined}{Abstract3DSeries.MeshUserDefined}. * Defaults to \c{false}. */ @@ -159,7 +163,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * The rotation should be a normalized quaternion. * For those series types that support item specific rotation, the rotations are * multiplied together. - * Bar3DSeries ignores any rotation that is not around Y-axis. + * Bar3DSeries ignores any rotation that is not around the y-axis. * Surface3DSeries applies the rotation only to the selection pointer. * Defaults to no rotation. */ @@ -167,10 +171,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty string Abstract3DSeries::userDefinedMesh * - * Sets the filename for user defined custom mesh for objects that is used when \l mesh + * Sets the filename for a user defined custom mesh for objects that is used when \l mesh * is \l{QAbstract3DSeries::MeshUserDefined}{Abstract3DSeries.MeshUserDefined}. - * \note The file needs to be in Wavefront obj format and include - * vertices, normals and UVs. It also needs to be in triangles. + * \note The file needs to be in the Wavefront OBJ format and include + * vertices, normals, and UVs. It also needs to be in triangles. */ /*! @@ -182,7 +186,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION */ /*! - * \qmlproperty Color Abstract3DSeries::baseColor + * \qmlproperty color Abstract3DSeries::baseColor * * Sets the base color of the series. * @@ -198,7 +202,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION */ /*! - * \qmlproperty Color Abstract3DSeries::singleHighlightColor + * \qmlproperty color Abstract3DSeries::singleHighlightColor * * Sets the single item highlight color of the series. * @@ -214,7 +218,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION */ /*! - * \qmlproperty Color Abstract3DSeries::multiHighlightColor + * \qmlproperty color Abstract3DSeries::multiHighlightColor * * Sets the multiple item highlight color of the series. * @@ -233,7 +237,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \qmlproperty string Abstract3DSeries::name * * The series name. - * Series name can be used in item label format with tag \c{@seriesName}. + * It can be used in item label format with the tag \c{@seriesName}. * * \sa itemLabelFormat */ @@ -252,9 +256,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \qmlproperty bool Abstract3DSeries::itemLabelVisible * \since QtDataVisualization 1.1 * - * If \c true, item labels are drawn as floating labels in the graph. Otherwise item labels are not - * drawn. If you prefer to show the item label in an external control, set this property to - * \c false. Defaults to \c true. + * If \c true, item labels are drawn as floating labels in the graph. Otherwise, + * item labels are not drawn. To show the item label in an external control, + * this property is set to \c false. Defaults to \c true. * * \sa itemLabelFormat, itemLabel */ @@ -262,7 +266,8 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlmethod void Abstract3DSeries::setMeshAxisAndAngle(vector3d axis, real angle) * - * A convenience function to construct mesh rotation quaternion from axis and angle. + * A convenience function to construct a mesh rotation quaternion from \a axis + * and \a angle. * * \sa meshRotation */ @@ -277,7 +282,7 @@ QAbstract3DSeries::QAbstract3DSeries(QAbstract3DSeriesPrivate *d, QObject *paren } /*! - * Destroys QAbstract3DSeries. + * Deletes the abstract 3D series. */ QAbstract3DSeries::~QAbstract3DSeries() { @@ -299,10 +304,8 @@ QAbstract3DSeries::SeriesType QAbstract3DSeries::type() const * \brief The label format for data items in this series. * * This format is used for single item labels, - * for example, when an item is selected. How the format is interpreted depends on series type. See - * each series class documentation for more information. - * - * \sa QBar3DSeries, QScatter3DSeries, QSurface3DSeries + * for example, when an item is selected. How the format is interpreted depends + * on series type: QBar3DSeries, QScatter3DSeries, QSurface3DSeries. */ void QAbstract3DSeries::setItemLabelFormat(const QString &format) { @@ -371,8 +374,8 @@ QAbstract3DSeries::Mesh QAbstract3DSeries::mesh() const * \brief Whether smooth versions of predefined meshes are used. * * If \c true, smooth versions set via the \l mesh property are used. - * This property doesn't affect custom meshes used when mesh is MeshUserDefined. - * Defaults to \c{false}. + * This property does not affect custom meshes used when the mesh is set to + * MeshUserDefined. Defaults to \c{false}. */ void QAbstract3DSeries::setMeshSmooth(bool enable) { @@ -395,7 +398,7 @@ bool QAbstract3DSeries::isMeshSmooth() const * The rotation should be a normalized QQuaternion. * For those series types that support item specific rotation, the rotations are * multiplied together. - * QBar3DSeries ignores any rotation that is not around Y-axis. + * QBar3DSeries ignores any rotation that is not around the y-axis. * QSurface3DSeries applies the rotation only to the selection pointer. * Defaults to no rotation. */ @@ -413,7 +416,8 @@ QQuaternion QAbstract3DSeries::meshRotation() const } /*! - * A convenience function to construct mesh rotation quaternion from \a axis and \a angle. + * A convenience function to construct a mesh rotation quaternion from + * \a axis and \a angle. * * \sa meshRotation */ @@ -428,8 +432,8 @@ void QAbstract3DSeries::setMeshAxisAndAngle(const QVector3D &axis, float angle) * \brief The filename for a user defined custom mesh for objects. * * The custom mesh is used when \l mesh is MeshUserDefined. - * \note The file needs to be in Wavefront obj format and include - * vertices, normals and UVs. It also needs to be in triangles. + * \note The file needs to be in the Wavefront OBJ format and include + * vertices, normals, and UVs. It also needs to be in triangles. */ void QAbstract3DSeries::setUserDefinedMesh(const QString &fileName) { @@ -635,9 +639,9 @@ QString QAbstract3DSeries::itemLabel() const * * \brief The visibility of item labels in the graph. * - * If \c true, item labels are drawn as floating labels in the graph. Otherwise item labels are not - * drawn. If you prefer to show the item label in an external control, set this property to - * \c false. Defaults to \c true. + * If \c true, item labels are drawn as floating labels in the graph. Otherwise, + * item labels are not drawn. To show the item label in an external control, + * this property is set to \c false. Defaults to \c true. * * \sa itemLabelFormat, itemLabel */ diff --git a/src/datavisualization/data/qabstractdataproxy.cpp b/src/datavisualization/data/qabstractdataproxy.cpp index fa25bc93..a9703e02 100644 --- a/src/datavisualization/data/qabstractdataproxy.cpp +++ b/src/datavisualization/data/qabstractdataproxy.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -35,11 +35,14 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QAbstractDataProxy * \inmodule QtDataVisualization - * \brief Base class for all QtDataVisualization data proxies. + * \brief The QAbstractDataProxy class is a base class for all data + * visualization data proxies. * \since QtDataVisualization 1.0 * - * You use the visualization type specific inherited classes instead of the base class. - * \sa QBarDataProxy, QScatterDataProxy, QSurfaceDataProxy, {Qt Data Visualization Data Handling} + * The following visualization type specific inherited classes are used instead + * of the base class: QBarDataProxy, QScatterDataProxy, and QSurfaceDataProxy. + * + * For more information, see \l{Qt Data Visualization Data Handling}. */ /*! @@ -50,22 +53,21 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \instantiates QAbstractDataProxy * \brief Base type for all QtDataVisualization data proxies. * - * This type is uncreatable, but contains properties that are exposed via subtypes. - * - * For AbstractDataProxy enums, see \l{QAbstractDataProxy::DataType}. + * This type is uncreatable, but contains properties that are exposed via the + * following subtypes: BarDataProxy, ScatterDataProxy, SurfaceDataProxy. * - * \sa BarDataProxy, ScatterDataProxy, SurfaceDataProxy, {Qt Data Visualization Data Handling} + * For more information, see \l {Qt Data Visualization Data Handling}. */ /*! * \qmlproperty AbstractDataProxy.DataType AbstractDataProxy::type - * The type of the proxy. + * The type of the proxy. One of the QAbstractDataProxy::DataType values. */ /*! * \enum QAbstractDataProxy::DataType * - * Data type of the proxy. + * This enum type specifies the data type of the proxy. * * \value DataTypeNone * No data type. @@ -87,7 +89,7 @@ QAbstractDataProxy::QAbstractDataProxy(QAbstractDataProxyPrivate *d, QObject *pa } /*! - * Destroys QAbstractDataProxy. + * Deletes the abstract data proxy. */ QAbstractDataProxy::~QAbstractDataProxy() { @@ -96,7 +98,7 @@ QAbstractDataProxy::~QAbstractDataProxy() /*! * \property QAbstractDataProxy::type * - * \brief The type of the proxy. + * \brief The data type of the proxy. */ QAbstractDataProxy::DataType QAbstractDataProxy::type() const { diff --git a/src/datavisualization/data/qbar3dseries.cpp b/src/datavisualization/data/qbar3dseries.cpp index 9d974695..c338b859 100644 --- a/src/datavisualization/data/qbar3dseries.cpp +++ b/src/datavisualization/data/qbar3dseries.cpp @@ -36,11 +36,11 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QBar3DSeries * \inmodule QtDataVisualization - * \brief Base series class for Q3DBars. + * \brief The QBar3DSeries class represents a data series in a 3D bar graph. * \since QtDataVisualization 1.0 * - * QBar3DSeries manages the series specific visual elements, as well as series data - * (via data proxy). + * This class manages the series specific visual elements, as well as the series + * data (via a data proxy). * * If no data proxy is set explicitly for the series, the series creates a default * proxy. Setting another proxy will destroy the existing proxy and all data added to it. @@ -54,21 +54,22 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \row * \li @valueTitle \li Title from value axis * \row - * \li @rowIdx \li Visible row index. Localized using graph locale. + * \li @rowIdx \li Visible row index. Localized using the graph locale. * \row - * \li @colIdx \li Visible Column index. Localized using graph locale. + * \li @colIdx \li Visible column index. Localized using the graph locale. * \row * \li @rowLabel \li Label from row axis * \row * \li @colLabel \li Label from column axis * \row - * \li @valueLabel \li Item value formatted using the same format the value axis attached to - * the graph uses. See \l{QValue3DAxis::labelFormat} for more information. + * \li @valueLabel \li Item value formatted using the format of the value + * axis attached to the graph. For more information, + * see \l{QValue3DAxis::labelFormat}. * \row * \li @seriesName \li Name of the series * \row - * \li %<format spec> \li Item value in specified format. Formatted using the same rules as - * \l{QValue3DAxis::labelFormat}. + * \li %<format spec> \li Item value in the specified format. Formatted + * using the same rules as \l{QValue3DAxis::labelFormat}. * \endtable * * For example: @@ -84,12 +85,12 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QBar3DSeries * \inherits Abstract3DSeries - * \brief Base series type for Bars3D. + * \brief Represents a data series in a 3D bar graph. * - * This type manages the series specific visual elements, as well as series data - * (via data proxy). + * This type manages the series specific visual elements, as well as the series + * data (via a data proxy). * - * For more complete description, see QBar3DSeries. + * For a more complete description, see QBar3DSeries. * * \sa {Qt Data Visualization Data Handling} */ @@ -126,8 +127,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty point Bar3DSeries::invalidSelectionPosition - * A constant property providing an invalid position for selection. Set this position to - * the selectedBar property if you want to clear the selection from this series. + * A constant property providing an invalid position for selection. This + * position is set to the selectedBar property to clear the selection from this + * series. * * \sa {AbstractGraph3D::clearSelection()}{AbstractGraph3D.clearSelection()} */ @@ -145,7 +147,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION */ /*! - * Constructs QBar3DSeries with the given \a parent. + * Constructsa bar 3D series with the parent \a parent. */ QBar3DSeries::QBar3DSeries(QObject *parent) : QAbstract3DSeries(new QBar3DSeriesPrivate(this), parent) @@ -156,7 +158,8 @@ QBar3DSeries::QBar3DSeries(QObject *parent) : } /*! - * Constructs QBar3DSeries with the given \a dataProxy and the \a parent. + * Constructs a bar 3D series with the data proxy \a dataProxy and the parent + * \a parent. */ QBar3DSeries::QBar3DSeries(QBarDataProxy *dataProxy, QObject *parent) : QAbstract3DSeries(new QBar3DSeriesPrivate(this), parent) @@ -166,7 +169,7 @@ QBar3DSeries::QBar3DSeries(QBarDataProxy *dataProxy, QObject *parent) : } /*! - * Destroys QBar3DSeries. + * Deletes a bar 3D series. */ QBar3DSeries::~QBar3DSeries() { @@ -204,7 +207,8 @@ QBarDataProxy *QBar3DSeries::dataProxy() const * * Only one bar can be selected at a time. * - * To clear selection from this series, set invalidSelectionPosition() as \a position. + * To clear selection from this series, invalidSelectionPosition() is set as + * \a position. * * If this series is added to a graph, the graph can adjust the selection according to user * interaction or if it becomes invalid. Selecting a bar on another added series will also @@ -230,8 +234,8 @@ QPoint QBar3DSeries::selectedBar() const } /*! - * \return an invalid position for selection. Set this position to selectedBar property if you - * want to clear the selection from this series. + * Returns an invalid position for selection. This position is set to the + * selectedBar property to clear the selection from this series. * * \sa QAbstract3DGraph::clearSelection() */ @@ -253,7 +257,8 @@ static inline float quaternionAngle(const QQuaternion &rotation) * Setting this property is equivalent to the following call: * \code setMeshRotation(QQuaternion::fromAxisAndAngle(0.0f, 1.0f, 0.0f, angle)) \endcode * - * \note When reading this property, it is calculated from QAbstract3DSeries::meshRotation value + * \note When reading this property, it is calculated from the + * QAbstract3DSeries::meshRotation value * using floating point precision and always returns a value from zero to 360 degrees. * * \sa QAbstract3DSeries::meshRotation diff --git a/src/datavisualization/data/qbardataitem.cpp b/src/datavisualization/data/qbardataitem.cpp index a5f13fb2..5827cf42 100644 --- a/src/datavisualization/data/qbardataitem.cpp +++ b/src/datavisualization/data/qbardataitem.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -37,14 +37,14 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \brief The QBarDataItem class provides a container for resolved data to be added to bar graphs. * \since QtDataVisualization 1.0 * - * A QBarDataItem holds data for a single rendered bar in a graph. - * Bar data proxies parse data into QBarDataItem instances for visualizing. + * A bar data item holds the data for a single rendered bar in a graph. + * Bar data proxies parse data into QBarDataItem instances for visualization. * * \sa QBarDataProxy, {Qt Data Visualization C++ Classes} */ /*! - * Constructs QBarDataItem. + * Constructs a bar data item. */ QBarDataItem::QBarDataItem() : d_ptr(0), // private data doesn't exist by default (optimization) @@ -54,7 +54,7 @@ QBarDataItem::QBarDataItem() } /*! - * Constructs QBarDataItem with \a value. + * Constructs a bar data item with the value \a value. */ QBarDataItem::QBarDataItem(float value) : d_ptr(0), @@ -64,7 +64,7 @@ QBarDataItem::QBarDataItem(float value) } /*! - * Constructs QBarDataItem with \a value and \a angle + * Constructs a bar data item with the value \a value and angle \a angle. */ QBarDataItem::QBarDataItem(float value, float angle) : d_ptr(0), @@ -82,7 +82,7 @@ QBarDataItem::QBarDataItem(const QBarDataItem &other) } /*! - * Destroys QBarDataItem. + * Deletes a bar data item. */ QBarDataItem::~QBarDataItem() { @@ -105,22 +105,22 @@ QBarDataItem &QBarDataItem::operator=(const QBarDataItem &other) /*! * \fn void QBarDataItem::setValue(float val) - * Sets value \a val to this data item. + * Sets the value \a val to this data item. */ /*! * \fn float QBarDataItem::value() const - * \return value of this data item. + * Returns the value of this data item. */ /*! * \fn void QBarDataItem::setRotation(float angle) - * Sets rotation \a angle in degrees for this data item. + * Sets the rotation angle \a angle in degrees for this data item. */ /*! * \fn float QBarDataItem::rotation() const - * \return rotation angle in degrees for this data item. + * Returns the rotation angle in degrees for this data item. */ /*! diff --git a/src/datavisualization/data/qbardataproxy.cpp b/src/datavisualization/data/qbardataproxy.cpp index c5dfe71a..0493543b 100644 --- a/src/datavisualization/data/qbardataproxy.cpp +++ b/src/datavisualization/data/qbardataproxy.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -35,22 +35,24 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QBarDataProxy * \inmodule QtDataVisualization - * \brief Base proxy class for Q3DBars. + * \brief The QBarDataProxy class is the data proxy for a 3D bars graph. * \since QtDataVisualization 1.0 * - * QBarDataProxy handles adding, inserting, changing and removing rows of data. + * A bar data proxy handles adding, inserting, changing, and removing rows of + * data. * * The data array is a list of vectors (rows) of QBarDataItem instances. - * Each row can contain different amount of items or even be null. + * Each row can contain a different number of items or even be null. * - * QBarDataProxy takes ownership of all QBarDataRows passed to it, whether directly or - * in a QBarDataArray container. - * If you use QBarDataRow pointers to directly modify data after adding the array to the proxy, - * you must also emit proper signal to make the graph update. + * QBarDataProxy takes ownership of all QtDataVisualization::QBarDataRow objects + * passed to it, whether directly or in a QtDataVisualization::QBarDataArray container. + * If bar data row pointers are used to directly modify data after adding the + * array to the proxy, the appropriate signal must be emitted to update the + * graph. * * QBarDataProxy optionally keeps track of row and column labels, which QCategory3DAxis can utilize - * to show axis labels. The row and column labels are stored in separate array from the data and - * row manipulation methods provide an alternate versions that don't affect the row labels. + * to show axis labels. The row and column labels are stored in a separate array from the data and + * row manipulation methods provide alternate versions that do not affect the row labels. * This enables the option of having row labels that relate to the position of the data in the * array rather than the data itself. * @@ -61,14 +63,14 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \typedef QtDataVisualization::QBarDataRow * \relates QBarDataProxy * - * A vector of \l {QBarDataItem}s. + * A vector of \l {QBarDataItem} objects. */ /*! * \typedef QtDataVisualization::QBarDataArray * \relates QBarDataProxy * - * A list of pointers to \l {QBarDataRow}s. + * A list of pointers to \l {QBarDataRow} objects. */ /*! @@ -78,13 +80,13 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QBarDataProxy * \inherits AbstractDataProxy - * \brief Base proxy type for Bars3D. + * \brief The data proxy for a 3D bars graph. * * This type handles adding, inserting, changing, and removing rows of data with Qt Quick 2. * * This type is uncreatable, but contains properties that are exposed via subtypes. * - * For more complete description, see QBarDataProxy. + * For a more complete description, see QBarDataProxy. * * \sa ItemModelBarDataProxy, {Qt Data Visualization Data Handling} */ @@ -99,7 +101,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * * The optional row labels for the array. Indexes in this array match the row * indexes in the data array. - * If the list is shorter than number of rows, all rows will not get labels. + * If the list is shorter than the number of rows, all rows will not get labels. */ /*! @@ -116,7 +118,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION */ /*! - * Constructs QBarDataProxy with the given \a parent. + * Constructs a bar data proxy with the given \a parent. */ QBarDataProxy::QBarDataProxy(QObject *parent) : QAbstractDataProxy(new QBarDataProxyPrivate(this), parent) @@ -132,7 +134,7 @@ QBarDataProxy::QBarDataProxy(QBarDataProxyPrivate *d, QObject *parent) : } /*! - * Destroys QBarDataProxy. + * Deletes the bar data proxy. */ QBarDataProxy::~QBarDataProxy() { @@ -158,10 +160,11 @@ void QBarDataProxy::resetArray() } /*! - * Takes ownership of the \a newArray. Clears the existing array if the \a newArray is - * different from the existing array. If it's the same array, this just triggers arrayReset() - * signal. - * Passing null array deletes the old array and creates a new empty array. + * Takes ownership of the array \a newArray. Clears the existing array if the + * new array differs from it. If the arrays are the same, this function + * just triggers the arrayReset() signal. + * + * Passing a null array deletes the old array and creates a new empty array. * Row and column labels are not affected. */ void QBarDataProxy::resetArray(QBarDataArray *newArray) @@ -172,10 +175,12 @@ void QBarDataProxy::resetArray(QBarDataArray *newArray) } /*! - * Takes ownership of the \a newArray. Clears the existing array if the \a newArray is - * different from the existing array. If it's the same array, this just triggers arrayReset() - * signal. + * Takes ownership of the array \a newArray. Clears the existing array if the + * new array differs from it. If the arrays are the same, this function + * just triggers the arrayReset() signal. + * * Passing a null array deletes the old array and creates a new empty array. + * * The \a rowLabels and \a columnLabels lists specify the new labels for rows and columns. */ void QBarDataProxy::resetArray(QBarDataArray *newArray, const QStringList &rowLabels, @@ -187,8 +192,9 @@ void QBarDataProxy::resetArray(QBarDataArray *newArray, const QStringList &rowLa } /*! - * Changes existing rows by replacing a row at \a rowIndex with a new \a row. The \a row can be - * the same as the existing row already stored at the \a rowIndex. + * Changes an existing row by replacing the row at the position \a rowIndex + * with the new row specified by \a row. The new row can be + * the same as the existing row already stored at \a rowIndex. * Existing row labels are not affected. */ void QBarDataProxy::setRow(int rowIndex, QBarDataRow *row) @@ -198,9 +204,10 @@ void QBarDataProxy::setRow(int rowIndex, QBarDataRow *row) } /*! - * Changes existing rows by replacing a row at \a rowIndex with \a row. The \a row can be - * the same as the existing row already stored at the \a rowIndex. - * Changes the row label to the \a label. + * Changes an existing row by replacing the row at the position \a rowIndex + * with the new row specified by \a row. The new row can be + * the same as the existing row already stored at \a rowIndex. + * Changes the row label to \a label. */ void QBarDataProxy::setRow(int rowIndex, QBarDataRow *row, const QString &label) { @@ -209,9 +216,10 @@ void QBarDataProxy::setRow(int rowIndex, QBarDataRow *row, const QString &label) } /*! - * Changes existing rows by replacing a rows starting at \a rowIndex with \a rows. + * Changes existing rows by replacing the rows starting at the position + * \a rowIndex with the new rows specifies by \a rows. * Existing row labels are not affected. The rows in the \a rows array can be - * the same as the existing rows already stored at the \a rowIndex. + * the same as the existing rows already stored at \a rowIndex. */ void QBarDataProxy::setRows(int rowIndex, const QBarDataArray &rows) { @@ -220,9 +228,10 @@ void QBarDataProxy::setRows(int rowIndex, const QBarDataArray &rows) } /*! - * Changes existing rows by replacing a rows starting at \a rowIndex with \a rows. + * Changes existing rows by replacing the rows starting at the position + * \a rowIndex with the new rows specifies by \a rows. * The row labels are changed to \a labels. The rows in the \a rows array can be - * the same as the existing rows already stored at the \a rowIndex. + * the same as the existing rows already stored at \a rowIndex. */ void QBarDataProxy::setRows(int rowIndex, const QBarDataArray &rows, const QStringList &labels) { @@ -231,7 +240,8 @@ void QBarDataProxy::setRows(int rowIndex, const QBarDataArray &rows, const QStri } /*! - * Changes a single item at \a rowIndex, \a columnIndex to the \a item. + * Changes a single item at the position specified by \a rowIndex and + * \a columnIndex to the item \a item. */ void QBarDataProxy::setItem(int rowIndex, int columnIndex, const QBarDataItem &item) { @@ -240,8 +250,9 @@ void QBarDataProxy::setItem(int rowIndex, int columnIndex, const QBarDataItem &i } /*! - * Changes a single item at \a position to the \a item. - * The X-value of \a position indicates the row and the Y-value indicates the column. + * Changes a single item at the position \a position to the item \a item. + * The x-value of \a position indicates the row and the y-value indicates the + * column. */ void QBarDataProxy::setItem(const QPoint &position, const QBarDataItem &item) { @@ -249,10 +260,10 @@ void QBarDataProxy::setItem(const QPoint &position, const QBarDataItem &item) } /*! - * Adds a new \a row to the end of array. + * Adds the new row \a row to the end of an array. * Existing row labels are not affected. * - * \return index of the added row. + * Returns the index of the added row. */ int QBarDataProxy::addRow(QBarDataRow *row) { @@ -263,9 +274,9 @@ int QBarDataProxy::addRow(QBarDataRow *row) } /*! - * Adds a new \a row with the \a label to the end of array. + * Adds a the new row \a row with the label \a label to the end of an array. * - * \return index of the added row. + * Returns the index of the added row. */ int QBarDataProxy::addRow(QBarDataRow *row, const QString &label) { @@ -276,10 +287,10 @@ int QBarDataProxy::addRow(QBarDataRow *row, const QString &label) } /*! - * Adds new \a rows to the end of array. + * Adds the new \a rows to the end of an array. * Existing row labels are not affected. * - * \return index of the first added row. + * Returns the index of the first added row. */ int QBarDataProxy::addRows(const QBarDataArray &rows) { @@ -290,9 +301,9 @@ int QBarDataProxy::addRows(const QBarDataArray &rows) } /*! - * Adds new \a rows with \a labels to the end of array. + * Adds the new \a rows with \a labels to the end of the array. * - * \return index of the first added row. + * Returns the index of the first added row. */ int QBarDataProxy::addRows(const QBarDataArray &rows, const QStringList &labels) { @@ -303,10 +314,11 @@ int QBarDataProxy::addRows(const QBarDataArray &rows, const QStringList &labels) } /*! - * Inserts a new \a row into \a rowIndex. - * If rowIndex is equal to array size, rows are added to end of the array. - * Any existing row labels are not affected. - * \note Row labels array will be out of sync with row array after this call, + * Inserts the new row \a row into \a rowIndex. + * If \a rowIndex is equal to the array size, the rows are added to the end of + * the array. + * The existing row labels are not affected. + * \note The row labels array will be out of sync with the row array after this call * if there were labeled rows beyond the inserted row. */ void QBarDataProxy::insertRow(int rowIndex, QBarDataRow *row) @@ -317,8 +329,9 @@ void QBarDataProxy::insertRow(int rowIndex, QBarDataRow *row) } /*! - * Inserts a new \a row with the \a label into \a rowIndex. - * If rowIndex is equal to array size, rows are added to end of the array. + * Inserts the new row \a row with the label \a label into \a rowIndex. + * If \a rowIndex is equal to array size, rows are added to the end of the + * array. */ void QBarDataProxy::insertRow(int rowIndex, QBarDataRow *row, const QString &label) { @@ -329,9 +342,9 @@ void QBarDataProxy::insertRow(int rowIndex, QBarDataRow *row, const QString &lab /*! * Inserts new \a rows into \a rowIndex. - * If rowIndex is equal to array size, rows are added to end of the array. - * Any existing row labels are not affected. - * \note Row labels array will be out of sync with row array after this call, + * If \a rowIndex is equal to the array size, the rows are added to the end of + * the array. The existing row labels are not affected. + * \note The row labels array will be out of sync with the row array after this call * if there were labeled rows beyond the inserted rows. */ void QBarDataProxy::insertRows(int rowIndex, const QBarDataArray &rows) @@ -343,7 +356,8 @@ void QBarDataProxy::insertRows(int rowIndex, const QBarDataArray &rows) /*! * Inserts new \a rows with \a labels into \a rowIndex. - * If rowIndex is equal to array size, rows are added to end of the array. + * If \a rowIndex is equal to the array size, the rows are added to the end of + * the array. */ void QBarDataProxy::insertRows(int rowIndex, const QBarDataArray &rows, const QStringList &labels) { @@ -353,11 +367,12 @@ void QBarDataProxy::insertRows(int rowIndex, const QBarDataArray &rows, const QS } /*! - * Removes \a removeCount rows staring at \a rowIndex. Attempting to remove rows past the end of the - * array does nothing. If \a removeLabels is true, corresponding row labels are also removed. Otherwise - * the row labels are not affected. - * \note If \a removeLabels is false, the row labels array will be out of sync with the row array - * if there are labeled rows beyond the removed rows. + * Removes the number of rows specified by \a removeCount starting at the + * position \a rowIndex. Attempting to remove rows past the end of the + * array does nothing. If \a removeLabels is \c true, the corresponding row + * labels are also removed. Otherwise, the row labels are not affected. + * \note If \a removeLabels is \c false, the row labels array will be out of + * sync with the row array if there are labeled rows beyond the removed rows. */ void QBarDataProxy::removeRows(int rowIndex, int removeCount, bool removeLabels) { @@ -421,7 +436,7 @@ void QBarDataProxy::setColumnLabels(const QStringList &labels) } /*! - * \return pointer to the data array. + * Returns the pointer to the data array. */ const QBarDataArray *QBarDataProxy::array() const { @@ -429,8 +444,8 @@ const QBarDataArray *QBarDataProxy::array() const } /*! - * \return pointer to the row at \a rowIndex. It is guaranteed to be valid only until the next call - * that modifies data. + * Returns the pointer to the row at the position \a rowIndex. It is guaranteed + * to be valid only until the next call that modifies data. */ const QBarDataRow *QBarDataProxy::rowAt(int rowIndex) const { @@ -440,7 +455,8 @@ const QBarDataRow *QBarDataProxy::rowAt(int rowIndex) const } /*! - * \return pointer to the item at \a rowIndex, \a columnIndex. It is guaranteed to be valid only + * Returns the pointer to the item at the position specified by \a rowIndex and + * \a columnIndex. It is guaranteed to be valid only * until the next call that modifies data. */ const QBarDataItem *QBarDataProxy::itemAt(int rowIndex, int columnIndex) const @@ -453,9 +469,9 @@ const QBarDataItem *QBarDataProxy::itemAt(int rowIndex, int columnIndex) const } /*! - * \return pointer to the item at \a position. The X-value of \a position indicates the row - * and the Y-value indicates the column. The item is guaranteed to be valid only - * until the next call that modifies data. + * Returns the pointer to the item at the position \a position. The x-value of + * \a position indicates the row and the y-value indicates the column. The item + * is guaranteed to be valid only until the next call that modifies data. */ const QBarDataItem *QBarDataProxy::itemAt(const QPoint &position) const { @@ -481,50 +497,57 @@ const QBarDataProxyPrivate *QBarDataProxy::dptrc() const /*! * \fn void QBarDataProxy::arrayReset() * - * Emitted when data array is reset. - * If you change the whole array contents without calling resetArray(), you need to - * emit this signal yourself or the graph won't get updated. + * This signal is emitted when the data array is reset. + * If the contents of the whole array are changed without calling resetArray(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QBarDataProxy::rowsAdded(int startIndex, int count) * - * Emitted when rows have been added. Provides \a startIndex and \a count of rows added. - * If you add rows directly to the array without calling addRow() or addRows(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of rows specified by \a count is + * added starting at the position \a startIndex. + * If rows are added to the array without calling addRow() or addRows(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QBarDataProxy::rowsChanged(int startIndex, int count) * - * Emitted when rows have changed. Provides \a startIndex and \a count of changed rows. - * If you change rows directly in the array without calling setRow() or setRows(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of rows specified by \a count is + * changed starting at the position \a startIndex. + * If rows are changed in the array without calling setRow() or setRows(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QBarDataProxy::rowsRemoved(int startIndex, int count) * - * Emitted when rows have been removed. Provides \a startIndex and \a count of rows removed. - * Index is the current array size if rows were removed from the end of the array. - * If you remove rows directly from the array without calling removeRows(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of rows specified by \a count is + * removed starting at the position \a startIndex. + * + * The index is the current array size if the rows were removed from the end of + * the array. If rows are removed from the array without calling removeRows(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QBarDataProxy::rowsInserted(int startIndex, int count) * - * Emitted when rows have been inserted. Provides \a startIndex and \a count of inserted rows. - * If you insert rows directly into the array without calling insertRow() or insertRows(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of rows specified by \a count is + * inserted at the position \a startIndex. + * + * If rows are inserted into the array without calling insertRow() or + * insertRows(), this signal needs to be emitted to update the graph. */ /*! * \fn void QBarDataProxy::itemChanged(int rowIndex, int columnIndex) * - * Emitted when an item has changed. Provides \a rowIndex and \a columnIndex of changed item. - * If you change an item directly in the array without calling setItem(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the item at the position specified by \a rowIndex + * and \a columnIndex changes. + * If the item is changed in the array without calling setItem(), + * this signal needs to be emitted to update the graph. */ // QBarDataProxyPrivate diff --git a/src/datavisualization/data/qcustom3ditem.cpp b/src/datavisualization/data/qcustom3ditem.cpp index 740d79e7..11df7750 100644 --- a/src/datavisualization/data/qcustom3ditem.cpp +++ b/src/datavisualization/data/qcustom3ditem.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -34,11 +34,11 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QCustom3DItem * \inmodule QtDataVisualization - * \brief The QCustom3DItem class is for creating custom items to be added to a graph. + * \brief The QCustom3DItem class adds a custom item to a graph. * \since QtDataVisualization 1.1 * - * This class is for creating custom items to be added to a graph. The item has a custom mesh, - * position, scaling, rotation, and an optional texture. + * A custom item has a custom mesh, position, scaling, rotation, and an optional + * texture. * * \sa QAbstract3DGraph::addCustomItem() */ @@ -49,15 +49,15 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \since QtDataVisualization 1.1 * \ingroup datavisualization_qml * \instantiates QCustom3DItem - * \brief The Custom3DItem type is for creating custom items to be added to a graph. + * \brief Adds a custom item to a graph. * - * This type is for creating custom items to be added to a graph. The item has a custom mesh, - * position, scaling, rotation, and an optional texture. + * A custom item has a custom mesh, position, scaling, rotation, and an optional + * texture. */ /*! \qmlproperty string Custom3DItem::meshFile * - * The item mesh file name. The item in the file must be in Wavefront obj format and include + * The item mesh file name. The item in the file must be in Wavefront OBJ format and include * vertices, normals, and UVs. It also needs to be in triangles. */ @@ -66,15 +66,18 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * The texture file name for the item. If left unset, a solid gray texture will be * used. * - * \note To conserve memory the QImage loaded from the file is cleared after a texture is created. + * \note To conserve memory, the QImage loaded from the file is cleared after a + * texture is created. */ /*! \qmlproperty vector3d Custom3DItem::position * - * The item position as a vector3d. Defaults to \c {vector3d(0.0, 0.0, 0.0)}. + * The item position as a \l vector3d type. Defaults to + * \c {vector3d(0.0, 0.0, 0.0)}. * - * Item position is either in data coordinates or in absolute coordinates, depending on the - * positionAbsolute property. When using absolute coordinates, values between \c{-1.0...1.0} are + * Item position is specified either in data coordinates or in absolute + * coordinates, depending on the value of the positionAbsolute property. When + * using absolute coordinates, values between \c{-1.0...1.0} are * within axis ranges. * * \note Items positioned outside any axis range are not rendered if positionAbsolute is \c{false}, @@ -95,12 +98,14 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! \qmlproperty vector3d Custom3DItem::scaling * - * The item scaling as a vector3d. Defaults to \c {vector3d(0.1, 0.1, 0.1)}. + * The item scaling as a \l vector3d type. Defaults to + * \c {vector3d(0.1, 0.1, 0.1)}. * - * Item scaling is either in data values or in absolute values, depending on the - * scalingAbsolute property. The default vector interpreted as absolute values sets the item to + * Item scaling is specified either in data values or in absolute values, + * depending on the value of the scalingAbsolute property. The default vector + * interpreted as absolute values sets the item to * 10% of the height of the graph, provided the item mesh is normalized and the graph aspect ratios - * haven't been changed from the defaults. + * have not been changed from the defaults. * * \sa scalingAbsolute */ @@ -111,7 +116,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * Defines whether item scaling is to be handled in data values or in absolute * values. Defaults to \c{true}. Items with absolute scaling will be rendered at the same * size, regardless of axis ranges. Items with data scaling will change their apparent size - * according to the axis ranges. If positionAbsolute value is \c{true}, this property is ignored + * according to the axis ranges. If positionAbsolute is \c{true}, this property is ignored * and scaling is interpreted as an absolute value. If the item has rotation, the data scaling * is calculated on the unrotated item. Similarly, for Custom3DVolume items, the range clipping * is calculated on the unrotated item. @@ -119,7 +124,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \note Only absolute scaling is supported for Custom3DLabel items or for custom items used in * \l{AbstractGraph3D::polar}{polar} graphs. * - * \note The custom item's mesh must be normalized to range \c{[-1 ,1]}, or the data + * \note The custom item's mesh must be normalized to the range \c{[-1 ,1]}, or the data * scaling will not be accurate. * * \sa scaling, positionAbsolute @@ -127,7 +132,8 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! \qmlproperty quaternion Custom3DItem::rotation * - * The item rotation as a quaternion. Defaults to \c {quaternion(0.0, 0.0, 0.0, 0.0)}. + * The item rotation as a \l quaternion. Defaults to + * \c {quaternion(0.0, 0.0, 0.0, 0.0)}. */ /*! \qmlproperty bool Custom3DItem::visible @@ -145,13 +151,14 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlmethod void Custom3DItem::setRotationAxisAndAngle(vector3d axis, real angle) * - * A convenience function to construct rotation quaternion from \a axis and \a angle. + * A convenience function to construct the rotation quaternion from \a axis and + * \a angle. * * \sa rotation */ /*! - * Constructs QCustom3DItem with given \a parent. + * Constructs a custom 3D item with the specified \a parent. */ QCustom3DItem::QCustom3DItem(QObject *parent) : QObject(parent), @@ -171,7 +178,7 @@ QCustom3DItem::QCustom3DItem(QCustom3DItemPrivate *d, QObject *parent) : } /*! - * Constructs QCustom3DItem with given \a meshFile, \a position, \a scaling, + * Constructs a custom 3D item with the specified \a meshFile, \a position, \a scaling, * \a rotation, \a texture image, and optional \a parent. */ QCustom3DItem::QCustom3DItem(const QString &meshFile, const QVector3D &position, @@ -184,7 +191,7 @@ QCustom3DItem::QCustom3DItem(const QString &meshFile, const QVector3D &position, } /*! - * Destroys QCustom3DItem. + * Deletes the custom 3D item. */ QCustom3DItem::~QCustom3DItem() { @@ -194,7 +201,7 @@ QCustom3DItem::~QCustom3DItem() * * \brief The item mesh file name. * - * The item in the file must be in Wavefront obj format and include + * The item in the file must be in Wavefront OBJ format and include * vertices, normals, and UVs. It also needs to be in triangles. */ void QCustom3DItem::setMeshFile(const QString &meshFile) @@ -218,7 +225,8 @@ QString QCustom3DItem::meshFile() const * * Defaults to \c {QVector3D(0.0, 0.0, 0.0)}. * - * Item position is either in data coordinates or in absolute coordinates, depending on + * Item position is specified either in data coordinates or in absolute + * coordinates, depending on the * positionAbsolute property. When using absolute coordinates, values between \c{-1.0...1.0} are * within axis ranges. * @@ -277,7 +285,7 @@ bool QCustom3DItem::isPositionAbsolute() const * Item scaling is either in data values or in absolute values, depending on the * scalingAbsolute property. The default vector interpreted as absolute values sets the item to * 10% of the height of the graph, provided the item mesh is normalized and the graph aspect ratios - * haven't been changed from the defaults. + * have not been changed from the defaults. * * \sa scalingAbsolute */ @@ -306,7 +314,7 @@ QVector3D QCustom3DItem::scaling() const * * Items with absolute scaling will be rendered at the same * size, regardless of axis ranges. Items with data scaling will change their apparent size - * according to the axis ranges. If positionAbsolute value is \c{true}, this property is ignored + * according to the axis ranges. If positionAbsolute is \c{true}, this property is ignored * and scaling is interpreted as an absolute value. If the item has rotation, the data scaling * is calculated on the unrotated item. Similarly, for QCustom3DVolume items, the range clipping * is calculated on the unrotated item. @@ -314,7 +322,7 @@ QVector3D QCustom3DItem::scaling() const * \note Only absolute scaling is supported for QCustom3DLabel items or for custom items used in * \l{QAbstract3DGraph::polar}{polar} graphs. * - * \note The custom item's mesh must be normalized to range \c{[-1 ,1]}, or the data + * \note The custom item's mesh must be normalized to the range \c{[-1 ,1]}, or the data * scaling will not be accurate. * * \sa scaling, positionAbsolute @@ -402,7 +410,8 @@ bool QCustom3DItem::isShadowCasting() const } /*! - * A convenience function to construct rotation quaternion from \a axis and \a angle. + * A convenience function to construct the rotation quaternion from \a axis and + * \a angle. * * \sa rotation */ @@ -412,9 +421,11 @@ void QCustom3DItem::setRotationAxisAndAngle(const QVector3D &axis, float angle) } /*! - * Sets the \a textureImage as a QImage for the item. Texture defaults to solid gray. + * Sets the value of \a textureImage as a QImage for the item. The texture + * defaults to solid gray. * - * \note To conserve memory the given QImage is cleared after a texture is created. + * \note To conserve memory, the given QImage is cleared after a texture is + * created. */ void QCustom3DItem::setTextureImage(const QImage &textureImage) { @@ -443,7 +454,8 @@ void QCustom3DItem::setTextureImage(const QImage &textureImage) * If both this property and the texture image are unset, a solid * gray texture will be used. * - * \note To conserve memory the QImage loaded from the file is cleared after a texture is created. + * \note To conserve memory, the QImage loaded from the file is cleared after a + * texture is created. */ void QCustom3DItem::setTextureFile(const QString &textureFile) { diff --git a/src/datavisualization/data/qcustom3dlabel.cpp b/src/datavisualization/data/qcustom3dlabel.cpp index 27d02993..5cc0a0e4 100644 --- a/src/datavisualization/data/qcustom3dlabel.cpp +++ b/src/datavisualization/data/qcustom3dlabel.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -35,16 +35,16 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QCustom3DLabel * \inmodule QtDataVisualization - * \brief The QCustom3DLabel class is for creating custom labels to be added to a graph. + * \brief The QCustom3DLabel class adds a custom label to a graph. * \since QtDataVisualization 1.1 * - * This class is for creating custom labels to be added to a graph. You can set text, font, - * position, scaling, rotation, and colors. You can also toggle borders and background for the - * label. Colors, borders and background are used from active theme unless any of them is set - * explicitly. + * The text, font, position, scaling, rotation, and colors of a custom label can + * be set. In addition, the visibility of the borders and background of the + * label can be toggled. Colors, borders, and background are determined by the + * active theme unless set explicitly. * - * \note In scaling, z has no effect. Setting the same x and y retains the original - * font dimensions. + * \note In scaling, the z-coordinate has no effect. Setting the same x- and + * y-coordinates retains the original font dimensions. * * \sa QAbstract3DGraph::addCustomItem() */ @@ -56,15 +56,15 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QCustom3DLabel * \inherits Custom3DItem - * \brief The Custom3DLabel type is for creating custom labels to be added to a graph. + * \brief Adds a custom label to a graph. * - * This type is for creating custom labels to be added to a graph. You can set text, font, - * position, scaling, rotation, and colors. You can also toggle borders and background for the - * label. Colors, borders and background are used from active theme unless any of them is set - * explicitly. + * The text, font, position, scaling, rotation, and colors of a custom label can + * be set. In addition, the visibility of the borders and background of the + * label can be toggled. Colors, borders, and background are determined by the + * active theme unless set explicitly. * - * \note In scaling, z has no effect. Setting the same x and y retains the original - * font dimensions. + * \note In scaling, the z-coordinate has no effect. Setting the same x- and + * y-coordinates retains the original font dimensions. */ /*! \qmlproperty string Custom3DLabel::text @@ -75,7 +75,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! \qmlproperty font Custom3DLabel::font * * The font to be used for the label. Defaults to \c{Font {family: "Arial"; pointSize: 20}}. - * Special formatting (for example outlined) is not supported. + * Special formatting (for example, outlined) is not supported. */ /*! \qmlproperty color Custom3DLabel::textColor @@ -106,11 +106,11 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! \qmlproperty bool Custom3DLabel::facingCamera * * Defines whether the label will always face the camera. Defaults to \c{false}. - * If set to \c{true}, rotation() has no effect. + * If set to \c{true}, \l {QCustom3DItem::}{rotation} has no effect. */ /*! - * Constructs QCustom3DLabel with given \a parent. + * Constructs a custom 3D label with the given \a parent. */ QCustom3DLabel::QCustom3DLabel(QObject *parent) : QCustom3DItem(new QCustom3DLabelPrivate(this), parent) @@ -118,10 +118,11 @@ QCustom3DLabel::QCustom3DLabel(QObject *parent) : } /*! - * Constructs QCustom3DLabel with given \a text, \a font, \a position, \a scaling, + * Constructs a custom 3D label with the given \a text, \a font, \a position, \a scaling, * \a rotation, and optional \a parent. * - * \note Setting the same x and y for \a scaling retains the original font dimensions. + * \note Setting the same x- and y-coordinates for \a scaling retains the + * original font dimensions. */ QCustom3DLabel::QCustom3DLabel(const QString &text, const QFont &font, const QVector3D &position, const QVector3D &scaling, @@ -132,7 +133,7 @@ QCustom3DLabel::QCustom3DLabel(const QString &text, const QFont &font, } /*! - * Destroys QCustom3DLabel. + * Deletes the custom 3D label. */ QCustom3DLabel::~QCustom3DLabel() { @@ -164,7 +165,7 @@ QString QCustom3DLabel::text() const * \brief The font to be used for the label. * * Defaults to \c{QFont("Arial", 20)}. Special formatting - * (for example outlined) is not supported. + * (for example, outlined) is not supported. */ void QCustom3DLabel::setFont(const QFont &font) { @@ -183,9 +184,9 @@ QFont QCustom3DLabel::font() const /*! \property QCustom3DLabel::textColor * - * \brief Color for the label text. + * \brief The color for the label text. * - * Also affects label border, if enabled. Defaults to \c{Qt::white}. + * Also affects the label border, if enabled. Defaults to \c{Qt::white}. * * \sa borderEnabled */ diff --git a/src/datavisualization/data/qcustom3dvolume.cpp b/src/datavisualization/data/qcustom3dvolume.cpp index 1e7bdb82..d54f34d1 100644 --- a/src/datavisualization/data/qcustom3dvolume.cpp +++ b/src/datavisualization/data/qcustom3dvolume.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -35,10 +35,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QCustom3DVolume * \inmodule QtDataVisualization - * \brief The QCustom3DVolume class is for creating volume rendered objects to be added to a graph. + * \brief The QCustom3DVolume class adds a volume rendered object to a graph. * \since QtDataVisualization 1.2 * - * This class is for creating volume rendered objects to be added to a graph. A volume rendered + * A volume rendered * object is a box with a 3D texture. Three slice planes are supported for the volume, one along * each main axis of the volume. * @@ -48,7 +48,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * smaller view or limiting the zoom level of the graph are easy ways to improve performance. * Similarly, the volume texture dimensions have a large impact on performance. * If the frame rate is more important than pixel-perfect rendering of the volume contents, consider - * turning the high definition shader off by setting useHighDefShader property to \c{false}. + * turning the high definition shader off by setting the useHighDefShader property to \c{false}. * * \note Volumetric objects are only supported with orthographic projection. * @@ -64,9 +64,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QCustom3DVolume * \inherits Custom3DItem - * \brief The Custom3DVolume type is for creating volume rendered objects to be added to a graph. + * \brief Adds a volume rendered object to a graph. * - * This class is for creating volume rendered objects to be added to a graph. A volume rendered + * A volume rendered * object is a box with a 3D texture. Three slice planes are supported for the volume, one along * each main axis of the volume. * @@ -76,11 +76,11 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * smaller view or limiting the zoom level of the graph are easy ways to improve performance. * Similarly, the volume texture dimensions have a large impact on performance. * If the frame rate is more important than pixel-perfect rendering of the volume contents, consider - * turning the high definition shader off by setting useHighDefShader property to \c{false}. + * turning the high definition shader off by setting the useHighDefShader property to \c{false}. * * \note Filling in the volume data would not typically be efficient or practical from pure QML, * so properties directly related to that are not fully supported from QML. - * Make a hybrid QML/C++ application if you want to use volume objects with a QML UI. + * Create a hybrid QML/C++ application if you want to use volume objects with a Qt Quick UI. * * \note Volumetric objects are only supported with orthographic projection. * @@ -94,7 +94,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * The width of the 3D texture defining the volume content in pixels. Defaults to \c{0}. * * \note Changing this property from QML is not supported, as the texture data cannot be resized - * to match. + * accordingly. */ /*! \qmlproperty int Custom3DVolume::textureHeight @@ -102,7 +102,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * The height of the 3D texture defining the volume content in pixels. Defaults to \c{0}. * * \note Changing this property from QML is not supported, as the texture data cannot be resized - * to match. + * accordingly. */ /*! \qmlproperty int Custom3DVolume::textureDepth @@ -110,12 +110,12 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * The depth of the 3D texture defining the volume content in pixels. Defaults to \c{0}. * * \note Changing this property from QML is not supported, as the texture data cannot be resized - * to match. + * accordingly. */ /*! \qmlproperty int Custom3DVolume::sliceIndexX * - * The X dimension index into the texture data indicating which vertical slice to show. + * The x-dimension index into the texture data indicating which vertical slice to show. * Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. * If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn * normally. @@ -126,7 +126,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! \qmlproperty int Custom3DVolume::sliceIndexY * - * The Y dimension index into the texture data indicating which horizontal slice to show. + * The y-dimension index into the texture data indicating which horizontal slice to show. * Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. * If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn * normally. @@ -137,7 +137,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! \qmlproperty int Custom3DVolume::sliceIndexZ * - * The Z dimension index into the texture data indicating which vertical slice to show. + * The z-dimension index into the texture data indicating which vertical slice to show. * Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. * If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn * normally. @@ -179,11 +179,12 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * The high definition shader guarantees that every visible texel of the volume texture is sampled * when the volume is rendered. * The low definition shader renders only a rough approximation of the volume contents, - * but at much higher frame rate. The low definition shader doesn't guarantee every texel of the + * but at a much higher frame rate. The low definition shader does not guarantee every texel of the * volume texture is sampled, so there may be flickering if the volume contains distinct thin * features. * - * \note This value doesn't affect the level of detail when rendering the slices of the volume. + * \note This value does not affect the level of detail when rendering the + * slices of the volume. * * Defaults to \c{true}. */ @@ -262,7 +263,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION */ /*! - * Constructs QCustom3DVolume with given \a parent. + * Constructs a custom 3D volume with the given \a parent. */ QCustom3DVolume::QCustom3DVolume(QObject *parent) : QCustom3DItem(new QCustom3DVolumePrivate(this), parent) @@ -270,7 +271,7 @@ QCustom3DVolume::QCustom3DVolume(QObject *parent) : } /*! - * Constructs QCustom3DVolume with given \a position, \a scaling, \a rotation, + * Constructs a custom 3D volume with the given \a position, \a scaling, \a rotation, * \a textureWidth, \a textureHeight, \a textureDepth, \a textureData, \a textureFormat, * \a colorTable, and optional \a parent. * @@ -289,7 +290,7 @@ QCustom3DVolume::QCustom3DVolume(const QVector3D &position, const QVector3D &sca /*! - * Destroys QCustom3DVolume. + * Deletes the custom 3D volume. */ QCustom3DVolume::~QCustom3DVolume() { @@ -301,7 +302,8 @@ QCustom3DVolume::~QCustom3DVolume() * * Defaults to \c{0}. * - * \note The textureData may need to be resized or recreated if this value is changed. + * \note The textureData value may need to be resized or recreated if this value + * is changed. * Defaults to \c{0}. * * \sa textureData, textureHeight, textureDepth, setTextureFormat(), textureDataWidth() @@ -331,7 +333,8 @@ int QCustom3DVolume::textureWidth() const * * Defaults to \c{0}. * - * \note The textureData may need to be resized or recreated if this value is changed. + * \note The textureData value may need to be resized or recreated if this value + * is changed. * Defaults to \c{0}. * * \sa textureData, textureWidth, textureDepth, setTextureFormat() @@ -362,7 +365,8 @@ int QCustom3DVolume::textureHeight() const * * Defaults to \c{0}. * - * \note The textureData may need to be resized or recreated if this value is changed. + * \note The textureData value may need to be resized or recreated if this value + * is changed. * Defaults to \c{0}. * * \sa textureData, textureWidth, textureHeight, setTextureFormat() @@ -401,7 +405,8 @@ void QCustom3DVolume::setTextureDimensions(int width, int height, int depth) /*! * Returns the actual texture data width. When the texture format is QImage::Format_Indexed8, - * this is textureWidth aligned to 32bit boundary. Otherwise this is four times textureWidth. + * this value equals textureWidth aligned to a 32-bit boundary. Otherwise, this + * value equals four times textureWidth. */ int QCustom3DVolume::textureDataWidth() const { @@ -417,7 +422,8 @@ int QCustom3DVolume::textureDataWidth() const /*! \property QCustom3DVolume::sliceIndexX * - * \brief The X dimension index into the texture data indicating which vertical slice to show. + * \brief The x-dimension index into the texture data indicating which vertical + * slice to show. * * Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. * If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn @@ -444,7 +450,8 @@ int QCustom3DVolume::sliceIndexX() const /*! \property QCustom3DVolume::sliceIndexY * - * \brief The Y dimension index into the texture data indicating which horizontal slice to show. + * \brief The y-dimension index into the texture data indicating which + * horizontal slice to show. * * Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. * If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn @@ -471,7 +478,8 @@ int QCustom3DVolume::sliceIndexY() const /*! \property QCustom3DVolume::sliceIndexZ * - * \brief The Z dimension index into the texture data indicating which vertical slice to show. + * \brief The z-dimension index into the texture data indicating which vertical + * slice to show. * * Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. * If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn @@ -541,20 +549,22 @@ QVector<QRgb> QCustom3DVolume::colorTable() const * (\c{textureDataWidth * textureHeight * textureDepth * texture format color depth in bytes}). * * A 3D texture is defined by a stack of 2D subtextures. Each subtexture must be of identical size - * (\c{textureDataWidth * textureHeight}), and the depth of the stack is defined by textureDepth - * property. Each 2D texture data is identical to a QImage data with the same format, so + * (\c{textureDataWidth * textureHeight}), and the depth of the stack is defined + * by the textureDepth property. The data in each 2D texture is identical to a + * QImage data with the same format, so * QImage::bits() can be used to supply the data for each subtexture. * - * Ownership of the new array transfers to QCustom3DVolume instance. + * Ownership of the new array transfers to the QCustom3DVolume instance. * If another array is set, the previous array is deleted. * If the same array is set again, it is assumed that the array contents have been changed and the * graph rendering is triggered. * - * \note Each X-line of the data needs to be 32bit aligned. If the textureFormat is - * QImage::Format_Indexed8 and textureWidth is not divisible by four, padding bytes need - * to be added to each X-line of the data. You can get the padded byte count with - * textureDataWidth() function. The padding bytes should indicate an fully transparent color - * to avoid rendering artifacts. + * \note Each x-dimension line of the data needs to be 32-bit aligned. + * If textureFormat is QImage::Format_Indexed8 and the textureWidth value is not + * divisible by four, padding bytes might need to be added to each x-dimension + * line of the \a data. The textureDataWidth() function returns the padded byte + * count. The padding bytes should indicate a fully transparent color to avoid + * rendering artifacts. * * Defaults to \c{0}. * @@ -577,8 +587,9 @@ void QCustom3DVolume::setTextureData(QVector<uchar> *data) * Creates a new texture data array from an array of \a images and sets it as * textureData for this volume object. The texture dimensions are also set according to image * and array dimensions. All of the images in the array must be the same size. If the images are not - * all in QImage::Format_Indexed8 format, all texture data will be converted into - * QImage::Format_ARGB32 format. If the images are in QImage::Format_Indexed8 format, the colorTable + * all in the QImage::Format_Indexed8 format, all texture data will be converted into the + * QImage::Format_ARGB32 format. If the images are in the + * QImage::Format_Indexed8 format, the colorTable value * for the entire volume will be taken from the first image. * * Returns a pointer to the newly created array. @@ -660,17 +671,19 @@ QVector<uchar> *QCustom3DVolume::textureData() const * Sets a single 2D subtexture of the 3D texture along the specified * \a axis of the volume. * The \a index parameter specifies the subtexture to set. - * The texture \a data must be in the format specified by textureFormat property and have size of + * The texture \a data must be in the format specified by the textureFormat + * property and have the size of * the cross-section of the volume texture along the specified axis multiplied by * the texture format color depth in bytes. - * The \a data is expected to be ordered similarly to the data in images produced by renderSlice() - * method along the same axis. + * The \a data is expected to be ordered similarly to the data in images + * produced by the renderSlice() method along the same axis. * - * \note Each X-line of the data needs to be 32bit aligned when targeting Y-axis or Z-axis. - * If the textureFormat is QImage::Format_Indexed8 and textureWidth is not divisible by four, - * padding bytes need to be added to each X-line of the \a data in cases it is not already - * properly aligned. The padding bytes should indicate an fully transparent color to avoid - * rendering artifacts. + * \note Each x-dimension line of the data needs to be 32-bit aligned when + * targeting the y-axis or z-axis. If textureFormat is QImage::Format_Indexed8 + * and the textureWidth value is not divisible by four, padding bytes might need + * to be added to each x-dimension line of the \a data to properly align it. The + * padding bytes should indicate a fully transparent color to avoid rendering + * artifacts. * * \sa textureData, renderSlice() */ @@ -740,17 +753,18 @@ void QCustom3DVolume::setSubTextureData(Qt::Axis axis, int index, const uchar *d * Sets a single 2D subtexture of the 3D texture along the specified * \a axis of the volume. * The \a index parameter specifies the subtexture to set. - * The source \a image must be in the format specified by the textureFormat property if the - * textureFormat is indexed. If the textureFormat is QImage::Format_ARGB32, the image is converted + * The source \a image must be in the format specified by the textureFormat property if + * textureFormat is indexed. If textureFormat is QImage::Format_ARGB32, the image is converted * to that format. The image must have the size of the cross-section of the volume texture along * the specified axis. The orientation of the image should correspond to the orientation of * the slice image produced by renderSlice() method along the same axis. * - * \note Each X-line of the data needs to be 32bit aligned when targeting Y-axis or Z-axis. - * If the textureFormat is QImage::Format_Indexed8 and textureWidth is not divisible by four, - * padding bytes need to be added to each X-line of the \a image in cases it is not already - * properly aligned. The padding bytes should indicate an fully transparent color to avoid - * rendering artifacts. It is not guaranteed QImage will do this automatically. + * \note Each x-dimension line of the data needs to be 32-bit aligned when + * targeting the y-axis or z-axis. If textureFormat is QImage::Format_Indexed8 + * and the textureWidth value is not divisible by four, padding bytes might need + * to be added to each x-dimension line of the image to properly align it. The + * padding bytes should indicate a fully transparent color to avoid rendering + * artifacts. It is not guaranteed that QImage will do this automatically. * * \sa textureData, renderSlice() */ @@ -792,7 +806,8 @@ void QCustom3DVolume::setSubTextureData(Qt::Axis axis, int index, const QImage & // doesn't allow QImage::format to be a property type. Qt 5.2.1 at least has this problem. /*! - * Sets the format of the textureData to \a format. Only two formats are supported currently: + * Sets the format of the textureData property to \a format. Only two formats + * are supported currently: * QImage::Format_Indexed8 and QImage::Format_ARGB32. If an indexed format is specified, colorTable * must also be set. * Defaults to QImage::Format_ARGB32. @@ -814,7 +829,7 @@ void QCustom3DVolume::setTextureFormat(QImage::Format format) } /*! - * Returns the format of the textureData. + * Returns the format of the textureData property value. * * \sa setTextureFormat() */ @@ -826,7 +841,7 @@ QImage::Format QCustom3DVolume::textureFormat() const /*! * \fn void QCustom3DVolume::textureFormatChanged(QImage::Format format) * - * This signal is emitted when the textureData \a format changes. + * This signal is emitted when the \a format of the textureData value changes. * * \sa setTextureFormat() */ @@ -902,11 +917,13 @@ bool QCustom3DVolume::preserveOpacity() const * The high definition shader guarantees that every visible texel of the volume texture is sampled * when the volume is rendered. * The low definition shader renders only a rough approximation of the volume contents, - * but at much higher frame rate. The low definition shader doesn't guarantee every texel of the + * but at a much higher frame rate. The low definition shader does not guarantee + * that every texel of the * volume texture is sampled, so there may be flickering if the volume contains distinct thin * features. * - * \note This value doesn't affect the level of detail when rendering the slices of the volume. + * \note This value does not affect the level of detail when rendering the + * slices of the volume. * * Defaults to \c{true}. * @@ -1106,10 +1123,11 @@ QVector3D QCustom3DVolume::sliceFrameThicknesses() const } /*! - * Renders the slice specified by \a index along \a axis into an image. + * Renders the slice specified by \a index along the axis specified by \a axis + * into an image. * The texture format of this object is used. * - * Returns the rendered image of the slice, or a null image if invalid index is + * Returns the rendered image of the slice, or a null image if an invalid index is * specified. * * \sa setTextureFormat() diff --git a/src/datavisualization/data/qitemmodelbardataproxy.cpp b/src/datavisualization/data/qitemmodelbardataproxy.cpp index b7c84ea7..f87016e1 100644 --- a/src/datavisualization/data/qitemmodelbardataproxy.cpp +++ b/src/datavisualization/data/qitemmodelbardataproxy.cpp @@ -48,21 +48,23 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * synchronously, unless the same frame also contains a change that causes the whole model to be * resolved. * - * There are three ways to use mappings: + * Mappings can be used in the following ways: * - * 1) If useModelCategories property is set to true, this proxy will map rows and + * \list + * \li If useModelCategories property is set to true, this proxy will map rows and * columns of QAbstractItemModel directly to rows and columns of Q3DBars, and uses the value * returned for Qt::DisplayRole as bar value by default. * The value role to be used can be redefined if Qt::DisplayRole is not suitable. * - * 2) For models that do not have data already neatly sorted into rows and columns, such as + * \li For models that do not have data already neatly sorted into rows and columns, such as * QAbstractListModel based models, you can define a role from the model to map for each of row, * column and value. * - * 3) If you do not want to include all data contained in the model, or the autogenerated rows and + * \li If you do not want to include all data contained in the model, or the autogenerated rows and * columns are not ordered as you wish, you can specify which rows and columns should be included * and in which order by defining an explicit list of categories for either or both of rows and * columns. + * \endlist * * For example, assume that you have a custom QAbstractItemModel for storing various monthly values * related to a business. @@ -116,22 +118,22 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty string ItemModelBarDataProxy::rowRole - * Defines the item model role to map into row category. + * The item model role to map into row category. */ /*! * \qmlproperty string ItemModelBarDataProxy::columnRole - * Defines the item model role to map into column category. + * The item model role to map into column category. */ /*! * \qmlproperty string ItemModelBarDataProxy::valueRole - * Defines the item model role to map into bar value. + * The item model role to map into bar value. */ /*! * \qmlproperty string ItemModelBarDataProxy::rotationRole - * Defines the item model role to map into bar rotation angle. + * The item model role to map into bar rotation angle. */ /*! @@ -150,21 +152,21 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty bool ItemModelBarDataProxy::useModelCategories - * When set to true, the mapping ignores row and column roles and categories, and uses + * When set to \c true, the mapping ignores row and column roles and categories, and uses * the rows and columns from the model instead. Row and column headers are used for row and column * labels. Defaults to \c{false}. */ /*! * \qmlproperty bool ItemModelBarDataProxy::autoRowCategories - * When set to true, the mapping ignores any explicitly set row categories + * When set to \c true, the mapping ignores any explicitly set row categories * and overwrites them with automatically generated ones whenever the * data from the model is resolved. Defaults to \c{true}. */ /*! * \qmlproperty bool ItemModelBarDataProxy::autoColumnCategories - * When set to true, the mapping ignores any explicitly set column categories + * When set to \c true, the mapping ignores any explicitly set column categories * and overwrites them with automatically generated ones whenever the * data from model is resolved. Defaults to \c{true}. */ @@ -251,7 +253,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty ItemModelBarDataProxy.MultiMatchBehavior ItemModelBarDataProxy::multiMatchBehavior - * This property defines how multiple matches for each row/column combination are handled. + * Defines how multiple matches for each row/column combination are handled. * Defaults to \l{QItemModelBarDataProxy::MMBLast}{ItemModelBarDataProxy.MMBLast}. The chosen * behavior affects both bar value and rotation. * @@ -423,8 +425,12 @@ QItemModelBarDataProxy::~QItemModelBarDataProxy() /*! * \property QItemModelBarDataProxy::itemModel * - * Defines item model. Does not take ownership of the model, but does connect to it to listen for - * changes. + * \brief The item model. + */ + +/*! + * Sets the item model to \a itemModel. Does not take ownership of the model, + * but does connect to it to listen for changes. */ void QItemModelBarDataProxy::setItemModel(QAbstractItemModel *itemModel) { @@ -439,7 +445,7 @@ QAbstractItemModel *QItemModelBarDataProxy::itemModel() const /*! * \property QItemModelBarDataProxy::rowRole * - * Defines the row \a role for the mapping. + * \brief The row role for the mapping. */ void QItemModelBarDataProxy::setRowRole(const QString &role) { @@ -457,7 +463,7 @@ QString QItemModelBarDataProxy::rowRole() const /*! * \property QItemModelBarDataProxy::columnRole * - * Defines the column \a role for the mapping. + * \brief The column role for the mapping. */ void QItemModelBarDataProxy::setColumnRole(const QString &role) { @@ -475,7 +481,7 @@ QString QItemModelBarDataProxy::columnRole() const /*! * \property QItemModelBarDataProxy::valueRole * - * Defines the value \a role for the mapping. + * \brief The value role for the mapping. */ void QItemModelBarDataProxy::setValueRole(const QString &role) { @@ -493,7 +499,7 @@ QString QItemModelBarDataProxy::valueRole() const /*! * \property QItemModelBarDataProxy::rotationRole * - * Defines the rotation \a role for the mapping. + * \brief The rotation role for the mapping. */ void QItemModelBarDataProxy::setRotationRole(const QString &role) { @@ -511,7 +517,7 @@ QString QItemModelBarDataProxy::rotationRole() const /*! * \property QItemModelBarDataProxy::rowCategories * - * Defines the row \a categories for the mapping. + * \brief The row categories for the mapping. */ void QItemModelBarDataProxy::setRowCategories(const QStringList &categories) { @@ -529,7 +535,7 @@ QStringList QItemModelBarDataProxy::rowCategories() const /*! * \property QItemModelBarDataProxy::columnCategories * - * Defines the column \a categories for the mapping. + * \brief The column categories for the mapping. */ void QItemModelBarDataProxy::setColumnCategories(const QStringList &categories) { @@ -547,7 +553,9 @@ QStringList QItemModelBarDataProxy::columnCategories() const /*! * \property QItemModelBarDataProxy::useModelCategories * - * When set to true, the mapping ignores row and column roles and categories, and uses + * \brief Whether row and column roles and categories are used for mapping. + * + * When set to \c true, the mapping ignores row and column roles and categories, and uses * the rows and columns from the model instead. Defaults to \c{false}. */ void QItemModelBarDataProxy::setUseModelCategories(bool enable) @@ -566,7 +574,9 @@ bool QItemModelBarDataProxy::useModelCategories() const /*! * \property QItemModelBarDataProxy::autoRowCategories * - * When set to true, the mapping ignores any explicitly set row categories + * \brief Whether row categories are generated automatically. + * + * When set to \c true, the mapping ignores any explicitly set row categories * and overwrites them with automatically generated ones whenever the * data from model is resolved. Defaults to \c{true}. */ @@ -586,7 +596,9 @@ bool QItemModelBarDataProxy::autoRowCategories() const /*! * \property QItemModelBarDataProxy::autoColumnCategories * - * When set to true, the mapping ignores any explicitly set column categories + * \brief Whether column categories are generated automatically. + * + * When set to \c true, the mapping ignores any explicitly set column categories * and overwrites them with automatically generated ones whenever the * data from model is resolved. Defaults to \c{true}. */ @@ -623,7 +635,7 @@ void QItemModelBarDataProxy::remap(const QString &rowRole, } /*! - * \return index of the specified \a category in row categories list. + * Returns the index of the specified \a category in row categories list. * If the row categories list is empty, -1 is returned. * \note If the automatic row categories generation is in use, this method will * not return a valid index before the data in the model is resolved for the first time. @@ -634,7 +646,7 @@ int QItemModelBarDataProxy::rowCategoryIndex(const QString &category) } /*! - * \return index of the specified \a category in column categories list. + * Returns the index of the specified \a category in column categories list. * If the category is not found, -1 is returned. * \note If the automatic column categories generation is in use, this method will * not return a valid index before the data in the model is resolved for the first time. @@ -647,8 +659,10 @@ int QItemModelBarDataProxy::columnCategoryIndex(const QString &category) /*! * \property QItemModelBarDataProxy::rowRolePattern * - * When set, a search and replace is done on the value mapped by row role before it is used as - * a row category. This property specifies the regular expression to find the portion of the + * \brief Whether a search and replace is performed on the value mapped by row + * role before it is used as a row category. + * + * This property specifies the regular expression to find the portion of the * mapped value to replace and rowRoleReplace property contains the replacement string. * This is useful for example in parsing row and column categories from a single * timestamp field in the item model. @@ -671,8 +685,10 @@ QRegExp QItemModelBarDataProxy::rowRolePattern() const /*! * \property QItemModelBarDataProxy::columnRolePattern * - * When set, a search and replace is done on the value mapped by column role before it is used - * as a column category. This property specifies the regular expression to find the portion of the + * \brief Whether a search and replace is done on the value mapped by column + * role before it is used as a column category. + * + * This property specifies the regular expression to find the portion of the * mapped value to replace and columnRoleReplace property contains the replacement string. * This is useful for example in parsing row and column categories from * a single timestamp field in the item model. @@ -695,8 +711,10 @@ QRegExp QItemModelBarDataProxy::columnRolePattern() const /*! * \property QItemModelBarDataProxy::valueRolePattern * - * When set, a search and replace is done on the value mapped by value role before it is used as - * a bar value. This property specifies the regular expression to find the portion of the + * \brief Whether a search and replace is done on the value mapped by value role + * before it is used as a bar value. + * + * This property specifies the regular expression to find the portion of the * mapped value to replace and valueRoleReplace property contains the replacement string. * * \sa valueRole, valueRoleReplace @@ -717,8 +735,10 @@ QRegExp QItemModelBarDataProxy::valueRolePattern() const /*! * \property QItemModelBarDataProxy::rotationRolePattern * - * When set, a search and replace is done on the value mapped by rotation role before it is used - * as a bar rotation angle. This property specifies the regular expression to find the portion + * \brief Whether a search and replace is done on the value mapped by rotation + * role before it is used as a bar rotation angle. + * + * This property specifies the regular expression to find the portion * of the mapped value to replace and rotationRoleReplace property contains the replacement string. * * \sa rotationRole, rotationRoleReplace @@ -739,7 +759,8 @@ QRegExp QItemModelBarDataProxy::rotationRolePattern() const /*! * \property QItemModelBarDataProxy::rowRoleReplace * - * This property defines the replace content to be used in conjunction with rowRolePattern. + * \brief The replace content to be used in conjunction with rowRolePattern. + * * Defaults to empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. @@ -762,7 +783,8 @@ QString QItemModelBarDataProxy::rowRoleReplace() const /*! * \property QItemModelBarDataProxy::columnRoleReplace * - * This property defines the replace content to be used in conjunction with columnRolePattern. + * \brief The replace content to be used in conjunction with columnRolePattern. + * * Defaults to empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. @@ -785,7 +807,8 @@ QString QItemModelBarDataProxy::columnRoleReplace() const /*! * \property QItemModelBarDataProxy::valueRoleReplace * - * This property defines the replace content to be used in conjunction with valueRolePattern. + * \brief The replace content to be used in conjunction with valueRolePattern. + * * Defaults to empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. @@ -808,7 +831,9 @@ QString QItemModelBarDataProxy::valueRoleReplace() const /*! * \property QItemModelBarDataProxy::rotationRoleReplace * - * This property defines the replace content to be used in conjunction with rotationRolePattern. + * \brief The replace content to be used in conjunction with + * rotationRolePattern. + * * Defaults to empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. @@ -831,7 +856,8 @@ QString QItemModelBarDataProxy::rotationRoleReplace() const /*! * \property QItemModelBarDataProxy::multiMatchBehavior * - * This property defines how multiple matches for each row/column combination are handled. + * \brief How multiple matches for each row/column combination are handled. + * * Defaults to QItemModelBarDataProxy::MMBLast. The chosen behavior affects both bar value * and rotation. * diff --git a/src/datavisualization/data/qitemmodelscatterdataproxy.cpp b/src/datavisualization/data/qitemmodelscatterdataproxy.cpp index 23cc890d..58180e69 100644 --- a/src/datavisualization/data/qitemmodelscatterdataproxy.cpp +++ b/src/datavisualization/data/qitemmodelscatterdataproxy.cpp @@ -94,28 +94,28 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty model ItemModelScatterDataProxy::itemModel - * The item model. + * The item model to use as a data source for Scatter3D. */ /*! * \qmlproperty string ItemModelScatterDataProxy::xPosRole - * Defines the item model role to map into X position. + * The item model role to map into the X position. */ /*! * \qmlproperty string ItemModelScatterDataProxy::yPosRole - * Defines the item model role to map into Y position. + * The item model role to map into the Y position. */ /*! * \qmlproperty string ItemModelScatterDataProxy::zPosRole - * Defines the item model role to map into Z position. + * The item model role to map into the Z position. */ /*! * \qmlproperty string ItemModelScatterDataProxy::rotationRole * - * Defines the item model role to map into item rotation. + * The item model role to map into item rotation. * The model may supply the value for rotation as either variant that is directly convertible * to \l quaternion, or as one of the string representations: \c{"scalar,x,y,z"} or * \c{"@angle,x,y,z"}. The first format will construct the \l quaternion directly with given values, @@ -125,8 +125,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty regExp ItemModelScatterDataProxy::xPosRolePattern * - * When set, a search and replace is done on the value mapped by xPos role before it is used as - * a item position value. This property specifies the regular expression to find the portion of the + * When set, a search and replace is done on the value mapped by the x position + * role before it is used as + * an item position value. This property specifies the regular expression to find the portion of the * mapped value to replace and xPosRoleReplace property contains the replacement string. * * \sa xPosRole, xPosRoleReplace @@ -135,8 +136,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty regExp ItemModelScatterDataProxy::yPosRolePattern * - * When set, a search and replace is done on the value mapped by yPos role before it is used as - * a item position value. This property specifies the regular expression to find the portion of the + * When set, a search and replace is done on the value mapped by the y position + * role before it is used as + * an item position value. This property specifies the regular expression to find the portion of the * mapped value to replace and yPosRoleReplace property contains the replacement string. * * \sa yPosRole, yPosRoleReplace @@ -145,8 +147,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty regExp ItemModelScatterDataProxy::zPosRolePattern * - * When set, a search and replace is done on the value mapped by zPos role before it is used as - * a item position value. This property specifies the regular expression to find the portion of the + * When set, a search and replace is done on the value mapped by the z position + * role before it is used as + * an item position value. This property specifies the regular expression to find the portion of the * mapped value to replace and zPosRoleReplace property contains the replacement string. * * \sa zPosRole, zPosRoleReplace @@ -154,8 +157,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty regExp ItemModelScatterDataProxy::rotationRolePattern - * When set, a search and replace is done on the value mapped by rotation role before it is used - * as a item rotation. This property specifies the regular expression to find the portion + * When set, a search and replace is done on the value mapped by the rotation + * role before it is used + * as item rotation. This property specifies the regular expression to find the portion * of the mapped value to replace and rotationRoleReplace property contains the replacement string. * * \sa rotationRole, rotationRoleReplace @@ -165,7 +169,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \qmlproperty string ItemModelScatterDataProxy::xPosRoleReplace * * This property defines the replace content to be used in conjunction with xPosRolePattern. - * Defaults to empty string. For more information on how the search and replace using regular + * Defaults to an empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. * @@ -176,7 +180,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \qmlproperty string ItemModelScatterDataProxy::yPosRoleReplace * * This property defines the replace content to be used in conjunction with yPosRolePattern. - * Defaults to empty string. For more information on how the search and replace using regular + * Defaults to an empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. * @@ -187,7 +191,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \qmlproperty string ItemModelScatterDataProxy::zPosRoleReplace * * This property defines the replace content to be used in conjunction with zPosRolePattern. - * Defaults to empty string. For more information on how the search and replace using regular + * Defaults to an empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. * @@ -197,7 +201,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty string ItemModelScatterDataProxy::rotationRoleReplace * This property defines the replace content to be used in conjunction with rotationRolePattern. - * Defaults to empty string. For more information on how the search and replace using regular + * Defaults to an empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. * @@ -277,8 +281,12 @@ QItemModelScatterDataProxy::~QItemModelScatterDataProxy() /*! * \property QItemModelScatterDataProxy::itemModel * - * Defines the item model. Does not take ownership of the model, but does connect to it to listen for - * changes. + * \brief The item model to use as a data source for a 3D scatter series. + */ + +/*! + * Sets \a itemModel as the item model for Q3DScatter. Does not take + * ownership of the model, but does connect to it to listen for changes. */ void QItemModelScatterDataProxy::setItemModel(QAbstractItemModel *itemModel) { @@ -293,7 +301,7 @@ QAbstractItemModel *QItemModelScatterDataProxy::itemModel() const /*! * \property QItemModelScatterDataProxy::xPosRole * - * Defines the item model role to map into X position. + * \brief The item model role to map into the X position. */ void QItemModelScatterDataProxy::setXPosRole(const QString &role) { @@ -311,7 +319,7 @@ QString QItemModelScatterDataProxy::xPosRole() const /*! * \property QItemModelScatterDataProxy::yPosRole * - * Defines the item model role to map into Y position. + * \brief The item model role to map into the Y position. */ void QItemModelScatterDataProxy::setYPosRole(const QString &role) { @@ -329,7 +337,7 @@ QString QItemModelScatterDataProxy::yPosRole() const /*! * \property QItemModelScatterDataProxy::zPosRole * - * Defines the item model role to map into Z position. + * \brief The item model role to map into the Z position. */ void QItemModelScatterDataProxy::setZPosRole(const QString &role) { @@ -347,7 +355,7 @@ QString QItemModelScatterDataProxy::zPosRole() const /*! * \property QItemModelScatterDataProxy::rotationRole * - * Defines the item model role to map into item rotation. + * \brief The item model role to map into item rotation. * * The model may supply the value for rotation as either variant that is directly convertible * to QQuaternion, or as one of the string representations: \c{"scalar,x,y,z"} or \c{"@angle,x,y,z"}. @@ -370,8 +378,10 @@ QString QItemModelScatterDataProxy::rotationRole() const /*! * \property QItemModelScatterDataProxy::xPosRolePattern * - * When set, a search and replace is done on the value mapped by xPos role before it is used as - * a item position value. This property specifies the regular expression to find the portion of the + * \brief Whether search and replace is done on the value mapped by the x + * position role before it is used as an item position value. + * + * This property specifies the regular expression to find the portion of the * mapped value to replace and xPosRoleReplace property contains the replacement string. * * \sa xPosRole, xPosRoleReplace @@ -392,8 +402,10 @@ QRegExp QItemModelScatterDataProxy::xPosRolePattern() const /*! * \property QItemModelScatterDataProxy::yPosRolePattern * - * When set, a search and replace is done on the value mapped by yPos role before it is used as - * a item position value. This property specifies the regular expression to find the portion of the + * \brief Whether a search and replace is done on the value mapped by the + * y position role before it is used as an item position value. + * + * This property specifies the regular expression to find the portion of the * mapped value to replace and yPosRoleReplace property contains the replacement string. * * \sa yPosRole, yPosRoleReplace @@ -414,8 +426,10 @@ QRegExp QItemModelScatterDataProxy::yPosRolePattern() const /*! * \property QItemModelScatterDataProxy::zPosRolePattern * - * When set, a search and replace is done on the value mapped by zPos role before it is used as - * a item position value. This property specifies the regular expression to find the portion of the + * \brief Whether a search and replace is done on the value mapped by the z + * position role before it is used as an item position value. + * + * This property specifies the regular expression to find the portion of the * mapped value to replace and zPosRoleReplace property contains the replacement string. * * \sa zPosRole, zPosRoleReplace @@ -436,8 +450,10 @@ QRegExp QItemModelScatterDataProxy::zPosRolePattern() const /*! * \property QItemModelScatterDataProxy::rotationRolePattern * - * When set, a search and replace is done on the value mapped by rotation role before it is used - * as a item rotation. This property specifies the regular expression to find the portion + * \brief Whether a search and replace is done on the value mapped by the + * rotation role before it is used as item rotation. + * + * This property specifies the regular expression to find the portion * of the mapped value to replace and rotationRoleReplace property contains the replacement string. * * \sa rotationRole, rotationRoleReplace @@ -458,8 +474,10 @@ QRegExp QItemModelScatterDataProxy::rotationRolePattern() const /*! * \property QItemModelScatterDataProxy::xPosRoleReplace * - * This property defines the replace content to be used in conjunction with xPosRolePattern. - * Defaults to empty string. For more information on how the search and replace using regular + * \brief The replace content to be used in conjunction with the x position role + * pattern. + * + * Defaults to an empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. * @@ -481,8 +499,10 @@ QString QItemModelScatterDataProxy::xPosRoleReplace() const /*! * \property QItemModelScatterDataProxy::yPosRoleReplace * - * This property defines the replace content to be used in conjunction with yPosRolePattern. - * Defaults to empty string. For more information on how the search and replace using regular + * \brief The replace content to be used in conjunction with the y position role + * pattern. + * + * Defaults to an empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. * @@ -504,8 +524,10 @@ QString QItemModelScatterDataProxy::yPosRoleReplace() const /*! * \property QItemModelScatterDataProxy::zPosRoleReplace * - * This property defines the replace content to be used in conjunction with zPosRolePattern. - * Defaults to empty string. For more information on how the search and replace using regular + * \brief The replace content to be used in conjunction with the z position role + * pattern. + * + * Defaults to an empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. * @@ -527,8 +549,10 @@ QString QItemModelScatterDataProxy::zPosRoleReplace() const /*! * \property QItemModelScatterDataProxy::rotationRoleReplace * - * This property defines the replace content to be used in conjunction with rotationRolePattern. - * Defaults to empty string. For more information on how the search and replace using regular + * \brief The replace content to be used in conjunction with the rotation role + * pattern. + * + * Defaults to an empty string. For more information on how the search and replace using regular * expressions works, see QString::replace(const QRegExp &rx, const QString &after) * function documentation. * diff --git a/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp b/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp index d2f63a94..47230326 100644 --- a/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp +++ b/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp @@ -101,10 +101,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \inherits SurfaceDataProxy * \brief Proxy class for presenting data in item models with Surface3D. * - * This type allows you to use AbstractItemModel derived models as a data source for Surface3D. + * This type allows you to use \c AbstractItemModel derived models as a data + * source for Surface3D. * * Data is resolved asynchronously whenever the mapping or the model changes. - * QSurfaceDataProxy::arrayReset() is emitted when the data has been resolved. * * For ItemModelSurfaceDataProxy enums, see \l{QItemModelSurfaceDataProxy::MultiMatchBehavior}. * @@ -141,7 +141,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty string ItemModelSurfaceDataProxy::xPosRole * The item model role to map to the X position. If this role is not defined, columnRole is - * used to determine the X-coordinate value of the resolved \l{QSurfaceDataItem} + * used to determine the X-coordinate value of the resolved \c QSurfaceDataItem * items. */ @@ -153,7 +153,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty string ItemModelSurfaceDataProxy::zPosRole * The item model role to map to the Z position. If this role is not defined, rowRole is - * used to determine the Z-coordinate value of resolved \l{QSurfaceDataItem} + * used to determine the Z-coordinate value of the resolved \c QSurfaceDataItem * items. */ diff --git a/src/datavisualization/data/qscatter3dseries.cpp b/src/datavisualization/data/qscatter3dseries.cpp index 54873485..1557a6c3 100644 --- a/src/datavisualization/data/qscatter3dseries.cpp +++ b/src/datavisualization/data/qscatter3dseries.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -35,11 +35,12 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QScatter3DSeries * \inmodule QtDataVisualization - * \brief Base series class for Q3DScatter. + * \brief The QScatter3DSeries class represents a data series in a 3D scatter + * graph. * \since QtDataVisualization 1.0 * - * QScatter3DSeries manages the series specific visual elements, as well as series data - * (via data proxy). + * This class manages the series specific visual elements, as well as the series + * data (via a data proxy). * * If no data proxy is set explicitly for the series, the series creates a default * proxy. Setting another proxy will destroy the existing proxy and all data added to it. @@ -47,20 +48,23 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * QScatter3DSeries supports the following format tags for QAbstract3DSeries::setItemLabelFormat(): * \table * \row - * \li @xTitle \li Title from X axis + * \li @xTitle \li Title from x-axis * \row - * \li @yTitle \li Title from Y axis + * \li @yTitle \li Title from y-axis * \row - * \li @zTitle \li Title from Z axis + * \li @zTitle \li Title from z-axis * \row - * \li @xLabel \li Item value formatted using the same format the X axis attached to the graph uses, - * see \l{QValue3DAxis::setLabelFormat()} for more information. + * \li @xLabel \li Item value formatted using the format of the x-axis. + * For more information, see + * \l{QValue3DAxis::setLabelFormat()}. * \row - * \li @yLabel \li Item value formatted using the same format the Y axis attached to the graph uses, - * see \l{QValue3DAxis::setLabelFormat()} for more information. + * \li @yLabel \li Item value formatted using the format of the y-axis. + * For more information, see + * \l{QValue3DAxis::setLabelFormat()}. * \row - * \li @zLabel \li Item value formatted using the same format the Z axis attached to the graph uses, - * see \l{QValue3DAxis::setLabelFormat()} for more information. + * \li @zLabel \li Item value formatted using the format of the z-axis. + * For more information, see + * \l{QValue3DAxis::setLabelFormat()}. * \row * \li @seriesName \li Name of the series * \endtable @@ -78,12 +82,12 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QScatter3DSeries * \inherits Abstract3DSeries - * \brief Base series type for Scatter3D. + * \brief Represents a data series in a 3D scatter graph. * - * This type manages the series specific visual elements, as well as series data - * (via data proxy). + * This type manages the series specific visual elements, as well as the series + * data (via a data proxy). * - * For more complete description, see QScatter3DSeries. + * For a more complete description, see QScatter3DSeries. * * \sa {Qt Data Visualization Data Handling} */ @@ -91,17 +95,17 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty ScatterDataProxy Scatter3DSeries::dataProxy * - * This property holds the active data \a proxy. The series assumes ownership of any proxy set to - * it and deletes any previously set proxy when a new one is added. The \a proxy cannot be null or - * set to another series. + * Sets the active data proxy. The series assumes ownership of any proxy set to + * it and deletes any previously set proxy when a new one is added. The proxy + * cannot be null or set to another series. */ /*! * \qmlproperty int Scatter3DSeries::selectedItem * - * Selects an item at the \a index. The \a index is the index in the data array of the series. + * The item that is selected at the index in the data array of the series. * Only one item can be selected at a time. - * To clear selection from this series, set invalidSelectionIndex as the \a index. + * To clear selection from this series, invalidSelectionIndex is set as the index. * If this series is added to a graph, the graph can adjust the selection according to user * interaction or if it becomes invalid. Selecting an item on another added series will also * clear the selection. @@ -114,21 +118,22 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty float Scatter3DSeries::itemSize * - * Set item size for the series. Size must be between 0.0 and 1.0. Setting the size to 0.0 - * causes item size to be automatically scaled based on combined item count in all the series for - * the graph. Preset default is \c 0.0. + * Sets the item size for the series. The size must be between \c 0.0 and + * \c 1.0. Setting the size to \c 0.0 causes the item size to be automatically + * scaled based on the total number of items in all the series for the graph. + * The preset default is \c 0.0. */ /*! * \qmlproperty int Scatter3DSeries::invalidSelectionIndex - * A constant property providing an invalid index for selection. Set this index to - * selectedItem property if you want to clear the selection from this series. + * A constant property providing an invalid index for selection. This index is + * set to the selectedItem property to clear the selection from this series. * * \sa AbstractGraph3D::clearSelection() */ /*! - * Constructs QScatter3DSeries with the given \a parent. + * Constructs a scatter 3D series with the parent \a parent. */ QScatter3DSeries::QScatter3DSeries(QObject *parent) : QAbstract3DSeries(new QScatter3DSeriesPrivate(this), parent) @@ -138,7 +143,8 @@ QScatter3DSeries::QScatter3DSeries(QObject *parent) : } /*! - * Constructs QScatter3DSeries with the given \a dataProxy and the \a parent. + * Constructs a scatter 3D series with the data proxy \a dataProxy and the + * parent \a parent. */ QScatter3DSeries::QScatter3DSeries(QScatterDataProxy *dataProxy, QObject *parent) : QAbstract3DSeries(new QScatter3DSeriesPrivate(this), parent) @@ -155,7 +161,7 @@ QScatter3DSeries::QScatter3DSeries(QScatter3DSeriesPrivate *d, QObject *parent) } /*! - * Destroys QScatter3DSeries. + * Deletes the scatter 3D series. */ QScatter3DSeries::~QScatter3DSeries() { @@ -164,9 +170,14 @@ QScatter3DSeries::~QScatter3DSeries() /*! * \property QScatter3DSeries::dataProxy * - * This property holds the active data \a proxy. The series assumes ownership of any proxy set to - * it and deletes any previously set proxy when a new one is added. The \a proxy cannot be null or - * set to another series. + * \brief The active data proxy. + */ + +/*! + * Sets the active data proxy for the series to \a proxy. The series assumes + * ownership of any proxy set to it and deletes any previously set proxy when + * a new one is added. The \a proxy argument cannot be null or set to another + * series. */ void QScatter3DSeries::setDataProxy(QScatterDataProxy *proxy) { @@ -181,12 +192,18 @@ QScatterDataProxy *QScatter3DSeries::dataProxy() const /*! * \property QScatter3DSeries::selectedItem * - * Selects an item at the \a index. The \a index is the index in the data array of the series. + * \brief The item that is selected in the series. + */ + +/*! + * Selects the item at the index \a index in the data array of the series. * Only one item can be selected at a time. - * To clear selection from this series, set invalidSelectionIndex() as the \a index. + * + * To clear selection from this series, invalidSelectionIndex() is set as \a index. * If this series is added to a graph, the graph can adjust the selection according to user * interaction or if it becomes invalid. Selecting an item on another added series will also * clear the selection. + * * Removing items from or inserting items to the series before the selected item * will adjust the selection so that the same item will stay selected. * @@ -209,9 +226,13 @@ int QScatter3DSeries::selectedItem() const /*! * \property QScatter3DSeries::itemSize * - * Set item \a size for the series. Size must be between 0.0f and 1.0f. Setting the size to 0.0f - * causes item size to be automatically scaled based on combined item count in all the series for - * the graph. Preset default is \c 0.0f. + * \brief Item size for the series. + * + * The size must be between \c 0.0f and \c 1.0f. Setting the size to \c 0.0f + * causes the item size to be automatically scaled based on the total number of + * items in all the series for the graph. + * + * The preset default is \c 0.0f. */ void QScatter3DSeries::setItemSize(float size) { @@ -229,8 +250,8 @@ float QScatter3DSeries::itemSize() const } /*! - * \return an invalid index for selection. Set this index to selectedItem property if you - * want to clear the selection from this series. + * Returns an invalid index for selection. This index is set to the selectedItem + * property to clear the selection from this series. * * \sa QAbstract3DGraph::clearSelection() */ diff --git a/src/datavisualization/data/qscatterdataitem.cpp b/src/datavisualization/data/qscatterdataitem.cpp index 50fac08d..12ea47af 100644 --- a/src/datavisualization/data/qscatterdataitem.cpp +++ b/src/datavisualization/data/qscatterdataitem.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -38,14 +38,15 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * graphs. * \since QtDataVisualization 1.0 * - * A QScatterDataItem holds data for a single rendered item in a scatter graph. - * Scatter data proxies parse data into QScatterDataItem instances for visualizing. + * A scatter data item holds the data for a single rendered item in a scatter + * graph. Scatter data proxies parse data into QScatterDataItem instances for + * visualization. * * \sa QScatterDataProxy, {Qt Data Visualization C++ Classes} */ /*! - * Constructs QScatterDataItem. + * Constructs a scatter data item. */ QScatterDataItem::QScatterDataItem() : d_ptr(0) // private data doesn't exist by default (optimization) @@ -54,7 +55,7 @@ QScatterDataItem::QScatterDataItem() } /*! - * Constructs QScatterDataItem with \a position. + * Constructs a scatter data item at the position \a position. */ QScatterDataItem::QScatterDataItem(const QVector3D &position) : d_ptr(0), @@ -63,7 +64,8 @@ QScatterDataItem::QScatterDataItem(const QVector3D &position) } /*! - * Constructs QScatterDataItem with \a position and \a rotation. + * Constructs a scatter data item at the position \a position with the rotation + * \a rotation. */ QScatterDataItem::QScatterDataItem(const QVector3D &position, const QQuaternion &rotation) : d_ptr(0), @@ -81,7 +83,7 @@ QScatterDataItem::QScatterDataItem(const QScatterDataItem &other) } /*! - * Destroys QScatterDataItem. + * Deletes a scatter data item. */ QScatterDataItem::~QScatterDataItem() { @@ -105,56 +107,56 @@ QScatterDataItem &QScatterDataItem::operator=(const QScatterDataItem &other) /*! * \fn void QScatterDataItem::setPosition(const QVector3D &pos) - * Sets position \a pos to this data item. + * Sets the position \a pos for this data item. */ /*! * \fn QVector3D QScatterDataItem::position() const - * \return position of this data item. + * Returns the position of this data item. */ /*! * \fn void QScatterDataItem::setRotation(const QQuaternion &rot) - * Sets rotation \a rot to this data item. - * The \a rot should be a normalized QQuaternion. - * If the series also has rotation, item and series rotations are multiplied together. + * Sets the rotation \a rot for this data item. + * The value of \a rot should be a normalized QQuaternion. + * If the series also has rotation, item rotation is multiplied by it. * Defaults to no rotation. */ /*! * \fn QQuaternion QScatterDataItem::rotation() const - * \return rotation of this data item. + * Returns the rotation of this data item. * \sa setRotation() */ /*! * \fn void QScatterDataItem::setX(float value) - * Sets the X component of the item position to the \a value. + * Sets the x-coordinate of the item position to the value \a value. */ /*! * \fn void QScatterDataItem::setY(float value) - * Sets the Y component of the item position to the \a value. + * Sets the y-coordinate of the item position to the value \a value. */ /*! * \fn void QScatterDataItem::setZ(float value) - * Sets the Z component of the item position to the \a value. + * Sets the z-coordinate of the item position to the value \a value. */ /*! * \fn float QScatterDataItem::x() const - * \return the X component of the position of this data item. + * Returns the x-coordinate of the position of this data item. */ /*! * \fn float QScatterDataItem::y() const - * \return the Y component of the position of this data item. + * Returns the y-coordinate of the position of this data item. */ /*! * \fn float QScatterDataItem::z() const - * \return the Z component of the position of this data item. + * Returns the z-coordinate of the position of this data item. */ /*! diff --git a/src/datavisualization/data/qscatterdataproxy.cpp b/src/datavisualization/data/qscatterdataproxy.cpp index 1fe5b3fc..3d81a641 100644 --- a/src/datavisualization/data/qscatterdataproxy.cpp +++ b/src/datavisualization/data/qscatterdataproxy.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -36,12 +36,15 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QScatterDataProxy * \inmodule QtDataVisualization - * \brief Base proxy class for Q3DScatter. + * \brief The QScatterDataProxy class is the data proxy for 3D scatter graphs. * \since QtDataVisualization 1.0 * - * QScatterDataProxy handles adding, inserting, changing, and removing data items. + * A scatter data proxy handles adding, inserting, changing, and removing data + * items. * - * QScatterDataProxy takes ownership of all QScatterDataArrays and QScatterDataItems passed to it. + * QScatterDataProxy takes ownership of all + * QtDataVisualization::QScatterDataArray and QScatterDataItem objects passed to + * it. * * \sa {Qt Data Visualization Data Handling} */ @@ -50,7 +53,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \typedef QtDataVisualization::QScatterDataArray * \relates QScatterDataProxy * - * A vector of \l {QScatterDataItem}s. + * A vector of \l {QScatterDataItem} objects. */ /*! @@ -60,20 +63,18 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QScatterDataProxy * \inherits AbstractDataProxy - * \brief Base proxy class for Scatter3D. + * \brief The data proxy for 3D scatter graphs. * * This type handles adding, inserting, changing, and removing data items. * * This type is uncreatable, but contains properties that are exposed via subtypes. * - * For more complete description, see QScatterDataProxy. - * * \sa ItemModelScatterDataProxy, {Qt Data Visualization Data Handling} */ /*! * \qmlproperty int ScatterDataProxy::itemCount - * Item count in the array. + * The number of items in the array. */ /*! @@ -99,7 +100,7 @@ QScatterDataProxy::QScatterDataProxy(QScatterDataProxyPrivate *d, QObject *paren } /*! - * Destroys QScatterDataProxy. + * Deletes the scatter data proxy. */ QScatterDataProxy::~QScatterDataProxy() { @@ -108,7 +109,7 @@ QScatterDataProxy::~QScatterDataProxy() /*! * \property QScatterDataProxy::series * - * The series this proxy is attached to. + * \brief The series this proxy is attached to. */ QScatter3DSeries *QScatterDataProxy::series() const { @@ -116,9 +117,10 @@ QScatter3DSeries *QScatterDataProxy::series() const } /*! - * Takes ownership of the \a newArray. Clears the existing array if the \a newArray is - * different from the existing array. If it's the same array, this just triggers arrayReset() - * signal. + * Takes ownership of the array \a newArray. Clears the existing array if the + * new array differs from it. If the arrays are the same, this function + * just triggers the arrayReset() signal. + * * Passing a null array deletes the old array and creates a new empty array. */ void QScatterDataProxy::resetArray(QScatterDataArray *newArray) @@ -131,7 +133,7 @@ void QScatterDataProxy::resetArray(QScatterDataArray *newArray) } /*! - * Changes a single item at \a index with \a item. + * Replaces the item at the position \a index with the item \a item. */ void QScatterDataProxy::setItem(int index, const QScatterDataItem &item) { @@ -140,7 +142,8 @@ void QScatterDataProxy::setItem(int index, const QScatterDataItem &item) } /*! - * Changes items starting from \a index with \a items. + * Replaces the items starting from the position \a index with the items + * specified by \a items. */ void QScatterDataProxy::setItems(int index, const QScatterDataArray &items) { @@ -149,9 +152,9 @@ void QScatterDataProxy::setItems(int index, const QScatterDataArray &items) } /*! - * Adds a single \a item to the end of the array. + * Adds the item \a item to the end of the array. * - * \return index of the added item. + * Returns the index of the added item. */ int QScatterDataProxy::addItem(const QScatterDataItem &item) { @@ -162,9 +165,9 @@ int QScatterDataProxy::addItem(const QScatterDataItem &item) } /*! - * Adds \a items to the end of the array. + * Adds the items specified by \a items to the end of the array. * - * \return index of the first added item. + * Returns the index of the first added item. */ int QScatterDataProxy::addItems(const QScatterDataArray &items) { @@ -175,8 +178,8 @@ int QScatterDataProxy::addItems(const QScatterDataArray &items) } /*! - * Inserts a single \a item to \a index. If index is equal to data array size, item is added to - * the array. + * Inserts the item \a item to the position \a index. If the index is equal to + * the data array size, the item is added to the array. */ void QScatterDataProxy::insertItem(int index, const QScatterDataItem &item) { @@ -186,7 +189,8 @@ void QScatterDataProxy::insertItem(int index, const QScatterDataItem &item) } /*! - * Inserts \a items to \a index. If index is equal to data array size, items are added to the array. + * Inserts the items specified by \a items to the position \a index. If the + * index is equal to data array size, the items are added to the array. */ void QScatterDataProxy::insertItems(int index, const QScatterDataArray &items) { @@ -196,7 +200,8 @@ void QScatterDataProxy::insertItems(int index, const QScatterDataArray &items) } /*! - * Removes \a removeCount items starting from \a index. Attempting to remove items past the end of + * Removes the number of items specified by \a removeCount starting at the + * position \a index. Attempting to remove items past the end of * the array does nothing. */ void QScatterDataProxy::removeItems(int index, int removeCount) @@ -212,7 +217,7 @@ void QScatterDataProxy::removeItems(int index, int removeCount) /*! * \property QScatterDataProxy::itemCount * - * \return item count in the array. + * \brief The number of items in the array. */ int QScatterDataProxy::itemCount() const { @@ -220,7 +225,7 @@ int QScatterDataProxy::itemCount() const } /*! - * \return pointer to the data array. + * Returns the pointer to the data array. */ const QScatterDataArray *QScatterDataProxy::array() const { @@ -228,8 +233,8 @@ const QScatterDataArray *QScatterDataProxy::array() const } /*! - * \return pointer to the item at \a index. It is guaranteed to be valid only until next call - * that modifies data. + * Returns the pointer to the item at the index \a index. It is guaranteed to be + * valid only until the next call that modifies data. */ const QScatterDataItem *QScatterDataProxy::itemAt(int index) const { @@ -255,42 +260,46 @@ const QScatterDataProxyPrivate *QScatterDataProxy::dptrc() const /*! * \fn void QScatterDataProxy::arrayReset() * - * Emitted when data array is reset. - * If you change the whole array contents without calling resetArray(), you need to - * emit this signal yourself or the graph won't get updated. + * This signal is emitted when the data array is reset. + * If the contents of the whole array are changed without calling resetArray(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QScatterDataProxy::itemsAdded(int startIndex, int count) * - * Emitted when items have been added. Provides \a startIndex and \a count of items added. - * If you add items directly to the array without calling addItem() or addItems(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of items specified by \a count is + * added starting at the position \a startIndex. + * If items are added to the array without calling addItem() or addItems(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QScatterDataProxy::itemsChanged(int startIndex, int count) * - * Emitted when items have changed. Provides \a startIndex and \a count of changed items. - * If you change items directly in the array without calling setItem() or setItems(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of items specified by \a count is + * changed starting at the position \a startIndex. + * If items are changed in the array without calling setItem() or setItems(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QScatterDataProxy::itemsRemoved(int startIndex, int count) * - * Emitted when items have been removed. Provides \a startIndex and \a count of items removed. - * Index may be over current array size if removed from end. - * If you remove items directly from the array without calling removeItems(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of rows specified by \a count is + * removed starting at the position \a startIndex. + * The index may be larger than the current array size if items are removed from + * the end. If items are removed from the array without calling removeItems(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QScatterDataProxy::itemsInserted(int startIndex, int count) * - * Emitted when items have been inserted. Provides \a startIndex and \a count of inserted items. - * If you insert items directly into the array without calling insertItem() or insertItems(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of items specified by \a count is + * inserted starting at the position \a startIndex. + * If items are inserted into the array without calling insertItem() or + * insertItems(), this signal needs to be emitted to update the graph. */ // QScatterDataProxyPrivate diff --git a/src/datavisualization/data/qsurface3dseries.cpp b/src/datavisualization/data/qsurface3dseries.cpp index 2e8e121d..83d766bd 100644 --- a/src/datavisualization/data/qsurface3dseries.cpp +++ b/src/datavisualization/data/qsurface3dseries.cpp @@ -35,35 +35,39 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QSurface3DSeries * \inmodule QtDataVisualization - * \brief Base series class for Q3DSurface. + * \brief The QSurface3DSeries class represents a data series in a 3D surface + * graph. * \since QtDataVisualization 1.0 * - * QSurface3DSeries manages the series specific visual elements, as well as series data - * (via data proxy). + * This class manages the series specific visual elements, as well as the series + * data (via a data proxy). * * If no data proxy is set explicitly for the series, the series creates a default * proxy. Setting another proxy will destroy the existing proxy and all data added to it. * - * The object mesh set via QAbstract3DSeries::mesh property defines the selection - * pointer shape in surface series. + * The object mesh set via the QAbstract3DSeries::mesh property defines the selection + * pointer shape in a surface series. * * QSurface3DSeries supports the following format tags for QAbstract3DSeries::setItemLabelFormat(): * \table * \row - * \li @xTitle \li Title from X axis + * \li @xTitle \li Title from x-axis * \row - * \li @yTitle \li Title from Y axis + * \li @yTitle \li Title from y-axis * \row - * \li @zTitle \li Title from Z axis + * \li @zTitle \li Title from z-axis * \row - * \li @xLabel \li Item value formatted using the same format as the X axis attached to the graph uses, - * see \l{QValue3DAxis::setLabelFormat()} for more information. + * \li @xLabel \li Item value formatted using the format of the x-axis. + * For more information, see + * \l{QValue3DAxis::setLabelFormat()}. * \row - * \li @yLabel \li Item value formatted using the same format as the Y axis attached to the graph uses, - * see \l{QValue3DAxis::setLabelFormat()} for more information. + * \li @yLabel \li Item value formatted using the format of the y-axis. + * For more information, see + * \l{QValue3DAxis::setLabelFormat()}. * \row - * \li @zLabel \li Item value formatted using the same format as the Z axis attached to the graph uses, - * see \l{QValue3DAxis::setLabelFormat()} for more information. + * \li @zLabel \li Item value formatted using the format of the z-axis. + * For more information, see + * \l{QValue3DAxis::setLabelFormat()}. * \row * \li @seriesName \li Name of the series * \endtable @@ -81,14 +85,12 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QSurface3DSeries * \inherits Abstract3DSeries - * \brief Base series type for Surfaces3D. + * \brief Represents a data series in a 3D surface graph. * - * This type manages the series specific visual elements, as well as series data - * (via data proxy). + * This type manages the series specific visual elements, as well as the series + * data (via a data proxy). * - * For Surface3DSeries enums, see \l{QSurface3DSeries::DrawFlag}. - * - * For more complete description, see QSurface3DSeries. + * For a more complete description, see QSurface3DSeries. * * \sa {Qt Data Visualization Data Handling} */ @@ -96,20 +98,22 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty SurfaceDataProxy Surface3DSeries::dataProxy * - * This property holds the active data \a proxy. The series assumes ownership of any proxy set to - * it and deletes any previously set proxy when a new one is added. The \a proxy cannot be null or + * The active data proxy. The series assumes ownership of any proxy set to + * it and deletes any previously set proxy when a new one is added. The proxy cannot be null or * set to another series. */ /*! * \qmlproperty point Surface3DSeries::selectedPoint * - * Selects a surface grid point in a \a position. The position is the (row, column) position in - * the data array of the series. + * Sets the surface grid point in the position specified by a row and a column + * in the data array of the series as selected. * Only one point can be selected at a time. - * To clear selection from this series, set invalidSelectionPosition as the \a position. + * + * To clear selection from this series, invalidSelectionPosition is set as the position. * If this series is added to a graph, the graph can adjust the selection according to user * interaction or if it becomes invalid. + * * Removing rows from or inserting rows to the series before the row of the selected point * will adjust the selection so that the same point will stay selected. * @@ -119,7 +123,8 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty point Surface3DSeries::invalidSelectionPosition * A constant property providing an invalid selection position. - * Set this to selectedPoint property to clear the selection from this series. + * This position is set to the selectedPoint property to clear the selection + * from this series. * * \sa AbstractGraph3D::clearSelection() */ @@ -127,42 +132,45 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty bool Surface3DSeries::flatShadingEnabled * - * Sets surface flat shading to \a enabled. It is preset to \c true by default. - * When disabled, the normals on the surface are interpolated making edges looking round. - * When enabled, the normals are kept same on a triangle making the color of the triangle solid. + * Sets surface flat shading to enabled. It is preset to \c true by default. + * When disabled, the normals on the surface are interpolated making the edges look round. + * When enabled, the normals are kept the same on a triangle making the color of the triangle solid. * This makes the data more readable from the model. * \note Flat shaded surfaces require at least GLSL version 1.2 with GL_EXT_gpu_shader4 extension. - * The value of flatShadingSupported property indicates if flat shading is supported at runtime. + * The value of the flatShadingSupported property indicates whether flat shading + * is supported at runtime. */ /*! * \qmlproperty bool Surface3DSeries::flatShadingSupported * - * Flat shading for surfaces requires at least GLSL version 1.2 with GL_EXT_gpu_shader4 extension. - * If true, flat shading for surfaces is supported by current system. - * \note This read-only property is set to its correct value after first render pass. - * Before then it is always true. + * Indicates whether flat shading for surfaces is supported by the current system. + * It requires at least GLSL version 1.2 with GL_EXT_gpu_shader4 extension. + * + * \note This read-only property is set to its correct value after the first + * render pass. Until then it is always \c true. */ /*! * \qmlproperty DrawFlag Surface3DSeries::drawMode * - * Sets the drawing \a mode to one of \l{QSurface3DSeries::DrawFlag}{Surface3DSeries.DrawFlag}. + * Sets the drawing mode to one of \l{QSurface3DSeries::DrawFlag}{Surface3DSeries.DrawFlag}. * Clearing all flags is not allowed. */ /*! * \qmlproperty string Surface3DSeries::textureFile * - * Holds the texture file name for the surface texture. To clear the texture, set empty - * file name. + * The texture file name for the surface texture. To clear the texture, an empty + * file name is set. */ /*! * \enum QSurface3DSeries::DrawFlag * - * Drawing mode of the surface. Values of this enumeration can be combined with OR operator. + * The drawing mode of the surface. Values of this enumeration can be combined + * with the OR operator. * * \value DrawWireframe * Only the grid is drawn. @@ -173,7 +181,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION */ /*! - * Constructs QSurface3DSeries with the given \a parent. + * Constructs a surface 3D series with the parent \a parent. */ QSurface3DSeries::QSurface3DSeries(QObject *parent) : QAbstract3DSeries(new QSurface3DSeriesPrivate(this), parent) @@ -183,7 +191,8 @@ QSurface3DSeries::QSurface3DSeries(QObject *parent) : } /*! - * Constructs QSurface3DSeries with the given \a dataProxy and the \a parent. + * Constructs a surface 3D series with the data proxy \a dataProxy and the + * parent \a parent. */ QSurface3DSeries::QSurface3DSeries(QSurfaceDataProxy *dataProxy, QObject *parent) : QAbstract3DSeries(new QSurface3DSeriesPrivate(this), parent) @@ -200,7 +209,7 @@ QSurface3DSeries::QSurface3DSeries(QSurface3DSeriesPrivate *d, QObject *parent) } /*! - * Destroys QSurface3DSeries. + * Deletes the surface 3D series. */ QSurface3DSeries::~QSurface3DSeries() { @@ -209,8 +218,10 @@ QSurface3DSeries::~QSurface3DSeries() /*! * \property QSurface3DSeries::dataProxy * - * This property holds the active data \a proxy. The series assumes ownership of any proxy set to - * it and deletes any previously set proxy when a new one is added. The \a proxy cannot be null or + * \brief The active data proxy. + * + * The series assumes ownership of any proxy set to it and deletes any + * previously set proxy when a new one is added. The proxy cannot be null or * set to another series. */ void QSurface3DSeries::setDataProxy(QSurfaceDataProxy *proxy) @@ -226,12 +237,19 @@ QSurfaceDataProxy *QSurface3DSeries::dataProxy() const /*! * \property QSurface3DSeries::selectedPoint * - * Selects a surface grid point in a \a position. The position is the (row, column) position in - * the data array of the series. + * \brief The surface grid point that is selected in the series. + */ + +/*! + * Selects a surface grid point at the position \a position in the data array of + * the series specified by a row and a column. + * * Only one point can be selected at a time. - * To clear selection from this series, set invalidSelectionPosition() as the \a position. + * + * To clear selection from this series, invalidSelectionPosition() is set as \a position. * If this series is added to a graph, the graph can adjust the selection according to user * interaction or if it becomes invalid. + * * Removing rows from or inserting rows to the series before the row of the selected point * will adjust the selection so that the same point will stay selected. * @@ -252,8 +270,8 @@ QPoint QSurface3DSeries::selectedPoint() const } /*! - * \return a QPoint signifying an invalid selection position. Set this to selectedPoint property - * to clear the selection from this series. + * Returns the QPoint signifying an invalid selection position. This is set to + * the selectedPoint property to clear the selection from this series. * * \sa QAbstract3DGraph::clearSelection() */ @@ -265,12 +283,16 @@ QPoint QSurface3DSeries::invalidSelectionPosition() /*! * \property QSurface3DSeries::flatShadingEnabled * - * Sets surface flat shading to \a enabled. It is preset to \c true by default. - * When disabled, the normals on the surface are interpolated making edges looking round. - * When enabled, the normals are kept same on a triangle making the color of the triangle solid. + * \brief Whether surface flat shading is enabled. + * + * Preset to \c true by default. + * + * When disabled, the normals on the surface are interpolated making the edges look round. + * When enabled, the normals are kept the same on a triangle making the color of the triangle solid. * This makes the data more readable from the model. * \note Flat shaded surfaces require at least GLSL version 1.2 with GL_EXT_gpu_shader4 extension. - * The value of flatShadingSupported property indicates if flat shading is supported at runtime. + * The value of the flatShadingSupported property indicates whether flat shading + * is supported at runtime. */ void QSurface3DSeries::setFlatShadingEnabled(bool enabled) { @@ -287,10 +309,13 @@ bool QSurface3DSeries::isFlatShadingEnabled() const /*! * \property QSurface3DSeries::flatShadingSupported + * + * \brief Whether surface flat shading is supported by the current system. + * * Flat shading for surfaces requires at least GLSL version 1.2 with GL_EXT_gpu_shader4 extension. - * If true, flat shading for surfaces is supported by current system. - * \note This read-only property is set to its correct value after first render pass. - * Before then it is always true. + * If \c true, flat shading for surfaces is supported. + * \note This read-only property is set to its correct value after the first + * render pass. Until then it is always \c true. */ bool QSurface3DSeries::isFlatShadingSupported() const { @@ -303,7 +328,9 @@ bool QSurface3DSeries::isFlatShadingSupported() const /*! * \property QSurface3DSeries::drawMode * - * Sets the drawing \a mode to one of DrawFlag. Clearing all flags is not allowed. + * The drawing mode. + * + * Possible values are the values of DrawFlag. Clearing all flags is not allowed. */ void QSurface3DSeries::setDrawMode(DrawFlags mode) { @@ -321,8 +348,9 @@ QSurface3DSeries::DrawFlags QSurface3DSeries::drawMode() const /*! * \property QSurface3DSeries::texture * - * Set the \a texture as a QImage for the surface. To clear the texture, set empty - * QImage as texture. + * \brief The texture for the surface as a QImage. + * + * Setting an empty QImage clears the texture. */ void QSurface3DSeries::setTexture(const QImage &texture) { @@ -342,8 +370,9 @@ QImage QSurface3DSeries::texture() const /*! * \property QSurface3DSeries::textureFile * - * Holds the texture file name for the surface texture. To clear the texture, set empty - * file name. + * \brief The texture for the surface as a file. + * + * Setting an empty file name clears the texture. */ void QSurface3DSeries::setTextureFile(const QString &filename) { diff --git a/src/datavisualization/data/qsurfacedataitem.cpp b/src/datavisualization/data/qsurfacedataitem.cpp index 2d361904..a4aeb18d 100644 --- a/src/datavisualization/data/qsurfacedataitem.cpp +++ b/src/datavisualization/data/qsurfacedataitem.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -38,14 +38,15 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * graphs. * \since QtDataVisualization 1.0 * - * A QSurfaceDataItem holds data for a single vertex in surface graph. - * Surface data proxies parse data into QSurfaceDataItem instances for visualizing. + * A surface data item holds the data for a single vertex in a surface graph. + * Surface data proxies parse data into QSurfaceDataItem instances for + * visualization. * * \sa QSurfaceDataProxy, {Qt Data Visualization C++ Classes} */ /*! - * Constructs QSurfaceDataItem. + * Constructs a surface data item. */ QSurfaceDataItem::QSurfaceDataItem() : d_ptr(0) // private data doesn't exist by default (optimization) @@ -54,7 +55,7 @@ QSurfaceDataItem::QSurfaceDataItem() } /*! - * Constructs QSurfaceDataItem with \a position. + * Constructs a surface data item at the position \a position. */ QSurfaceDataItem::QSurfaceDataItem(const QVector3D &position) : d_ptr(0), @@ -71,7 +72,7 @@ QSurfaceDataItem::QSurfaceDataItem(const QSurfaceDataItem &other) } /*! - * Destroys QSurfaceDataItem. + * Deletes a surface data item. */ QSurfaceDataItem::~QSurfaceDataItem() { @@ -94,42 +95,42 @@ QSurfaceDataItem &QSurfaceDataItem::operator=(const QSurfaceDataItem &other) /*! * \fn void QSurfaceDataItem::setPosition(const QVector3D &pos) - * Sets position \a pos to this data item. + * Sets the position \a pos to this data item. */ /*! * \fn QVector3D QSurfaceDataItem::position() const - * \return position of this data item. + * Returns the position of this data item. */ /*! * \fn void QSurfaceDataItem::setX(float value) - * Sets the X component of the item position to the \a value. + * Sets the x-coordinate of the item position to the value \a value. */ /*! * \fn void QSurfaceDataItem::setY(float value) - * Sets the Y component of the item position to the \a value. + * Sets the y-coordinate of the item position to the value \a value. */ /*! * \fn void QSurfaceDataItem::setZ(float value) - * Sets the Z component of the item position to the \a value. + * Sets the z-coordinate of the item position to the value \a value. */ /*! * \fn float QSurfaceDataItem::x() const - * \return the X component of the position of this data item. + * Returns the x-coordinate of the position of this data item. */ /*! * \fn float QSurfaceDataItem::y() const - * \return the Y component of the position of this data item. + * Returns the y-coordinate of the position of this data item. */ /*! * \fn float QSurfaceDataItem::z() const - * \return the Z component of the position of this data item. + * Returns the z-coordinate of the position of this data item. */ /*! diff --git a/src/datavisualization/data/qsurfacedataproxy.cpp b/src/datavisualization/data/qsurfacedataproxy.cpp index fa7990b1..a5339e9d 100644 --- a/src/datavisualization/data/qsurfacedataproxy.cpp +++ b/src/datavisualization/data/qsurfacedataproxy.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Data Visualization module of the Qt Toolkit. @@ -36,38 +36,41 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QSurfaceDataProxy * \inmodule QtDataVisualization - * \brief Base proxy class for Q3DSurface. + * \brief The QSurfaceDataProxy class is the data proxy for a 3D surface graph. * \since QtDataVisualization 1.0 * - * QSurfaceDataProxy takes care of surface related data handling. The QSurfaceDataProxy handles the - * data in rows and for this it provides two auxiliary typedefs. QSurfaceDataArray is a QList for - * controlling the rows. For rows there is a QVector QSurfaceDataRow which contains QSurfaceDataItem - * objects. See Q3DSurface documentation and basic sample code there how to feed the data for the - * QSurfaceDataProxy. + * A surface data proxy handles surface related data in rows. For this it + * provides two auxiliary typedefs: QtDataVisualization::QSurfaceDataArray and + * QtDataVisualization::QSurfaceDataRow. \c QSurfaceDataArray is a QList that + * controls the rows. \c QSurfaceDataRow is a QVector that contains + * QSurfaceDataItem objects. For more information about how to feed the data to + * the proxy, see the sample code in the Q3DSurface documentation. * * All rows must have the same number of items. * - * QSurfaceDataProxy takes ownership of all QSurfaceDataRows passed to it, whether directly or - * in a QSurfaceDataArray container. - * If you use QSurfaceDataRow pointers to directly modify data after adding the array to the proxy, - * you must also emit proper signal to make the graph update. + * QSurfaceDataProxy takes ownership of all \c QSurfaceDataRow objects passed to + * it, whether directly or in a \c QSurfaceDataArray container. + * To use surface data row pointers to directly modify data after adding the + * array to the proxy, the appropriate signal must be emitted to update the + * graph. * - * To make a sensible surface, the X-value of each successive item in all rows must be + * To make a sensible surface, the x-value of each successive item in all rows must be * either ascending or descending throughout the row. - * Similarly, the Z-value of each successive item in all columns must be either ascending or + * Similarly, the z-value of each successive item in all columns must be either ascending or * descending throughout the column. * * \note Currently only surfaces with straight rows and columns are fully supported. Any row - * with items that do not have the exact same Z-value or any column with items that do not have - * the exact same X-value may get clipped incorrectly if the whole surface doesn't completely fit - * in the visible X or Z axis ranges. + * with items that do not have the exact same z-value or any column with items + * that do not have the exact same x-value may get clipped incorrectly if the + * whole surface does not completely fit within the visible x-axis or z-axis + * ranges. * * \note Surfaces with less than two rows or columns are not considered valid surfaces and will * not be rendered. * * \note On some environments, surfaces with a lot of visible vertices may not render, because * they exceed the per-draw vertex count supported by the graphics driver. - * This is mostly an issue on 32bit and/or OpenGL ES2 platforms. + * This is mostly an issue on 32-bit and OpenGL ES2 platforms. * * \sa {Qt Data Visualization Data Handling} */ @@ -76,14 +79,14 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \typedef QtDataVisualization::QSurfaceDataRow * \relates QSurfaceDataProxy * - * A vector of \l {QSurfaceDataItem}s. + * A vector of \l {QSurfaceDataItem} objects. */ /*! * \typedef QtDataVisualization::QSurfaceDataArray * \relates QSurfaceDataProxy * - * A list of pointers to \l {QSurfaceDataRow}s. + * A list of pointers to \l {QSurfaceDataRow} objects. */ /*! @@ -93,7 +96,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QSurfaceDataProxy * \inherits AbstractDataProxy - * \brief Base proxy class for Surface3D. + * \brief The data proxy for a 3D surface graph. * * This type handles surface data items. The data is arranged into rows and columns, and all rows must have * the same number of columns. @@ -107,12 +110,12 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty int SurfaceDataProxy::rowCount - * Number of the rows in the array. + * The number of rows in the data array. */ /*! * \qmlproperty int SurfaceDataProxy::columnCount - * Number of the columns in the array. + * The number of columns in the data array. */ /*! @@ -138,7 +141,7 @@ QSurfaceDataProxy::QSurfaceDataProxy(QSurfaceDataProxyPrivate *d, QObject *paren } /*! - * Destroys QSurfaceDataProxy. + * Deletes the surface data proxy. */ QSurfaceDataProxy::~QSurfaceDataProxy() { @@ -147,7 +150,7 @@ QSurfaceDataProxy::~QSurfaceDataProxy() /*! * \property QSurfaceDataProxy::series * - * The series this proxy is attached to. + * \brief The series this proxy is attached to. */ QSurface3DSeries *QSurfaceDataProxy::series() const { @@ -155,9 +158,10 @@ QSurface3DSeries *QSurfaceDataProxy::series() const } /*! - * Takes ownership of the \a newArray. Clears the existing array if the \a newArray is - * different from the existing array. If it's the same array, this just triggers arrayReset() - * signal. + * Takes ownership of the array \a newArray. Clears the existing array if the + * new array differs from it. If the arrays are the same, this function + * just triggers the arrayReset() signal. + * * Passing a null array deletes the old array and creates a new empty array. * All rows in \a newArray must be of same length. */ @@ -172,8 +176,9 @@ void QSurfaceDataProxy::resetArray(QSurfaceDataArray *newArray) } /*! - * Changes existing row by replacing a row at \a rowIndex with a new \a row. The \a row can be - * the same as the existing row already stored at the \a rowIndex. The new \a row must have + * Changes an existing row by replacing the row at the position \a rowIndex + * with the new row specified by \a row. The new row can be the same as the + * existing row already stored at the \a rowIndex. The new row must have * the same number of columns as the row it is replacing. */ void QSurfaceDataProxy::setRow(int rowIndex, QSurfaceDataRow *row) @@ -183,7 +188,8 @@ void QSurfaceDataProxy::setRow(int rowIndex, QSurfaceDataRow *row) } /*! - * Changes existing rows by replacing a rows starting at \a rowIndex with \a rows. + * Changes existing rows by replacing the rows starting at the position + * \a rowIndex with the new rows specifies by \a rows. * The rows in the \a rows array can be the same as the existing rows already * stored at the \a rowIndex. The new rows must have the same number of columns * as the rows they are replacing. @@ -195,7 +201,8 @@ void QSurfaceDataProxy::setRows(int rowIndex, const QSurfaceDataArray &rows) } /*! - * Changes a single item at \a rowIndex, \a columnIndex to the \a item. + * Changes a single item at the position specified by \a rowIndex and + * \a columnIndex to the item \a item. */ void QSurfaceDataProxy::setItem(int rowIndex, int columnIndex, const QSurfaceDataItem &item) { @@ -204,8 +211,9 @@ void QSurfaceDataProxy::setItem(int rowIndex, int columnIndex, const QSurfaceDat } /*! - * Changes a single item at \a position to the \a item. - * The X-value of \a position indicates the row and the Y-value indicates the column. + * Changes a single item at the position \a position to the item \a item. + * The x-value of \a position indicates the row and the y-value indicates the + * column. */ void QSurfaceDataProxy::setItem(const QPoint &position, const QSurfaceDataItem &item) { @@ -213,10 +221,10 @@ void QSurfaceDataProxy::setItem(const QPoint &position, const QSurfaceDataItem & } /*! - * Adds a new \a row to the end of array. The new \a row must have - * the same number of columns as the rows at the initial array. + * Adds the new row \a row to the end of an array. The new row must have + * the same number of columns as the rows in the initial array. * - * \return index of the added row. + * Returns the index of the added row. */ int QSurfaceDataProxy::addRow(QSurfaceDataRow *row) { @@ -227,10 +235,10 @@ int QSurfaceDataProxy::addRow(QSurfaceDataRow *row) } /*! - * Adds new \a rows to the end of array. The new rows must have the same number of columns - * as the rows at the initial array. + * Adds new \a rows to the end of an array. The new rows must have the same + * number of columns as the rows in the initial array. * - * \return index of the first added row. + * Returns the index of the first added row. */ int QSurfaceDataProxy::addRows(const QSurfaceDataArray &rows) { @@ -241,9 +249,10 @@ int QSurfaceDataProxy::addRows(const QSurfaceDataArray &rows) } /*! - * Inserts a new \a row into \a rowIndex. - * If rowIndex is equal to array size, rows are added to end of the array. The new \a row must have - * the same number of columns as the rows at the initial array. + * Inserts the new row \a row into \a rowIndex. + * If \a rowIndex is equal to the array size, the rows are added to the end of + * the array. The new row must have the same number of columns as the rows in + * the initial array. */ void QSurfaceDataProxy::insertRow(int rowIndex, QSurfaceDataRow *row) { @@ -254,8 +263,9 @@ void QSurfaceDataProxy::insertRow(int rowIndex, QSurfaceDataRow *row) /*! * Inserts new \a rows into \a rowIndex. - * If rowIndex is equal to array size, rows are added to end of the array. The new \a rows must have - * the same number of columns as the rows at the initial array. + * If \a rowIndex is equal to the array size, the rows are added to the end of + * the array. The new \a rows must have the same number of columns as the rows + * in the initial array. */ void QSurfaceDataProxy::insertRows(int rowIndex, const QSurfaceDataArray &rows) { @@ -265,7 +275,8 @@ void QSurfaceDataProxy::insertRows(int rowIndex, const QSurfaceDataArray &rows) } /*! - * Removes \a removeCount rows staring at \a rowIndex. Attempting to remove rows past the end of the + * Removes the number of rows specified by \a removeCount starting at the + * position \a rowIndex. Attempting to remove rows past the end of the * array does nothing. */ void QSurfaceDataProxy::removeRows(int rowIndex, int removeCount) @@ -278,7 +289,7 @@ void QSurfaceDataProxy::removeRows(int rowIndex, int removeCount) } /*! - * \return pointer to the data array. + * Returns the pointer to the data array. */ const QSurfaceDataArray *QSurfaceDataProxy::array() const { @@ -286,7 +297,8 @@ const QSurfaceDataArray *QSurfaceDataProxy::array() const } /*! - * \return pointer to the item at \a rowIndex, \a columnIndex. It is guaranteed to be valid only + * Returns the pointer to the item at the position specified by \a rowIndex and + * \a columnIndex. It is guaranteed to be valid only * until the next call that modifies data. */ const QSurfaceDataItem *QSurfaceDataProxy::itemAt(int rowIndex, int columnIndex) const @@ -299,9 +311,9 @@ const QSurfaceDataItem *QSurfaceDataProxy::itemAt(int rowIndex, int columnIndex) } /*! - * \return pointer to the item at \a position. The X-value of \a position indicates the row - * and the Y-value indicates the column. The item is guaranteed to be valid only - * until the next call that modifies data. + * Returns the pointer to the item at the position \a position. The x-value of + * \a position indicates the row and the y-value indicates the column. The item + * is guaranteed to be valid only until the next call that modifies data. */ const QSurfaceDataItem *QSurfaceDataProxy::itemAt(const QPoint &position) const { @@ -311,7 +323,7 @@ const QSurfaceDataItem *QSurfaceDataProxy::itemAt(const QPoint &position) const /*! * \property QSurfaceDataProxy::rowCount * - * \return number of rows in the data. + * \brief The number of rows in the data array. */ int QSurfaceDataProxy::rowCount() const { @@ -321,7 +333,7 @@ int QSurfaceDataProxy::rowCount() const /*! * \property QSurfaceDataProxy::columnCount * - * \return number of items in the columns. + * \brief The number of columns in the data array. */ int QSurfaceDataProxy::columnCount() const { @@ -350,50 +362,57 @@ const QSurfaceDataProxyPrivate *QSurfaceDataProxy::dptrc() const /*! * \fn void QSurfaceDataProxy::arrayReset() * - * Emitted when the data array is reset. - * If you change the whole array contents without calling resetArray(), you need to - * emit this signal yourself or the graph won't get updated. + * This signal is emitted when the data array is reset. + * If the contents of the whole array are changed without calling resetArray(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QSurfaceDataProxy::rowsAdded(int startIndex, int count) * - * Emitted when rows have been added. Provides \a startIndex and \a count of rows added. - * If you add rows directly to the array without calling addRow() or addRows(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of rows specified by \a count is + * added starting at the position \a startIndex. + * If rows are added to the array without calling addRow() or addRows(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QSurfaceDataProxy::rowsChanged(int startIndex, int count) * - * Emitted when rows have changed. Provides \a startIndex and \a count of changed rows. - * If you change rows directly in the array without calling setRow() or setRows(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of rows specified by \a count is + * changed starting at the position \a startIndex. + * If rows are changed in the array without calling setRow() or setRows(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QSurfaceDataProxy::rowsRemoved(int startIndex, int count) * - * Emitted when rows have been removed. Provides \a startIndex and \a count of rows removed. - * Index is the current array size if rows were removed from the end of the array. - * If you remove rows directly from the array without calling removeRows(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of rows specified by \a count is + * removed starting at the position \a startIndex. + * + * The index is the current array size if the rows were removed from the end of + * the array. If rows are removed from the array without calling removeRows(), + * this signal needs to be emitted to update the graph. */ /*! * \fn void QSurfaceDataProxy::rowsInserted(int startIndex, int count) * - * Emitted when rows have been inserted. Provides \a startIndex and \a count of inserted rows. - * If you insert rows directly into the array without calling insertRow() or insertRows(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the number of rows specified by \a count is + * inserted at the position \a startIndex. + * + * If rows are inserted into the array without calling insertRow() or + * insertRows(), this signal needs to be emitted to update the graph. */ /*! * \fn void QSurfaceDataProxy::itemChanged(int rowIndex, int columnIndex) * - * Emitted when an item has changed. Provides \a rowIndex and \a columnIndex of changed item. - * If you change an item directly in the array without calling setItem(), you - * need to emit this signal yourself or the graph won't get updated. + * This signal is emitted when the item at the position specified by \a rowIndex + * and \a columnIndex changes. + * If the item is changed in the array without calling setItem(), + * this signal needs to be emitted to update the graph. */ // QSurfaceDataProxyPrivate |