Axis label dragging support, part 2

Task-number: QTRD-2367

+ Added emitting selection signals
+ Added an example about creating an input handler for axis label dragging
- Snapshot for example docs to be taken

Change-Id: I641f4feb9e31c32023727b1c7c695324923accc4
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@digia.com>

8 files changed, 611 insertions, 0 deletions

diff --git a/examples/datavisualization/draggableaxes/axesinputhandler.cpp b/examples/datavisualization/draggableaxes/axesinputhandler.cpp
new file mode 100644
index 00000000..70086b1c
--- /dev/null
+++ b/examples/datavisualization/draggableaxes/axesinputhandler.cpp
@@ -0,0 +1,135 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+#include "axesinputhandler.h"
+#include <QtCore/qmath.h>
+
+AxesInputHandler::AxesInputHandler(QAbstract3DGraph *graph, QObject *parent) :
+    Q3DInputHandler(parent),
+    m_mousePressed(false),
+    m_state(StateNormal),
+    m_axisX(0),
+    m_axisZ(0),
+    m_axisY(0),
+    m_speedModifier(15.0f)
+{
+    //! [3]
+    // Connect to the item selection signal from graph
+    connect(graph, &QAbstract3DGraph::elementSelected, this,
+            &AxesInputHandler::handleElementSelected);
+    //! [3]
+}
+
+//! [0]
+void AxesInputHandler::mousePressEvent(QMouseEvent *event, const QPoint &mousePos)
+{
+    Q3DInputHandler::mousePressEvent(event, mousePos);
+    if (Qt::LeftButton == event->button())
+        m_mousePressed = true;
+}
+//! [0]
+
+//! [2]
+void AxesInputHandler::mouseMoveEvent(QMouseEvent *event, const QPoint &mousePos)
+{
+    //! [5]
+    // Check if we're trying to drag axis label
+    if (m_mousePressed && m_state != StateNormal) {
+        //! [5]
+        setPreviousInputPos(inputPosition());
+        setInputPosition(mousePos);
+        handleAxisDragging();
+    } else {
+        Q3DInputHandler::mouseMoveEvent(event, mousePos);
+    }
+}
+//! [2]
+
+//! [1]
+void AxesInputHandler::mouseReleaseEvent(QMouseEvent *event, const QPoint &mousePos)
+{
+    Q3DInputHandler::mouseReleaseEvent(event, mousePos);
+    m_mousePressed = false;
+    m_state = StateNormal;
+}
+//! [1]
+
+void AxesInputHandler::handleElementSelected(QAbstract3DGraph::ElementType type)
+{
+    //! [4]
+    switch (type) {
+    case QAbstract3DGraph::ElementAxisXLabel:
+        m_state = StateDraggingX;
+        break;
+    case QAbstract3DGraph::ElementAxisZLabel:
+        m_state = StateDraggingZ;
+        break;
+    case QAbstract3DGraph::ElementAxisYLabel:
+        m_state = StateDraggingY;
+        break;
+    default:
+        m_state = StateNormal;
+        break;
+    }
+    //! [4]
+}
+
+void AxesInputHandler::handleAxisDragging()
+{
+    float distance = 0.0f;
+
+    //! [6]
+    // Get scene orientation from active camera
+    float xRotation = scene()->activeCamera()->xRotation();
+    float yRotation = scene()->activeCamera()->yRotation();
+    //! [6]
+
+    //! [7]
+    // Calculate directional drag multipliers based on rotation
+    float xMulX = qCos(qDegreesToRadians(xRotation));
+    float xMulY = qSin(qDegreesToRadians(xRotation));
+    float zMulX = qSin(qDegreesToRadians(xRotation));
+    float zMulY = qCos(qDegreesToRadians(xRotation));
+    //! [7]
+
+    //! [8]
+    // Get the drag amount
+    QPoint move = inputPosition() - previousInputPos();
+
+    // Flip the effect of y movement if we're viewing from below
+    float yMove = (yRotation < 0) ? -move.y() : move.y();
+    //! [8]
+
+    //! [9]
+    // Adjust axes
+    switch (m_state) {
+    case StateDraggingX:
+        distance = (move.x() * xMulX - yMove * xMulY) / m_speedModifier;
+        m_axisX->setRange(m_axisX->min() - distance, m_axisX->max() - distance);
+        break;
+    case StateDraggingZ:
+        distance = (move.x() * zMulX + yMove * zMulY) / m_speedModifier;
+        m_axisZ->setRange(m_axisZ->min() + distance, m_axisZ->max() + distance);
+        break;
+    case StateDraggingY:
+        distance = move.y() / m_speedModifier; // No need to use adjusted y move here
+        m_axisY->setRange(m_axisY->min() + distance, m_axisY->max() + distance);
+        break;
+    }
+    //! [9]
+}
diff --git a/examples/datavisualization/draggableaxes/axesinputhandler.h b/examples/datavisualization/draggableaxes/axesinputhandler.h
new file mode 100644
index 00000000..e912ba74
--- /dev/null
+++ b/examples/datavisualization/draggableaxes/axesinputhandler.h
@@ -0,0 +1,71 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+#ifndef AXESINPUTHANDLER_H
+#define AXESINPUTHANDLER_H
+
+#include <QtDataVisualization/Q3DInputHandler>
+#include <QtDataVisualization/QAbstract3DGraph>
+#include <QtDataVisualization/QValue3DAxis>
+
+using namespace QtDataVisualization;
+
+//! [0]
+class AxesInputHandler : public Q3DInputHandler
+//! [0]
+{
+    Q_OBJECT
+
+    enum InputState {
+        StateNormal = 0,
+        StateDraggingX,
+        StateDraggingZ,
+        StateDraggingY
+    };
+
+public:
+    explicit AxesInputHandler(QAbstract3DGraph *graph, QObject *parent = 0);
+
+    inline void setAxes(QValue3DAxis *axisX, QValue3DAxis *axisZ, QValue3DAxis *axisY) {
+        m_axisX = axisX;
+        m_axisZ = axisZ;
+        m_axisY = axisY;
+    }
+
+    //! [1]
+    inline void setDragSpeedModifier(float modifier) { m_speedModifier = modifier; }
+    //! [1]
+
+    virtual void mousePressEvent(QMouseEvent *event, const QPoint &mousePos);
+    virtual void mouseMoveEvent(QMouseEvent *event, const QPoint &mousePos);
+    virtual void mouseReleaseEvent(QMouseEvent *event, const QPoint &mousePos);
+
+private:
+    void handleElementSelected(QAbstract3DGraph::ElementType type);
+    void handleAxisDragging();
+
+private:
+    bool m_mousePressed;
+    InputState m_state;
+    QValue3DAxis *m_axisX;
+    QValue3DAxis *m_axisZ;
+    QValue3DAxis *m_axisY;
+    float m_speedModifier;
+};
+
+#endif
diff --git a/examples/datavisualization/draggableaxes/data.cpp b/examples/datavisualization/draggableaxes/data.cpp
new file mode 100644
index 00000000..992c9ee8
--- /dev/null
+++ b/examples/datavisualization/draggableaxes/data.cpp
@@ -0,0 +1,160 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+#include "data.h"
+
+#include <QtDataVisualization/QScatterDataProxy>
+#include <QtDataVisualization/Q3DScene>
+#include <QtDataVisualization/Q3DCamera>
+#include <QtDataVisualization/QScatter3DSeries>
+#include <QtDataVisualization/Q3DTheme>
+
+using namespace QtDataVisualization;
+
+const int itemCount = 500;
+
+Data::Data(Q3DScatter *scatter)
+    : m_graph(scatter),
+      //! [1]
+      m_inputHandler(new AxesInputHandler(scatter)),
+      //! [1]
+      m_autoAdjust(false)
+{
+    m_graph->activeTheme()->setType(Q3DTheme::ThemeEbony);
+    m_graph->activeTheme()->setLabelBorderEnabled(true);
+    m_graph->activeTheme()->setLabelBackgroundColor(QColor(QRgb(0x151550)));
+    m_graph->activeTheme()->setLabelTextColor(Qt::lightGray);
+    m_graph->activeTheme()->setFont(QFont("Arial Black", 30));
+    m_graph->setShadowQuality(QAbstract3DGraph::ShadowQualityMedium);
+    m_graph->scene()->activeCamera()->setCameraPreset(Q3DCamera::CameraPresetIsometricRight);
+
+    m_graph->axisX()->setRange(-20.0f, 20.0f);
+    m_graph->axisY()->setRange(-10.0f, 10.0f);
+    m_graph->axisZ()->setRange(-20.0f, 20.0f);
+
+    //! [0]
+    // Give ownership of the handler to the graph and make it the active handler
+    m_graph->setActiveInputHandler(m_inputHandler);
+    //! [0]
+
+    //! [2]
+    // Give our axes to the input handler
+    m_inputHandler->setAxes(m_graph->axisX(), m_graph->axisZ(), m_graph->axisY());
+    //! [2]
+
+    addData();
+}
+
+Data::~Data()
+{
+    delete m_graph;
+}
+
+void Data::toggleRanges()
+{
+    if (!m_autoAdjust) {
+        m_graph->axisX()->setAutoAdjustRange(true);
+        m_graph->axisZ()->setAutoAdjustRange(true);
+        m_graph->axisY()->setAutoAdjustRange(true);
+        m_inputHandler->setDragSpeedModifier(1.5f);
+        m_autoAdjust = true;
+    } else {
+        m_graph->axisX()->setRange(-20.0f, 20.0f);
+        m_graph->axisY()->setRange(-10.0f, 10.0f);
+        m_graph->axisZ()->setRange(-20.0f, 20.0f);
+        m_inputHandler->setDragSpeedModifier(15.0f);
+        m_autoAdjust = false;
+    }
+}
+
+void Data::addData()
+{
+    QScatter3DSeries *series = new QScatter3DSeries;
+    series->setMesh(QAbstract3DSeries::MeshCube);
+    series->setMeshSmooth(true);
+    m_graph->addSeries(series);
+
+    QScatter3DSeries *series2 = new QScatter3DSeries;
+    series2->setMesh(QAbstract3DSeries::MeshMinimal);
+    series2->setMeshSmooth(true);
+    m_graph->addSeries(series2);
+
+    QScatter3DSeries *series3 = new QScatter3DSeries;
+    series3->setMesh(QAbstract3DSeries::MeshSphere);
+    series3->setMeshSmooth(true);
+    m_graph->addSeries(series3);
+
+    QScatter3DSeries *series4 = new QScatter3DSeries;
+    series4->setMesh(QAbstract3DSeries::MeshBevelCube);
+    series4->setMeshSmooth(true);
+    m_graph->addSeries(series4);
+
+    QScatter3DSeries *series5 = new QScatter3DSeries;
+    series5->setMesh(QAbstract3DSeries::MeshSphere);
+    m_graph->addSeries(series5);
+
+    QScatterDataArray *dataArray = new QScatterDataArray;
+    dataArray->resize(itemCount);
+    QScatterDataItem *ptrToDataArray = &dataArray->first();
+    for (int i = 0; i < itemCount; i++) {
+        ptrToDataArray->setPosition(randVector());
+        ptrToDataArray++;
+    }
+    QScatterDataArray *dataArray2 = new QScatterDataArray;
+    dataArray2->resize(itemCount);
+    ptrToDataArray = &dataArray2->first();
+    for (int i = 0; i < itemCount; i++) {
+        ptrToDataArray->setPosition(randVector());
+        ptrToDataArray++;
+    }
+    QScatterDataArray *dataArray3 = new QScatterDataArray;
+    dataArray3->resize(itemCount);
+    ptrToDataArray = &dataArray3->first();
+    for (int i = 0; i < itemCount; i++) {
+        ptrToDataArray->setPosition(randVector());
+        ptrToDataArray++;
+    }
+    QScatterDataArray *dataArray4 = new QScatterDataArray;
+    dataArray4->resize(itemCount);
+    ptrToDataArray = &dataArray4->first();
+    for (int i = 0; i < itemCount; i++) {
+        ptrToDataArray->setPosition(randVector());
+        ptrToDataArray++;
+    }
+    QScatterDataArray *dataArray5 = new QScatterDataArray;
+    dataArray5->resize(itemCount);
+    ptrToDataArray = &dataArray5->first();
+    for (int i = 0; i < itemCount; i++) {
+        ptrToDataArray->setPosition(randVector());
+        ptrToDataArray++;
+    }
+
+    m_graph->seriesList().at(0)->dataProxy()->resetArray(dataArray);
+    m_graph->seriesList().at(1)->dataProxy()->resetArray(dataArray2);
+    m_graph->seriesList().at(2)->dataProxy()->resetArray(dataArray3);
+    m_graph->seriesList().at(3)->dataProxy()->resetArray(dataArray4);
+    m_graph->seriesList().at(4)->dataProxy()->resetArray(dataArray5);
+}
+
+QVector3D Data::randVector()
+{
+    return QVector3D(
+                (float)(rand() % 100) / 2.0f - (float)(rand() % 100) / 2.0f,
+                (float)(rand() % 100) / 2.0f - (float)(rand() % 100) / 2.0f,
+                (float)(rand() % 100) / 2.0f - (float)(rand() % 100) / 2.0f);
+}
diff --git a/examples/datavisualization/draggableaxes/data.h b/examples/datavisualization/draggableaxes/data.h
new file mode 100644
index 00000000..40a69497
--- /dev/null
+++ b/examples/datavisualization/draggableaxes/data.h
@@ -0,0 +1,48 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+#ifndef DATA_H
+#define DATA_H
+
+#include "axesinputhandler.h"
+
+#include <QtDataVisualization/q3dscatter.h>
+#include <QtGui/QVector3D>
+
+using namespace QtDataVisualization;
+
+class Data : public QObject
+{
+    Q_OBJECT
+public:
+    explicit Data(Q3DScatter *scatter);
+    ~Data();
+
+    void toggleRanges();
+
+private:
+    void addData();
+    QVector3D randVector();
+
+private:
+    Q3DScatter *m_graph;
+    AxesInputHandler *m_inputHandler;
+    bool m_autoAdjust;
+};
+
+#endif
diff --git a/examples/datavisualization/draggableaxes/doc/images/draggableaxes-example.png b/examples/datavisualization/draggableaxes/doc/images/draggableaxes-example.png
new file mode 100644
index 00000000..b2656b69
--- /dev/null
+++ b/examples/datavisualization/draggableaxes/doc/images/draggableaxes-example.png
diff --git a/examples/datavisualization/draggableaxes/doc/src/draggableaxes.qdoc b/examples/datavisualization/draggableaxes/doc/src/draggableaxes.qdoc
new file mode 100644
index 00000000..82add19d
--- /dev/null
+++ b/examples/datavisualization/draggableaxes/doc/src/draggableaxes.qdoc
@@ -0,0 +1,121 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+/*!
+    \example draggableaxes
+    \title Axis Range Dragging With Labels Example
+    \ingroup qtdatavisualization_examples
+    \brief Implementing a custom input handler to support axis dragging.
+
+    The Axis Range Dragging example shows how to customize the 3D graph controls in a widget
+    application to allow changing axis ranges by clicking on an axis label and dragging. This is
+    done by implementing a custom input handler to react to selection signals emitted from the
+    graph.
+
+    \image draggableaxes-example.png
+
+    \section1 Replacing default input handling
+
+    The default input handling mechanism is replaced by setting the active input handler of
+    Q3DScatter to \c AxesInputHandler that implements the custom behavior:
+
+    \snippet draggableaxes/data.cpp 0
+
+    \c m_inputHandler was initialized in the constructor:
+
+    \snippet draggableaxes/data.cpp 1
+
+    We will also need the pointers to the axes, so we will pass them to our input handler too:
+
+    \snippet draggableaxes/data.cpp 2
+
+    \section1 Extending mouse event handling
+
+    First of all, we inherited our input handler from Q3DInputHandler instead of
+    QAbstract3DInputHandler. The reason for doing this is to keep all the functionality of the
+    default input handling, and to add our own functionality on top of it:
+
+    \snippet draggableaxes/axesinputhandler.h 0
+
+    We start extending the default functionality by re-implementing some of the mouse events.
+    Let's start with \c {mousePressEvent}. We'll just add button pressed flag for left mouse button
+    into it, and keep the rest of the default functionality:
+
+    \snippet draggableaxes/axesinputhandler.cpp 0
+
+    We'll need to modify \c mouseReleaseEvent too to clear the flag and reset the internal state:
+
+    \snippet draggableaxes/axesinputhandler.cpp 1
+
+    Then we'll modify \c {mouseMoveEvent}. Here we check if the \c m_mousePressed is \c true and
+    our internal state is something other than \c StateNormal. If so, we'll set the input positions
+    for mouse move distance calculations and call the axis dragging function (see
+    \l {Implementing axis dragging} for details):
+
+    \snippet draggableaxes/axesinputhandler.cpp 2
+
+    We don't need to change the functionality of mouse wheel, so we will not re-implement that.
+
+    \section1 Implementing axis dragging
+
+    First we need to start listening to the selection signal from the graph. We do that in the
+    constructor, and connect it to \c handleElementSelected method:
+
+    \snippet draggableaxes/axesinputhandler.cpp 3
+
+    In \c handleElementSelected we check the type of the selection and set our internal state based on
+    it:
+
+    \snippet draggableaxes/axesinputhandler.cpp 4
+
+    The actual dragging logic is implemented in \c handleAxisDragging method, which we call from
+    \c mouseMoveEvent in case the required conditions are met:
+
+    \snippet draggableaxes/axesinputhandler.cpp 5
+
+    In \c handleAxisDragging we first get the scene orientation from our active camera:
+
+    \snippet draggableaxes/axesinputhandler.cpp 6
+
+    Then we calculate the modifiers to mouse move direction based on the orientation:
+
+    \snippet draggableaxes/axesinputhandler.cpp 7
+
+    After that, we calculate the mouse movement, and modify it based on the y rotation of the
+    camera:
+
+    \snippet draggableaxes/axesinputhandler.cpp 8
+
+    And finally apply the moved distance to the correct axis:
+
+    \snippet draggableaxes/axesinputhandler.cpp 9
+
+    We also have a function for setting the dragging speed:
+
+    \snippet draggableaxes/axesinputhandler.h 1
+
+    This is needed, as the mouse movement distance is absolute (in screen coordinates) and we
+    need to adjust it to the axis range. The larger the value, the slower the dragging will be.
+    Note that on this example we do not take scene zoom level into account when determining the
+    drag speed, so you'll notice changes in the range adjustment as you change the zoom level.
+
+    The modifier could be adjusted automatically based on the axis range and camera zoom level, but
+    we'll leave implementing that as an excercise for the reader.
+
+    \section1 Example contents
+*/
diff --git a/examples/datavisualization/draggableaxes/draggableaxes.pro b/examples/datavisualization/draggableaxes/draggableaxes.pro
new file mode 100644
index 00000000..34db5133
--- /dev/null
+++ b/examples/datavisualization/draggableaxes/draggableaxes.pro
@@ -0,0 +1,18 @@
+android|ios {
+    error( "This example is not supported for android or ios." )
+}
+
+!include( ../examples.pri ) {
+    error( "Couldn't find the examples.pri file!" )
+}
+
+SOURCES +=  main.cpp \
+            data.cpp \
+            axesinputhandler.cpp
+HEADERS +=  data.h \
+            axesinputhandler.h
+
+QT += widgets
+
+OTHER_FILES += doc/src/* \
+               doc/images/*
diff --git a/examples/datavisualization/draggableaxes/main.cpp b/examples/datavisualization/draggableaxes/main.cpp
new file mode 100644
index 00000000..0834313e
--- /dev/null
+++ b/examples/datavisualization/draggableaxes/main.cpp
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+#include "data.h"
+
+#include <QtWidgets/QApplication>
+#include <QtWidgets/QWidget>
+#include <QtWidgets/QHBoxLayout>
+#include <QtWidgets/QVBoxLayout>
+#include <QtWidgets/QCommandLinkButton>
+
+int main(int argc, char **argv)
+{
+    QApplication app(argc, argv);
+    Q3DScatter *graph = new Q3DScatter();
+    QWidget *container = QWidget::createWindowContainer(graph);
+
+    container->setMinimumSize(800, 600);
+    container->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);
+    container->setFocusPolicy(Qt::StrongFocus);
+
+    QWidget *widget = new QWidget;
+    QHBoxLayout *hLayout = new QHBoxLayout(widget);
+    QVBoxLayout *vLayout = new QVBoxLayout();
+    hLayout->addWidget(container, 1);
+    hLayout->addLayout(vLayout);
+
+    QCommandLinkButton *rangeButton = new QCommandLinkButton(widget);
+    rangeButton->setText(QStringLiteral("Toggle axis ranges"));
+    rangeButton->setDescription(QStringLiteral("Switch between automatic axis ranges and preset ranges"));
+    rangeButton->setIconSize(QSize(0, 0));
+
+    vLayout->addWidget(rangeButton, 1, Qt::AlignTop);
+
+    widget->setWindowTitle(QStringLiteral("Input Handling for Axes"));
+
+    Data *graphData = new Data(graph);
+
+    QObject::connect(rangeButton, &QCommandLinkButton::clicked, graphData, &Data::toggleRanges);
+
+    widget->show();
+    return app.exec();
+}