diff options
| author | Liang Qi <liang.qi@qt.io> | 2017-04-21 11:08:17 +0200 |
|---|---|---|
| committer | Liang Qi <liang.qi@qt.io> | 2017-04-21 11:12:27 +0200 |
| commit | e7b022ec334ce6768c30402c1e17fe0a1e3a0bb0 (patch) | |
| tree | 72641f2dc53522ca1959ac8c1d06692303c3a17b | |
| parent | 5adf257bebf2df7f54b92fb724cd547dc58a1163 (diff) | |
| parent | 73ec35fa12a4b150670ea93d3021ca8e658063e1 (diff) | |
Merge remote-tracking branch 'origin/5.9' into dev
Conflicts:
.qmake.conf
Change-Id: Ibb41c2bb83df7e02696e27afe62e94ed059284ae
46 files changed, 2232 insertions, 1506 deletions
diff --git a/.qmake.conf b/.qmake.conf index 6f049d24..8ea914a7 100644 --- a/.qmake.conf +++ b/.qmake.conf @@ -1,5 +1,5 @@ load(qt_build_config) MODULE_VERSION = 5.10.0 - +CONFIG += warning_clean CMAKE_MODULE_TESTS=- diff --git a/src/datavisualization/axis/qabstract3daxis.cpp b/src/datavisualization/axis/qabstract3daxis.cpp index 90f93eb9..72754ac8 100644 --- a/src/datavisualization/axis/qabstract3daxis.cpp +++ b/src/datavisualization/axis/qabstract3daxis.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,10 +34,12 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QAbstract3DAxis * \inmodule QtDataVisualization - * \brief QAbstract3DAxis is base class for axes of a graph. + * \brief The QAbstract3DAxis class is a base class for the axes of a graph. * \since QtDataVisualization 1.0 * - * You should not need to use this class directly, but one of its subclasses instead. + * This class specifies the enumerations, properties, and functions shared by + * graph axes. It should not be used directly, but one of its subclasses should + * be used instead. * * \sa QCategory3DAxis, QValue3DAxis */ @@ -48,7 +50,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \since QtDataVisualization 1.0 * \ingroup datavisualization_qml * \instantiates QAbstract3DAxis - * \brief AbstractAxis3D is base type for axes of a graph. + * \brief A base type for the axes of a graph. * * This type is uncreatable, but contains properties that are exposed via subtypes. * @@ -83,16 +85,16 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \qmlproperty real AbstractAxis3D::min * * The minimum value on the axis. - * When setting this property the max is adjusted if necessary, to ensure that the range remains - * valid. + * When setting this property, the maximum value is adjusted if necessary, to + * ensure that the range remains valid. */ /*! * \qmlproperty real AbstractAxis3D::max * * The maximum value on the axis. - * When setting this property the min is adjusted if necessary, to ensure that the range remains - * valid. + * When setting this property, the minimum value is adjusted if necessary, to + * ensure that the range remains valid. */ /*! @@ -130,7 +132,8 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * to the axis labels. * If \c{false}, axis titles are only rotated around their axis but are not otherwise oriented * towards the camera. - * This property doesn't have any effect if labelAutoRotation property value is zero. + * This property does not have any effect if the labelAutoRotation property + * value is zero. * Default value is \c{true}. * * \sa labelAutoRotation, title, titleVisible @@ -235,9 +238,11 @@ QStringList QAbstract3DAxis::labels() const } /*! - * Sets value range of the axis from \a min to \a max. - * When setting the range, the max is adjusted if necessary, to ensure that the range remains valid. - * \note For QCategory3DAxis this specifies the index range of rows or columns to show. + * Sets the value range of the axis from \a min to \a max. + * When setting the range, the maximum value is adjusted if necessary, to ensure + * that the range remains valid. + * \note For QCategory3DAxis, specifies the index range of rows or columns to + * show. */ void QAbstract3DAxis::setRange(float min, float max) { @@ -303,7 +308,8 @@ bool QAbstract3DAxis::isTitleVisible() const * to the axis labels. * If \c{false}, axis titles are only rotated around their axis but are not otherwise oriented * towards the camera. - * This property doesn't have any effect if labelAutoRotation property value is zero. + * This property does not have any effect if the labelAutoRotation property + * value is zero. * Default value is \c{true}. * * \sa labelAutoRotation, title, titleVisible @@ -326,9 +332,10 @@ bool QAbstract3DAxis::isTitleFixed() const * * \brief The minimum value on the axis. * - * When setting this property the max is adjusted if necessary, to ensure that the range remains - * valid. - * \note For QCategory3DAxis this specifies the index of the first row or column to show. + * When setting this property, the maximum value is adjusted if necessary, to + * ensure that the range remains valid. + * \note For QCategory3DAxis, specifies the index of the first row or column to + * show. */ void QAbstract3DAxis::setMin(float min) { @@ -341,9 +348,10 @@ void QAbstract3DAxis::setMin(float min) * * \brief The maximum value on the axis. * - * When setting this property the min is adjusted if necessary, to ensure that the range remains - * valid. - * \note For QCategory3DAxis this specifies the index of the last row or column to show. + * When setting this property, the minimum value is adjusted if necessary, to + * ensure that the range remains valid. + * \note For QCategory3DAxis, specifies the index of the last row or column to + * show. */ void QAbstract3DAxis::setMax(float max) { @@ -384,7 +392,8 @@ bool QAbstract3DAxis::isAutoAdjustRange() const /*! * \fn QAbstract3DAxis::rangeChanged(float min, float max) * - * Emits range \a min and \a max values when range changes. + * Emits the minimum and maximum values of the range, \a min and \a max, when + * the range changes. */ // QAbstract3DAxisPrivate diff --git a/src/datavisualization/axis/qcategory3daxis.cpp b/src/datavisualization/axis/qcategory3daxis.cpp index faf286ab..17bfe490 100644 --- a/src/datavisualization/axis/qcategory3daxis.cpp +++ b/src/datavisualization/axis/qcategory3daxis.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,7 +35,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QCategory3DAxis * \inmodule QtDataVisualization - * \brief The QCategory3DAxis class is used for manipulating an axis of a graph. + * \brief The QCategory3DAxis class manipulates an axis of a graph. * \since QtDataVisualization 1.0 * * QCategory3DAxis provides an axis that can be given labels. The axis is divided into equal-sized @@ -52,7 +52,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QCategory3DAxis * \inherits AbstractAxis3D - * \brief The CategoryAxis3D type is used for manipulating an axis of a graph. + * \brief Manipulates an axis of a graph. * * This type provides an axis that can be given labels. */ @@ -66,7 +66,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION */ /*! - * Constructs QCategory3DAxis with \a parent. + * Constructs a category 3D axis with the parent \a parent. */ QCategory3DAxis::QCategory3DAxis(QObject *parent) : QAbstract3DAxis(new QCategory3DAxisPrivate(this), parent) @@ -75,7 +75,7 @@ QCategory3DAxis::QCategory3DAxis(QObject *parent) : } /*! - * Destroys QCategory3DAxis. + * Destroys the category 3D axis. */ QCategory3DAxis::~QCategory3DAxis() { diff --git a/src/datavisualization/axis/qlogvalue3daxisformatter.cpp b/src/datavisualization/axis/qlogvalue3daxisformatter.cpp index fb1e7447..3e044ed5 100644 --- a/src/datavisualization/axis/qlogvalue3daxisformatter.cpp +++ b/src/datavisualization/axis/qlogvalue3daxisformatter.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,11 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QLogValue3DAxisFormatter * \inmodule QtDataVisualization - * \brief QLogValue3DAxisFormatter implements logarithmic value axis formatter. + * \brief The QLogValue3DAxisFormatter class provides formatting rules for a + * logarithmic value axis. * \since QtDataVisualization 1.1 * - * This class provides formatting rules for a logarithmic QValue3DAxis. - * - * When a QLogValue3DAxisFormatter is attached to a QValue3DAxis, the axis range + * When a formatter is attached to a value axis, the axis range * cannot include negative values or the zero. * * \sa QValue3DAxisFormatter @@ -54,10 +53,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QLogValue3DAxisFormatter * \inherits ValueAxis3DFormatter - * \brief LogValueAxis3DFormatter implements logarithmic value axis formatter. + * \brief Provides formatting rules for a logarithmic value axis. * - * This type provides formatting rules for a logarithmic ValueAxis3D. - * When a LogValueAxis3DFormatter is attached to a ValueAxis3D, the axis range + * When a formatter is attached to a value axis, the axis range * cannot include negative values or the zero. */ @@ -66,10 +64,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * * The base of the logarithm used to map axis values. If the base is non-zero, the parent axis * segment count will be ignored when the grid line and label positions are calculated. - * If you want the range to be divided into equal segments like normal value axis, set this + * If you want the range to be divided into equal segments like a normal value axis, set this * property value to zero. * - * The base has to be zero or positive value and not equal to one. + * The base has to be zero or a positive value and it cannot be equal to one. * Defaults to ten. * * \sa ValueAxis3D::segmentCount @@ -82,9 +80,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * * If this property value is set to \c true, the parent axis sub-segment count is ignored * when calculating sub-grid line positions. The sub-grid positions are generated automatically - * according to the base property value. - * The number of sub-grid lines is set to base value minus one, rounded down. - * This property is ignored when base property value is zero. + * according to the \l base property value. + * The number of sub-grid lines is set to the base value minus one, rounded down. + * This property is ignored when the base value is zero. * Defaults to \c true. * * \sa base, ValueAxis3D::subSegmentCount @@ -95,9 +93,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * * Defines whether the first and last label on the axis are visible. * - * When the base property value is non-zero, the whole axis range is often not equally divided into + * When the \l base property value is non-zero, the whole axis range is often + * not equally divided into * segments. The first and last segments are often smaller than the other segments. - * In extreme cases this can lead to overlapping labels on the first and last two grid lines. + * In extreme cases, this can lead to overlapping labels on the first and last two grid lines. * By setting this property to \c false, you can suppress showing the minimum and maximum labels * for the axis in cases where the segments do not exactly fit the axis. * Defaults to \c true. @@ -117,7 +116,8 @@ QLogValue3DAxisFormatter::QLogValue3DAxisFormatter(QLogValue3DAxisFormatterPriva } /*! - * Constructs a new QLogValue3DAxisFormatter instance with optional \a parent. + * Constructs a new logarithmic value 3D axis formatter with the optional + * parent \a parent. */ QLogValue3DAxisFormatter::QLogValue3DAxisFormatter(QObject *parent) : QValue3DAxisFormatter(new QLogValue3DAxisFormatterPrivate(this), parent) @@ -127,7 +127,7 @@ QLogValue3DAxisFormatter::QLogValue3DAxisFormatter(QObject *parent) : } /*! - * Destroys QLogValue3DAxisFormatter. + * Deletes the logarithmic value 3D axis formatter. */ QLogValue3DAxisFormatter::~QLogValue3DAxisFormatter() { @@ -140,10 +140,10 @@ QLogValue3DAxisFormatter::~QLogValue3DAxisFormatter() * * If the base is non-zero, the parent axis * segment count will be ignored when the grid line and label positions are calculated. - * If you want the range to be divided into equal segments like normal value axis, set this + * If you want the range to be divided into equal segments like a normal value axis, set this * property value to zero. * - * The base has to be zero or positive value and not equal to one. + * The base has to be zero or a positive value and it cannot be equal to one. * Defaults to ten. * * \sa QValue3DAxis::segmentCount @@ -174,9 +174,9 @@ qreal QLogValue3DAxisFormatter::base() const * * If this property value is set to \c true, the parent axis sub-segment count is ignored * when calculating sub-grid line positions. The sub-grid positions are generated automatically - * according to the base property value. - * The number of sub-grid lines is set to base value minus one, rounded down. - * This property is ignored when base property value is zero. + * according to the \l base property value. The number of sub-grid lines is set + * to the base value minus one, rounded down. This property is ignored when the + * base value is zero. * Defaults to \c true. * * \sa base, QValue3DAxis::subSegmentCount @@ -200,9 +200,10 @@ bool QLogValue3DAxisFormatter::autoSubGrid() const * * \brief Whether the first and last label on the axis are visible. * - * When the base property value is non-zero, the whole axis range is often not equally divided into + * When the \l base property value is non-zero, the whole axis range is often + * not equally divided into * segments. The first and last segments are often smaller than the other segments. - * In extreme cases this can lead to overlapping labels on the first and last two grid lines. + * In extreme cases, this can lead to overlapping labels on the first and last two grid lines. * By setting this property to \c false, you can suppress showing the minimum and maximum labels * for the axis in cases where the segments do not exactly fit the axis. * Defaults to \c true. diff --git a/src/datavisualization/axis/qvalue3daxis.cpp b/src/datavisualization/axis/qvalue3daxis.cpp index efdf7143..f0a72ed4 100644 --- a/src/datavisualization/axis/qvalue3daxis.cpp +++ b/src/datavisualization/axis/qvalue3daxis.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,10 +36,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QValue3DAxis * \inmodule QtDataVisualization - * \brief The QValue3DAxis class is used for manipulating an axis of a graph. + * \brief The QValue3DAxis class manipulates an axis of a graph. * \since QtDataVisualization 1.0 * - * QValue3DAxis provides an axis that can be given a range of values and segment and subsegment + * A value axis can be given a range of values and segment and subsegment * counts to divide the range into. * * Labels are drawn between each segment. Grid lines are drawn between each segment and each @@ -54,7 +54,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \ingroup datavisualization_qml * \instantiates QValue3DAxis * \inherits AbstractAxis3D - * \brief The ValueAxis3D type is used for manipulating an axis of a graph. + * \brief Manipulates an axis of a graph. * * This type provides an axis that can be given a range of values and segment and subsegment * counts to divide the range into. @@ -65,8 +65,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \qmlproperty int ValueAxis3D::segmentCount * * The number of segments on the axis. This indicates how many labels are drawn. The number - * of grid lines to be drawn is calculated with formula: \c {segments * subsegments + 1}. - * The preset default is \c 5, and it can not be below \c 1. + * of grid lines to be drawn is calculated with the following formula: + * \c {segments * subsegments + 1}. + * The preset default is \c 5. The value cannot be below \c 1. */ /*! @@ -74,20 +75,22 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * * The number of subsegments inside each segment on the axis. Grid lines are drawn between * each subsegment, in addition to each segment. - * The preset default is \c 1, and it can not be below \c 1. + * The preset default is \c 1. The value cannot be below \c 1. */ /*! * \qmlproperty string ValueAxis3D::labelFormat * - * The label format to be used for the labels on this axis. How the format is interpreted - * depends on the axis formatter and the locale in use. Using the default formatter and default - * locale (\c{"C"}), the formatting uses QString::sprintf(). Supported specifiers are: - * \c {d, i, o, x, X, f, F, e, E, g, G, c}. See QString::sprintf() for additional details. - * For other locales, the default formatter uses reduced set of printf format specifiers: - * \c {d, i, f, F, e, E, g, G}. In these cases, the only supported modifier is the precision - * modifier for the floating point and exponential formats. The decimal point and other locale - * dependent formatting is done according to the graph locale. + * The label format to be used for the labels on this axis. + * + * The format string supports the following conversion specifiers, length + * modifiers, and flags provided by \c printf() in the standard C++ library: + * d, i, o, x, X, f, F, e, E, g, G, c. + * + * If AbstractGraph3D::locale is anything else than \c{"C"}, the supported + * specifiers are limited to: d, e, E, f, g, G, and i. Also, only the precision + * modifier is supported. The rest of the formatting comes from the default + * \l Locale of the application. * * \sa AbstractGraph3D::locale */ @@ -105,9 +108,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \qmlproperty bool ValueAxis3D::reversed * \since QtDataVisualization 1.1 * - * If \c{true}, the axis will be rendered in reverse, i.e. the positions of minimum and maximum - * values are swapped when the graph is rendered. This property doesn't affect the actual - * minimum and maximum values of the axis. + * If \c{true}, the axis will be rendered in reverse. That is, the positions of + * the minimum and maximum values are swapped when the graph is rendered. This + * property does not affect the actual minimum and maximum values of the axis. */ /*! @@ -133,7 +136,7 @@ QValue3DAxis::~QValue3DAxis() * * This indicates how many labels are drawn. The number * of grid lines to be drawn is calculated with formula: \c {segments * subsegments + 1}. - * The preset default is \c 5, and it can not be below \c 1. + * The preset default is \c 5. The value cannot be below \c 1. * * \sa setSubSegmentCount() */ @@ -163,7 +166,7 @@ int QValue3DAxis::segmentCount() const * * Grid lines are drawn between * each subsegment, in addition to each segment. - * The preset default is \c 1, and it can not be below \c 1. + * The preset default is \c 1. The value cannot be below \c 1. * * \sa setSegmentCount() */ @@ -190,14 +193,14 @@ int QValue3DAxis::subSegmentCount() const * * \brief The label format to be used for the labels on this axis. * - * How the format is interpreted - * depends on the axis formatter and the locale in use. Using the default formatter and default - * locale (\c{"C"}), the formatting uses QString::sprintf(). Supported specifiers are: - * \c {d, i, o, x, X, f, F, e, E, g, G, c}. See QString::sprintf() for additional details. - * For other locales, the default formatter uses reduced set of printf format specifiers: - * \c {d, i, f, F, e, E, g, G}. In these cases, the only supported modifier is the precision - * modifier for the floating point and exponential formats. The decimal point and other locale - * dependent formatting is done according to the graph locale. + * The format string supports the following conversion specifiers, length + * modifiers, and flags provided by \c printf() in the standard C++ library: + * d, i, o, x, X, f, F, e, E, g, G, c. + * + * If QAbstract3DGraph::locale is anything else than \c{"C"}, the supported + * specifiers are limited to: d, e, E, f, g, G, and i. Also, only the precision + * modifier is supported. The rest of the formatting comes from the default + * QLocale of the application. * * Usage example: * diff --git a/src/datavisualization/axis/qvalue3daxisformatter.cpp b/src/datavisualization/axis/qvalue3daxisformatter.cpp index 01463894..4bc3e7e3 100644 --- a/src/datavisualization/axis/qvalue3daxisformatter.cpp +++ b/src/datavisualization/axis/qvalue3daxisformatter.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,17 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \class QValue3DAxisFormatter * \inmodule QtDataVisualization - * \brief QValue3DAxisFormatter is base class for value axis formatters. + * \brief The QValue3DAxisFormatter class is a base class for value axis + * formatters. * \since QtDataVisualization 1.1 * - * This class provides formatting rules for a linear QValue3DAxis. Subclass it if you + * This class provides formatting rules for a linear value 3D axis. Subclass it if you * want to implement custom value axes. * * The base class has no public API beyond constructors and destructors. It is meant to be only * used internally. However, subclasses may implement public properties as needed. * - * \sa QLogValue3DAxisFormatter + * \sa QValue3DAxis, QLogValue3DAxisFormatter */ /*! @@ -53,11 +54,13 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \since QtDataVisualization 1.1 * \ingroup datavisualization_qml * \instantiates QValue3DAxisFormatter - * \brief ValueAxis3DFormatter is base type for value axis formatters. + * \brief A base type for value axis formatters. * - * This type provides formatting rules for a linear ValueAxis3D. + * This type provides formatting rules for a linear value 3D axis. * This type is the default type for ValueAxis3D and thus never needs to be explicitly created. - * This type has not public functionality. + * This type has no public functionality. + * + * \sa ValueAxis3D */ /*! @@ -70,7 +73,7 @@ QValue3DAxisFormatter::QValue3DAxisFormatter(QValue3DAxisFormatterPrivate *d, QO } /*! - * Constructs a new QValue3DAxisFormatter instance with an optional \a parent. + * Constructs a new value 3D axis formatter with the optional parent \a parent. */ QValue3DAxisFormatter::QValue3DAxisFormatter(QObject *parent) : QObject(parent), @@ -79,14 +82,14 @@ QValue3DAxisFormatter::QValue3DAxisFormatter(QObject *parent) : } /*! - * Destroys QValue3DAxisFormatter. + * Deletes the value 3D axis formatter. */ QValue3DAxisFormatter::~QValue3DAxisFormatter() { } /*! - * Allow the parent axis to have negative values if \a allow is true. + * Allows the parent axis to have negative values if \a allow is \c true. */ void QValue3DAxisFormatter::setAllowNegatives(bool allow) { @@ -94,8 +97,8 @@ void QValue3DAxisFormatter::setAllowNegatives(bool allow) } /*! - * \return \c true if negative values are valid values for parent axis. - * The default implementation always returns true. + * Returns \c true if negative values are valid values for the parent axis. + * The default implementation always returns \c true. */ bool QValue3DAxisFormatter::allowNegatives() const { @@ -103,7 +106,7 @@ bool QValue3DAxisFormatter::allowNegatives() const } /*! - * Allow the parent axis to have zero value if \a allow is true. + * Allows the parent axis to have a zero value if \a allow is \c true. */ void QValue3DAxisFormatter::setAllowZero(bool allow) { @@ -111,8 +114,8 @@ void QValue3DAxisFormatter::setAllowZero(bool allow) } /*! - * \return \c true if zero is a valid value for parent axis. - * The default implementation always returns true. + * Returns \c true if zero is a valid value for the parent axis. + * The default implementation always returns \c true. */ bool QValue3DAxisFormatter::allowZero() const { @@ -120,10 +123,11 @@ bool QValue3DAxisFormatter::allowZero() const } /*! - * Creates a new empty instance of this formatter. Must be reimplemented in a subclass. + * Creates a new empty value 3D axis formatter. Must be reimplemented in a + * subclass. * - * \return the new instance. The renderer uses this method to cache a copy of the - * the formatter. The ownership of the new copy transfers to the caller. + * Returns the new formatter. The renderer uses this method to cache a copy of + * the formatter. The ownership of the new copy is transferred to the caller. */ QValue3DAxisFormatter *QValue3DAxisFormatter::createNewInstance() const { @@ -131,9 +135,9 @@ QValue3DAxisFormatter *QValue3DAxisFormatter::createNewInstance() const } /*! - * This method resizes and populates the label and grid line position arrays and the label strings - * array, as well as calculates any values needed for mapping between value and position. - * It is allowed to access the parent axis from inside this function. + * Resizes and populates the label and grid line position arrays and the label + * strings array, as well as calculates any values needed to map a value to its + * position. The parent axis can be accessed from inside this function. * * This method must be reimplemented in a subclass if the default array contents are not suitable. * @@ -148,13 +152,13 @@ void QValue3DAxisFormatter::recalculate() } /*! - * This method is used to format a string using the specified value and the specified format. + * Returns the formatted label string using the specified \a value and + * \a format. + * * Reimplement this method in a subclass to resolve the formatted string for a given \a value * if the default formatting rules specified for QValue3DAxis::labelFormat property are not * sufficient. * - * \return the formatted label string using a \a value and a \a format. - * * \sa recalculate(), labelStrings(), QValue3DAxis::labelFormat */ QString QValue3DAxisFormatter::stringForValue(qreal value, const QString &format) const @@ -163,12 +167,13 @@ QString QValue3DAxisFormatter::stringForValue(qreal value, const QString &format } /*! - * Reimplement this method if the position cannot be resolved by linear interpolation - * between the parent axis minimum and maximum values. + * Returns the normalized position along the axis for the given \a value. + * The returned value should be between \c 0.0 (the minimum value) and + * \c 1.0 (the maximum value), inclusive, if the value is within the parent + * axis range. * - * \return the normalized position along the axis for the given \a value. - * The returned value should be between 0.0 (for minimum value) and 1.0 (for maximum value), - * inclusive, if the value is within the parent axis range. + * Reimplement this method if the position cannot be resolved by linear + * interpolation between the parent axis minimum and maximum values. * * \sa recalculate(), valueAt() */ @@ -178,12 +183,13 @@ float QValue3DAxisFormatter::positionAt(float value) const } /*! - * Reimplement this method if the value cannot be resolved by linear interpolation - * between the parent axis minimum and maximum values. + * Returns the value at the normalized \a position along the axis. + * The \a position value should be between \c 0.0 (the minimum value) and + * \c 1.0 (the maximum value), inclusive, to obtain values within the parent + * axis range. * - * \return the value at the normalized \a position along the axis. - * The \a position value should be between 0.0 (for minimum value) and 1.0 (for maximum value), - * inclusive to obtain values within the parent axis range. + * Reimplement this method if the value cannot be resolved by linear + * interpolation between the parent axis minimum and maximum values. * * \sa recalculate(), positionAt() */ @@ -193,12 +199,12 @@ float QValue3DAxisFormatter::valueAt(float position) const } /*! - * Copies all necessary values for resolving positions, values, and strings with this formatter - * from this formatter to the \a copy. - * When reimplementing this method in a subclass, call the the superclass version at some point. - * The renderer uses this method to cache a copy of the the formatter. + * Copies all the values necessary for resolving positions, values, and strings + * with this formatter to the \a copy of the formatter. When reimplementing + * this method in a subclass, call the superclass version at some point. + * The renderer uses this method to cache a copy of the formatter. * - * \return the new copy. The ownership of the new copy transfers to the caller. + * Returns the new copy. The ownership of the new copy transfers to the caller. */ void QValue3DAxisFormatter::populateCopy(QValue3DAxisFormatter ©) const { @@ -208,8 +214,8 @@ void QValue3DAxisFormatter::populateCopy(QValue3DAxisFormatter ©) const /*! * Marks this formatter dirty, prompting the renderer to make a new copy of its cache on the next * renderer synchronization. This method should be called by a subclass whenever the formatter - * is changed in a way that affects the resolved values. Specify \c true for \a labelsChange - * parameter if the change was such that it requires regenerating the parent axis label strings. + * is changed in a way that affects the resolved values. Set \a labelsChange to + * \c true if the change requires regenerating the parent axis label strings. */ void QValue3DAxisFormatter::markDirty(bool labelsChange) { @@ -217,7 +223,7 @@ void QValue3DAxisFormatter::markDirty(bool labelsChange) } /*! - * \return the parent axis. The parent axis must only be accessed in recalculate() + * Returns the parent axis. The parent axis must only be accessed in the recalculate() * method to maintain thread safety in environments using a threaded renderer. * * \sa recalculate() @@ -228,10 +234,11 @@ QValue3DAxis *QValue3DAxisFormatter::axis() const } /*! - * \return a reference to the array of normalized grid line positions. + * Returns a reference to the array of normalized grid line positions. * The default array size is equal to the segment count of the parent axis plus one, but - * a subclassed implementation of recalculate method may resize the array differently. - * The values should be between 0.0 (for minimum value) and 1.0 (for maximum value), inclusive. + * a subclassed implementation of the recalculate() method may resize the array differently. + * The values should be between \c 0.0 (the minimum value) and \c 1.0 (the + * maximum value), inclusive. * * \sa QValue3DAxis::segmentCount, recalculate() */ @@ -241,11 +248,12 @@ QVector<float> &QValue3DAxisFormatter::gridPositions() const } /*! - * \return a reference to the array of normalized subgrid line positions. - * The default array size is equal to segment count of the parent axis times sub-segment count - * of the parent axis minus one, but a subclassed implementation of recalculate method may resize - * the array differently. - * The values should be between 0.0 (for minimum value) and 1.0 (for maximum value), inclusive. + * Returns a reference to the array of normalized subgrid line positions. + * The default array size is equal to the segment count of the parent axis times + * the sub-segment count of the parent axis minus one, but a subclassed + * implementation of the recalculate() method may resize the array differently. + * The values should be between \c 0.0 (the minimum value) and \c 1.0 (the + * maximum value), inclusive. * * \sa QValue3DAxis::segmentCount, QValue3DAxis::subSegmentCount, recalculate() */ @@ -255,11 +263,12 @@ QVector<float> &QValue3DAxisFormatter::subGridPositions() const } /*! - * \return a reference to the array of normalized label positions. + * Returns a reference to the array of normalized label positions. * The default array size is equal to the segment count of the parent axis plus one, but - * a subclassed implementation of recalculate method may resize the array differently. - * The values should be between 0.0 (for minimum value) and 1.0 (for maximum value), inclusive. - * The default behavior is that the label at the index zero corresponds to the minimum value + * a subclassed implementation of the recalculate() method may resize the array + * differently. The values should be between \c 0.0 (the minimum value) and + * \c 1.0 (the maximum value), inclusive. + * By default, the label at the index zero corresponds to the minimum value * of the axis. * * \sa QValue3DAxis::segmentCount, QAbstract3DAxis::labels, recalculate() @@ -270,9 +279,9 @@ QVector<float> &QValue3DAxisFormatter::labelPositions() const } /*! - * \return a reference to the string list containing formatter label strings. - * The array size must be equal to the size of the label positions array and - * the indexes correspond to that array as well. + * Returns a reference to the string list containing formatter label strings. + * The array size must be equal to the size of the label positions array, which + * the indexes also correspond to. * * \sa labelPositions() */ @@ -296,7 +305,7 @@ void QValue3DAxisFormatter::setLocale(const QLocale &locale) markDirty(true); } /*! - * \return the current locale this formatter is using. + * Returns the current locale this formatter is using. */ QLocale QValue3DAxisFormatter::locale() const { 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 diff --git a/src/datavisualization/doc/src/qtdatavisualization-index.qdoc b/src/datavisualization/doc/src/qtdatavisualization-index.qdoc index 0a5f0434..fc09b08e 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-index.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-index.qdoc @@ -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. @@ -32,29 +32,15 @@ \page qtdatavisualization-index.html \brief Provides functionality for 3D visualization. - Qt Data Visualization module provides a way to visualize data in 3D. - \section1 Features + Qt Data Visualization module provides a way to visualize data in 3D as bar, + scatter, and surface graphs. It is especially useful for visualizing depth + maps and large quantities of rapidly changing data, such as data received + from multiple sensors. The look and feel of graphs can be customized + by using themes or by adding custom items and labels to them. - \list - \li Multiple data visualization options: 3D Bars, 3D Scatter, and 3D Surface - \li 2D slice views of the 3D data - \li Interactive data: rotate, zoom, and highlight data using mouse or touch - \li Uses OpenGL for rendering the data - \li QML2 support - \li Customizable axes for data - \list - \li Control viewable data window with axis ranges - \li Customize value axis grid lines and labels with axis formatters - \li Polar horizontal axes support for surface and scatter graphs - \endlist - \li Customizable input handling - \li Customizable themes - \li Custom items and labels can be added to any graph - \li Ready-made data proxies to visualize data from Qt item models and height maps - \li Perspective and orthographic projections - \li Volumetric custom items - \endlist + Qt Data Visualization is built on Qt 5 and OpenGL to take advantage of + hardware acceleration and Qt Quick 2. \section1 Getting Started @@ -75,12 +61,9 @@ \snippet doc_src_qtdatavisualization.pro 0 - See the \l{Qt Data Visualization Getting Started}{Getting started} page for further information on - how to use Qt Data Visualization in your application. - \section1 Articles \list - \li \l{Qt Data Visualization Getting Started}{Getting Started} + \li \l{Qt Data Visualization Overview}{Overview} \li \l{Qt Data Visualization Data Handling}{Data Handling} \li \l{Qt Data Visualization Interacting with Data}{Interacting with Data} \li \l{Qt Data Visualization Known Issues}{Known Issues} diff --git a/src/datavisualization/doc/src/qtdatavisualization-overview.qdoc b/src/datavisualization/doc/src/qtdatavisualization-overview.qdoc new file mode 100644 index 00000000..8cb656b1 --- /dev/null +++ b/src/datavisualization/doc/src/qtdatavisualization-overview.qdoc @@ -0,0 +1,250 @@ +/**************************************************************************** +** +** 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. +** +** $QT_BEGIN_LICENSE:GPL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3 or (at your option) any later version +** approved by the KDE Free Qt Foundation. The licenses are as published by +** the Free Software Foundation and appearing in the file LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Qt Data Visualization Overview + \page qtdatavisualization-overview.html + \brief An overview of the Qt Data Visualization module. + + The Qt Data Visualization module provides a way to develop rapidly + responding, complex, and dynamic 3D visualization for analytical demanding + industries such as academic research and medical. Qt 3D Data Visualization + provides 3D bars, scatter, and surface visualizations. Combining user + interaction and real time 3D drawing visualizations enables creating user + interfaces that use space effectively. Changing between 3D and 2D + presentation enables truly utilizing the value of 3D in visualizing data. + + The look and feel of the graphs can be customized by using the predefined + themes or defining new ones. In addition, scenes can be customized by + specifying settings for the camera, and individual items can be customized + by using predefined or user-defined meshes. + + Qt Data Visualization offers ready-made data proxies that can be used to + visualize data from Qt item models and height maps. Each graph type has a + basic proxy type, which accepts data in a format suitable for that + visualization. For more information, see \l{Qt Data Visualization Data + Handling}. + + End users can interact with the data presented by graphs in several ways, + including rotating graphs, zooming into and out of data, selecting items, + and viewing 2D slices of the 3D data for increased readability. For more + information, see \l{Qt Data Visualization Interacting with Data}. + + \section1 Graph Types + + The Qt Data Visualization module provides the following 3D graph types: + + \list + \li \l{3D Bar Graphs}{3D bar graphs} + \li \l{3D Scatter Graphs}{3D scatter graphs} + \li \l{3D Surface Graphs}{3D surface graphs} + \endlist + + The QAbstract3DGraph class subclasses a QWindow and provides a render loop + for its own subclasses that implement the different graph types: Q3DBars, + Q3DScatter, and Q3DSurface. The graph type determines how the data is + presented. + + \section2 3D Bar Graphs + + 3D bar graphs present data as 3D bars that are grouped by category. The + Q3DBars class is used to create a graph and the QBar3DSeries and + QBarDataProxy classes are used to set data to the graph, as well as to + control the visual properties of the graph, such as draw mode and shading. + In QML, the corresponding types are Bars3D, Bar3DSeries, and BarDataProxy. + + \image q3dbars-minimal.png + + For more information, see \l{How to construct a minimal Q3DBars graph}, + \l {Bars Example}, and \l {Qt Quick 2 Bars Example}. + + \section2 3D Scatter Graphs + + 3D scatter graphs present data as a collection of points. The Q3DScatter + class is used to create a graph and the QScatter3DSeries and + QScatterDataProxy classes are used to set data to the graph, as well as to + control the visual properties of the graph. In QML, the corresponding types + are Scatter3D, Scatter3DSeries, and ScatterDataProxy. + + \image q3dscatter-minimal.png + + For more information, see \l{How to construct a minimal Q3DScatter graph}, + \l{Scatter Example}, and \l{Qt Quick 2 Scatter Example}. + + \section2 3D Surface Graphs + + 3D surface graphs present data as 3D surface plots. The Q3DSurface class is + used to create a graph and the QSurface3DSeries and QSurfaceDataProxy + classes are used to set data to the graph, as well as to control the visual + properties of the graph. In QML, the corresponding types are Surface3D, + Surface3DSeries, and SurfaceDataProxy. + + \image q3dsurface-minimal.png + + For more information, see \l{How to construct a minimal Q3DSurface graph}, + \l{Surface Example}, \l{Textured Surface Example}, \l{Qt Quick 2 Surface + Example}, and \l{Qt Quick 2 Surface Multiseries Example}. + + \section1 Using OpenGL for Rendering Data + + It is recommended to use OpenGL 2.1 or later for data rendering. + If OpenGL ES2 is used (including Angle builds in Windows), the following + features are not supported: + + \list + \li Shadows + \li Antialiasing + \li Flat shading for surfaces + \li Volumetric objects, because they use 3D textures + \endlist + + Only OpenGL ES2 emulation is available for software renderer (that is, when + using QCoreApplication::setAttribute(Qt::AA_UseSoftwareOpenGL)). + + \section2 Selecting Rendering Mode + + In QML, you can set the \l{AbstractGraph3D::renderingMode} + {AbstractGraph3D.RenderingMode} property to determine whether the graph will + be rendered directly on the window background or to an offscreen surface + that is then drawn during normal QML item rendering. + + Background rendering modes offer slightly better performance than the + indirect rendering mode, at the cost of non-standard QML behavior. For + example, the graphs do not obey the z ordering of QML items and they cannot + be partially transparent. Therefore, changing the rendering mode is a + question of performance versus quality. + + Qt Quick 2 uses a dedicated scenegraph for data rendering, and is therefore + the best choice for data visualization. + + \section1 3D Axes + + Qt Data Visualization supports the following axis types: + + \list + \li Value axis + \li Category axis + \endlist + + An axis can be set up to show a line or a grid. Both axis types are + specializations of the QAbstract3DAxis class or the AbstractAxis3D QML type. + + A value axis can be given a range of values and segment and subsegment + counts to divide the range into. Labels are drawn between each segment. + Grid lines are drawn between each segment and each subsegment. The value + axis is implemented using the QValue3DAxis class or the ValueAxis3D QML type. + + A category axis has named ranges and adjustable range widths. It is divided + into equal-sized categories based on the data window size defined by the + axis range. Labels are drawn to the positions of categories, if provided. + Grid lines are drawn between categories, if visible. A category axis is + implemented using the QCategory3DAxis class or the CategoryAxis3D QML type. + + If no axes are set explicitly for a graph, temporary default axes with no + labels are created. These default axes can be modified via axis accessors, + but as soon as any axis is set explicitly for a particular orientation, the + default axis for that orientation is destroyed. + + All graph types support showing multiple series simultaneously. All the + series do not need to contain the same number of rows and columns. Row and + column labels are taken from the first series added, unless they are + explicitly defined for the row and column axes. + + Axis formatters can be used to customize value axis grid lines and labels. + The QValue3DAxisFormatter class and ValueAxis3DFormatter QML type provide + formatting rules for a linear value 3D axis. The QLogValue3DAxisFormatter + class and the LogValueAxis3DFormatter QML type provide formatting rules for + a logarithmic value 3D axis. + + Polar horizontal axes can be used for surface and scatter graphs by setting + the \l{QAbstract3DGraph::}{polar} property. + + \section1 3D Themes + + A theme is a built-in collection of UI style related settings applied to all + the visual elements of a graph, such as the colors, fonts, and visibility of + the elements, as well as the strenght of the light and ambient light. + + Qt Charts comes with the following predefined themes that can be used as + basis for custom themes: + + \list + \li \e Qt is a light theme with green as the base color. + \li \e {Primary colors} is a light theme with yellow as the base color. + \li \e Digia is a light theme with gray as the base color. + \li \e {Stone moss} is a medium dark theme with yellow as the base + color. + \li \e {Army blue} is a medium light theme with blue as the base color. + \li \e Retro is a medium light theme with brown as the base color. + \li \e Ebony is a dark theme with white as the base color. + \li \e Isabelle is a dark theme with yellow as the base color. + \li \e {User defined} is the default theme that is meant to be + customized. For more information, see \l {Default Theme}. + \endlist + + Custom themes can also be created from scratch. + + If a graph displays the data from several data series, some settings can be + specified separately for each series. For example, different gradients can + be specified for different layers of the graph to make it look more + realistic. For an example, see \l{Qt Quick 2 Surface Multiseries Example}. + + \section1 Customizing 3D Scenes + + A 3D scene is implemented by using the Q3DScene class or the Scene3D QML + type. A scene contains a single active camera, implemented by using the + Q3DCamera class or the Camera3D type, and a single active light source, + implemented by using the Q3DLight class or the Light3D type. The light + source is always positioned in relation to the camera. By default, the light + position follows the camera automatically. + + The camera can be customized by specifying its preset position, rotation, + and zoom level. For an example, see \l{Qt Quick 2 Scatter Example}. + + \section1 Customizing Items + + Qt Data Visualization has predefined mesh types for bars, items, and + surfaces. The mesh type determines how a bar, an item, or a surface looks on + a graph. A user-defined mesh can be specified as a Wavefront OBJ geometry + definition file. For more variety, a quaternion can be set for mesh + rotation. + + In addition to customizing individual items, the QCustom3DItem class or the + Custom3DItem QML type can be used to add custom items to graphs. The items + have a custom mesh, position, scaling, rotation, and an optional texture. + + The QCustom3DVolume class and the Custom3DVolume QML type can be used to + create volume rendered objects to be added to a graph. 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. + + The The QCustom3DLabel class and the Custom3DLabel QML type implement custom + labels with the specified text, font, position, scaling, and rotation. Label + colors, borders, and background are determined by the active theme. +*/ diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc index e688ffb3..746a854f 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-abstractdeclarative.qdoc @@ -34,62 +34,65 @@ \ingroup datavisualization_qml \brief Base type for 3D visualizations. - This type is the base type for all 3D visualizations in QtDataVisualization. + The base type for all 3D visualizations in QtDataVisualization. - Note that this type is uncreatable, but contains properties that are shared between + This type is uncreatable, but it contains properties that are shared between the 3D visualizations. - For AbstractGraph3D enums, see \l{QAbstract3DGraph::SelectionFlag}, - \l{QAbstract3DGraph::ShadowQuality}, \l{QAbstract3DGraph::ElementType}, and - \l{QAbstract3DGraph::OptimizationHint}. - \sa Bars3D, Scatter3D, Surface3D, {Qt Data Visualization C++ Classes} */ /*! \qmlproperty AbstractGraph3D.SelectionMode AbstractGraph3D::selectionMode - Active selection mode in the visualization. + The active selection mode in the visualization. + One of the QAbstract3DGraph::SelectionFlag enum values. + + \sa QAbstract3DGraph::SelectionFlag */ /*! \qmlproperty AbstractGraph3D.ShadowQuality AbstractGraph3D::shadowQuality - Shadow quality. + The quality of shadows. One of the QAbstract3DGraph::ShadowQuality enum + values. + + \sa QAbstract3DGraph::ShadowQuality */ /*! \qmlproperty bool AbstractGraph3D::shadowsSupported - This read-only property indicates if shadows are supported with the - current configuration or not. OpenGL ES2 configurations do not support shadows. + This read-only property indicates whether shadows are supported with the + current configuration. OpenGL ES2 configurations do not support shadows. */ /*! \qmlproperty Scene3D AbstractGraph3D::scene - Read only property that can be used to access for example Camera3D via the Scene3D held here. + The Scene3D pointer that can be used to manipulate the scene and access the + scene elements, such as the active camera. + + This property is read-only. */ /*! \qmlproperty AbstractInputHandler3D AbstractGraph3D::inputHandler - Input handler. You can disable default input handlers by setting this property to \c {null}. + The active input handler used in the graph. You can disable default input + handlers by setting this property to null. */ /*! \qmlproperty Theme3D AbstractGraph3D::theme The active theme of the graph. + + \sa Theme3D */ /*! \qmlproperty AbstractGraph3D.RenderingMode AbstractGraph3D::renderingMode - Defaults to \c{RenderIndirect}. + How the graph will be rendered. Defaults to \c{RenderIndirect}. - \table - \header - \li Render Mode - \li Description - \row - \li RenderDirectToBackground - \li Indicates the graph will be rendered directly on the window background. - This mode also clears the whole window before rendering the graph, including the areas + \value RenderDirectToBackground + Indicates that the graph will be rendered directly on the window background. + Clears the whole window before rendering the graph, including the areas outside the graph. Since the graphs in this rendering mode are drawn on the window background under other QML items, the regular QML window clearing before rendering is suppressed. The graphs handle the clearing @@ -97,10 +100,10 @@ If the surface format of the window supports antialiasing, it will be used (see \c {QtDataVisualization::qDefaultSurfaceFormat()}). This rendering mode offers the best performance at the expense of non-standard QML behavior. For example, - the graphs do not obey the Z ordering of QML items and the opacity value has no effect on them. - \row - \li RenderDirectToBackground_NoClear - \li Similar to RenderDirectToBackground mode, except that the graph will not clear the whole + the graphs do not obey the z ordering of QML items and the opacity value has no effect on them. + + \value RenderDirectToBackground_NoClear + Similar to \c RenderDirectToBackground mode, except that the graph will not clear the whole window before rendering the graph. This mode is better for windows where you have other custom items besides the graphs that also draw on the window background. In that case you need to either take care of the window clearing yourself or ensure that all areas of the window are fully covered with opaque @@ -108,18 +111,17 @@ If one graph in the window uses either of the direct rendering modes, then all other graphs in the same window also drawn in direct modes should use the exact same direct rendering mode. Otherwise some graphs may not show up, depending on the drawing order of the graphs. - \row - \li RenderIndirect - \li Indicates the graph will be first rendered to an offscreen surface that + + \value RenderIndirect + Indicates the graph will be first rendered to an offscreen surface that is then drawn during normal QML item rendering. The rendered image is - antialiased using multisampling method if it is supported in the current environment and the + antialiased using the multisampling method if it is supported in the current environment and the msaaSamples property value is greater than zero. This rendering mode offers good quality and normal QML item behavior at the expense of performance. - \endtable \note Antialiasing is not supported in OpenGL ES2 environments in any rendering mode. - \note Setting the \c antialiasing property of the graphs doesn't do anything. However, it is + \note Setting the \c antialiasing property of the graph does not do anything. However, it is set by the graph itself if the current rendering mode uses antialiasing. \sa msaaSamples @@ -140,8 +142,8 @@ * \qmlproperty bool AbstractGraph3D::measureFps * \since QtDataVisualization 1.1 * - * If \c {true}, the rendering is done continuously instead of on demand, and currentFps property - * is updated. Defaults to \c{false}. + * If \c {true}, the rendering is done continuously instead of on demand, and + * the value of the currentFps property is updated. Defaults to \c{false}. * * \sa currentFps */ @@ -150,8 +152,8 @@ * \qmlproperty int AbstractGraph3D::currentFps * \since QtDataVisualization 1.1 * - * When fps measuring is enabled, the results for the last second are stored in this read-only - * property. It takes at least a second before this value updates after measurement is activated. + * When FPS measuring is enabled, the results for the last second are stored in this read-only + * property. It takes at least a second before this value updates after measuring is activated. * * \sa measureFps */ @@ -160,15 +162,16 @@ * \qmlproperty list<Custom3DItem> AbstractGraph3D::customItemList * \since QtDataVisualization 1.1 * - * Add a list of \l{Custom3DItem}s to the graph. Graph takes ownership of the added items. + * The list of \l{Custom3DItem} items added to the graph. The graph takes ownership + * of the added items. */ /*! * \qmlproperty bool AbstractGraph3D::polar * \since QtDataVisualization 1.2 * - * If \c {true}, the horizontal axes are changed into polar axes. The X axis becomes the - * angular axis and the Z axis becomes the radial axis. + * If \c {true}, the horizontal axes are changed into polar axes. The x-axis + * becomes the angular axis and the z-axis becomes the radial axis. * Polar mode is not available for bar graphs. * * Defaults to \c{false}. @@ -181,10 +184,11 @@ * \since QtDataVisualization 1.2 * * This property specifies the normalized horizontal offset for the axis labels of the radial - * polar axis. The value 0.0 indicates the labels should be drawn next to the 0-angle angular - * axis grid line. The value 1.0 indicates the labels are drawn on their normal place at the edge - * of the graph background. - * This property is ignored if polar property value is \c{false}. Defaults to 1.0. + * polar axis. The value \c 0.0 indicates that the labels should be drawn next + * to the 0-angle angular axis grid line. The value \c 1.0 indicates that the + * labels are drawn in their usual place at the edge of the graph background. + * This property is ignored if the polar property value is \c{false}. Defaults + * to \c 1.0. * * \sa polar */ @@ -300,16 +304,18 @@ /*! * \qmlproperty AbstractGraph3D.ElementType AbstractGraph3D::selectedElement * - * Can be used to query the selected element type. - * Type is valid until the next \c selectedElementChanged signal. + * The element selected in the graph. * - * \c selectedElementChanged signal is emitted when a selection is made in the graph. + * This property can be used to query the selected element type. + * The type is valid until a new selection is made in the graph and the + * \c selectedElementChanged signal is emitted. * - * Signal can be used for example for implementing customized input handling, as demonstrated in - * this \l {Qt Quick 2 Axis Dragging Example}{example}. + * The signal can be used for example for implementing customized input + * handling, as demonstrated by the \l {Qt Quick 2 Axis Dragging Example}. * * \sa selectedLabelIndex(), selectedAxis(), selectedCustomItemIndex(), selectedCustomItem(), - * Bars3D::selectedSeries, Scatter3D::selectedSeries, Scene3D::selectionQueryPosition + * Bars3D::selectedSeries, Scatter3D::selectedSeries, Scene3D::selectionQueryPosition, + * QAbstract3DGraph::ElementType * * \since QtDataVisualization 1.1 */ @@ -326,8 +332,8 @@ * \qmlproperty real AbstractGraph3D::aspectRatio * \since QtDataVisualization 1.1 * - * The aspect ratio is the ratio of the graph scaling between the longest axis on the horizontal - * plane and the Y-axis. Defaults to \c{2.0}. + * The ratio of the graph scaling between the longest axis on the horizontal + * plane and the y-axis. Defaults to \c{2.0}. * * \note Has no effect on Bars3D. * @@ -338,11 +344,11 @@ * \qmlproperty real AbstractGraph3D::horizontalAspectRatio * \since QtDataVisualization 1.2 * - * The horizontal aspect ratio is the ratio of the graph scaling between the X and Z axes. - * Value of 0.0 indicates automatic scaling according to axis ranges. + * The ratio of the graph scaling between the x-axis and z-axis. + * The value of \c 0.0 indicates automatic scaling according to axis ranges. * Defaults to \c{0.0}. * - * \note Has no effect on Bars3D, which handles scaling on the horizontal plane via + * \note Has no effect on Bars3D, which handles scaling on the horizontal plane via the * \l{Bars3D::barThickness}{barThickness} and \l{Bars3D::barSpacing}{barSpacing} properties. * Polar graphs also ignore this property. * @@ -353,20 +359,23 @@ * \qmlproperty AbstractGraph3D.OptimizationHints AbstractGraph3D::optimizationHints * \since QtDataVisualization 1.1 * - * Defines if the rendering optimization is default or static. Default mode provides the full - * feature set at reasonable performance. Static mode optimizes graph rendering and is ideal for + * Whether the default or static mode is used for rendering optimization. + * + * The default mode provides the full feature set at a reasonable level of + * performance. The static mode optimizes graph rendering and is ideal for * large non-changing data sets. It is slower with dynamic data changes and item rotations. - * Selection is not optimized, so using it with massive data sets is not advisable. - * Static works only on the Scatter graph. - * Defaults to \c{OptimizationDefault}. + * Selection is not optimized, so using the static mode with massive data sets is not advisable. + * Static optimization works only on scatter graphs. + * Defaults to \l{QAbstract3DGraph::OptimizationDefault}{OptimizationDefault}. * * \note On some environments, large graphs using static optimization may not render, because - * all of the items are rendered using a single draw call, and different graphics drivers have - * different maximum vertice counts per call that they support. - * This is mostly an issue on 32bit and/or OpenGL ES2 platforms. - * To work around this issue, choose an item mesh with low vertex count or use the point mesh. + * all of the items are rendered using a single draw call, and different graphics drivers + * support different maximum vertice counts per call. + * This is mostly an issue on 32bit and OpenGL ES2 platforms. + * To work around this issue, choose an item mesh with a low vertex count or use + * the point mesh. * - * \sa Abstract3DSeries::mesh + * \sa Abstract3DSeries::mesh, QAbstract3DGraph::OptimizationHint */ /*! @@ -375,9 +384,8 @@ * * Sets floor reflections on or off. Defaults to \c{false}. * - * \note Affects only Bars3D. - * - * \note In Bars3D graphs holding both positive and negative values, reflections are not supported + * \note Affects only Bars3D. However, in Bars3D graphs holding both positive + * and negative values, reflections are not supported * for custom items that intersect the floor plane. In that case, reflections should be turned off * to avoid incorrect rendering. * @@ -388,7 +396,8 @@ * \qmlproperty real AbstractGraph3D::reflectivity * \since QtDataVisualization 1.2 * - * Adjusts floor reflectivity, larger number being more reflective. Valid range is \c{[0...1]}. + * Sets floor reflectivity. Larger numbers make the floor more reflective. The + * valid range is \c{[0...1]}. * Defaults to \c{0.5}. * * \note Affects only Bars3D. @@ -401,7 +410,7 @@ * \since QtDataVisualization 1.2 * * Sets the locale used for formatting various numeric labels. - * Defaults to \c{"C"} locale. + * Defaults to the \c{"C"} locale. * * \sa ValueAxis3D::labelFormat */ @@ -414,14 +423,14 @@ * Scene3D::graphPositionQuery. The values are normalized to range \c{[-1, 1]}. * If the queried position was outside the graph bounds, the values * will not reflect the real position, but will instead be some undefined position outside - * the range \c{[-1, 1]}. The value will be undefined before any queries are made. + * the range \c{[-1, 1]}. The value will be undefined until a query is made. * - * There isn't a single correct 3D coordinate to match to each specific screen position, so to be + * There is no single correct 3D coordinate to match a particular screen position, so to be * consistent, the queries are always done against the inner sides of an invisible box surrounding * the graph. * * \note Bar graphs only allow querying graph position at the graph floor level, - * so the Y-value is always zero for bar graphs and the valid queries can be only made at + * so the y-value is always zero for bar graphs and valid queries can be only made at * screen positions that contain the floor of the graph. * * \sa Scene3D::graphPositionQuery @@ -431,18 +440,20 @@ * \qmlproperty real AbstractGraph3D::margin * \since QtDataVisualization 1.2 * - * This property contains the absolute value used for graph margin. The graph margin is the space - * left between the edge of the plottable graph area and the edge of the graph background. + * The absolute value used for the space left between the edge of the + * plottable graph area and the edge of the graph background. + * * If the margin value is negative, the margins are determined automatically and can vary according - * to size of the items in the series and the type of the graph. - * The value is interpreted as a fraction of Y-axis range, provided the graph aspect ratios have - * not beed changed from the defaults. + * to the size of the items in the series and the type of the graph. + * The value is interpreted as a fraction of the y-axis range if the graph + * aspect ratios have not beed changed from the default values. * Defaults to \c{-1.0}. * - * \note Having smaller than the automatically determined margin on scatter graph can cause - * the scatter items at the edges of the graph to overlap with the graph background. + * \note Setting a smaller margin for a scatter graph than the automatically + * determined margin can cause the scatter items at the edges of the graph to + * overlap with the graph background. * - * \note On scatter and surface graphs, if the margin is comparatively small to the axis label + * \note On scatter and surface graphs, if the margin is small in comparison to the axis label * size, the positions of the edge labels of the axes are adjusted to avoid overlap with * the edge labels of the neighboring axes. */ diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc index 5f625a96..0149c805 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc @@ -55,16 +55,18 @@ * The active row axis. * * If an axis is not given, a temporary default axis with no labels is created. - * This temporary axis is destroyed if another axis is explicitly set to same orientation. + * This temporary axis is destroyed if another axis is explicitly set to the + * same orientation. */ /*! * \qmlproperty ValueAxis3D Bars3D::valueAxis * The active value axis. * - * If an axis is not given, a temporary default axis with no labels and automatically adjusting - * range is created. - * This temporary axis is destroyed if another axis is explicitly set to same orientation. + * If an axis is not given, a temporary default axis with no labels and an + * automatically adjusting range is created. + * This temporary axis is destroyed if another axis is explicitly set to the + * same orientation. */ /*! @@ -72,64 +74,79 @@ * The active column axis. * * If an axis is not given, a temporary default axis with no labels is created. - * This temporary axis is destroyed if another axis is explicitly set to same orientation. + * This temporary axis is destroyed if another axis is explicitly set to the + * same orientation. */ /*! * \qmlproperty bool Bars3D::multiSeriesUniform - * This property controls if bars are to be scaled with proportions set to a single series bar even + * Defines whether bars are to be scaled with proportions set to a single series bar even * if there are multiple series displayed. If set to \c {true}, \l{barSpacing}{bar spacing} will - * affect only X-axis correctly. It is preset to \c false by default. + * be correctly applied only to the X-axis. Preset to \c false by default. */ /*! * \qmlproperty real Bars3D::barThickness - * Bar thickness ratio between X and Z dimensions. 1.0 means bars are as wide as they are deep, 0.5 + * The bar thickness ratio between the X and Z dimensions. The value \c 1.0 + * means that the bars are as wide as they are deep, whereas \c 0.5 * makes them twice as deep as they are wide. */ /*! * \qmlproperty size Bars3D::barSpacing * Bar spacing in X and Z dimensions. + * + * Preset to \c {(1.0, 1.0)} by default. Spacing is affected by the + * barSpacingRelative property. */ /*! * \qmlproperty bool Bars3D::barSpacingRelative - * Relative or absolute bar spacing. + * Whether spacing is absolute or relative to bar thickness. + * + * If \c true, the value of \c 0.0 means that the bars are placed + * side-to-side, \c 1.0 means that a space as wide as the thickness of one bar + * is left between the bars, and so on. Preset to \c true. */ /*! * \qmlproperty Bar3DSeries Bars3D::selectedSeries * The selected series or \c null. If \l {QAbstract3DGraph::selectionMode}{selectionMode} has - * \c SelectionMultiSeries flag set, this property holds the series which owns the selected bar. + * the \c SelectionMultiSeries flag set, this property holds the series that + * owns the selected bar. */ /*! * \qmlproperty list<Bar3DSeries> Bars3D::seriesList * \default - * This property holds the series of the graph. + * The series of the graph. * By default, this property contains an empty list. * To set the series, either use the addSeries() function or define them as children of the graph. */ /*! * \qmlproperty Bar3DSeries Bars3D::primarySeries - * Specifies the \a series that is the primary series of the graph. The primary series + * The primary series of the graph. It * is used to determine the row and column axis labels when the labels are not explicitly * set to the axes. - * If the specified \a series is not already added to the graph, setting it as the + * + * If the specified series is not yet added to the graph, setting it as the * primary series will also implicitly add it to the graph. + * * If the primary series itself is removed from the graph, this property * resets to default. - * If \a series is null, this property resets to default. + * + * If the series is null, this property resets to default. * Defaults to the first added series or zero if no series are added to the graph. */ /*! * \qmlproperty real Bars3D::floorLevel * - * The desired floor level for the bar graph in Y-axis data coordinates. - * The actual floor level cannot go below Y-axis minimum or above Y-axis maximum. + * The floor level for the bar graph in Y-axis data coordinates. + * + * The actual floor level will be restricted by the Y-axis minimum and maximum + * values. * Defaults to zero. */ diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc index 10487420..50e8df83 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc @@ -52,34 +52,37 @@ /*! \qmlproperty ValueAxis3D Scatter3D::axisX - The active X axis. + The active x-axis. - If an axis is not given, a temporary default axis with no labels and automatically adjusting - range is created. - This temporary axis is destroyed if another axis is explicitly set to same orientation. + If an axis is not given, a temporary default axis with no labels and an + automatically adjusting range is created. + This temporary axis is destroyed if another axis is explicitly set to the same + orientation. */ /*! \qmlproperty ValueAxis3D Scatter3D::axisY - The active Y axis. + The active y-axis. - If an axis is not given, a temporary default axis with no labels and automatically adjusting - range is created. - This temporary axis is destroyed if another axis is explicitly set to same orientation. + If an axis is not given, a temporary default axis with no labels and an + automatically adjusting range is created. + This temporary axis is destroyed if another axis is explicitly set to the same + orientation. */ /*! \qmlproperty ValueAxis3D Scatter3D::axisZ - The active Z axis. + The active z-axis. - If an axis is not given, a temporary default axis with no labels and automatically adjusting - range is created. - This temporary axis is destroyed if another axis is explicitly set to same orientation. + If an axis is not given, a temporary default axis with no labels and an + automatically adjusting range is created. + This temporary axis is destroyed if another axis is explicitly set to the same + orientation. */ /*! * \qmlproperty Scatter3DSeries Scatter3D::selectedSeries - * The selected series or \c null. + * The selected series or null. */ /*! @@ -87,7 +90,8 @@ * \default * This property holds the series of the graph. * By default, this property contains an empty list. - * To set the series, either use the addSeries() function or define them as children of the graph. + * To set the series, either use the addSeries() method or define them as + * children of the graph. */ /*! diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc index 0aca2af4..8c465216 100644 --- a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc @@ -52,34 +52,34 @@ /*! \qmlproperty ValueAxis3D Surface3D::axisX - The active X axis. + The active x-axis. - If an axis is not given, a temporary default axis with no labels and automatically adjusting - range is created. + If an axis is not given, a temporary default axis with no labels and an + automatically adjusting range is created. This temporary axis is destroyed if another axis is explicitly set to the same orientation. */ /*! \qmlproperty ValueAxis3D Surface3D::axisY - The active Y axis. + The active y-axis. - If an axis is not given, a temporary default axis with no labels and automatically adjusting - range is created. + If an axis is not given, a temporary default axis with no labels and an + automatically adjusting range is created. This temporary axis is destroyed if another axis is explicitly set to the same orientation. */ /*! \qmlproperty ValueAxis3D Surface3D::axisZ - The active Z axis. + The active z-axis. - If an axis is not given, a temporary default axis with no labels and automatically adjusting - range is created. + If an axis is not given, a temporary default axis with no labels and an + automatically adjusting range is created. This temporary axis is destroyed if another axis is explicitly set to the same orientation. */ /*! * \qmlproperty Surface3DSeries Surface3D::selectedSeries - * The selected series or \c null. If \l {QAbstract3DGraph::selectionMode}{selectionMode} has + * The selected series or null. If \l {QAbstract3DGraph::selectionMode}{selectionMode} has the * \c SelectionMultiSeries flag set, this property holds the series which owns the selected point. */ @@ -114,5 +114,5 @@ /*! * \qmlmethod void Surface3D::removeSeries(Surface3DSeries series) - * Remove the \a series from the graph. + * Removes the \a series from the graph. */ diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc index 37a05d9d..72f2302c 100644 --- a/src/datavisualization/doc/src/qtdatavisualization.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc @@ -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. @@ -73,119 +73,6 @@ */ /*! - \group qtdatavisualization_getting_started - \title Qt Data Visualization Getting Started - - \section1 Installing the Qt Data Visualization Module - - Use the \c {Package Manager} in \c {Maintenance Tool} or the \c {Online installer} to install - the Qt Data Visualization module. The module can be found under \c {Qt Enterprise Add-Ons} - in the package manager. - - After installation Qt Data Visualization documentation and examples are available in Qt Creator. - Examples can be found on the examples page of Qt Creator by selecting the Qt Data Visualization - component from the drop-down menu. - - The source code is installed into the QtDataVisualization folder under EnterpriseAddOns. - - \section1 Building Qt Data Visualization - - To build the Qt Data Visualization module from source code yourself, set up a command prompt - with an environment for building Qt applications, navigate to the directory containing - \c {qtdatavisualization.pro}, and configure the project with qmake: - \code - qmake - \endcode - - After running qmake, build the project with make: - \table - \header - \li OS \li Make command - \row - \li Linux \li make - \row - \li Windows (MinGw) \li mingw32-make - \row - \li Windows (MSVC) \li nmake - \row - \li OS X \li make - \endtable - - The above generates the default makefiles for your configuration, which is typically - the release build if you are using precompiled binary Qt distribution. To build both debug - and release, or one specifically, use one of the following qmake lines instead. - - For debug builds: - \code - qmake CONFIG+=debug - make - \endcode - or - \code - qmake CONFIG+=debug_and_release - make debug - \endcode - - For release builds: - \code - qmake CONFIG+=release - make - \endcode - or - \code - qmake CONFIG+=debug_and_release - make release - \endcode - - For both builds (Windows/OS X only): - \code - qmake CONFIG+="debug_and_release build_all" - make - \endcode - - After building, install the module to your Qt directory: - \code - make install - \endcode - - If you want to uninstall the module: - \code - make uninstall - \endcode - - To build a statically linked version of the Qt Data Visualization module, give the following - commands: - - \snippet doc_src_qtdatavisualization.cpp 7 - - \section1 Creating a Simple Application - - To create a simple application, start by creating a new Qt Gui Application project in Qt - Creator and add this line to the \c .pro file of the project: - - \snippet doc_src_qtdatavisualization.pro 0 - - In the \c main.cpp file, include the module headers and declare namespace usage: - - \snippet doc_src_qtdatavisualization.cpp 0 - - Then, add the sample code found in one of the following pages, depending on what kind of - visualization you are interested in: - \l{How to construct a minimal Q3DBars graph}, - \l{How to construct a minimal Q3DScatter graph}, or - \l{How to construct a minimal Q3DSurface graph}. - - To use Qt Data Visualization graphs in widget based applications, you can use - the QWidget::createWindowContainer() function to wrap the graph into a widget: - - \snippet doc_src_qtdatavisualization.cpp 9 - - For further code examples, see one of the Qt Data Visualization examples: - - \annotatedlist qtdatavisualization_examples -*/ - -/*! \page qtdatavisualization_data_handling.html \title Qt Data Visualization Data Handling @@ -294,9 +181,27 @@ \section1 Interacting with Data - You can interact with the rendered graph with either mouse or touch to rotate, zoom, or select - data. For the default mouse controls, see Q3DInputHandler documentation, and for the default - touch controls, see QTouch3DInputHandler documentation. + End users can interact with the rendered graph by using either the mouse or + touch to rotate, zoom, or select data. Graphs can be rotated freely by + holding down the right mouse button and moving the mouse. Zooming is done by + rolling the mouse wheel. Selecting, if enabled, is done by pressing the left + mouse button. The scene can be reset to the default camera view by clicking + the mouse wheel. In touch devices, rotation is done by tap-and-move, + selection by tap-and-hold, and zoom by pinch. + + Qt Data Visualization has default handlers for mouse actions and touch + gestures. For the default mouse controls, see Q3DInputHandler, and for + the default touch controls, see QTouch3DInputHandler. The default handlers + must be disabled when using customized input handlers. + + The \l{Custom Input Example} illustrates how to use a custom input handler + to select items upon mouseover instead of mouse click. The information + below the mouse cursor is displayed as a popup. + + In addition to perspective projection, orthographic projection can be used + to create 2D graphs by replacing the default input handler with one that + does not allow rotating the graph and setting the camera to view the graph + directly from the side or from the top. \section1 Data Selection Modes @@ -324,10 +229,6 @@ \list \li Some platforms like Android and WinRT cannot handle multiple native windows properly, so only the Qt Quick 2 graphs are available in practice for those platforms. - \li Shadows are not supported with OpenGL ES2 (including Angle builds in Windows). - \li Anti-aliasing doesn't work with OpenGL ES2 (including Angle builds in Windows). - \li QCustom3DVolume items are not supported with OpenGL ES2 (including Angle builds in - Windows). \li Surfaces with non-straight rows and columns do not always render properly. \li Q3DLight class (and Light3D QML item) are currently not usable for anything. \li Changing most of Q3DScene properties affecting subviewports currently has no effect. @@ -337,13 +238,11 @@ "QT += datavisualization" in the pro file. This is because Qt Data Visualization QML plugin has a dependency to Qt Data Visualization C++ library, which Qt Creator doesn't automatically add to the deployment package. - \li Only OpenGL ES2 emulation is available for software renderer (that is, when using - QCoreApplication::setAttribute(Qt::AA_UseSoftwareOpenGL)) \endlist */ /*! - * \fn QSurfaceFormat QtDataVisualization::qDefaultSurfaceFormat(bool antialias = true) + * \fn QSurfaceFormat QtDataVisualization::qDefaultSurfaceFormat(bool antialias) * \relates QAbstract3DGraph * * This convenience function can be used to create a custom surface format suitable for use by @@ -352,7 +251,7 @@ * The \a antialias parameter specifies whether or not antialiasing is activated. * * Give the surface format returned by this function to the graph constructor (C++) or set - * it as the window format for QQuickView (QML) before calling show on it. + * it as the window format for QQuickView (QML) before calling \c show() on it. * * For example, disable antialiasing on C++ application: * diff --git a/src/datavisualization/engine/q3dbars.cpp b/src/datavisualization/engine/q3dbars.cpp index 3444bb0d..daeedf3c 100644 --- a/src/datavisualization/engine/q3dbars.cpp +++ b/src/datavisualization/engine/q3dbars.cpp @@ -122,13 +122,20 @@ Q3DBars::~Q3DBars() /*! * \property Q3DBars::primarySeries * - * Specifies the \a series that is the primary series of the graph. The primary series - * is used to determine the row and column axis labels when the labels are not explicitly + * \brief The primary series of the graph. + */ + +/*! + * Sets \a series as the primary series of the graph. The primary series + * determines the row and column axis labels when the labels are not explicitly * set to the axes. - * If the specified \a series is not already added to the graph, setting it as the + * + * If the specified series is not yet added to the graph, setting it as the * primary series will also implicitly add it to the graph. + * * If the primary series itself is removed from the graph, this property * resets to default. + * * If \a series is null, this property resets to default. * Defaults to the first added series or zero if no series are added to the graph. */ @@ -181,7 +188,7 @@ void Q3DBars::insertSeries(int index, QBar3DSeries *series) } /*! - * \return list of series added to this graph. + * Returns the list of series added to this graph. */ QList<QBar3DSeries *> Q3DBars::seriesList() const { @@ -191,9 +198,11 @@ QList<QBar3DSeries *> Q3DBars::seriesList() const /*! * \property Q3DBars::multiSeriesUniform * - * This property controls if bars are to be scaled with proportions set to a single series bar even - * if there are multiple series displayed. If set to \c {true}, \l{barSpacing}{bar spacing} will - * affect only X-axis correctly. It is preset to \c false by default. + * \brief Whether bars are to be scaled with proportions set to a single series + * bar even if there are multiple series displayed. + * + * If set to \c {true}, \l{barSpacing}{bar spacing} will be correctly applied + * only to the X-axis. Preset to \c false by default. */ void Q3DBars::setMultiSeriesUniform(bool uniform) { @@ -211,8 +220,10 @@ bool Q3DBars::isMultiSeriesUniform() const /*! * \property Q3DBars::barThickness * - * Bar thickness ratio between X and Z dimensions. 1.0 means bars are as wide as they are deep, 0.5 - * makes them twice as deep as they are wide. It is preset to \c 1.0 by default. + * \brief The bar thickness ratio between the X and Z dimensions. + * + * The value \c 1.0 means that the bars are as wide as they are deep, whereas + *\c 0.5 makes them twice as deep as they are wide. Preset to \c 1.0 by default. */ void Q3DBars::setBarThickness(float thicknessRatio) { @@ -231,8 +242,10 @@ float Q3DBars::barThickness() const /*! * \property Q3DBars::barSpacing * - * Bar spacing, which is the empty space between bars, in X and Z dimensions. It is preset to - * \c {(1.0, 1.0)} by default. Spacing is affected by barSpacingRelative -property. + * \brief Bar spacing in the X and Z dimensions. + * + * Preset to \c {(1.0, 1.0)} by default. Spacing is affected by the + * barSpacingRelative property. * * \sa barSpacingRelative, multiSeriesUniform */ @@ -252,9 +265,11 @@ QSizeF Q3DBars::barSpacing() const /*! * \property Q3DBars::barSpacingRelative * - * This is used to indicate if spacing is meant to be absolute or relative to bar thickness. - * If it is true, value of 0.0 means the bars are side-to-side and for example 1.0 means - * there is one thickness in between the bars. It is preset to \c true. + * \brief Whether spacing is absolute or relative to bar thickness. + * + * If it is \c true, the value of \c 0.0 means that the bars are placed + * side-to-side, \c 1.0 means that a space as wide as the thickness of one bar + * is left between the bars, and so on. Preset to \c true. */ void Q3DBars::setBarSpacingRelative(bool relative) { @@ -272,11 +287,16 @@ bool Q3DBars::isBarSpacingRelative() const /*! * \property Q3DBars::rowAxis * - * The active row \a axis. Implicitly calls addAxis() to transfer ownership of - * the \a axis to this graph. + * \brief The axis attached to the active row. + */ + +/*! + * Sets the axis of the active row to \a axis. Implicitly calls addAxis() to + * transfer the ownership of the axis to this graph. * - * If the \a axis is null, a temporary default axis with no labels is created. - * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation. + * If \a axis is null, a temporary default axis with no labels is created. + * This temporary axis is destroyed if another axis is set explicitly to the + * same orientation. * * \sa addAxis(), releaseAxis() */ @@ -293,11 +313,16 @@ QCategory3DAxis *Q3DBars::rowAxis() const /*! * \property Q3DBars::columnAxis * - * The active column \a axis. Implicitly calls addAxis() to transfer ownership of - * the \a axis to this graph. + * \brief The axis attached to the active column. + */ + +/*! + * Sets the axis of the active column to \a axis. Implicitly calls addAxis() to + * transfer the ownership of the axis to this graph. * - * If the \a axis is null, a temporary default axis with no labels is created. - * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation. + * If \a axis is null, a temporary default axis with no labels is created. + * This temporary axis is destroyed if another axis is set explicitly to the + * same orientation. * * \sa addAxis(), releaseAxis() */ @@ -314,12 +339,13 @@ QCategory3DAxis *Q3DBars::columnAxis() const /*! * \property Q3DBars::valueAxis * - * The active value \a axis (the Y-axis). Implicitly calls addAxis() to transfer ownership - * of the \a axis to this graph. + * Sets the active value axis (the Y-axis) to \a axis. Implicitly calls + * addAxis() to transfer the ownership of \a axis to this graph. * - * If the \a axis is null, a temporary default axis with no labels and automatically adjusting - * range is created. - * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation. + * If \a axis is null, a temporary default axis with no labels and + * an automatically adjusting range is created. + * This temporary axis is destroyed if another axis is set explicitly to the + * same orientation. * * \sa addAxis(), releaseAxis() */ @@ -336,8 +362,10 @@ QValue3DAxis *Q3DBars::valueAxis() const /*! * \property Q3DBars::selectedSeries * - * The selected series or \c null. If selectionMode has \c SelectionMultiSeries flag set, this - * property holds the series which owns the selected bar. + * \brief The selected series or a null value. + * + * If selectionMode has the \c SelectionMultiSeries flag set, this + * property holds the series that owns the selected bar. */ QBar3DSeries *Q3DBars::selectedSeries() const { @@ -347,8 +375,10 @@ QBar3DSeries *Q3DBars::selectedSeries() const /*! * \property Q3DBars::floorLevel * - * The desired floor level for the bar graph in Y-axis data coordinates. - * The actual floor level cannot go below Y-axis minimum or above Y-axis maximum. + * \brief The floor level for the bar graph in Y-axis data coordinates. + * + * The actual floor level will be restricted by the Y-axis minimum and maximum + * values. * Defaults to zero. */ void Q3DBars::setFloorLevel(float level) @@ -390,7 +420,7 @@ void Q3DBars::releaseAxis(QAbstract3DAxis *axis) } /*! - * \return list of all added axes. + * Returns the list of all added axes. * * \sa addAxis() */ diff --git a/src/datavisualization/engine/q3dcamera.cpp b/src/datavisualization/engine/q3dcamera.cpp index 5de68c28..1150870d 100644 --- a/src/datavisualization/engine/q3dcamera.cpp +++ b/src/datavisualization/engine/q3dcamera.cpp @@ -99,31 +99,31 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty float Camera3D::xRotation * - * This property contains the X-rotation angle of the camera around the target point in degrees + * The X-rotation angle of the camera around the target point in degrees * starting from the current base position. */ /*! * \qmlproperty float Camera3D::yRotation * - * This property contains the Y-rotation angle of the camera around the target point in degrees + * The Y-rotation angle of the camera around the target point in degrees * starting from the current base position. */ /*! * \qmlproperty Camera3D.CameraPreset Camera3D::cameraPreset * - * This property contains the currently active camera preset, which is one of - * \l{Q3DCamera::CameraPreset}{Camera3D.CameraPreset}. If no preset is active the value + * The currently active camera preset, which is one of + * \l{Q3DCamera::CameraPreset}{Camera3D.CameraPreset}. If no preset is active, the value * is \l{Q3DCamera::CameraPresetNone}{Camera3D.CameraPresetNone}. */ /*! * \qmlproperty float Camera3D::zoomLevel * - * This property contains the the camera zoom level in percentage. The default value of \c{100.0} + * The camera zoom level in percentage. The default value of \c{100.0} * means there is no zoom in or out set in the camera. - * The value is limited within the bounds defined by minZoomLevel and maxZoomLevel properties. + * The value is limited by the minZoomLevel and maxZoomLevel properties. * * \sa minZoomLevel, maxZoomLevel */ @@ -131,10 +131,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty float Camera3D::minZoomLevel * - * This property contains the the minimum allowed camera zoom level. - * If the new minimum level is more than the existing maximum level, the maximum level is + * Sets the minimum allowed camera zoom level. + * If the new minimum level is higher than the existing maximum level, the maximum level is * adjusted to the new minimum as well. - * If current zoomLevel is outside the new bounds, it is adjusted as well. + * If the current zoomLevel is outside the new bounds, it is adjusted as well. * The minZoomLevel cannot be set below \c{1.0}. * Defaults to \c{10.0}. * @@ -144,10 +144,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty float Camera3D::maxZoomLevel * - * This property contains the the maximum allowed camera zoom level. - * If the new maximum level is less than the existing minimum level, the minimum level is + * Sets the maximum allowed camera zoom level. + * If the new maximum level is lower than the existing minimum level, the minimum level is * adjusted to the new maximum as well. - * If current zoomLevel is outside the new bounds, it is adjusted as well. + * If the current zoomLevel is outside the new bounds, it is adjusted as well. * Defaults to \c{500.0f}. * * \sa zoomLevel, minZoomLevel @@ -156,30 +156,33 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty bool Camera3D::wrapXRotation * - * This property determines the behavior of the minimum and maximum limits in the X-rotation. - * By default the X-rotation wraps from minimum value to maximum and from maximum to minimum. + * The behavior of the minimum and maximum limits in the X-rotation. + * By default, the X-rotation wraps from minimum value to maximum and from + * maximum to minimum. * - * If set to \c true the X-rotation of the camera is wrapped from minimum to maximum and from maximum - * to minimum. If set to \c false the X-rotation of the camera is limited to the sector determined by - * minimum and maximum values. + * If set to \c true, the X-rotation of the camera is wrapped from minimum to + * maximum and from maximum to minimum. If set to \c false, the X-rotation of + * the camera is limited to the sector determined by the minimum and maximum + * values. */ /*! * \qmlproperty bool Camera3D::wrapYRotation * - * This property determines the behavior of the minimum and maximum limits in the Y-rotation. - * By default the Y-rotation is limited between the minimum and maximum values without any wrapping. + * The behavior of the minimum and maximum limits in the Y-rotation. + * By default, the Y-rotation is limited between the minimum and maximum values + * without any wrapping. * - * If \c true the Y-rotation of the camera is wrapped from minimum to maximum and from maximum - * to minimum. If \c false the Y-rotation of the camera is limited to the sector determined by minimum - * and maximum values. + * If \c true, the Y-rotation of the camera is wrapped from minimum to maximum + * and from maximum to minimum. If \c false, the Y-rotation of the camera is + * limited to the sector determined by the minimum and maximum values. */ /*! * \qmlproperty vector3d Camera3D::target * \since QtDataVisualization 1.2 * - * Holds the camera \a target as a vector3d. Defaults to \c {vector3d(0.0, 0.0, 0.0)}. + * The camera target as a vector3d. Defaults to \c {vector3d(0.0, 0.0, 0.0)}. * * Valid coordinate values are between \c{-1.0...1.0}, where the edge values indicate * the edges of the corresponding axis range. Any values outside this range are clamped to the edge. @@ -238,7 +241,7 @@ void Q3DCamera::copyValuesFrom(const Q3DObject &source) /*! * \property Q3DCamera::xRotation * - * This property contains the X-rotation angle of the camera around the target point in degrees. + * \brief The X-rotation angle of the camera around the target point in degrees. */ float Q3DCamera::xRotation() const { return d_ptr->m_xRotation; @@ -267,7 +270,7 @@ void Q3DCamera::setXRotation(float rotation) /*! * \property Q3DCamera::yRotation * - * This property contains the Y-rotation angle of the camera around the target point in degrees. + * \brief The Y-rotation angle of the camera around the target point in degrees. */ float Q3DCamera::yRotation() const { return d_ptr->m_yRotation; @@ -296,8 +299,9 @@ void Q3DCamera::setYRotation(float rotation) /*! * \property Q3DCamera::cameraPreset * - * This property contains the currently active camera preset, if no preset is active the value - * is CameraPresetNone. + * \brief The currently active camera preset. + * + * If no CameraPreset value is set, CameraPresetNone is used by default. */ Q3DCamera::CameraPreset Q3DCamera::cameraPreset() const { @@ -445,9 +449,10 @@ void Q3DCamera::setCameraPreset(CameraPreset preset) /*! * \property Q3DCamera::zoomLevel * - * This property contains the the camera zoom level in percentage. The default value of \c{100.0f} - * means there is no zoom in or out set in the camera. - * The value is limited within the bounds defined by minZoomLevel and maxZoomLevel properties. + * \brief The camera zoom level in percentage. + * + * The default value of \c{100.0f} means there is no zoom in or out set in the + * camera. The value is limited by the minZoomLevel and maxZoomLevel properties. * * \sa minZoomLevel, maxZoomLevel */ @@ -470,10 +475,11 @@ void Q3DCamera::setZoomLevel(float zoomLevel) /*! * \property Q3DCamera::minZoomLevel * - * This property contains the the minimum allowed camera zoom level. - * If the new minimum level is more than the existing maximum level, the maximum level is - * adjusted to the new minimum as well. - * If current zoomLevel is outside the new bounds, it is adjusted as well. + * \brief The minimum allowed camera zoom level. + * + * If the minimum level is set to a new value that is higher than the existing + * maximum level, the maximum level is adjusted to the new minimum as well. + * If the current zoomLevel is outside the new bounds, it is adjusted as well. * The minZoomLevel cannot be set below \c{1.0f}. * Defaults to \c{10.0f}. * @@ -501,10 +507,11 @@ void Q3DCamera::setMinZoomLevel(float zoomLevel) /*! * \property Q3DCamera::maxZoomLevel * - * This property contains the the maximum allowed camera zoom level. - * If the new maximum level is less than the existing minimum level, the minimum level is - * adjusted to the new maximum as well. - * If current zoomLevel is outside the new bounds, it is adjusted as well. + * \brief The maximum allowed camera zoom level. + * + * If the maximum level is set to a new value that is lower than the existing + * minimum level, the minimum level is adjusted to the new maximum as well. + * If the current zoomLevel is outside the new bounds, it is adjusted as well. * Defaults to \c{500.0f}. * * \sa zoomLevel, minZoomLevel @@ -531,12 +538,12 @@ void Q3DCamera::setMaxZoomLevel(float zoomLevel) /*! * \property Q3DCamera::wrapXRotation * - * This property determines the behavior of the minimum and maximum limits in the X-rotation. - * By default the X-rotation wraps from minimum value to maximum and from maximum to minimum. + * \brief The behavior of the minimum and maximum limits in the X-rotation. * - * If set to \c true the X-rotation of the camera is wrapped from minimum to maximum and from - * maximum to minimum. If set to \c false the X-rotation of the camera is limited to the sector - * determined by minimum and maximum values. + * If set to \c true, the X-rotation of the camera is wrapped from minimum to + * maximum and from maximum to minimum. If set to \c false, the X-rotation of + * the camera is limited to the sector determined by the minimum and maximum + * values. Set to \c true by default. */ bool Q3DCamera::wrapXRotation() const { @@ -551,12 +558,12 @@ void Q3DCamera::setWrapXRotation(bool isEnabled) /*! * \property Q3DCamera::wrapYRotation * - * This property determines the behavior of the minimum and maximum limits in the Y-rotation. - * By default the Y-rotation is limited between the minimum and maximum values without any wrapping. + * \brief The behavior of the minimum and maximum limits in the Y-rotation. * - * If \c true the Y-rotation of the camera is wrapped from minimum to maximum and from maximum to - * minimum. If \c false the Y-rotation of the camera is limited to the sector determined by minimum - * and maximum values. + * If \c true, the Y-rotation of the camera is wrapped from minimum to maximum + * and from maximum to minimum. If \c false, the Y-rotation of the camera is + * limited to the sector determined by the minimum and maximum values. + * Set to \c true by default. */ bool Q3DCamera::wrapYRotation() const { @@ -585,7 +592,9 @@ void Q3DCamera::setCameraPosition(float horizontal, float vertical, float zoom) * \property Q3DCamera::target * \since QtDataVisualization 1.2 * - * Holds the camera \a target as a QVector3D. Defaults to \c {QVector3D(0.0, 0.0, 0.0)}. + * \brief The camera target as a a vector or vertex in the 3D space. + * + * Defaults to \c {QVector3D(0.0, 0.0, 0.0)}. * * Valid coordinate values are between \c{-1.0...1.0}, where the edge values indicate * the edges of the corresponding axis range. Any values outside this range are clamped to the edge. @@ -677,7 +686,7 @@ void Q3DCameraPrivate::setYRotation(const float rotation) /*! * \internal - * This property contains the current minimum X-rotation for the camera. + * The current minimum X-rotation for the camera. * The full circle range is \c{[-180, 180]} and the minimum value is limited to \c -180. * Also the value can't be higher than the maximum, and is adjusted if necessary. * @@ -706,7 +715,7 @@ void Q3DCameraPrivate::setMinXRotation(float minRotation) /*! * \internal - * This property contains the current minimum Y-rotation for the camera. + * The current minimum Y-rotation for the camera. * The full Y angle range is \c{[-90, 90]} and the minimum value is limited to \c -90. * Also the value can't be higher than the maximum, and is adjusted if necessary. * @@ -735,7 +744,7 @@ void Q3DCameraPrivate::setMinYRotation(float minRotation) /*! * \internal - * This property contains the current maximum X-rotation for the camera. + * The current maximum X-rotation for the camera. * The full circle range is \c{[-180, 180]} and the maximum value is limited to \c 180. * Also the value can't be lower than the minimum, and is adjusted if necessary. * @@ -765,7 +774,7 @@ void Q3DCameraPrivate::setMaxXRotation(float maxRotation) /*! * \internal - * This property contains the current maximum Y-rotation for the camera. + * The current maximum Y-rotation for the camera. * The full Y angle range is \c{[-90, 90]} and the maximum value is limited to \c 90. * Also the value can't be lower than the minimum, and is adjusted if necessary. * @@ -823,7 +832,7 @@ void Q3DCameraPrivate::updateViewMatrix(float zoomAdjustment) /*! * \internal - * This property contains the view matrix used in the 3D calculations. When the default orbiting + * The view matrix used in the 3D calculations. When the default orbiting * camera behavior is sufficient, there is no need to touch this property. If the default * behavior is insufficient, the view matrix can be set directly. * \note When setting the view matrix directly remember to set viewMatrixAutoUpdateEnabled to diff --git a/src/datavisualization/engine/q3dlight.cpp b/src/datavisualization/engine/q3dlight.cpp index 8c439023..bce35d99 100644 --- a/src/datavisualization/engine/q3dlight.cpp +++ b/src/datavisualization/engine/q3dlight.cpp @@ -58,10 +58,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty bool Light3D::autoPosition * \since QtDataVisualization 1.3 - * Holds a flag telling if the light position is automatic or not. If true, light position follows - * camera automatically. + * Defines whether the light position follows the camera automatically. * \note Has no effect if shadows are enabled. Remember to disable shadows before setting light's - * position, or it will be overwritten by automatic positioning, if autoPosition is false. + * position, or it will be overwritten by automatic positioning if this + * property is \c false. */ /*! @@ -84,10 +84,10 @@ Q3DLight::~Q3DLight() /*! * \property Q3DLight::autoPosition * \since QtDataVisualization 5.9 - * Holds a flag telling if the light position is automatic or not. If true, light position follows - * camera automatically. + * \brief Whether the light position follows the camera automatically. * \note Has no effect if shadows are enabled. Remember to disable shadows before setting light's - * position, or it will be overwritten by automatic positioning, if isAutoPosition() is false. + * position, or it will be overwritten by automatic positioning if + * \c isAutoPosition() is \c false. */ void Q3DLight::setAutoPosition(bool enabled) { diff --git a/src/datavisualization/engine/q3dlight_p.h b/src/datavisualization/engine/q3dlight_p.h index afb3330b..6348deb9 100644 --- a/src/datavisualization/engine/q3dlight_p.h +++ b/src/datavisualization/engine/q3dlight_p.h @@ -57,8 +57,8 @@ public: void sync(Q3DLight &other); public: - bool m_automaticLight; Q3DLight *q_ptr; + bool m_automaticLight; }; QT_END_NAMESPACE_DATAVISUALIZATION diff --git a/src/datavisualization/engine/q3dobject.cpp b/src/datavisualization/engine/q3dobject.cpp index f7757293..099fa2f0 100644 --- a/src/datavisualization/engine/q3dobject.cpp +++ b/src/datavisualization/engine/q3dobject.cpp @@ -35,10 +35,11 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! \class Q3DObject \inmodule QtDataVisualization - \brief Simple baseclass for all the objects in the 3D scene. + \brief The Q3DObject class is a simple base class for all the objects in a + 3D scene. \since QtDataVisualization 1.0 - Q3DObject is a baseclass that contains only position information for an object in 3D scene. + Contains position information for an object in a 3D scene. The object is considered to be a single point in the coordinate space without dimensions. */ @@ -48,25 +49,26 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION \since QtDataVisualization 1.0 \ingroup datavisualization_qml \instantiates Q3DObject - \brief Simple baseclass for all the objects in the 3D scene. + \brief A base type for all the objects in a 3D scene. - Object3D is an uncreatable base type that contains only position information for an object in - 3D scene. The object is considered to be a single point in the coordinate space without + An uncreatable base type that contains position information for an object in + a 3D scene. The object is considered to be a single point in the coordinate space without dimensions. */ /*! * \qmlproperty vector3d Object3D::position * - * This property contains the 3D position of the object. + * The 3D position of the object. * * \note Currently setting this property has no effect for Camera3D, as the position is handled * internally. */ /*! - * Constructs a new 3D object with position set to origin by default. An - * optional \a parent parameter can be given and is then passed to QObject constructor. + * Constructs a new 3D object with the position set to origin by default. An + * optional \a parent parameter can be given and is then passed to the QObject + * constructor. */ Q3DObject::Q3DObject(QObject *parent) : QObject(parent), @@ -93,8 +95,9 @@ void Q3DObject::copyValuesFrom(const Q3DObject &source) /*! * \property Q3DObject::parentScene * - * This property contains the parent scene as read only value. - * If the object has no parent scene the value is 0. + * \brief The parent scene as a read only value. + * + * If the object has no parent scene, the value is 0. */ Q3DScene *Q3DObject::parentScene() { @@ -104,7 +107,7 @@ Q3DScene *Q3DObject::parentScene() /*! * \property Q3DObject::position * - * This property contains the 3D position of the object. + * \brief The 3D position of the object. * * \note Currently setting this property has no effect for Q3DCamera, as the position is handled * internally. @@ -124,8 +127,7 @@ void Q3DObject::setPosition(const QVector3D &position) } /*! - * Sets and clears the \a dirty flag that is used to track - * when the 3D object has changed since last update. + * Sets \a dirty to \c true if the 3D object has changed since the last update. */ void Q3DObject::setDirty(bool dirty) { @@ -135,7 +137,7 @@ void Q3DObject::setDirty(bool dirty) } /*! - * \return flag that indicates if the 3D object has changed. + * Returns whether the 3D object has changed. */ bool Q3DObject::isDirty() const { diff --git a/src/datavisualization/engine/q3dscatter.cpp b/src/datavisualization/engine/q3dscatter.cpp index 26325b33..b16b2513 100644 --- a/src/datavisualization/engine/q3dscatter.cpp +++ b/src/datavisualization/engine/q3dscatter.cpp @@ -125,7 +125,7 @@ void Q3DScatter::removeSeries(QScatter3DSeries *series) } /*! - * \return list of series added to this graph. + * Returns the list of series added to this graph. */ QList<QScatter3DSeries *> Q3DScatter::seriesList() const { @@ -145,12 +145,17 @@ const Q3DScatterPrivate *Q3DScatter::dptrc() const /*! * \property Q3DScatter::axisX * - * The active X-axis. Implicitly calls addAxis() to transfer ownership - * of the \a axis to this graph. + * \brief The active x-axis. + */ + +/*! + * Sets \a axis as the active x-axis. Implicitly calls addAxis() to transfer the + * ownership of the axis to this graph. * - * If the \a axis is null, a temporary default axis with no labels and automatically adjusting + * If \a axis is null, a temporary default axis with no labels and an automatically adjusting * range is created. - * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation. + * This temporary axis is destroyed if another axis is set explicitly to the + * same orientation. * * \sa addAxis(), releaseAxis() */ @@ -167,12 +172,17 @@ QValue3DAxis *Q3DScatter::axisX() const /*! * \property Q3DScatter::axisY * - * The active Y-axis. Implicitly calls addAxis() to transfer ownership - * of the \a axis to this graph. + * \brief The active y-axis. + */ + +/*! + * Sets \a axis as the active y-axis. Implicitly calls addAxis() to transfer the + * ownership of the axis to this graph. * - * If the \a axis is null, a temporary default axis with no labels and automatically adjusting + * If \a axis is null, a temporary default axis with no labels and an automatically adjusting * range is created. - * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation. + * This temporary axis is destroyed if another axis is set explicitly to the + * same orientation. * * \sa addAxis(), releaseAxis() */ @@ -189,12 +199,17 @@ QValue3DAxis *Q3DScatter::axisY() const /*! * \property Q3DScatter::axisZ * - * The active Z-axis. Implicitly calls addAxis() to transfer ownership - * of the \a axis to this graph. + * \brief The active z-axis. + */ + +/*! + * Sets \a axis as the active z-axis. Implicitly calls addAxis() to transfer the + * ownership of the axis to this graph. * - * If the \a axis is null, a temporary default axis with no labels and automatically adjusting + * If \a axis is null, a temporary default axis with no labels and an automatically adjusting * range is created. - * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation. + * This temporary axis is destroyed if another axis is set explicitly to the + * same orientation. * * \sa addAxis(), releaseAxis() */ @@ -204,7 +219,7 @@ void Q3DScatter::setAxisZ(QValue3DAxis *axis) } /*! - * \return used Z-axis. + * Returns the used z-axis. */ QValue3DAxis *Q3DScatter::axisZ() const { @@ -214,7 +229,7 @@ QValue3DAxis *Q3DScatter::axisZ() const /*! * \property Q3DScatter::selectedSeries * - * The selected series or \c null. + * \brief The selected series or null. */ QScatter3DSeries *Q3DScatter::selectedSeries() const { @@ -247,7 +262,7 @@ void Q3DScatter::releaseAxis(QValue3DAxis *axis) } /*! - * \return list of all added axes. + * Returns the list of all added axes. * * \sa addAxis() */ diff --git a/src/datavisualization/engine/q3dscene.cpp b/src/datavisualization/engine/q3dscene.cpp index 93056bfc..75437c9c 100644 --- a/src/datavisualization/engine/q3dscene.cpp +++ b/src/datavisualization/engine/q3dscene.cpp @@ -79,50 +79,55 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty rect Scene3D::viewport * - * This property contains the current viewport rectangle where all 3D rendering - * is targeted. + * The current viewport rectangle where all 3D rendering is targeted. */ /*! * \qmlproperty rect Scene3D::primarySubViewport * - * This property contains the current subviewport rectangle inside the viewport where the - * primary view of the data visualization is targeted to. If slicingActive is false, it will be - * equal to viewport. If slicingActive is true and it hasn't been explicitly set, it will be one - * fifth of viewport. + * The current subviewport rectangle inside the viewport where the + * primary view of the data visualization is targeted. + * + * If slicingActive is \c false, the primary sub viewport will be equal to the + * viewport. If slicingActive is \c true and the primary sub viewport has not + * been explicitly set, it will be one fifth of the viewport. * \note Setting primarySubViewport larger than or outside of viewport resizes viewport accordingly. */ /*! * \qmlproperty rect Scene3D::secondarySubViewport * - * This property contains the secondary viewport rectangle inside the viewport. The secondary - * viewport is used for drawing the 2D slice view in some visualizations. If it hasn't been - * explicitly set, it will be null, or viewport if slicingActive is true. - * \note Setting secondarySubViewport larger than or outside of viewport resizes viewport accordingly. - */ + * The secondary viewport rectangle inside the viewport. The secondary viewport + * is used for drawing the 2D slice view in some visualizations. If it has not + * been explicitly set, it will be null. If slicingActive is \c true, it will + * be equal to the viewport. + * \note If the secondary sub viewport is larger than or outside of the + * viewport, the viewport is resized accordingly. +*/ /*! * \qmlproperty point Scene3D::selectionQueryPosition * - * This property contains the coordinates for the user input that should be processed - * by the scene as selection. If this is set to value other than invalidSelectionPoint the + * The coordinates for the user input that should be processed + * by the scene as a selection. If this property is set to a value other than + * invalidSelectionPoint, the * graph tries to select a data item at the given point within the primary viewport. - * After the rendering pass the property is returned to its default state of invalidSelectionPoint. + * After the rendering pass, the property is returned to its default state of + * invalidSelectionPoint. */ /*! * \qmlproperty point Scene3D::graphPositionQuery * - * This property contains the coordinates for the user input that should be processed - * by the scene as a graph position query. If this is set to value other than - * invalidSelectionPoint, the graph tries to match a graph position to the given \a point + * The coordinates for the user input that should be processed by the scene as a + * graph position query. If this property is set to value other than + * invalidSelectionPoint, the graph tries to match a graph position to the given point * within the primary viewport. - * After the rendering pass this property is returned to its default state of - * invalidSelectionPoint. The queried graph position can be read from + * After the rendering pass, this property is returned to its default state of + * invalidSelectionPoint. The queried graph position can be read from the * AbstractGraph3D::queriedGraphPosition property after the next render pass. * - * There isn't a single correct 3D coordinate to match to each specific screen position, so to be + * There is no single correct 3D coordinate to match a particular screen position, so to be * consistent, the queries are always done against the inner sides of an invisible box surrounding * the graph. * @@ -134,39 +139,40 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty bool Scene3D::slicingActive * - * This property contains whether 2D slicing view is currently active or not. If setting it, you - * must make sure AbstractGraph3D::selectionMode has either + * Defines whether the 2D slicing view is currently active. If \c true, + * AbstractGraph3D::selectionMode must have either the * \l{QAbstract3DGraph::SelectionRow}{AbstractGraph3D.SelectionRow} or - * \l{QAbstract3DGraph::SelectionColumn}{AbstractGraph3D.SelectionColumn} flag set, and there is a - * valid selection. + * \l{QAbstract3DGraph::SelectionColumn}{AbstractGraph3D.SelectionColumn} + * set to a valid selection. * \note Not all visualizations support the 2D slicing view. */ /*! * \qmlproperty bool Scene3D::secondarySubviewOnTop * - * This property contains whether 2D slicing view is currently drawn on top or if the 3D view is - * drawn on top. + * Defines whether the 2D slicing view or the 3D view is drawn on top. */ /*! * \qmlproperty Camera3D Scene3D::activeCamera * - * This property contains the currently active camera in the 3D scene. - * When a Camera3D is set in the property it gets automatically added as child of the scene. + * The currently active camera in the 3D scene. + * When a Camera3D is set in the property, it is automatically added as child of + * the scene. */ /*! * \qmlproperty Light3D Scene3D::activeLight * - * This property contains the currently active light in the 3D scene. - * When a Light3D is set in the property it gets automatically added as child of the scene. + * The currently active light in the 3D scene. + * When a Light3D is set in the property, it is automatically added as child of + * the scene. */ /*! * \qmlproperty float Scene3D::devicePixelRatio * - * This property contains the current device pixel ratio that is used when mapping input + * The current device pixel ratio that is used when mapping input * coordinates to pixel coordinates. */ @@ -197,8 +203,8 @@ Q3DScene::~Q3DScene() /*! * \property Q3DScene::viewport * - * This read only property contains the current viewport rectangle where all 3D rendering - * is targeted. + * \brief A read only property that contains the current viewport rectangle + * where all the 3D rendering is targeted. */ QRect Q3DScene::viewport() const { @@ -208,11 +214,15 @@ QRect Q3DScene::viewport() const /*! * \property Q3DScene::primarySubViewport * - * This property contains the current subviewport rectangle inside the viewport where the - * primary view of the data visualization is targeted to. If isSlicingActive() is false, it will be - * equal to viewport(). If isSlicingActive() is true and it hasn't been explicitly set, it will be - * one fifth of viewport(). - * \note Setting primarySubViewport larger than or outside of viewport resizes viewport accordingly. + * \brief The current subviewport rectangle inside the viewport where the + * primary view of the data visualization is targeted. + * + * If isSlicingActive() is \c false, the primary sub viewport is equal to + * viewport(). If isSlicingActive() is \c true and the primary sub viewport has + * not been explicitly set, it will be one fifth of viewport(). + * + * \note Setting primarySubViewport larger than or outside of the viewport + * resizes the viewport accordingly. */ QRect Q3DScene::primarySubViewport() const { @@ -293,10 +303,13 @@ bool Q3DScene::isPointInSecondarySubView(const QPoint &point) /*! * \property Q3DScene::secondarySubViewport * - * This property contains the secondary viewport rectangle inside the viewport. The secondary - * viewport is used for drawing the 2D slice view in some visualizations. If it hasn't been - * explicitly set, it will be equal to QRect(), or viewport() if isSlicingActive() is true. - * \note Setting secondarySubViewport larger than or outside of viewport resizes viewport accordingly. + * \brief The secondary viewport rectangle inside the viewport. + * + * The secondary viewport is used for drawing the 2D slice view in some + * visualizations. If it has not been explicitly set, it will be equal to + * QRect. If isSlicingActive() is \c true, it will be equal to \l viewport. + * \note If the secondary sub viewport is larger than or outside of the + * viewport, the viewport is resized accordingly. */ QRect Q3DScene::secondarySubViewport() const { @@ -341,11 +354,13 @@ void Q3DScene::setSecondarySubViewport(const QRect &secondarySubViewport) /*! * \property Q3DScene::selectionQueryPosition * - * This property contains the coordinates for the user input that should be processed - * by the scene as a selection. If this is set to value other than invalidSelectionPoint(), the - * graph tries to select a data item, axis label, or a custom item at the given \a point within - * the primary viewport. - * After the rendering pass the property is returned to its default state of + * \brief The coordinates for the user input that should be processed + * by the scene as a selection. + * + * If this property is set to a value other than invalidSelectionPoint(), the + * graph tries to select a data item, axis label, or a custom item at the + * specified coordinates within the primary viewport. + * After the rendering pass, the property is returned to its default state of * invalidSelectionPoint(). * * \sa QAbstract3DGraph::selectedElement @@ -379,15 +394,17 @@ QPoint Q3DScene::invalidSelectionPoint() /*! * \property Q3DScene::graphPositionQuery * - * This property contains the coordinates for the user input that should be processed - * by the scene as a graph position query. If this is set to value other than - * invalidSelectionPoint(), the graph tries to match a graph position to the given \a point + * \brief The coordinates for the user input that should be processed + * by the scene as a graph position query. + * + * If this property is set to a value other than invalidSelectionPoint(), the + * graph tries to match a graph position to the specified coordinates * within the primary viewport. - * After the rendering pass this property is returned to its default state of - * invalidSelectionPoint(). The queried graph position can be read from + * After the rendering pass, this property is returned to its default state of + * invalidSelectionPoint(). The queried graph position can be read from the * QAbstract3DGraph::queriedGraphPosition property after the next render pass. * - * There isn't a single correct 3D coordinate to match to each specific screen position, so to be + * There is no single correct 3D coordinate to match a particular screen position, so to be * consistent, the queries are always done against the inner sides of an invisible box surrounding * the graph. * @@ -415,9 +432,11 @@ QPoint Q3DScene::graphPositionQuery() const /*! * \property Q3DScene::slicingActive * - * This property contains whether 2D slicing view is currently active or not. If setting it, you - * must make sure QAbstract3DGraph::selectionMode has either QAbstract3DGraph::SelectionRow or - * QAbstract3DGraph::SelectionColumn flag set, and there is a valid selection. + * \brief Whether the 2D slicing view is currently active. + * + * If \c true, QAbstract3DGraph::selectionMode must have either + * QAbstract3DGraph::SelectionRow or QAbstract3DGraph::SelectionColumn set + * to a valid selection. * \note Not all visualizations support the 2D slicing view. */ bool Q3DScene::isSlicingActive() const @@ -445,8 +464,7 @@ void Q3DScene::setSlicingActive(bool isSlicing) /*! * \property Q3DScene::secondarySubviewOnTop * - * This property contains whether 2D slicing view is currently drawn on top or if the 3D view is - * drawn on top. + * \brief Whether the 2D slicing view or the 3D view is drawn on top. */ bool Q3DScene::isSecondarySubviewOnTop() const { @@ -468,8 +486,9 @@ void Q3DScene::setSecondarySubviewOnTop(bool isSecondaryOnTop) /*! * \property Q3DScene::activeCamera * - * This property contains the currently active camera in the 3D scene. - * When a new Q3DCamera objects is set in the property it gets automatically added as child of + * \brief The currently active camera in the 3D scene. + * + * When a new Q3DCamera object is set, it is automatically added as child of * the scene. */ Q3DCamera *Q3DScene::activeCamera() const @@ -517,8 +536,9 @@ void Q3DScene::setActiveCamera(Q3DCamera *camera) /*! * \property Q3DScene::activeLight * - * This property contains the currently active light in the 3D scene. - * When a new Q3DLight objects is set in the property it gets automatically added as child of + * \brief The currently active light in the 3D scene. + * + * When a new Q3DLight objects is set, it is automatically added as child of * the scene. */ Q3DLight *Q3DScene::activeLight() const @@ -547,7 +567,7 @@ void Q3DScene::setActiveLight(Q3DLight *light) /*! * \property Q3DScene::devicePixelRatio * - * This property contains the current device pixel ratio that is used when mapping input + * \brief The device pixel ratio that is used when mapping input * coordinates to pixel coordinates. */ float Q3DScene::devicePixelRatio() const diff --git a/src/datavisualization/engine/q3dsurface.cpp b/src/datavisualization/engine/q3dsurface.cpp index e4fc2221..f3fac1c7 100644 --- a/src/datavisualization/engine/q3dsurface.cpp +++ b/src/datavisualization/engine/q3dsurface.cpp @@ -142,7 +142,7 @@ void Q3DSurface::removeSeries(QSurface3DSeries *series) } /*! - * \return list of series added to this graph. + * Returns the list of series added to this graph. */ QList<QSurface3DSeries *> Q3DSurface::seriesList() const { @@ -162,12 +162,18 @@ const Q3DSurfacePrivate *Q3DSurface::dptrc() const /*! * \property Q3DSurface::axisX * - * The active X-axis. Implicitly calls addAxis() to transfer ownership - * of the \a axis to this graph. + * \brief The active x-axis. + */ + +/*! + * Sets \a axis as the active x-axis. Implicitly calls addAxis() to transfer the + * ownership of the axis to this graph. * - * If the \a axis is null, a temporary default axis with no labels and automatically adjusting - * range is created. - * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation. + * If \a axis is null, a temporary default axis with no labels and an + * automatically adjusting range is created. + * + * This temporary axis is destroyed if another axis is set explicitly to the + * same orientation. * * \sa addAxis(), releaseAxis() */ @@ -176,9 +182,6 @@ void Q3DSurface::setAxisX(QValue3DAxis *axis) dptr()->m_shared->setAxisX(axis); } -/*! - * \return used X-axis. - */ QValue3DAxis *Q3DSurface::axisX() const { return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisX()); @@ -187,12 +190,18 @@ QValue3DAxis *Q3DSurface::axisX() const /*! * \property Q3DSurface::axisY * - * The active Y-axis. Implicitly calls addAxis() to transfer ownership - * of the \a axis to this graph. + * \brief The active y-axis. + */ + +/*! + * Sets \a axis as the active y-axis. Implicitly calls addAxis() to transfer the + * ownership of the axis to this graph. + * + * If \a axis is null, a temporary default axis with no labels and an + * automatically adjusting range is created. * - * If the \a axis is null, a temporary default axis with no labels and automatically adjusting - * range is created. - * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation. + * This temporary axis is destroyed if another axis is set explicitly to the + * same orientation. * * \sa addAxis(), releaseAxis() */ @@ -201,9 +210,6 @@ void Q3DSurface::setAxisY(QValue3DAxis *axis) dptr()->m_shared->setAxisY(axis); } -/*! - * \return used Y-axis. - */ QValue3DAxis *Q3DSurface::axisY() const { return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisY()); @@ -212,12 +218,18 @@ QValue3DAxis *Q3DSurface::axisY() const /*! * \property Q3DSurface::axisZ * - * The active Z-axis. Implicitly calls addAxis() to transfer ownership - * of the \a axis to this graph. + * \brief The active z-axis. + */ + +/*! + * Sets \a axis as the active z-axis. Implicitly calls addAxis() to transfer the + * ownership of the axis to this graph. + * + * If \a axis is null, a temporary default axis with no labels and an + * automatically adjusting range is created. * - * If the \a axis is null, a temporary default axis with no labels and automatically adjusting - * range is created. - * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation. + * This temporary axis is destroyed if another axis is set explicitly to the + * same orientation. * * \sa addAxis(), releaseAxis() */ @@ -226,9 +238,6 @@ void Q3DSurface::setAxisZ(QValue3DAxis *axis) dptr()->m_shared->setAxisZ(axis); } -/*! - * \return used Z-axis. - */ QValue3DAxis *Q3DSurface::axisZ() const { return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisZ()); @@ -237,7 +246,9 @@ QValue3DAxis *Q3DSurface::axisZ() const /*! * \property Q3DSurface::selectedSeries * - * The selected series or \c null. If selectionMode has \c SelectionMultiSeries flag set, this + * \brief The selected series or null. + * + * If selectionMode has \c SelectionMultiSeries set, this * property holds the series which owns the selected point. */ QSurface3DSeries *Q3DSurface::selectedSeries() const @@ -249,6 +260,9 @@ QSurface3DSeries *Q3DSurface::selectedSeries() const * \property Q3DSurface::flipHorizontalGrid * \since QtDataVisualization 1.2 * + * \brief Whether the horizontal axis grid is displayed on top of the graph + * rather than on the bottom. + * * In some use cases the horizontal axis grid is mostly covered by the surface, so it can be more * useful to display the horizontal axis grid on top of the graph rather than on the bottom. * A typical use case for this is showing 2D spectrograms using orthoGraphic projection with @@ -296,7 +310,7 @@ void Q3DSurface::releaseAxis(QValue3DAxis *axis) } /*! - * \return list of all added axes. + * Returns the list of all added axes. * * \sa addAxis() */ diff --git a/src/datavisualization/engine/qabstract3dgraph.cpp b/src/datavisualization/engine/qabstract3dgraph.cpp index 50ccef00..dfedacd0 100644 --- a/src/datavisualization/engine/qabstract3dgraph.cpp +++ b/src/datavisualization/engine/qabstract3dgraph.cpp @@ -143,15 +143,15 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION \value ElementNone No defined element. \value ElementSeries - A series (i.e. an item in a series). + A series (that is, an item in a series). \value ElementAxisXLabel - X axis label. + The x-axis label. \value ElementAxisYLabel - Y axis label. + The y-axis label. \value ElementAxisZLabel - Z axis label. + The z-axis label. \value ElementCustomItem - Custom item. + A custom item. */ /*! @@ -269,10 +269,15 @@ void QAbstract3DGraph::releaseInputHandler(QAbstract3DInputHandler *inputHandler /*! * \property QAbstract3DGraph::activeInputHandler * - * The active \a inputHandler used in the graph. Implicitly calls addInputHandler() to transfer - * ownership of the \a inputHandler to this graph. + * \brief The active input handler used in the graph. + */ + +/*! + * Sets \a inputHandler as the active input handler used in the graph. + * Implicitly calls addInputHandler() to transfer ownership of \a inputHandler + * to this graph. * - * If the \a inputHandler is null, no input handler will be active after this call. + * If \a inputHandler is null, no input handler will be active after this call. * * \sa addInputHandler(), releaseInputHandler() */ @@ -287,7 +292,7 @@ QAbstract3DInputHandler *QAbstract3DGraph::activeInputHandler() const } /*! - * \return list of all added input handlers. + * Returns the list of all added input handlers. * * \sa addInputHandler() */ @@ -298,7 +303,7 @@ QList<QAbstract3DInputHandler *> QAbstract3DGraph::inputHandlers() const /*! * Adds the given \a theme to the graph. The themes added via addTheme are not taken in to use - * directly. Only the ownership of the a\ theme is given to the graph. + * directly. Only the ownership of the theme is given to the graph. * The \a theme must not be null or already added to another graph. * * \sa releaseTheme(), setActiveTheme() @@ -324,11 +329,16 @@ void QAbstract3DGraph::releaseTheme(Q3DTheme *theme) /*! * \property QAbstract3DGraph::activeTheme * - * The active \a theme to be used for the graph. Implicitly calls addTheme() to transfer ownership - * of the \a theme to this graph. - * If the \a theme is null, a temporary default theme is created. This temporary theme is destroyed + * \brief The active theme of the graph. + */ + +/*! + * Sets \a theme as the active theme to be used for the graph. Implicitly calls + * addTheme() to transfer the ownership of the theme to this graph. + * + * If \a theme is null, a temporary default theme is created. This temporary theme is destroyed * if any theme is explicitly set later. - * Properties of the \a theme can be modified even after setting it, and the modifications take + * Properties of the theme can be modified even after setting it, and the modifications take * effect immediately. */ void QAbstract3DGraph::setActiveTheme(Q3DTheme *theme) @@ -343,7 +353,7 @@ Q3DTheme *QAbstract3DGraph::activeTheme() const } /*! - * \return list of all added themes. + * Returns the list of all added themes. * * \sa addTheme() */ @@ -355,10 +365,12 @@ QList<Q3DTheme *> QAbstract3DGraph::themes() const /*! * \property QAbstract3DGraph::selectionMode * - * Sets selection \a mode to a combination of SelectionFlags. It is preset to - * \c SelectionItem by default. - * Different graph types support different selection modes. See SelectionFlags - * documentation for details. + * \brief Item selection mode. + * + * A combination of SelectionFlags. By default, \c SelectionItem. + * Different graph types support different selection modes. + * + * \sa SelectionFlags */ void QAbstract3DGraph::setSelectionMode(SelectionFlags mode) { @@ -373,12 +385,15 @@ QAbstract3DGraph::SelectionFlags QAbstract3DGraph::selectionMode() const /*! * \property QAbstract3DGraph::shadowQuality * - * Sets the shadow \a quality to one of the ShadowQuality enum values. It is preset to - * \c ShadowQualityMedium by default. + * \brief The quality of the shadow. + * + * One of the ShadowQuality enum values. By default, \c ShadowQualityMedium. * * \note If setting the shadow quality to a certain level fails, the level is lowered - * until it is successfully set. The \c shadowQualityChanged signal is emitted for each time - * a change is done. + * until it is successfully set. The \c shadowQualityChanged signal is emitted each time + * a change is made. + * + * \sa ShadowQuality */ void QAbstract3DGraph::setShadowQuality(ShadowQuality quality) { @@ -391,7 +406,7 @@ QAbstract3DGraph::ShadowQuality QAbstract3DGraph::shadowQuality() const } /*! - * \return true if shadows are supported with the current configuration. + * Returns \c true if shadows are supported with the current configuration. * OpenGL ES2 configurations do not support shadows. */ bool QAbstract3DGraph::shadowsSupported() const @@ -402,8 +417,10 @@ bool QAbstract3DGraph::shadowsSupported() const /*! * \property QAbstract3DGraph::scene * - * This property is read-only and contains the Q3DScene pointer that can be used to manipulate - * the scene and access the scene elements, such as the active camera. + * \brief The Q3DScene pointer that can be used to manipulate the scene and + * access the scene elements, such as the active camera. + * + * This property is read-only. */ Q3DScene *QAbstract3DGraph::scene() const { @@ -421,8 +438,9 @@ void QAbstract3DGraph::clearSelection() /*! * Adds a QCustom3DItem \a item to the graph. Graph takes ownership of the added item. * - * \return index to the added item if add was successful, -1 if trying to add a null item, and - * index of the item if trying to add an already added item. + * Returns the index to the added item if the add operation was successful, -1 + * if trying to add a null item, and the index of the item if trying to add an + * already added item. * * \sa removeCustomItems(), removeCustomItem(), removeCustomItemAt(), customItems() * @@ -479,7 +497,7 @@ void QAbstract3DGraph::releaseCustomItem(QCustom3DItem *item) } /*! - * \return list of all added custom items. + * Returns the list of all added custom items. * \since QtDataVisualization 1.2 * \sa addCustomItem() */ @@ -492,7 +510,7 @@ QList<QCustom3DItem *> QAbstract3DGraph::customItems() const * Can be used to query the index of the selected label after receiving \c selectedElementChanged * signal with any label type. Selection is valid until the next \c selectedElementChanged signal. * - * \return index of the selected label, or -1. + * Returns the index of the selected label, or -1. * * \since QtDataVisualization 1.1 * @@ -507,7 +525,7 @@ int QAbstract3DGraph::selectedLabelIndex() const * Can be used to get the selected axis after receiving \c selectedElementChanged signal with any label * type. Selection is valid until the next \c selectedElementChanged signal. * - * \return pointer to the selected axis, or null. + * Returns the pointer to the selected axis, or null. * * \since QtDataVisualization 1.1 * @@ -523,7 +541,7 @@ QAbstract3DAxis *QAbstract3DGraph::selectedAxis() const * signal with QAbstract3DGraph::ElementCustomItem type. Selection is valid until the next * \c selectedElementChanged signal. * - * \return index of the selected custom item, or -1. + * Returns the index of the selected custom item, or -1. * * \since QtDataVisualization 1.1 * @@ -539,7 +557,7 @@ int QAbstract3DGraph::selectedCustomItemIndex() const * QAbstract3DGraph::ElementCustomItem type. Ownership of the item remains with the graph. * Selection is valid until the next \c selectedElementChanged signal. * - * \return pointer to the selected custom item, or null. + * Returns the pointer to the selected custom item, or null. * * \since QtDataVisualization 1.1 * @@ -553,13 +571,14 @@ QCustom3DItem *QAbstract3DGraph::selectedCustomItem() const /*! * \property QAbstract3DGraph::selectedElement * - * Can be used to query the selected element type. - * Type is valid until the next \c selectedElementChanged signal. + * \brief The element selected in the graph. * - * \c selectedElementChanged signal is emitted when a selection is made in the graph. + * This property can be used to query the selected element type. The type is + * valid until a new selection is made in the graph and the + * \c selectedElementChanged signal is emitted. * - * Signal can be used for example for implementing custom input handlers, as demonstrated in this - * \l {Axis Range Dragging With Labels Example}{example}. + * The signal can be used for example for implementing custom input handlers, as + * demonstrated by the \l {Axis Range Dragging With Labels Example}. * * \sa selectedLabelIndex(), selectedAxis(), selectedCustomItemIndex(), selectedCustomItem(), * Q3DBars::selectedSeries(), Q3DScatter::selectedSeries(), Q3DSurface::selectedSeries(), @@ -578,7 +597,7 @@ QAbstract3DGraph::ElementType QAbstract3DGraph::selectedElement() const * * \since QtDataVisualization 1.1 * - * \return rendered image. + * Returns the rendered image. * * \note OpenGL ES2 does not support anitialiasing, so \a msaaSamples is always forced to \c{0}. */ @@ -594,8 +613,10 @@ QImage QAbstract3DGraph::renderToImage(int msaaSamples, const QSize &imageSize) * \property QAbstract3DGraph::measureFps * \since QtDataVisualization 1.1 * - * If \c {true}, the rendering is done continuously instead of on demand, and currentFps property - * is updated. Defaults to \c{false}. + * \brief Whether rendering is done continuously instead of on demand. + * + * If \c {true}, rendering is continuous and the value of the currentFps + * property is updated. Defaults to \c{false}. * * \sa currentFps */ @@ -613,8 +634,11 @@ bool QAbstract3DGraph::measureFps() const * \property QAbstract3DGraph::currentFps * \since QtDataVisualization 1.1 * - * When fps measuring is enabled, the results for the last second are stored in this read-only - * property. It takes at least a second before this value updates after measurement is activated. + * \brief The rendering results for the last second. + * + * The results are stored in this read-only property when FPS measuring is + * enabled. It takes at least a second before this value is updated after + * measuring is activated. * * \sa measureFps */ @@ -627,9 +651,11 @@ qreal QAbstract3DGraph::currentFps() const * \property QAbstract3DGraph::orthoProjection * \since QtDataVisualization 1.1 * - * If \c {true}, orthographic projection will be used for displaying the graph. - * \note Orthographic projection can be used to create 2D graphs by replacing the default input - * handler with one that doesn't allow rotating the graph and setting the camera to view the graph + * \brief Whether orthographic projection is used for displaying the graph. + * + * If \c {true}, ortographic projection is used to create 2D graphs by replacing + * the default input handler with one that does not allow rotating the graph and + * by setting the camera to view the graph * directly from the side or from the top. Also, axis labels typically need to be rotated when * viewing the graph from the sides. * Defaults to \c{false}. @@ -651,8 +677,10 @@ bool QAbstract3DGraph::isOrthoProjection() const * \property QAbstract3DGraph::aspectRatio * \since QtDataVisualization 1.1 * - * The aspect ratio is the ratio of the graph scaling between the longest axis on the horizontal - * plane and the Y-axis. Defaults to \c{2.0}. + * \brief The ratio of the graph scaling between the longest axis on the + * horizontal plane and the y-axis. + * + * Defaults to \c{2.0}. * * \note Has no effect on Q3DBars. * @@ -671,18 +699,21 @@ qreal QAbstract3DGraph::aspectRatio() const /*! * \property QAbstract3DGraph::optimizationHints * - * Defines if the rendering optimization is default or static. Default mode provides the full - * feature set at reasonable performance. Static mode optimizes graph rendering and is ideal for + * \brief Whether the default or static mode is used for rendering optimization. + * + * The default mode provides the full feature set at a reasonable level of + * performance. The static mode optimizes graph rendering and is ideal for * large non-changing data sets. It is slower with dynamic data changes and item rotations. - * Selection is not optimized, so using it with massive data sets is not advisable. - * Static works only on the Scatter graph. - * Defaults to \c{OptimizationDefault}. + * Selection is not optimized, so using the static mode with massive data sets is not advisable. + * Static optimization works only on scatter graphs. + * Defaults to \l{OptimizationDefault}. * * \note On some environments, large graphs using static optimization may not render, because - * all of the items are rendered using a single draw call, and different graphics drivers have - * different maximum vertice counts per call that they support. - * This is mostly an issue on 32bit and/or OpenGL ES2 platforms. - * To work around this issue, choose an item mesh with low vertex count or use the point mesh. + * all of the items are rendered using a single draw call, and different graphics drivers + * support different maximum vertice counts per call. + * This is mostly an issue on 32bit and OpenGL ES2 platforms. + * To work around this issue, choose an item mesh with a low vertex count or use + * the point mesh. * * \sa QAbstract3DSeries::mesh */ @@ -700,8 +731,10 @@ QAbstract3DGraph::OptimizationHints QAbstract3DGraph::optimizationHints() const * \property QAbstract3DGraph::polar * \since QtDataVisualization 1.2 * - * If \c {true}, the horizontal axes are changed into polar axes. The X axis becomes the - * angular axis and the Z axis becomes the radial axis. + * \brief Whether horizontal axes are changed into polar axes. + * + * If \c {true}, the x-axis becomes the angular axis and the z-axis becomes the + * radial axis. * Polar mode is not available for bar graphs. * * Defaults to \c{false}. @@ -722,11 +755,14 @@ bool QAbstract3DGraph::isPolar() const * \property QAbstract3DGraph::radialLabelOffset * \since QtDataVisualization 1.2 * - * This property specifies the normalized horizontal offset for the axis labels of the radial - * polar axis. The value 0.0 indicates the labels should be drawn next to the 0-angle angular - * axis grid line. The value 1.0 indicates the labels are drawn on their normal place at the edge - * of the graph background. - * This property is ignored if polar property value is \c{false}. Defaults to 1.0. + * \brief The normalized horizontal offset for the axis labels of the radial + * polar axis. + * + * The value \c 0.0 indicates that the labels should be drawn next to the 0-angle + * angular axis grid line. The value \c 1.0 indicates that the labels are drawn + * in their usual place at the edge of the graph background. Defaults to \c 1.0. + * + * This property is ignored if the \l polar property value is \c{false}. * * \sa polar */ @@ -744,12 +780,13 @@ float QAbstract3DGraph::radialLabelOffset() const * \property QAbstract3DGraph::horizontalAspectRatio * \since QtDataVisualization 1.2 * - * The horizontal aspect ratio is the ratio of the graph scaling between the X and Z axes. - * Value of 0.0 indicates automatic scaling according to axis ranges. + * \brief The ratio of the graph scaling between the x-axis and z-axis. + * + * The value of \c 0.0 indicates automatic scaling according to axis ranges. * Defaults to \c{0.0}. * - * \note Has no effect on Q3DBars, which handles scaling on the horizontal plane via - * \l{Q3DBars::barThickness}{barThickness} and \l{Q3DBars::barSpacing}{barSpacing} properties. + * Has no effect on Q3DBars, which handles scaling on the horizontal plane via + * the \l{Q3DBars::barThickness}{barThickness} and \l{Q3DBars::barSpacing}{barSpacing} properties. * Polar graphs also ignore this property. * * \sa aspectRatio, polar, Q3DBars::barThickness, Q3DBars::barSpacing @@ -768,15 +805,16 @@ qreal QAbstract3DGraph::horizontalAspectRatio() const * \property QAbstract3DGraph::reflection * \since QtDataVisualization 1.2 * - * Sets floor reflections on or off. Defaults to \c{false}. + * \brief Whether floor reflections are on or off. * - * \note Affects only Q3DBars. + * Defaults to \c{false}. * - * \note In Q3DBars graphs holding both positive and negative values, reflections are not supported - * for custom items that intersect the floor plane. In that case, reflections should be turned off + * Affects only Q3DBars. However, in Q3DBars graphs holding both positive and + * negative values, reflections are not supported for custom items that + * intersect the floor plane. In that case, reflections should be turned off * to avoid incorrect rendering. * - * \note If using custom surface format, stencil buffer needs to be defined + * If using a custom surface format, the stencil buffer needs to be defined * (QSurfaceFormat::setStencilBufferSize()) for reflections to work. * * \sa reflectivity @@ -795,7 +833,9 @@ bool QAbstract3DGraph::isReflection() const * \property QAbstract3DGraph::reflectivity * \since QtDataVisualization 1.2 * - * Adjusts floor reflectivity, larger number being more reflective. Valid range is \c{[0...1]}. + * \brief Floor reflectivity. + * + * Larger numbers make the floor more reflective. The valid range is \c{[0...1]}. * Defaults to \c{0.5}. * * \note Affects only Q3DBars. @@ -816,8 +856,9 @@ qreal QAbstract3DGraph::reflectivity() const * \property QAbstract3DGraph::locale * \since QtDataVisualization 1.2 * - * Sets the locale used for formatting various numeric labels. - * Defaults to \c{"C"} locale. + * \brief The locale used for formatting various numeric labels. + * + * Defaults to the \c{"C"} locale. * * \sa QValue3DAxis::labelFormat */ @@ -835,18 +876,20 @@ QLocale QAbstract3DGraph::locale() const * \property QAbstract3DGraph::queriedGraphPosition * \since QtDataVisualization 1.2 * - * This read-only property contains the latest graph position values along each axis queried using - * Q3DScene::graphPositionQuery. The values are normalized to range \c{[-1, 1]}. + * \brief The latest queried graph position values along each axis. + * + * This read-only property contains the results from + * Q3DScene::graphPositionQuery. The values are normalized to the range \c{[-1, 1]}. * If the queried position was outside the graph bounds, the values - * will not reflect the real position, but will instead be some undefined position outside - * the range \c{[-1, 1]}. The value will be undefined before any queries are made. + * will not reflect the real position, but will instead indicate an undefined position outside + * the range \c{[-1, 1]}. The value will be undefined until a query is made. * - * There isn't a single correct 3D coordinate to match to each specific screen position, so to be + * There is no single correct 3D coordinate to match a particular screen position, so to be * consistent, the queries are always done against the inner sides of an invisible box surrounding * the graph. * * \note Bar graphs only allow querying graph position at the graph floor level, - * so the Y-value is always zero for bar graphs and the valid queries can be only made at + * so the y-value is always zero for bar graphs and the valid queries can be only made at * screen positions that contain the floor of the graph. * * \sa Q3DScene::graphPositionQuery @@ -860,18 +903,20 @@ QVector3D QAbstract3DGraph::queriedGraphPosition() const * \property QAbstract3DGraph::margin * \since QtDataVisualization 1.2 * - * This property contains the absolute value used for graph margin. The graph margin is the space - * left between the edge of the plottable graph area and the edge of the graph background. + * \brief The absolute value used for the space left between the edge of the + * plottable graph area and the edge of the graph background. + * * If the margin value is negative, the margins are determined automatically and can vary according - * to size of the items in the series and the type of the graph. - * The value is interpreted as a fraction of Y-axis range, provided the graph aspect ratios have - * not beed changed from the defaults. + * to the size of the items in the series and the type of the graph. + * The value is interpreted as a fraction of the y-axis range if the graph + * aspect ratios have not beed changed from the default values. * Defaults to \c{-1.0}. * - * \note Having smaller than the automatically determined margin on scatter graph can cause - * the scatter items at the edges of the graph to overlap with the graph background. + * \note Setting a smaller margin for a scatter graph than the automatically + * determined margin can cause the scatter items at the edges of the graph to + * overlap with the graph background. * - * \note On scatter and surface graphs, if the margin is comparatively small to the axis label + * \note On scatter and surface graphs, if the margin is small in comparison to the axis label * size, the positions of the edge labels of the axes are adjusted to avoid overlap with * the edge labels of the neighboring axes. */ @@ -886,7 +931,7 @@ qreal QAbstract3DGraph::margin() const } /*! - * \return \c{true} if the OpenGL context of the graph has been successfully initialized. + * Returns \c{true} if the OpenGL context of the graph has been successfully initialized. * Trying to use a graph when the context initialization has failed typically results in a crash. * A common reason for a context initialization failure is lack of sufficient platform support * for OpenGL. diff --git a/src/datavisualization/engine/selectionpointer.cpp b/src/datavisualization/engine/selectionpointer.cpp index da5d5e54..d646429a 100644 --- a/src/datavisualization/engine/selectionpointer.cpp +++ b/src/datavisualization/engine/selectionpointer.cpp @@ -78,7 +78,7 @@ void SelectionPointer::updateScene(Q3DScene *scene) m_cachedScene = scene; } -void SelectionPointer::render(GLuint defaultFboHandle, bool useOrtho) +void SelectionPointer::renderSelectionPointer(GLuint defaultFboHandle, bool useOrtho) { Q_UNUSED(defaultFboHandle) @@ -86,7 +86,6 @@ void SelectionPointer::render(GLuint defaultFboHandle, bool useOrtho) m_mainViewPort.width(), m_mainViewPort.height()); Q3DCamera *camera = m_cachedScene->activeCamera(); - QSize textureSize = m_labelItem.size(); QMatrix4x4 itModelMatrix; @@ -111,10 +110,6 @@ void SelectionPointer::render(GLuint defaultFboHandle, bool useOrtho) projectionMatrix.perspective(45.0f, viewPortRatio, 0.1f, 100.0f); } - // Calculate scale factor to get uniform font size - GLfloat scaledFontSize = 0.05f + m_drawer->font().pointSizeF() / 500.0f; - GLfloat scaleFactor = scaledFontSize / (GLfloat)textureSize.height(); - QMatrix4x4 modelMatrix; QMatrix4x4 MVPMatrix; @@ -152,11 +147,44 @@ void SelectionPointer::render(GLuint defaultFboHandle, bool useOrtho) Utils::vectorFromColor(m_cachedTheme->lightColor())); m_drawer->drawObject(m_pointShader, m_pointObj); +} - // - // Draw the label - // +void SelectionPointer::renderSelectionLabel(GLuint defaultFboHandle, bool useOrtho) +{ + Q_UNUSED(defaultFboHandle) + + glViewport(m_mainViewPort.x(), m_mainViewPort.y(), + m_mainViewPort.width(), m_mainViewPort.height()); + + Q3DCamera *camera = m_cachedScene->activeCamera(); + + // Get view matrix + QMatrix4x4 viewMatrix; QMatrix4x4 modelMatrixLabel; + QMatrix4x4 projectionMatrix; + GLfloat viewPortRatio = (GLfloat)m_mainViewPort.width() / (GLfloat)m_mainViewPort.height(); + if (m_cachedIsSlicingActivated) { + GLfloat sliceUnitsScaled = sliceUnits / m_autoScaleAdjustment; + viewMatrix.lookAt(QVector3D(0.0f, 0.0f, 1.0f), zeroVector, upVector); + projectionMatrix.ortho(-sliceUnitsScaled * viewPortRatio, sliceUnitsScaled * viewPortRatio, + -sliceUnitsScaled, sliceUnitsScaled, + -1.0f, 4.0f); + } else if (useOrtho) { + viewMatrix = camera->d_ptr->viewMatrix(); + GLfloat orthoRatio = 2.0f; + projectionMatrix.ortho(-viewPortRatio * orthoRatio, viewPortRatio * orthoRatio, + -orthoRatio, orthoRatio, + 0.0f, 100.0f); + } else { + viewMatrix = camera->d_ptr->viewMatrix(); + projectionMatrix.perspective(45.0f, viewPortRatio, 0.1f, 100.0f); + } + + QSize textureSize = m_labelItem.size(); + + // Calculate scale factor to get uniform font size + GLfloat scaledFontSize = 0.05f + m_drawer->font().pointSizeF() / 500.0f; + GLfloat scaleFactor = scaledFontSize / (GLfloat)textureSize.height(); // Position label QVector3D labelAlign(0.0f, 1.0f * scaledFontSize + 0.05f, 0.0f); @@ -184,6 +212,8 @@ void SelectionPointer::render(GLuint defaultFboHandle, bool useOrtho) m_labelShader->bind(); + QMatrix4x4 MVPMatrix; + // Set shader bindings MVPMatrix = projectionMatrix * viewMatrix * modelMatrixLabel; m_labelShader->setUniformValue(m_labelShader->MVP(), MVPMatrix); diff --git a/src/datavisualization/engine/selectionpointer_p.h b/src/datavisualization/engine/selectionpointer_p.h index 31856130..0ba9b53a 100644 --- a/src/datavisualization/engine/selectionpointer_p.h +++ b/src/datavisualization/engine/selectionpointer_p.h @@ -58,7 +58,8 @@ public: explicit SelectionPointer(Drawer *drawer); ~SelectionPointer(); - void render(GLuint defaultFboHandle = 0, bool useOrtho = false); + void renderSelectionPointer(GLuint defaultFboHandle = 0, bool useOrtho = false); + void renderSelectionLabel(GLuint defaultFboHandle = 0, bool useOrtho = false); void setPosition(const QVector3D &position); void setLabel(const QString &label, bool themeChange = false); void setPointerObject(ObjectHelper *object); diff --git a/src/datavisualization/engine/surface3drenderer.cpp b/src/datavisualization/engine/surface3drenderer.cpp index 848dc0f7..9cfa0edc 100644 --- a/src/datavisualization/engine/surface3drenderer.cpp +++ b/src/datavisualization/engine/surface3drenderer.cpp @@ -760,17 +760,19 @@ void Surface3DRenderer::render(GLuint defaultFboHandle) if (m_cachedIsSlicingActivated) drawSlicedScene(); - // Render selection ball + // Render selection label if (m_selectionActive && m_cachedSelectionMode.testFlag(QAbstract3DGraph::SelectionItem)) { - foreach (SeriesRenderCache *baseCache, m_renderCacheList) { - SurfaceSeriesRenderCache *cache = static_cast<SurfaceSeriesRenderCache *>(baseCache); + for (SeriesRenderCache *baseCache: m_renderCacheList) { + const SurfaceSeriesRenderCache *cache = static_cast<SurfaceSeriesRenderCache *>(baseCache); if (cache->slicePointerActive() && cache->renderable() && m_cachedIsSlicingActivated ) { - cache->sliceSelectionPointer()->render(defaultFboHandle); + cache->sliceSelectionPointer()->renderSelectionLabel(defaultFboHandle); + } + if (cache->mainPointerActive() && cache->renderable()) { + cache->mainSelectionPointer()->renderSelectionLabel(defaultFboHandle, + m_useOrthoProjection); } - if (cache->mainPointerActive() && cache->renderable()) - cache->mainSelectionPointer()->render(defaultFboHandle, m_useOrthoProjection); } } } @@ -1328,6 +1330,38 @@ void Surface3DRenderer::drawScene(GLuint defaultFboHandle) m_primarySubViewport.height()); } + // Selection handling + if (m_selectionDirty || m_selectionLabelDirty) { + QPoint visiblePoint = Surface3DController::invalidSelectionPosition(); + if (m_selectedSeries) { + SurfaceSeriesRenderCache *cache = + static_cast<SurfaceSeriesRenderCache *>( + m_renderCacheList.value(const_cast<QSurface3DSeries *>(m_selectedSeries))); + if (cache && m_selectedPoint != Surface3DController::invalidSelectionPosition()) { + const QRect &sampleSpace = cache->sampleSpace(); + int x = m_selectedPoint.x() - sampleSpace.y(); + int y = m_selectedPoint.y() - sampleSpace.x(); + if (x >= 0 && y >= 0 && x < sampleSpace.height() && y < sampleSpace.width() + && cache->dataArray().size()) { + visiblePoint = QPoint(x, y); + } + } + } + + if (m_cachedSelectionMode == QAbstract3DGraph::SelectionNone + || visiblePoint == Surface3DController::invalidSelectionPosition()) { + m_selectionActive = false; + } else { + if (m_cachedIsSlicingActivated) + updateSliceDataModel(visiblePoint); + if (m_cachedSelectionMode.testFlag(QAbstract3DGraph::SelectionItem)) + surfacePointSelected(visiblePoint); + m_selectionActive = true; + } + + m_selectionDirty = false; + } + // Draw the surface if (!m_renderCacheList.isEmpty()) { // For surface we can see glimpses from underneath @@ -1452,6 +1486,22 @@ void Surface3DRenderer::drawScene(GLuint defaultFboHandle) } } + // Render selection ball + if (m_selectionActive + && m_cachedSelectionMode.testFlag(QAbstract3DGraph::SelectionItem)) { + for (SeriesRenderCache *baseCache: m_renderCacheList) { + const SurfaceSeriesRenderCache *cache = static_cast<SurfaceSeriesRenderCache *>(baseCache); + if (cache->slicePointerActive() && cache->renderable() && + m_cachedIsSlicingActivated ) { + cache->sliceSelectionPointer()->renderSelectionPointer(defaultFboHandle); + } + if (cache->mainPointerActive() && cache->renderable()) { + cache->mainSelectionPointer()->renderSelectionPointer(defaultFboHandle, + m_useOrthoProjection); + } + } + } + // Bind background shader m_backgroundShader->bind(); glCullFace(GL_BACK); @@ -1481,7 +1531,13 @@ void Surface3DRenderer::drawScene(GLuint defaultFboHandle) MVPMatrix = projectionViewMatrix * modelMatrix; #endif + bool blendEnabled = false; QVector4D backgroundColor = Utils::vectorFromColor(m_cachedTheme->backgroundColor()); + if (backgroundColor.w() < 1.0f) { + blendEnabled = true; + glEnable(GL_BLEND); + glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA); + } // Set shader bindings m_backgroundShader->setUniformValue(m_backgroundShader->lightP(), lightPos); @@ -1516,6 +1572,9 @@ void Surface3DRenderer::drawScene(GLuint defaultFboHandle) // Draw the object m_drawer->drawObject(m_backgroundShader, m_backgroundObj); } + + if (blendEnabled) + glDisable(GL_BLEND); } // Draw grid lines @@ -1865,38 +1924,6 @@ void Surface3DRenderer::drawScene(GLuint defaultFboHandle) // Release shader glUseProgram(0); - - // Selection handling - if (m_selectionDirty || m_selectionLabelDirty) { - QPoint visiblePoint = Surface3DController::invalidSelectionPosition(); - if (m_selectedSeries) { - SurfaceSeriesRenderCache *cache = - static_cast<SurfaceSeriesRenderCache *>( - m_renderCacheList.value(const_cast<QSurface3DSeries *>(m_selectedSeries))); - if (cache && m_selectedPoint != Surface3DController::invalidSelectionPosition()) { - const QRect &sampleSpace = cache->sampleSpace(); - int x = m_selectedPoint.x() - sampleSpace.y(); - int y = m_selectedPoint.y() - sampleSpace.x(); - if (x >= 0 && y >= 0 && x < sampleSpace.height() && y < sampleSpace.width() - && cache->dataArray().size()) { - visiblePoint = QPoint(x, y); - } - } - } - - if (m_cachedSelectionMode == QAbstract3DGraph::SelectionNone - || visiblePoint == Surface3DController::invalidSelectionPosition()) { - m_selectionActive = false; - } else { - if (m_cachedIsSlicingActivated) - updateSliceDataModel(visiblePoint); - if (m_cachedSelectionMode.testFlag(QAbstract3DGraph::SelectionItem)) - surfacePointSelected(visiblePoint); - m_selectionActive = true; - } - - m_selectionDirty = false; - } } void Surface3DRenderer::drawLabels(bool drawSelection, const Q3DCamera *activeCamera, diff --git a/src/datavisualization/input/q3dinputhandler.cpp b/src/datavisualization/input/q3dinputhandler.cpp index 263ab321..85934482 100644 --- a/src/datavisualization/input/q3dinputhandler.cpp +++ b/src/datavisualization/input/q3dinputhandler.cpp @@ -95,7 +95,7 @@ static const float rotationSpeed = 100.0f; * \qmlproperty bool InputHandler3D::rotationEnabled * \since QtDataVisualization 1.2 * - * This property specifies if this input handler allows graph rotation. + * Defines whether this input handler allows graph rotation. * Defaults to \c{true}. */ @@ -103,7 +103,7 @@ static const float rotationSpeed = 100.0f; * \qmlproperty bool InputHandler3D::zoomEnabled * \since QtDataVisualization 1.2 * - * This property specifies if this input handler allows graph zooming. + * Defines whether this input handler allows graph zooming. * Defaults to \c{true}. */ @@ -111,7 +111,7 @@ static const float rotationSpeed = 100.0f; * \qmlproperty bool InputHandler3D::selectionEnabled * \since QtDataVisualization 1.2 * - * This property specifies if this input handler allows selection from the graph. + * Defines whether this input handler allows selection from the graph. * Defaults to \c{true}. */ @@ -119,7 +119,7 @@ static const float rotationSpeed = 100.0f; * \qmlproperty bool InputHandler3D::zoomAtTargetEnabled * \since QtDataVisualization 1.2 * - * This property specifies if zooming changes the camera target to the position of the input + * Defines whether zooming changes the camera target to the position of the input * at the time of the zoom. * Defaults to \c{true}. */ @@ -277,7 +277,8 @@ void Q3DInputHandler::wheelEvent(QWheelEvent *event) * \property Q3DInputHandler::rotationEnabled * \since QtDataVisualization 1.2 * - * This property specifies if this input handler allows graph rotation. + * \brief Whether this input handler allows graph rotation. + * * Defaults to \c{true}. */ void Q3DInputHandler::setRotationEnabled(bool enable) @@ -297,7 +298,8 @@ bool Q3DInputHandler::isRotationEnabled() const * \property Q3DInputHandler::zoomEnabled * \since QtDataVisualization 1.2 * - * This property specifies if this input handler allows graph zooming. + * \brief Whether this input handler allows graph zooming. + * * Defaults to \c{true}. */ void Q3DInputHandler::setZoomEnabled(bool enable) @@ -317,7 +319,8 @@ bool Q3DInputHandler::isZoomEnabled() const * \property Q3DInputHandler::selectionEnabled * \since QtDataVisualization 1.2 * - * This property specifies if this input handler allows selection from the graph. + * \brief Whether this input handler allows selection from the graph. + * * Defaults to \c{true}. */ void Q3DInputHandler::setSelectionEnabled(bool enable) @@ -337,8 +340,9 @@ bool Q3DInputHandler::isSelectionEnabled() const * \property Q3DInputHandler::zoomAtTargetEnabled * \since QtDataVisualization 1.2 * - * This property specifies if zooming should change the camera target so that the zoomed point + * \brief Whether zooming should change the camera target so that the zoomed point * of the graph stays at the same location after the zoom. + * * Defaults to \c{true}. */ void Q3DInputHandler::setZoomAtTargetEnabled(bool enable) diff --git a/src/datavisualization/input/qabstract3dinputhandler.cpp b/src/datavisualization/input/qabstract3dinputhandler.cpp index 2f4629ae..d0ab00a1 100644 --- a/src/datavisualization/input/qabstract3dinputhandler.cpp +++ b/src/datavisualization/input/qabstract3dinputhandler.cpp @@ -148,8 +148,14 @@ void QAbstract3DInputHandler::wheelEvent(QWheelEvent *event) /*! * \property QAbstract3DInputHandler::inputView * - * Current enumerated input view based on the view of the processed input events. - * When the view changes \c inputViewChanged signal is emitted. + * \brief The current enumerated input view based on the view of the processed + * input events. + * + * One of the InputView enum values. + * + * When the view changes, the \c inputViewChanged signal is emitted. + * + * \sa InputView */ QAbstract3DInputHandler::InputView QAbstract3DInputHandler::inputView() const { @@ -167,7 +173,7 @@ void QAbstract3DInputHandler::setInputView(InputView inputView) /*! * \property QAbstract3DInputHandler::inputPosition * - * Last input position based on the processed input events. + * \brief The last input position based on the processed input events. */ QPoint QAbstract3DInputHandler::inputPosition() const { @@ -183,7 +189,7 @@ void QAbstract3DInputHandler::setInputPosition(const QPoint &position) } /*! - * \return the manhattan length between last two input positions. + * Returns the manhattan length between last two input positions. */ int QAbstract3DInputHandler::prevDistance() const { @@ -201,9 +207,10 @@ void QAbstract3DInputHandler::setPrevDistance(int distance) /*! * \property QAbstract3DInputHandler::scene * - * The 3D scene this abstract input handler is controlling. Only one scene can - * be controlled by one input handler. Setting a \a scene to an input handler doesn't - * transfer the ownership of the \a scene. + * \brief The 3D scene this abstract input handler is controlling. + * + * One input handler can control one scene. Setting a scene to an input handler + * does not transfer the ownership of the scene. */ Q3DScene *QAbstract3DInputHandler::scene() const { @@ -228,7 +235,6 @@ void QAbstract3DInputHandler::setPreviousInputPos(const QPoint &position) /*! * Returns the previous input position. - * \return Previous input position. */ QPoint QAbstract3DInputHandler::previousInputPos() const { diff --git a/src/datavisualization/theme/q3dtheme.cpp b/src/datavisualization/theme/q3dtheme.cpp index c9cb6fb7..46a7a5c3 100644 --- a/src/datavisualization/theme/q3dtheme.cpp +++ b/src/datavisualization/theme/q3dtheme.cpp @@ -38,125 +38,92 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \brief Q3DTheme class provides a visual style for graphs. * \since QtDataVisualization 1.0 * - * Q3DTheme is used to specify visual properties that affect the whole graph. There are several - * built-in themes that can be used directly, or be modified freely. User can also create a theme - * from scratch using \c ThemeUserDefined. Creating a theme using the default constructor - * produces a new user-defined theme. + * Specifies visual properties that affect the whole graph. There are several + * built-in themes that can be used as is or modified freely. + * + * The following properties can be overridden by using QAbstract3DSeries + * properties to set them explicitly in the series: baseColors, baseGradients, + * and colorStyle. + * + * Themes can be created from scratch using the ThemeUserDefined enum value. + * Creating a theme using the default constructor produces a new user-defined + * theme. + * + * \section1 Default Theme + * + * The following table lists the properties controlled by themes and the + * default values for ThemeUserDefined. * - * \section1 Properties controlled by theme * \table * \header * \li Property - * \li Effect - * \li Default in ThemeUserDefined + * \li Default Value * \row * \li ambientLightStrength - * \li The strength of the ambient light in the graph. This affects how evenly and brightly the - * colors are shown throughout the graph regardless of light position. * \li 0.25 * \row * \li backgroundColor - * \li Color of the graph background. * \li Qt::black * \row * \li backgroundEnabled - * \li Is the graph background drawn or not. - * \li true + * \li \c true * \row * \li baseColors - * \li List of colors for the objects in the graph. Colors are applied to series one by one. - * If there are more series than colors, the color list is reused from the start. - * The colors in this property are used if colorStyle is ColorStyleUniform. This can be - * overridden by setting the \l{QAbstract3DSeries::baseColor}{baseColor} explicitly in series. * \li Qt::black * \row * \li baseGradients - * \li List of gradients for the objects in the graph. Gradients are applied to series one by - * one. If there are more series than gradients, the gradient list is reused from the start. - * The gradients in this property are used if colorStyle is ColorStyleObjectGradient or - * ColorStyleRangeGradient. This can be overridden by setting the - * \l{QAbstract3DSeries::baseGradient}{baseGradient} explicitly in series. - * \li QLinearGradient(). Essentially fully black. + * \li QLinearGradient. Essentially fully black. * \row * \li colorStyle - * \li The color style of the objects in the graph. See ColorStyle for detailed description of - * the styles. This can be overridden by setting the - * \l{QAbstract3DSeries::colorStyle}{colorStyle} explicitly in series. * \li ColorStyleUniform * \row * \li \l font - * \li The font to be used for labels. - * \li QFont() + * \li QFont * \row * \li gridEnabled - * \li Is the grid on the background drawn or not. This affects all grid lines. - * \li true + * \li \c true * \row * \li gridLineColor - * \li The color for the grid lines. * \li Qt::white * \row * \li highlightLightStrength - * \li The specular light strength for highlighted objects. * \li 7.5 * \row * \li labelBackgroundColor - * \li The color of the label background. This property has no effect if labelBackgroundEnabled - * is \c false. * \li Qt::gray * \row * \li labelBackgroundEnabled - * \li Are the labels to be drawn with a background using labelBackgroundColor (including alpha), - * or with a fully transparent background. Labels with background are drawn to equal sizes - * per axis based on the longest label, and the text is centered in it. Labels without - * background are drawn as is and are left/right aligned based on their position in the - * graph. - * \li true + * \li \c true * \row * \li labelBorderEnabled - * \li Are the labels to be drawn with a border or not. This property affects only labels with - * a background. - * \li true + * \li \c true * \row * \li labelTextColor - * \li The color for the font used in labels. * \li Qt::white * \row * \li lightColor - * \li The color of the light. Affects both ambient and specular light. * \li Qt::white * \row * \li lightStrength - * \li The strength of the specular light in the graph. This affects the light specified in - * Q3DScene. * \li 5.0 * \row * \li multiHighlightColor - * \li The color to be used for highlighted objects, if \l{Q3DBars::selectionMode}{selectionMode} - * of the graph has \c QAbstract3DGraph::SelectionRow or \c QAbstract3DGraph::SelectionColumn flag set. * \li Qt::blue * \row * \li multiHighlightGradient - * \li The gradient to be used for highlighted objects, if \l{Q3DBars::selectionMode}{selectionMode} - * of the graph has \c QAbstract3DGraph::SelectionRow or \c QAbstract3DGraph::SelectionColumn flag set. - * \li QLinearGradient(). Essentially fully black. + * \li QLinearGradient. Essentially fully black. * \row * \li singleHighlightColor - * \li The color to be used for a highlighted object, if \l{Q3DBars::selectionMode}{selectionMode} - * of the graph has \c QAbstract3DGraph::SelectionItem flag set. * \li Qt::red * \row * \li singleHighlightGradient - * \li The gradient to be used for a highlighted object, if \l{Q3DBars::selectionMode}{selectionMode} - * of the graph has \c QAbstract3DGraph::SelectionItem flag set. - * \li QLinearGradient(). Essentially fully black. + * \li QLinearGradient. Essentially fully black. * \row * \li windowColor - * \li The color of the window the graph is drawn into. * \li Qt::black * \endtable * - * \section1 Usage examples + * \section1 Usage Examples * * Creating a built-in theme without any modifications: * @@ -216,7 +183,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \value ThemeIsabelle * A dark theme with yellow as the base color. * \value ThemeUserDefined - * A user-defined theme. See \l {Properties controlled by theme} for theme defaults. + * A user-defined theme. For more information, see \l {Default Theme}. */ /*! @@ -228,10 +195,89 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION * \brief A visual style for graphs. * * This type is used to specify visual properties that affect the whole graph. There are several - * built-in themes that can be used directly, or be modified freely. User can also create a theme - * from scratch using \c Theme3D.ThemeUserDefined. + * built-in themes that can be used as is or modified freely. + * + * The following properties can be overridden by using Abstract3DSeries + * properties to set them explicitly in the series: + * baseColors, baseGradients, and colorStyle. * - * For a more complete description, see Q3DTheme. + * Themes can be created from scratch by using the + * \l{Q3DTheme::ThemeUserDefined}{Theme3D.ThemeUserDefined} enum value. + * + * \section1 Default Theme + * + * The following table lists the properties controlled by themes and the + * default values for \l{Q3DTheme::ThemeUserDefined} + * {Theme3D.ThemeUserDefined}. + * + * \table + * \header + * \li Property + * \li Default Value + * \row + * \li ambientLightStrength + * \li 0.25 + * \row + * \li backgroundColor + * \li "black". For more information, see \l [QtQuick] color. + * \row + * \li backgroundEnabled + * \li \c true + * \row + * \li baseColors + * \li "black" + * \row + * \li baseGradients + * \li QLinearGradient. Essentially fully black. + * \row + * \li colorStyle + * \li ColorStyleUniform + * \row + * \li \l font + * \li \l [QtQuick] font + * \row + * \li gridEnabled + * \li \c true + * \row + * \li gridLineColor + * \li "white" + * \row + * \li highlightLightStrength + * \li 7.5 + * \row + * \li labelBackgroundColor + * \li "gray" + * \row + * \li labelBackgroundEnabled + * \li \c true + * \row + * \li labelBorderEnabled + * \li \c true + * \row + * \li labelTextColor + * \li "white" + * \row + * \li lightColor + * \li "white" + * \row + * \li lightStrength + * \li 5.0 + * \row + * \li multiHighlightColor + * \li "blue" + * \row + * \li multiHighlightGradient + * \li QLinearGradient. Essentially fully black. + * \row + * \li singleHighlightColor + * \li "red" + * \row + * \li singleHighlightGradient + * \li QLinearGradient. Essentially fully black. + * \row + * \li windowColor + * \li "black" + * \endtable * * \section1 Usage examples * @@ -253,142 +299,175 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION /*! * \qmlproperty list<ThemeColor> Theme3D::baseColors * - * List of base colors to be used for all the objects in the graph, series by series. If there + * The list of base colors to be used for all the objects in the graph, series by series. If there * are more series than colors, color list wraps and starts again with the first color in the list. * Has no immediate effect if colorStyle is not \c Theme3D.ColorStyleUniform. + * + * This can be overridden by setting \l{Abstract3DSeries::baseColor} + * {Abstract3DSeries.baseColor} explicitly in the series. */ /*! * \qmlproperty color Theme3D::backgroundColor * - * Color for the graph background. + * The color of the graph background. */ /*! * \qmlproperty color Theme3D::windowColor * - * Color for the application window. + * The color of the application window the graph is drawn into. */ /*! * \qmlproperty color Theme3D::labelTextColor * - * Color for the font used for labels. + * The color of the font used for labels. */ /*! * \qmlproperty color Theme3D::labelBackgroundColor * - * Color for the label backgrounds. Has no effect if labelBackgroundEnabled is \c false. + * The color of the label backgrounds. Has no effect if labelBackgroundEnabled is \c false. */ /*! * \qmlproperty color Theme3D::gridLineColor * - * Color for the grid lines. + * The color of the grid lines. */ /*! * \qmlproperty color Theme3D::singleHighlightColor * - * Highlight color for a highlighted object. Used if \l{AbstractGraph3D::selectionMode}{selectionMode} - * has \c AbstractGraph3D.SelectionItem flag set. + * The highlight color for a selected object. Used if + * \l{AbstractGraph3D::selectionMode}{selectionMode} + * has the \c AbstractGraph3D.SelectionItem flag set. */ /*! * \qmlproperty color Theme3D::multiHighlightColor * - * Highlight color for highlighted objects. Used if \l{AbstractGraph3D::selectionMode}{selectionMode} - * has \c AbstractGraph3D.SelectionRow or \c AbstractGraph3D.SelectionColumn flag set. + * The highlight color for selected objects. Used if + * \l{AbstractGraph3D::selectionMode}{selectionMode} + * has the \c AbstractGraph3D.SelectionRow or \c AbstractGraph3D.SelectionColumn + * flag set. */ /*! * \qmlproperty color Theme3D::lightColor * - * Color for the specular light defined in Scene3D. + * The color of the ambient and specular light defined in Scene3D. */ /*! * \qmlproperty list<ColorGradient> Theme3D::baseGradients * - * List of base gradients to be used for all the objects in the graph, series by series. If there - * are more series than gradients, gradient list wraps and starts again with the first gradient in - * the list - * Has no immediate effect if colorStyle is \c Theme3D.ColorStyleUniform. + * The list of base gradients to be used for all the objects in the graph, + * series by series. If there are more series than gradients, the gradient list + * wraps and starts again with the first gradient in the list. + * + * Has no immediate effect if colorStyle is \l{Q3DTheme::ColorStyleUniform} + * {Theme3D.ColorStyleUniform}. + * + * This value can be overridden by setting \l{Abstract3DSeries::baseGradient} + *{Abstract3DSeries.baseGradient} explicitly in the series. */ /*! * \qmlproperty ColorGradient Theme3D::singleHighlightGradient * - * Highlight gradient for a highlighted object. Used if \l{AbstractGraph3D::selectionMode}{selectionMode} - * has \c AbstractGraph3D.SelectionItem flag set. + * The highlight gradient for a selected object. Used if + * \l{AbstractGraph3D::selectionMode}{selectionMode} + * has the \c AbstractGraph3D.SelectionItem flag set. */ /*! * \qmlproperty ColorGradient Theme3D::multiHighlightGradient * - * Highlight gradient for highlighted objects. Used if \l{AbstractGraph3D::selectionMode}{selectionMode} - * has \c AbstractGraph3D.SelectionRow or \c AbstractGraph3D.SelectionColumn flag set. + * The highlight gradient for selected objects. Used if + * \l{AbstractGraph3D::selectionMode}{selectionMode} + * has the \c AbstractGraph3D.SelectionRow or \c AbstractGraph3D.SelectionColumn + * flag set. */ /*! * \qmlproperty real Theme3D::lightStrength * - * Specular light strength for the whole graph. Value must be between 0.0 and 10.0. + * The specular light strength for the whole graph. The value must be between + * \c 0.0 and \c 10.0. + * + * This value affects the light specified in Scene3D. */ /*! * \qmlproperty real Theme3D::ambientLightStrength * - * Ambient light strength for the whole graph. Value must be between 0.0 and 1.0. + * The ambient light strength for the whole graph. This value determines how + * evenly and brightly the colors are shown throughout the graph regardless of + * the light position. The value must be between \c 0.0 and \c 1.0. */ /*! * \qmlproperty real Theme3D::highlightLightStrength * - * Specular light strength for highlighted objects. Value must be between 0.0 and 10.0. + * The specular light strength for selected objects. The value must be + * between \c 0.0 and \c 10.0. */ /*! * \qmlproperty bool Theme3D::labelBorderEnabled * - * Set label borders enabled or disabled. Has no effect if labelBackgroundEnabled is \c false. + * Defines whether label borders are drawn for labels that have a background. + * Has no effect if labelBackgroundEnabled is \c false. */ /*! * \qmlproperty font Theme3D::font * - * Set font to be used for labels. + * Sets the font to be used for labels. */ /*! * \qmlproperty bool Theme3D::backgroundEnabled * - * Set background enabled or disabled. + * Defines whether the background is drawn by using the value of + * backgroundColor. */ /*! * \qmlproperty bool Theme3D::gridEnabled * - * Set grid lines enabled or disabled. + * Defines whether the grid lines are drawn. This value affects all grid lines. */ /*! * \qmlproperty bool Theme3D::labelBackgroundEnabled * - * Set label backgrounds enabled or disabled. + * Defines whether the label is drawn with a background that uses + * labelBackgroundColor (including alpha), or with a fully transparent + * background. Labels with a background are drawn to equal sizes per axis based + * on the longest label, and the text is centered in them. Labels without + * a background are drawn as is and are left or right aligned based on their + * position in the graph. */ /*! * \qmlproperty Theme3D.ColorStyle Theme3D::colorStyle * - * The \a style of the graph colors. One of \c Theme3D.ColorStyle. + * The style of the graph colors. One of Q3DTheme::ColorStyle enum values. + * + * This value can be overridden by setting \l{Abstract3DSeries::colorStyle} + * {Abstract3DSeries.colorStyle} explicitly in the series. + * + * \sa Q3DTheme::ColorStyle */ /*! * \qmlproperty Theme3D.Theme Theme3D::type * - * The type of the theme. If no type is set, the type is \c Theme3D.ThemeUserDefined. + * The type of the theme. If no type is set, the type is + * \l{Q3DTheme::ThemeUserDefined}{Theme3D.ThemeUserDefined}. * Changing the theme type after the item has been constructed will change all other properties * of the theme to what the predefined theme specifies. Changing the theme type of the active theme * of the graph will also reset all attached series to use the new theme. @@ -437,9 +516,16 @@ Q3DTheme::~Q3DTheme() /*! * \property Q3DTheme::baseColors * - * List of base colors to be used for all the objects in the graph, series by series. If there - * are more series than colors, color list wraps and starts again with the first color in the list. + * \brief The list of base colors to be used for all the objects in the graph, + * series by series. + * + * If there are more series than colors, the color list wraps and starts again + * with the first color in the list. + * * Has no immediate effect if colorStyle is not ColorStyleUniform. + * + * This value can be overridden by setting the \l{QAbstract3DSeries::baseColor} + * {baseColor} explicitly in the series. */ void Q3DTheme::setBaseColors(const QList<QColor> &colors) { @@ -463,7 +549,7 @@ QList<QColor> Q3DTheme::baseColors() const /*! * \property Q3DTheme::backgroundColor * - * Color for the graph background. + * \brief The color of the graph background. */ void Q3DTheme::setBackgroundColor(const QColor &color) { @@ -483,7 +569,7 @@ QColor Q3DTheme::backgroundColor() const /*! * \property Q3DTheme::windowColor * - * Color for the application window. + * \brief The color of the application window the graph is drawn into. */ void Q3DTheme::setWindowColor(const QColor &color) { @@ -503,7 +589,7 @@ QColor Q3DTheme::windowColor() const /*! * \property Q3DTheme::labelTextColor * - * Color for the font used for labels. + * \brief The color of the font used for labels. */ void Q3DTheme::setLabelTextColor(const QColor &color) { @@ -523,7 +609,9 @@ QColor Q3DTheme::labelTextColor() const /*! * \property Q3DTheme::labelBackgroundColor * - * Color for the label backgrounds. Has no effect if labelBackgroundEnabled is \c false. + * \brief The color of the label backgrounds. + * + * Has no effect if labelBackgroundEnabled is \c false. */ void Q3DTheme::setLabelBackgroundColor(const QColor &color) { @@ -543,7 +631,7 @@ QColor Q3DTheme::labelBackgroundColor() const /*! * \property Q3DTheme::gridLineColor * - * Color for the grid lines. + * \brief The color of the grid lines. */ void Q3DTheme::setGridLineColor(const QColor &color) { @@ -563,7 +651,9 @@ QColor Q3DTheme::gridLineColor() const /*! * \property Q3DTheme::singleHighlightColor * - * Highlight color for a highlighted object. Used if \l{Q3DBars::selectionMode}{selectionMode} has + * \brief The highlight color for a selected object. + * + * Used if \l{QAbstract3DGraph::selectionMode}{selectionMode} has the * \c QAbstract3DGraph::SelectionItem flag set. */ void Q3DTheme::setSingleHighlightColor(const QColor &color) @@ -583,8 +673,11 @@ QColor Q3DTheme::singleHighlightColor() const /*! * \property Q3DTheme::multiHighlightColor * - * Highlight color for highlighted objects. Used if \l{Q3DBars::selectionMode}{selectionMode} has - * \c QAbstract3DGraph::SelectionRow or \c QAbstract3DGraph::SelectionColumn flag set. + * \brief The highlight color for selected objects. + * + * Used if \l{QAbstract3DGraph::selectionMode}{selectionMode} has the + * \c QAbstract3DGraph::SelectionRow or \c QAbstract3DGraph::SelectionColumn + * flag set. */ void Q3DTheme::setMultiHighlightColor(const QColor &color) { @@ -603,7 +696,9 @@ QColor Q3DTheme::multiHighlightColor() const /*! * \property Q3DTheme::lightColor * - * Color for the specular light defined in Q3DScene. + * \brief The color for the ambient and specular light. + * + * This value affects the light specified in Q3DScene. */ void Q3DTheme::setLightColor(const QColor &color) { @@ -623,10 +718,16 @@ QColor Q3DTheme::lightColor() const /*! * \property Q3DTheme::baseGradients * - * List of base gradients to be used for all the objects in the graph, series by series. If there - * are more series than gradients, gradient list wraps and starts again with the first gradient in - * the list + * \brief The list of base gradients to be used for all the objects in the + * graph, series by series. + * + * If there are more series than gradients, the gradient list wraps and starts + * again with the first gradient in the list + * * Has no immediate effect if colorStyle is ColorStyleUniform. + * + * This value can be overridden by setting the + * \l{QAbstract3DSeries::baseGradient}{baseGradient} explicitly in the series. */ void Q3DTheme::setBaseGradients(const QList<QLinearGradient> &gradients) { @@ -650,8 +751,10 @@ QList<QLinearGradient> Q3DTheme::baseGradients() const /*! * \property Q3DTheme::singleHighlightGradient * - * Highlight gradient for a highlighted object. Used if \l{Q3DBars::selectionMode}{selectionMode} - * has \c QAbstract3DGraph::SelectionItem flag set. + * \brief The highlight gradient for a selected object. + * + * Used if \l{QAbstract3DGraph::selectionMode}{selectionMode} + * has the \c QAbstract3DGraph::SelectionItem flag set. */ void Q3DTheme::setSingleHighlightGradient(const QLinearGradient &gradient) { @@ -670,8 +773,11 @@ QLinearGradient Q3DTheme::singleHighlightGradient() const /*! * \property Q3DTheme::multiHighlightGradient * - * Highlight gradient for highlighted objects. Used if \l{Q3DBars::selectionMode}{selectionMode} - * has \c QAbstract3DGraph::SelectionRow or \c QAbstract3DGraph::SelectionColumn flag set. + * \brief The highlight gradient for selected objects. + * + * Used if \l{QAbstract3DGraph::selectionMode}{selectionMode} + * has the \c QAbstract3DGraph::SelectionRow or + * \c QAbstract3DGraph::SelectionColumn flag set. */ void Q3DTheme::setMultiHighlightGradient(const QLinearGradient &gradient) { @@ -690,7 +796,11 @@ QLinearGradient Q3DTheme::multiHighlightGradient() const /*! * \property Q3DTheme::lightStrength * - * Specular light strength for the whole graph. Value must be between 0.0f and 10.0f. + * \brief The specular light strength for the whole graph. + * + * The value must be between \c 0.0f and \c 10.0f. + * + * This value affects the light specified in Q3DScene. */ void Q3DTheme::setLightStrength(float strength) { @@ -712,7 +822,12 @@ float Q3DTheme::lightStrength() const /*! * \property Q3DTheme::ambientLightStrength * - * Ambient light strength for the whole graph. Value must be between 0.0f and 1.0f. + * \brief The ambient light strength for the whole graph. + * + * This value determines how evenly and brightly the colors are shown throughout + * the graph regardless of the light position. + * + * The value must be between \c 0.0f and \c 1.0f. */ void Q3DTheme::setAmbientLightStrength(float strength) { @@ -734,7 +849,9 @@ float Q3DTheme::ambientLightStrength() const /*! * \property Q3DTheme::highlightLightStrength * - * Specular light strength for highlighted objects. Value must be between 0.0f and 10.0f. + * \brief The specular light strength for selected objects. + * + * The value must be between \c 0.0f and \c 10.0f. */ void Q3DTheme::setHighlightLightStrength(float strength) { @@ -756,7 +873,9 @@ float Q3DTheme::highlightLightStrength() const /*! * \property Q3DTheme::labelBorderEnabled * - * Set label borders enabled or disabled. Has no effect if labelBackgroundEnabled is \c false. + * \brief Whether label borders are drawn for labels that have a background. + * + * Has no effect if labelBackgroundEnabled is \c false. */ void Q3DTheme::setLabelBorderEnabled(bool enabled) { @@ -776,7 +895,7 @@ bool Q3DTheme::isLabelBorderEnabled() const /*! * \property Q3DTheme::font * - * Set \a font to be used for labels. + * \brief The font to be used for labels. */ void Q3DTheme::setFont(const QFont &font) { @@ -796,7 +915,9 @@ QFont Q3DTheme::font() const /*! * \property Q3DTheme::backgroundEnabled * - * Set background enabled or disabled. + * \brief Whether the background is visible. + * + * The background is drawn by using the value of backgroundColor. */ void Q3DTheme::setBackgroundEnabled(bool enabled) { @@ -816,7 +937,9 @@ bool Q3DTheme::isBackgroundEnabled() const /*! * \property Q3DTheme::gridEnabled * - * Set grid lines enabled or disabled. + * \brief Whether the grid lines are drawn. + * + * This value affects all grid lines. */ void Q3DTheme::setGridEnabled(bool enabled) { @@ -836,7 +959,16 @@ bool Q3DTheme::isGridEnabled() const /*! * \property Q3DTheme::labelBackgroundEnabled * - * Set label backgrounds enabled or disabled. + *\brief Whether the label is drawn with a color background or with a fully + * transparent background. + * + * The labelBackgroundColor value (including alpha) is used for drawing the + * background. + * + * Labels with a background are drawn to equal sizes per axis based + * on the longest label, and the text is centered in them. Labels without a + * background are drawn as is and are left or right aligned based on their + * position in the graph. */ void Q3DTheme::setLabelBackgroundEnabled(bool enabled) { @@ -856,7 +988,12 @@ bool Q3DTheme::isLabelBackgroundEnabled() const /*! * \property Q3DTheme::colorStyle * - * The \a style of the graph colors. One of ColorStyle. + * \brief The style of the graph colors. + * + * One of the ColorStyle enum values. + * + * This value can be overridden by setting \l{Abstract3DSeries::colorStyle} + * {colorStyle} explicitly in the series. */ void Q3DTheme::setColorStyle(ColorStyle style) { @@ -875,7 +1012,9 @@ Q3DTheme::ColorStyle Q3DTheme::colorStyle() const /*! * \property Q3DTheme::type * - * The type of the theme. The type is automatically set when constructing a theme, + * \brief The type of the theme. + * + * The type is automatically set when constructing a theme, * but can also be changed later. Changing the theme type will change all other * properties of the theme to what the predefined theme specifies. * Changing the theme type of the active theme of the graph will also reset all diff --git a/src/datavisualization/utils/qutils.h b/src/datavisualization/utils/qutils.h index e80e9170..4e3f3d0e 100644 --- a/src/datavisualization/utils/qutils.h +++ b/src/datavisualization/utils/qutils.h @@ -38,7 +38,9 @@ namespace QtDataVisualization { +#ifndef Q_QDOC static inline QSurfaceFormat qDefaultSurfaceFormat(bool antialias = true) Q_DECL_UNUSED; +#endif static inline QSurfaceFormat qDefaultSurfaceFormat(bool antialias) { bool isES = false; |