/******************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the Qt Data Visualization module.
**
** $QT_BEGIN_LICENSE:COMM$
**
** 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 http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** $QT_END_LICENSE$
**
******************************************************************************/

/*!
    \example qmlaxisdrag
    \title Qt Quick 2 Axis Dragging Example
    \ingroup qtdatavisualization_examples
    \brief Implementing axis dragging in QML
    \since QtDataVisualization 1.1

    The Qt Quick 2 axis dragging example concentrates on showing how to implement axis range
    changing by dragging axis labels in QML. It also gives a quick peek to two other new features
    in Qt Data Visualization 1.1: orthographic projection and dynamic custom item handling.

    \image qmlaxisdrag-example.png

    \section1 Overriding default input handling

    First we deactivate the default input handling mechanism by setting the active input handler
    of Scatter3D graph to \c{null}:

    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 0
    \dots

    Then we add a MouseArea and set it to fill the parent, which is the same \c Item our
    \c scatterGraph is contained in. We also set it to accept only left mouse button presses,
    as in this example we are not interested in other buttons:

    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 1
    \dots

    Then we need to listen to mouse presses, and when caught, send a selection query to the graph:

    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 2

    Current mouse position, that will be needed for move distance calculation, is caught in
    \c{onPositionChanged}:

    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 3
    \dots

    At the end of \c{onPositionChanged}, we'll save the previous mouse position for move distance
    calculation that will be introduced later:

    \dots 0
    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 4

    \section1 Translating mouse movement to axis range change

    in \c scatterGraph we will need to listen to \c onSelectedElementChanged signal. The signal
    is emitted after the selection query has been made in the \c{onPressed} of \c{inputArea}. We
    set the element type into a property we defined (\c{property int selectedAxisLabel: -1}) in our
    main component, since it is of a type we are interested in:

    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 5

    Then, back in the \c onPositionChanged of \c{inputArea}, we check if a mouse button is pressed
    and if we have a current axis label selection. If the conditions are met, we'll call the
    function that does the conversion from mouse movement to axis range update:

    \dots 0
    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 6
    \dots 0

    The conversion is easy in this case, as we have a fixed camera rotation. We can use some
    precalculated values, calculate mouse move distance, and apply the values to the
    selected axis range:

    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 7

    For a more sophisticated conversion from mouse movement to axis range update, see
    \l{Axis Range Dragging With Labels Example}{this example}.

    \section1 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 \c orthoProjection property
    of \c{scatterGraph}. In this example we have a button for toggling it on and off:

    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 8

    For custom items, first we'll add one in the \c customItemList of \c{scatterGraph}:

    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 9

    We have implemented a timer to add, remove, and rotate all the items in the graph,
    and we'll use the same timer for rotating the custom item:

    \snippet qmlaxisdrag/qml/qmlaxisdrag/main.qml 10
    \dots

    \section1 Example contents
*/