From 13da6f0f3c979ffce623189f35b6c1b705097dce Mon Sep 17 00:00:00 2001 From: Tomi Korpipaa Date: Thu, 14 Nov 2024 11:31:53 +0200 Subject: [PATCH] Add docs for Graphs3D enums MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pick-to: 6.8.1 Fixes: QTBUG-127800 Fixes: QTBUG-131123 Change-Id: Ia023ed3abc4dbd9f386049282c6c53fabe05e02c Reviewed-by: Tomi Korpipää Reviewed-by: Sami Varanka (cherry picked from commit 20c6562ecaf688144ccf0bc913688ba9d7073187) Reviewed-by: Qt Cherry-pick Bot --- src/common/theme/qgraphstheme.cpp | 24 ++- .../doc/src/qtgraphs3d-qml-namespace.qdoc | 182 ++++++++++++++++++ src/graphs3d/qml/qquickgraphsitem.cpp | 46 ++--- src/graphs3d/utils/qgraphs3dnamespace.cpp | 126 ++++++++---- 4 files changed, 303 insertions(+), 75 deletions(-) create mode 100644 src/graphs3d/doc/src/qtgraphs3d-qml-namespace.qdoc diff --git a/src/common/theme/qgraphstheme.cpp b/src/common/theme/qgraphstheme.cpp index 309a24c6..7acd9a92 100644 --- a/src/common/theme/qgraphstheme.cpp +++ b/src/common/theme/qgraphstheme.cpp @@ -337,8 +337,10 @@ QT_BEGIN_NAMESPACE * * The highlight color for a selected object. Used if * \l{GraphsItem3D::selectionMode}{selectionMode} - * has the \c GraphsItem3D.SelectionFlag.Item flag set. + * has the \c Graphs3D.SelectionFlag.Item flag set. * The default value depends on \l colorScheme. + * + * \sa Graphs3D.SelectionFlag */ /*! @@ -346,9 +348,11 @@ QT_BEGIN_NAMESPACE * * The highlight color for selected objects. Used if * \l{GraphsItem3D::selectionMode}{selectionMode} - * has the \c GraphsItem3D.SelectionFlag.Row or \c GraphsItem3D.SelectionFlag.Column + * has the \c Graphs3D.SelectionFlag.Row or \c Graphs3D.SelectionFlag.Column * flag set. * The default value depends on \l colorScheme. + * + * \sa Graphs3D.SelectionFlag */ /*! @@ -370,8 +374,10 @@ QT_BEGIN_NAMESPACE * * The highlight gradient for a selected object. Used if * \l{GraphsItem3D::selectionMode}{selectionMode} - * has the \c GraphsItem3D.SelectionFlag.Item flag set. + * has the \c Graphs3D.SelectionFlag.Item flag set. * The default value depends on \l colorScheme. + * + * \sa Graphs3D.SelectionFlag */ /*! @@ -379,9 +385,11 @@ QT_BEGIN_NAMESPACE * * The highlight gradient for selected objects. Used if * \l{GraphsItem3D::selectionMode}{selectionMode} - * has the \c GraphsItem3D.SelectionFlag.Row or \c GraphsItem3D.SelectionFlag.Column + * has the \c Graphs3D.SelectionFlag.Row or \c Graphs3D.SelectionFlag.Column * flag set. * The default value depends on \l colorScheme. + * + * \sa Graphs3D.SelectionFlag */ /*! @@ -543,7 +551,9 @@ QT_BEGIN_NAMESPACE * The default value is \c 2.0. * * If it is set for grid lines, only has effect if - * \l{Q3DGraphsWidgetItem::gridLineType} is \c Graphs3D.GridLineType.Shader + * \l{GraphsItem3D::gridLineType} is \c Graphs3D.GridLineType.Shader + * + * \sa Graphs3D.GridLineType */ /*! @@ -553,7 +563,9 @@ QT_BEGIN_NAMESPACE * The default value is \c 1.0. * * If it is set for grid lines, only has effect if - * \l{Q3DGraphsWidgetItem::gridLineType} is \c Graphs3D.GridLineType.Shader + * \l{GraphsItem3D::gridLineType} is \c Graphs3D.GridLineType.Shader + * + * \sa Graphs3D.GridLineType */ /*! diff --git a/src/graphs3d/doc/src/qtgraphs3d-qml-namespace.qdoc b/src/graphs3d/doc/src/qtgraphs3d-qml-namespace.qdoc new file mode 100644 index 00000000..55b656fe --- /dev/null +++ b/src/graphs3d/doc/src/qtgraphs3d-qml-namespace.qdoc @@ -0,0 +1,182 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype Graphs3D + \qmlabstract + \inqmlmodule QtGraphs + \ingroup graphs_qml_3D + \brief Graphs3D namespace enums. + + The Graphs3D namespace provides the following enums used by QtGraphs' 3D API. + + \section1 Graphs3D.SelectionFlag + + Item selection modes. Values of this enumeration can be combined with OR operator. + + \value None + Selection mode disabled. + \value Item + Selection highlights a single item. + \value Row + Selection highlights a single row. + \value ItemAndRow + Combination flag for highlighting both item and row with different colors. + \value Column + Selection highlights a single column. + \value ItemAndColumn + Combination flag for highlighting both item and column with different colors. + \value RowAndColumn + Combination flag for highlighting both row and column. + \value ItemRowAndColumn + Combination flag for highlighting item, row, and column. + \value Slice + Setting this mode flag indicates that the graph should take care of the slice view handling + automatically. If you wish to control the slice view yourself via Q3DScene, do not set this + flag. When setting this mode flag, either \c Row or \c Column must also + be set, but not both. Slicing is supported by Bars3D and Surface3D only. + When this flag is set, slice mode is entered in the following situations: + \list + \li When selection is changed explicitly via series API to a visible item + \li When selection is changed by clicking on the graph + \li When the selection mode changes and the selected item is visible + \endlist + \value MultiSeries + Setting this mode means that items for all series at same position are highlighted, instead + of just the selected item. The actual selection in the other series doesn't change. + When setting this mode flag, one or more of the basic selection flags (\c {Item}, + \c {Row}, or \c Column) must also be set. + Multi-series selection is not supported for Scatter3D. + + \section1 Graphs3D.ShadowQuality + + Quality and softness of shadows. + + \value None + Shadows are disabled. + \value Low + Shadows are rendered in low quality. + \value Medium + Shadows are rendered in medium quality. + \value High + Shadows are rendered in high quality. + \value SoftLow + Shadows are rendered in low quality with softened edges. + \value SoftMedium + Shadows are rendered in medium quality with softened edges. + \value SoftHigh + Shadows are rendered in high quality with softened edges. + + \section1 Graphs3D.ElementType + + Type of an element in the graph. + + \value None + No defined element. + \value Series + An item in a series. + \value AxisXLabel + The x-axis label. + \value AxisYLabel + The y-axis label. + \value AxisZLabel + The z-axis label. + \value CustomItem + A custom item. + + \section1 Graphs3D.OptimizationHint + + The optimization hint for rendering. + + \value Default + Provides the full feature set with instancing at a good performance. + \value Legacy + Provides the full feature set at a reasonable performance. To be used if + OptimizationHint.Default performs poorly or does not work. + + \section1 Graphs3D.CameraPreset + + Predefined positions for camera. + + \value NoPreset + Used to indicate a preset has not been set, or the scene has been rotated freely. + \value FrontLow + Both x and y rotations of the camera are 0. + \value Front + X rotation is 0 and y rotation is 22.5 degrees. + \value FrontHigh + X rotation is 0 and y rotation is 45 degrees. + \value LeftLow + X rotation is 90 and y rotation is 0 degrees. + \value Left + X rotation is 90 and y rotation is 22.5 degrees. + \value LeftHigh + X rotation is 90 and y rotation is 45 degrees. + \value RightLow + X rotation is -90 and y rotation is 0 degrees. + \value Right + X rotation is -90 and y rotation is 22.5 degrees. + \value RightHigh + X rotation is -90 and y rotation is 45 degrees. + \value BehindLow + X rotation is 180 and y rotation is 0 degrees. + \value Behind + X rotation is 180 and y rotation is 22.5 degrees. + \value BehindHigh + X rotation is 180 and y rotation is 45 degrees. + \value IsometricLeft + X rotation is 45 and y rotation is 22.5 degrees. + \value IsometricLeftHigh + X rotation is 45 and y rotation is 45 degrees. + \value IsometricRight + X rotation is -45 and y rotation is 22.5 degrees. + \value IsometricRightHigh + X rotation is -45 and y rotation is 45 degrees. + \value DirectlyAbove + X rotation is 0 and y rotation is 90 degrees. + \value DirectlyAboveCW45 + X rotation is -45 and y rotation is 90 degrees. + \value DirectlyAboveCCW45 + X rotation is 45 and y rotation is 90 degrees. + \value FrontBelow + X rotation is 0 and y rotation is -45 degrees. + In Bars3D from FrontBelow onward these only work for graphs including negative + values. They act as CameraPreset...Low for positive-only values. + \value LeftBelow + X rotation is 90 and y rotation is -45 degrees. + \value RightBelow + X rotation is -90 and y rotation is -45 degrees. + \value BehindBelow + X rotation is 180 and y rotation is -45 degrees. + \value DirectlyBelow + X rotation is 0 and y rotation is -90 degrees. + Acts as FrontLow for positive-only bars. + + \section1 Graphs3D.GridLineType + + \value Shader + Grid lines are rendered with GPU in a shader. + \value Geometry + Grid lines are rendered with 3D models. + + \section1 Graphs3D.RenderingMode + + \value DirectToBackground + Indicates that the graph will be rendered directly on the window + background and QML items are rendered on top of it. Using non-transparent QML + item as a background will hide the graph. Clears the whole window before + rendering the graph, including the areas outside the graph. If the surface + format of the window supports antialiasing, it will be used (see + \c {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. + + \value Indirect + 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 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. + */ diff --git a/src/graphs3d/qml/qquickgraphsitem.cpp b/src/graphs3d/qml/qquickgraphsitem.cpp index a5b5117a..f377c3a8 100644 --- a/src/graphs3d/qml/qquickgraphsitem.cpp +++ b/src/graphs3d/qml/qquickgraphsitem.cpp @@ -58,25 +58,21 @@ constexpr float polarRoundness = 64.0f; /*! * \qmlproperty Graphs3D.SelectionMode GraphsItem3D::selectionMode * The active selection mode in the graph. - * One of the QtGraphs3D::SelectionFlag enum values. - * - * \sa QtGraphs3D::SelectionFlag + * One of the \l Graphs3D.SelectionFlag enum values. */ /*! * \qmlproperty Graphs3D.ShadowQuality GraphsItem3D::shadowQuality - * The quality of shadows. One of the QtGraphs3D::ShadowQuality enum + * The quality of shadows. One of the \l Graphs3D.ShadowQuality enum * values. - * - * \sa QtGraphs3D::ShadowQuality */ /*! * \qmlproperty Graphs3D.CameraPreset GraphsItem3D::cameraPreset * * The currently active camera preset, which is one of - * \l{GraphsItem3D::cameraPreset}{Graphs3D.CameraPreset}. If no - * preset is active, the value is \c {Graphs3D.CameraPreset.None}. + * \l{Graphs3D.CameraPreset}. If no + * preset is active, the value is \c {Graphs3D.CameraPreset.NoPreset}. */ /*! @@ -220,33 +216,11 @@ constexpr float polarRoundness = 64.0f; * * How the graph will be rendered. Defaults to \c{Indirect}. * - * \value DirectToBackground - * Indicates that the graph will be rendered directly on the window - * background and QML items are rendered on top of it. Using non-transparent QML - * item as a background will hide the graph. Clears the whole window before - * rendering the graph, including the areas outside the graph. If the surface - * format of the window supports antialiasing, it will be used (see - * \c {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. - * - * \value Indirect - * 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 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. - * - * \note Antialiasing is not supported in OpenGL ES2 environments in any - * rendering mode. - * * \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 + * \sa msaaSamples, Graphs3D.RenderingMode */ /*! @@ -440,7 +414,7 @@ constexpr float polarRoundness = 64.0f; * * \sa selectedLabelIndex(), selectedAxis(), selectedCustomItemIndex(), * selectedCustomItem(), Bars3D::selectedSeries, Scatter3D::selectedSeries, - * Scene3D::selectionQueryPosition, QtGraphs3D::ElementType + * Scene3D::selectionQueryPosition, Graphs3D.ElementType */ /*! @@ -498,7 +472,7 @@ constexpr float polarRoundness = 64.0f; * 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, QtGraphs3D::OptimizationHint + * \sa Abstract3DSeries::mesh, Graphs3D.OptimizationHint */ /*! @@ -555,10 +529,12 @@ constexpr float polarRoundness = 64.0f; /*! * \qmlproperty Graphs3D.GridLineType GraphsItem3D::gridLineType * - * Defines whether the grid lines type is Graphs3D.GridLineType.Shader or - * Graphs3D.GridLineType.Geometry. + * Defines whether the grid lines type is \c Graphs3D.GridLineType.Shader or + * \c Graphs3D.GridLineType.Geometry. * * This value affects all grid lines. + * + * \sa Graphs3D.GridLineType */ /*! diff --git a/src/graphs3d/utils/qgraphs3dnamespace.cpp b/src/graphs3d/utils/qgraphs3dnamespace.cpp index 2859288b..8acb2c88 100644 --- a/src/graphs3d/utils/qgraphs3dnamespace.cpp +++ b/src/graphs3d/utils/qgraphs3dnamespace.cpp @@ -14,7 +14,7 @@ QT_BEGIN_NAMESPACE \enum QtGraphs3D::SelectionFlag Item selection modes. Values of this enumeration can be combined with OR - operator. + operator. \value None Selection mode disabled. @@ -104,38 +104,96 @@ QT_BEGIN_NAMESPACE */ /*! - * \enum QtGraphs3D::CameraPreset - * - * Predefined positions for camera. - * - * \value NoPreset - * Used to indicate a preset has not been set, or the scene has been rotated freely. - * \value FrontLow - * \value Front - * \value FrontHigh - * \value LeftLow - * \value Left - * \value LeftHigh - * \value RightLow - * \value Right - * \value RightHigh - * \value BehindLow - * \value Behind - * \value BehindHigh - * \value IsometricLeft - * \value IsometricLeftHigh - * \value IsometricRight - * \value IsometricRightHigh - * \value DirectlyAbove - * \value DirectlyAboveCW45 - * \value DirectlyAboveCCW45 - * \value FrontBelow - * In Q3DBarsWidgetItem from FrontBelow onward these only work for graphs including negative - * values. They act as Preset...Low for positive-only values. - * \value LeftBelow - * \value RightBelow - * \value BehindBelow - * \value DirectlyBelow - * Acts as FrontLow for positive-only bars. + \enum QtGraphs3D::CameraPreset + + Predefined positions for camera. + + \value NoPreset + Used to indicate a preset has not been set, or the scene has been rotated freely. + \value FrontLow + Both x and y rotations of the camera are 0. + \value Front + X rotation is 0 and y rotation is 22.5 degrees. + \value FrontHigh + X rotation is 0 and y rotation is 45 degrees. + \value LeftLow + X rotation is 90 and y rotation is 0 degrees. + \value Left + X rotation is 90 and y rotation is 22.5 degrees. + \value LeftHigh + X rotation is 90 and y rotation is 45 degrees. + \value RightLow + X rotation is -90 and y rotation is 0 degrees. + \value Right + X rotation is -90 and y rotation is 22.5 degrees. + \value RightHigh + X rotation is -90 and y rotation is 45 degrees. + \value BehindLow + X rotation is 180 and y rotation is 0 degrees. + \value Behind + X rotation is 180 and y rotation is 22.5 degrees. + \value BehindHigh + X rotation is 180 and y rotation is 45 degrees. + \value IsometricLeft + X rotation is 45 and y rotation is 22.5 degrees. + \value IsometricLeftHigh + X rotation is 45 and y rotation is 45 degrees. + \value IsometricRight + X rotation is -45 and y rotation is 22.5 degrees. + \value IsometricRightHigh + X rotation is -45 and y rotation is 45 degrees. + \value DirectlyAbove + X rotation is 0 and y rotation is 90 degrees. + \value DirectlyAboveCW45 + X rotation is -45 and y rotation is 90 degrees. + \value DirectlyAboveCCW45 + X rotation is 45 and y rotation is 90 degrees. + \value FrontBelow + X rotation is 0 and y rotation is -45 degrees. + In Q3DBarsWidgetItem from FrontBelow onward these only work for graphs including negative + values. They act as CameraPreset...Low for positive-only values. + \value LeftBelow + X rotation is 90 and y rotation is -45 degrees. + \value RightBelow + X rotation is -90 and y rotation is -45 degrees. + \value BehindBelow + X rotation is 180 and y rotation is -45 degrees. + \value DirectlyBelow + X rotation is 0 and y rotation is -90 degrees. + Acts as FrontLow for positive-only bars. + */ + +/*! + \enum QtGraphs3D::GridLineType + + \value Shader + Grid lines are rendered with GPU in a shader. + \value Geometry + Grid lines are rendered with 3D models. +*/ + +/*! + \enum QtGraphs3D::RenderingMode + + \value DirectToBackground + Indicates that the graph will be rendered directly on the window + background and QML items are rendered on top of it. Using non-transparent QML + item as a background will hide the graph. Clears the whole window before + rendering the graph, including the areas outside the graph. If the surface + format of the window supports antialiasing, it will be used (see + \c {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. + + \value Indirect + 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 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. + */ + QT_END_NAMESPACE