diff options
Diffstat (limited to 'examples/datavisualization/qmlaxishandling/doc/src/qmlaxishandling.qdoc')
| -rw-r--r-- | examples/datavisualization/qmlaxishandling/doc/src/qmlaxishandling.qdoc | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/examples/datavisualization/qmlaxishandling/doc/src/qmlaxishandling.qdoc b/examples/datavisualization/qmlaxishandling/doc/src/qmlaxishandling.qdoc new file mode 100644 index 00000000..087630c6 --- /dev/null +++ b/examples/datavisualization/qmlaxishandling/doc/src/qmlaxishandling.qdoc @@ -0,0 +1,188 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \example qmlaxishandling + \meta tags {DataVisualization, Scatter3D, Custom Input Handler, Dynamic Data, Custom Axis Formatter, Scatter Graph} + \title Axis Handling + \ingroup qtdatavisualization_qmlexamples + \brief Implementing axis dragging with a custom input handler in QML, and creating a custom axis formatter. + \since QtDataVisualization 6.5 + + \e {Axis Handling} demonstrates two different custom features with axes. The features have their + own tabs in the application. + + The following sections concentrate on those features only and skip explaining the basic + functionality - for more detailed QML example documentation, see \l{Simple Scatter Graph}. + + \image qmlaxishandling-example.png + + \include examples-run.qdocinc + + \section1 Axis Dragging + + In the \uicontrol {Axis Dragging} tab, implement a custom input handler in QML that enables you + to drag axis labels to change axis ranges. Further, use orthographic projection and dynamically + update the properties of a custom item. + + \section2 Overriding Default Input Handling + + To deactivate the default input handling mechanism, set the active input handler of Scatter3D + graph to \c{null}: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 0 + \dots + + Then, add a MouseArea and set it to fill the parent, which is the same \c Item our + \c scatterGraph is contained in. Also, set it to accept only left mouse button presses, + as in this example the other buttons are not needed: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 1 + \dots + + Then, listen to mouse presses, and when caught, send a selection query to the graph: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 2 + + The \c{onPositionChanged} signal handler catches the current mouse position that will be + needed for move distance calculation: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 3 + \dots + + At the end of \c{onPositionChanged}, save the previous mouse position for move distance + calculation that will be introduced later: + + \dots 0 + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 4 + + \section2 Translating Mouse Movement to Axis Range Change + + In \c {scatterGraph}, listen to \c {onSelectedElementChanged}. The signal + is emitted after the selection query has been made in the \c{onPressed} of the \c{inputArea}. + Set the element type into a property you defined (\c{property int selectedAxisLabel: -1}) in the + main component, since it is of a type you are interested in: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 5 + + Then, back in the \c onPositionChanged of \c{inputArea}, check if a mouse button is pressed + and if you have a current axis label selection. If the conditions are met, call the + function that does the conversion from mouse movement to axis range update: + + \dots 0 + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 6 + \dots 0 + + The conversion is easy in this case, as the camera rotation is fixed. You can use some + precalculated values, calculate mouse move distance, and apply the values to the + selected axis range: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 7 + + For a more sophisticated conversion from mouse movement to axis range update, see + \l{Graph Gallery}. + + \section2 Other Features + + The example also demonstrates how to use orthographic projection and how to update properties + of a custom item on the fly. + + Orthographic projection is very simple. You'll just need to change the \c orthoProjection + property of \c{scatterGraph}. The example has a button for toggling it on and off: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 8 + + For custom items, add one to the \c customItemList of \c{scatterGraph}: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 9 + + You implement a timer to add, remove, and rotate all the items in the graph, and use the same + timer for rotating the custom item: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisDragging.qml 10 + \dots + + \section1 Axis Formatters + + In the \uicontrol {Axis Formatter} tab, create a custom axis formatter. It also illustrates how + to use predefined axis formatters. + + \section2 Custom Axis Formatter + + Customizing axis formatters requires subclassing the QValue3DAxisFormatter, which cannot be + done in QML code alone. In this example, the axis interprets the float values as + a timestamp and shows the date in the axis labels. To achieve this, introduce a new class + called \c CustomFormatter, which subclasses the QValue3DAxisFormatter: + + \snippet qmlaxishandling/customformatter.h 2 + \dots 0 + + Since float values of a QScatter3DSeries cannot be directly cast into QDateTime values due to + difference in data width, some sort of mapping between the two is needed. To do the mapping, + specify an origin date for the formatter and interpret the float values from the + QScatter3DSeries as date offsets to that origin value. The origin date is given as + a property: + + \snippet qmlaxishandling/customformatter.h 1 + + For the mapping from value to QDateTime, use the \c valueToDateTime() method: + + \snippet qmlaxishandling/customformatter.cpp 0 + + To function as an axis formatter, \c CustomFormatter needs to reimplement some virtual + methods: + + \snippet qmlaxishandling/customformatter.h 0 + + The first two are simple, just create a new instance of \c CustomFormatter and copy the + necessary data over to it. Use these two methods to create and update a cache of formatter for + rendering purposes. Remember to call the superclass implementation of \c populateCopy(): + + \snippet qmlaxishandling/customformatter.cpp 1 + + \c CustomFormatter does the bulk of its work in the \c recalculate() method, where + our formatter calculates the grid, subgrid, and label positions, as well as formats the label + strings. + In the custom formatter, ignore the segment count of the axis and draw a grid line always at + midnight. Subsegment count and label positioning is handled normally: + + \snippet qmlaxishandling/customformatter.cpp 2 + + The axis labels are formatted to show only the date. However, to increase the resolution of the + timestamp of the selection label, specify another property for the custom formatter to allow + the user to customize it: + + \snippet qmlaxishandling/customformatter.h 3 + + This selection format property is used in the reimplemented \c stringToValue method, where + the submitted format is ignored and the custom selection format substituted for it: + + \snippet qmlaxishandling/customformatter.cpp 3 + + To expose our new custom formatter to the QML, declare it and make it a QML module. + For information about how to do this, see \l{Surface Graph Gallery}. + + \section2 QML + + In the QML code, define a different axis for each dimension: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisFormatting.qml 3 + + The Z-axis is just a regular ValueAxis3D: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisFormatting.qml 0 + + For the Y-axis, define a logarithmic axis. To make ValueAxis3D show a logarithmic scale, + specify LogValueAxis3DFormatter for \c formatter property of the axis: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisFormatting.qml 2 + + And finally, for the X-axis use the new \c CustomFormatter: + + \snippet qmlaxishandling/qml/qmlaxishandling/AxisFormatting.qml 1 + + The rest of the application consists of fairly self-explanatory logic for modifying the axes and + showing the graph. + + \section1 Example Contents +*/ |