From 6725566ff329c2ec94b7f7acd017221587f7cd8d Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Tue, 4 Apr 2017 14:20:14 +0200 Subject: Doc: Edit data proxy documentation for grammar and style MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: Ibf26f40e53e8dab3cea717c6ca55e2568cb747e1 Reviewed-by: Tomi Korpipää --- src/datavisualization/data/qabstractdataproxy.cpp | 26 +-- src/datavisualization/data/qbardataproxy.cpp | 193 ++++++++++++---------- src/datavisualization/data/qscatterdataproxy.cpp | 80 +++++---- src/datavisualization/data/qsurfacedataproxy.cpp | 145 +++++++++------- 4 files changed, 249 insertions(+), 195 deletions(-) (limited to 'src/datavisualization/data') 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/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/qscatterdataproxy.cpp b/src/datavisualization/data/qscatterdataproxy.cpp index 8d1626cf..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,13 +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 QScatterDataArray and QScatterDataItem - * objects passed to it. + * QScatterDataProxy takes ownership of all + * QtDataVisualization::QScatterDataArray and QScatterDataItem objects passed to + * it. * * \sa {Qt Data Visualization Data Handling} */ @@ -51,7 +53,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \typedef QtDataVisualization::QScatterDataArray * \relates QScatterDataProxy * - * A vector of \l {QScatterDataItem}s. + * A vector of \l {QScatterDataItem} objects. */ /*! @@ -61,7 +63,7 @@ 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. * @@ -98,7 +100,7 @@ QScatterDataProxy::QScatterDataProxy(QScatterDataProxyPrivate *d, QObject *paren } /*! - * Destroys QScatterDataProxy. + * Deletes the scatter data proxy. */ QScatterDataProxy::~QScatterDataProxy() { @@ -115,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) @@ -130,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) { @@ -139,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) { @@ -148,7 +152,7 @@ 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. * * Returns the index of the added item. */ @@ -161,7 +165,7 @@ 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. * * Returns the index of the first added item. */ @@ -174,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) { @@ -185,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) { @@ -195,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) @@ -254,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/qsurfacedataproxy.cpp b/src/datavisualization/data/qsurfacedataproxy.cpp index 61abbe58..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. @@ -138,7 +141,7 @@ QSurfaceDataProxy::QSurfaceDataProxy(QSurfaceDataProxyPrivate *d, QObject *paren } /*! - * Destroys QSurfaceDataProxy. + * Deletes the surface data proxy. */ QSurfaceDataProxy::~QSurfaceDataProxy() { @@ -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,8 +221,8 @@ 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. * * Returns the index of the added row. */ @@ -227,8 +235,8 @@ 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. * * Returns the index of the first added row. */ @@ -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) @@ -286,7 +297,8 @@ const QSurfaceDataArray *QSurfaceDataProxy::array() const } /*! - * Returns the 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) } /*! - * Returns the 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 { @@ -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 -- cgit v1.2.3