/****************************************************************************
**
** Copyright (C) 2016 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$
**
****************************************************************************/

/*!
    \example custominput
    \title Custom Input Example
    \ingroup qtdatavisualization_examples
    \brief Implementing custom input handler in a widget application.

    The Custom Input example shows how to customize the 3D graph controls in a widget application
    using a custom graph input handler to capture and process mouse events.
    The code in this example shows also how the camera is controlled by using QPropertyAnimation
    to animate the camera and item selection is done on mouseover rather than clicking any mouse
    buttons. Also the code shows how to implement similar zoom with mouse wheel functionality as
    the default input handler implements.

    \image custominput-example.png

    \section1 Replacing default input handling

    The default input handling mechanism is replaced by setting the active input handler of
    Q3DScatter to \c CustomInputHandler that implements the custom behavior.

    \snippet custominput/scatterdatamodifier.cpp 0

    \section1 Implementing custom selection handling

    The on mouseover selection handling is implemented in the \c CustomInputHandler that captures
    the mouse events. It then stores the last known coordinates to the
    QAbstract3DInputHandler::inputPosition property.

    \snippet custominput/custominputhandler.cpp 0

    As the selection is one shot, and is cleared each time a 3D frame is rendered, a timer is setup
    to retrigger selection so that the selection moves to the item currently under the mouse cursor
    as the camera animates around the graph even when the mouse cursor is not moving.

    \snippet custominput/scatterdatamodifier.cpp 1

    \section1 Implementing custom zoom handling

    The camera has a zoom factor that represents amount of zoom in percentages. In this example the
    zoom range is limited between 10% and 500%. This range is then divided to four subranges where
    \c angleDelta is scaled to different amount of zoom change based on the current subrange.

    \snippet custominput/custominputhandler.cpp 1

    \section1 Implementing custom camera handling

    The camera is animated to constantly rotate around the graph with two animations. The rotation
    around the graph is done with a simple QPropertyAnimation that just increments during 20
    seconds from 0 degrees to 360 degrees and sets the Q3DCamera::xRotation property.

    \snippet custominput/scatterdatamodifier.cpp 2

    The camera movement up and down is implemented with a QSequentialAnimationGroup that varies
    the Q3DCamera::yRotation property of the camera from 5 degrees to 45 degrees and back with in
    and out easing.

    \snippet custominput/scatterdatamodifier.cpp 3
*/
