Qdoc documentation for new scene and input classes.

Change-Id: I5d9680fcf2e49655c1b9bcdf961bbda02bf31968
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@digia.com>
Reviewed-by: Tomi Korpipää <tomi.korpipaa@digia.com>

6 files changed, 166 insertions, 41 deletions

diff --git a/src/datavisualization/input/q3dinputhandler.cpp b/src/datavisualization/input/q3dinputhandler.cpp
index 8c7d83d0..6fd5f08b 100644
--- a/src/datavisualization/input/q3dinputhandler.cpp
+++ b/src/datavisualization/input/q3dinputhandler.cpp
@@ -19,6 +19,7 @@
 #include "datavisualizationglobal_p.h"
 #include "q3dinputhandler.h"
 #include "q3dcamera.h"
+#include "q3dcamera_p.h"
 #include "q3dlight.h"
 
 QT_DATAVISUALIZATION_BEGIN_NAMESPACE
@@ -32,28 +33,46 @@ const int nearZoomRangeDivider = 12;
 const int midZoomRangeDivider  = 60;
 const int farZoomRangeDivider  = 120;
 
-const qreal rotationSpeed    = 100.0;
+const float rotationSpeed    = 100.0f;
 
+/*!
+   \class Q3DInputHandler
+   \inmodule QtDataVisualization
+   \brief Basic wheel mouse based input handler.
+   \since 1.0.0
+
+    Q3DInputHandler is the basic input handler for wheel mouse type of input devices.
+*/
+
+/*!
+ * Constructs the basic mouse input handler. An optional \a parent parameter can be given
+ * and is then passed to QObject constructor.
+ */
 Q3DInputHandler::Q3DInputHandler(QObject *parent) :
     QAbstract3DInputHandler(parent)
 {
 }
 
+/*!
+ *  Destroys the input handler.
+ */
 Q3DInputHandler::~Q3DInputHandler()
 {
 }
 
 // Input event listeners
+/*!
+ * Override this to change handling of mouse press events.
+ * Mouse press event is given in the \a event and the mouse position in \a mousePos.
+ */
 void Q3DInputHandler::mousePressEvent(QMouseEvent *event, const QPoint &mousePos)
 {
     if (Qt::LeftButton == event->button()) {
-        if (scene()->isSlicingActivated()) {
-            if (scene()->isInputInsideMainView(mousePos)) {
+        if (scene()->isSlicingActive()) {
+            if (scene()->isPointInPrimarySubView(mousePos)) {
                 setInputState(QDataVis::InputOnOverview);
-                //qDebug() << "Mouse pressed on overview";
-            } else if (scene()->isInputInsideSliceView(mousePos)) {
+            } else if (scene()->isPointInSecondarySubView(mousePos)) {
                 setInputState(QDataVis::InputOnSlice);
-                //qDebug() << "Mouse pressed on zoom";
             } else {
                 setInputState(QDataVis::InputNone);
             }
@@ -63,21 +82,23 @@ void Q3DInputHandler::mousePressEvent(QMouseEvent *event, const QPoint &mousePos
             setInputPosition(mousePos);
             // TODO: Get rid of these (QTRD-2307)
             emit selectionAtPoint(mousePos);
-            //qDebug() << "Mouse pressed on scene";
-
         }
     } else if (Qt::MiddleButton == event->button()) {
         // reset rotations
         setInputPosition(QPoint(0, 0));
     } else if (Qt::RightButton == event->button()) {
         // disable rotating when in slice view
-        if (!scene()->isSlicingActivated())
+        if (!scene()->isSlicingActive())
             setInputState(QDataVis::InputRotating);
         // update mouse positions to prevent jumping when releasing or repressing a button
         setInputPosition(mousePos);
     }
 }
 
+/*!
+ * Override this to change handling of mouse release events.
+ * Mouse release event is given in the \a event and the mouse position in \a mousePos.
+ */
 void Q3DInputHandler::mouseReleaseEvent(QMouseEvent *event, const QPoint &mousePos)
 {
     Q_UNUSED(event);
@@ -88,13 +109,17 @@ void Q3DInputHandler::mouseReleaseEvent(QMouseEvent *event, const QPoint &mouseP
     setInputState(QDataVis::InputNone);
 }
 
+/*!
+ * Override this to change handling of mouse move events.
+ * Mouse move event is given in the \a event and the mouse position in \a mousePos.
+ */
 void Q3DInputHandler::mouseMoveEvent(QMouseEvent *event, const QPoint &mousePos)
 {
     Q_UNUSED(event);
 
     if (QDataVis::InputRotating == inputState()) {
         // Calculate mouse movement since last frame
-        QPointF rotations = scene()->camera()->rotations();
+        QPointF rotations = scene()->activeCamera()->rotations();
         GLfloat xRotation = rotations.x();
         GLfloat yRotation = rotations.y();
         GLfloat mouseMoveX = GLfloat(inputPosition().x() - mousePos.x())
@@ -104,22 +129,26 @@ void Q3DInputHandler::mouseMoveEvent(QMouseEvent *event, const QPoint &mousePos)
         // Apply to rotations
         xRotation -= mouseMoveX;
         yRotation -= mouseMoveY;
-        scene()->camera()->setRotations(QPointF(xRotation, yRotation));
-        scene()->camera()->updateViewMatrix(1.0f);
+        scene()->activeCamera()->setRotations(QPointF(xRotation, yRotation));
+        scene()->activeCamera()->d_ptr->updateViewMatrix(1.0f);
 
         setPreviousInputPos(inputPosition());
         setInputPosition(mousePos);
     }
 }
 
+/*!
+ * Override this to change handling of wheel events.
+ * The wheel event is given in the \a event.
+ */
 void Q3DInputHandler::wheelEvent(QWheelEvent *event)
 {
     // disable zooming if in slice view
-    if (scene()->isSlicingActivated())
+    if (scene()->isSlicingActive())
         return;
 
     // Adjust zoom level based on what zoom range we're in.
-    int zoomLevel = scene()->camera()->zoomLevel();
+    int zoomLevel = scene()->activeCamera()->zoomLevel();
     if (zoomLevel > oneToOneZoomLevel)
         zoomLevel += event->angleDelta().y() / nearZoomRangeDivider;
     else if (zoomLevel > halfSizeZoomLevel)
@@ -131,7 +160,7 @@ void Q3DInputHandler::wheelEvent(QWheelEvent *event)
     else if (zoomLevel < minZoomLevel)
         zoomLevel = minZoomLevel;
 
-    scene()->camera()->setZoomLevel(zoomLevel);
+    scene()->activeCamera()->setZoomLevel(zoomLevel);
 }
 
 QT_DATAVISUALIZATION_END_NAMESPACE
diff --git a/src/datavisualization/input/q3dinputhandler.h b/src/datavisualization/input/q3dinputhandler.h
index a337d4d6..4d49d318 100644
--- a/src/datavisualization/input/q3dinputhandler.h
+++ b/src/datavisualization/input/q3dinputhandler.h
@@ -37,9 +37,6 @@ public:
     virtual void mouseMoveEvent(QMouseEvent *event, const QPoint &mousePos);
     virtual void wheelEvent(QWheelEvent *event);
 
-signals:
-    void rotationSpeedChanged(int rotationSpeed);
-
 private:
     Q_DISABLE_COPY(Q3DInputHandler)
 };
diff --git a/src/datavisualization/input/qabstract3dinputhandler.cpp b/src/datavisualization/input/qabstract3dinputhandler.cpp
index 8b1a3419..9dd5f862 100644
--- a/src/datavisualization/input/qabstract3dinputhandler.cpp
+++ b/src/datavisualization/input/qabstract3dinputhandler.cpp
@@ -19,51 +19,99 @@
 
 QT_DATAVISUALIZATION_BEGIN_NAMESPACE
 
+/*!
+   \class QAbstract3DInputHandler
+   \inmodule QtDataVisualization
+   \brief Baseclass for implementations of input handlers.
+   \since 1.0.0
+
+    QAbstract3DInputHandler is a baseclass that is subclassed by different input handling implementations
+    that take input events and translate those to camera and light movements. Input handlers also translate
+    raw input events to slicing and selection events in the scene.
+*/
+
+/*!
+ * Constructs the baseclass. An optional \a parent parameter can be given
+ * and is then passed to QObject constructor.
+ */
 QAbstract3DInputHandler::QAbstract3DInputHandler(QObject *parent) :
     QObject(parent),
     d_ptr(new QAbstract3DInputHandlerPrivate(this))
 {
 }
 
+/*!
+ *  Destroys the baseclass.
+ */
 QAbstract3DInputHandler::~QAbstract3DInputHandler()
 {
 }
 
 // Input event listeners
+/*!
+ * Override this to handle mouse double click events.
+ * Mouse double click event is given in the \a event.
+ */
 void QAbstract3DInputHandler::mouseDoubleClickEvent(QMouseEvent *event)
 {
     Q_UNUSED(event);
 }
 
+/*!
+ * Override this to handle touch input events.
+ * Touch event is given in the \a event.
+ */
 void QAbstract3DInputHandler::touchEvent(QTouchEvent *event)
 {
     Q_UNUSED(event);
 }
 
+/*!
+ * Override this to handle mouse press events.
+ * Mouse press event is given in the \a event and the mouse position in \a mousePos.
+ */
 void QAbstract3DInputHandler::mousePressEvent(QMouseEvent *event, const QPoint &mousePos)
 {
     Q_UNUSED(event);
     Q_UNUSED(mousePos);
 }
 
+/*!
+ * Override this to handle mouse release events.
+ * Mouse release event is given in the \a event and the mouse position in \a mousePos.
+ */
 void QAbstract3DInputHandler::mouseReleaseEvent(QMouseEvent *event, const QPoint &mousePos)
 {
     Q_UNUSED(event);
     Q_UNUSED(mousePos);
 }
 
+/*!
+ * Override this to handle mouse move events.
+ * Mouse move event is given in the \a event and the mouse position in \a mousePos.
+ */
 void QAbstract3DInputHandler::mouseMoveEvent(QMouseEvent *event, const QPoint &mousePos)
 {
     Q_UNUSED(event);
     Q_UNUSED(mousePos);
 }
 
+/*!
+ * Override this to handle wheel events.
+ * Wheel event is given in the \a event.
+ */
 void QAbstract3DInputHandler::wheelEvent(QWheelEvent *event)
 {
     Q_UNUSED(event);
 }
 
 // Property get/set
+/*!
+ * \property QAbstract3DInputHandler::inputState
+ *
+ * Current enumerated input state based on the processed input events.
+ * When the state changes inputStateChanged() is emitted.
+ */
 QDataVis::InputState QAbstract3DInputHandler::inputState()
 {
     return d_ptr->m_inputState;
@@ -77,6 +125,11 @@ void QAbstract3DInputHandler::setInputState(QDataVis::InputState inputState)
     }
 }
 
+/*!
+ * \property QAbstract3DInputHandler::inputPosition
+ *
+ * Last input position based on the processed input events.
+ */
 QPoint QAbstract3DInputHandler::inputPosition() const
 {
     return d_ptr->m_inputPosition;
@@ -90,17 +143,27 @@ void QAbstract3DInputHandler::setInputPosition(const QPoint &position)
     }
 }
 
-void QAbstract3DInputHandler::setPrevDistance(int distance)
-{
-    d_ptr->m_prevDistance = distance;
-}
-
+/*!
+ * \return the manhattan length between last two input positions.
+ */
 int QAbstract3DInputHandler::prevDistance() const
 {
     return d_ptr->m_prevDistance;
 }
 
+/*!
+ * Sets the \a distance (manhattan length) between last two input positions.
+ */
+void QAbstract3DInputHandler::setPrevDistance(int distance)
+{
+    d_ptr->m_prevDistance = distance;
+}
 
+/*!
+ * \property QAbstract3DInputHandler::scene
+ *
+ * The 3D scene this abstract inputhandler is controlling. Only one scene can be controlled by one input handler.
+ */
 Q3DScene *QAbstract3DInputHandler::scene() const
 {
     return d_ptr->m_scene;
@@ -111,18 +174,24 @@ void QAbstract3DInputHandler::setScene(Q3DScene *scene)
     d_ptr->m_scene = scene;
 }
 
+/*!
+ * Sets the previous input position to the point given by \a position.
+ */
 void QAbstract3DInputHandler::setPreviousInputPos(const QPoint &position)
 {
     d_ptr->m_previousInputPos = position;
 }
 
+/*!
+ * Returns the previous input position.
+ * \return Previous input position.
+ */
 QPoint QAbstract3DInputHandler::previousInputPos() const
 {
     return d_ptr->m_previousInputPos;
 }
 
 
-
 QAbstract3DInputHandlerPrivate::QAbstract3DInputHandlerPrivate(QAbstract3DInputHandler *q) :
     q_ptr(q),
     m_prevDistance(0),
diff --git a/src/datavisualization/input/qabstract3dinputhandler.h b/src/datavisualization/input/qabstract3dinputhandler.h
index d19f626d..96d4de97 100644
--- a/src/datavisualization/input/qabstract3dinputhandler.h
+++ b/src/datavisualization/input/qabstract3dinputhandler.h
@@ -32,7 +32,7 @@ class QT_DATAVISUALIZATION_EXPORT QAbstract3DInputHandler : public QObject
     Q_OBJECT
     Q_PROPERTY(QtDataVisualization::QDataVis::InputState inputState READ inputState WRITE setInputState NOTIFY inputStateChanged)
     Q_PROPERTY(QPoint inputPosition READ inputPosition WRITE setInputPosition NOTIFY positionChanged)
-    Q_PROPERTY(Q3DScene *scene READ scene WRITE setScene)
+    Q_PROPERTY(Q3DScene *scene READ scene WRITE setScene NOTIFY sceneChanged)
 
 public:
     explicit QAbstract3DInputHandler(QObject *parent = 0);
@@ -47,28 +47,28 @@ public:
     virtual void wheelEvent(QWheelEvent *event);
 
 public:
-    // Property get/set functions
-
     // TODO: Check if the inputState needs to be visible outside of subclasses in the final architecture
     QDataVis::InputState inputState();
     void setInputState(QDataVis::InputState inputState);
-    void setInputPosition(const QPoint &position);
+
     QPoint inputPosition() const;
+    void setInputPosition(const QPoint &position);
 
     Q3DScene *scene() const;
     void setScene(Q3DScene *scene);
 
+signals:
+    void positionChanged(const QPoint &position);
+    void inputStateChanged(QDataVis::InputState state);
+    void selectionAtPoint(const QPoint &point);
+    void sceneChanged(const Q3DScene *scene);
+
 protected:
     void setPrevDistance(int distance);
     int prevDistance() const;
     void setPreviousInputPos(const QPoint &position);
     QPoint previousInputPos() const;
 
-signals:
-    void positionChanged(const QPoint &position);
-    void inputStateChanged(QDataVis::InputState state);
-    void selectionAtPoint(const QPoint &point);
-
 private:
     Q_DISABLE_COPY(QAbstract3DInputHandler)
 
diff --git a/src/datavisualization/input/qtouch3dinputhandler.cpp b/src/datavisualization/input/qtouch3dinputhandler.cpp
index f77ac9c0..de5ba843 100644
--- a/src/datavisualization/input/qtouch3dinputhandler.cpp
+++ b/src/datavisualization/input/qtouch3dinputhandler.cpp
@@ -25,20 +25,40 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
 const qreal maxTapAndHoldJitter = 10;
 const int tapAndHoldTime = 250;
 
+/*!
+   \class QTouch3DInputHandler
+   \inmodule QtDataVisualization
+   \brief Basic touch display based input handler.
+   \since 1.0.0
+
+    QTouch3DInputHandler is the basic input handler for touch screen devices.
+*/
+
+/*!
+ * Constructs the basic touch display input handler. An optional \a parent parameter can be given
+ * and is then passed to QObject constructor.
+ */
 QTouch3DInputHandler::QTouch3DInputHandler(QObject *parent)
     : Q3DInputHandler(parent),
       d_ptr(new QTouch3DInputHandlerPrivate(this))
 {
 }
 
+/*!
+ *  Destroys the input handler.
+ */
 QTouch3DInputHandler::~QTouch3DInputHandler()
 {
 }
 
 // Input event listeners
+/*!
+ * Override this to change handling of mouse double click events.
+ * Mouse double click event is given in the \a event.
+ */
 void QTouch3DInputHandler::mouseDoubleClickEvent(QMouseEvent *event)
 {
-    if (!scene()->isSlicingActivated()) {
+    if (!scene()->isSlicingActive()) {
         setInputState(QDataVis::InputOnScene);
         // update mouse positions to prevent jumping when releasing or repressing a button
         setInputPosition(event->pos());
@@ -47,12 +67,16 @@ void QTouch3DInputHandler::mouseDoubleClickEvent(QMouseEvent *event)
     }
 }
 
+/*!
+ * Override this to change handling of touch events.
+ * Touch event is given in the \a event.
+ */
 void QTouch3DInputHandler::touchEvent(QTouchEvent *event)
 {
     QList<QTouchEvent::TouchPoint> points;
     points = event->touchPoints();
 
-    if (!scene()->isSlicingActivated() && points.count() == 2) {
+    if (!scene()->isSlicingActive() && points.count() == 2) {
         d_ptr->m_holdTimer->stop();
 
         setInputState(QDataVis::InputOnPinch);
@@ -60,7 +84,7 @@ void QTouch3DInputHandler::touchEvent(QTouchEvent *event)
         QPointF distance = points.at(0).pos() - points.at(1).pos();
         int newDistance = distance.manhattanLength();
         int zoomRate = 1;
-        int zoomLevel = scene()->camera()->zoomLevel();
+        int zoomLevel = scene()->activeCamera()->zoomLevel();
         if (zoomLevel > 100)
             zoomRate = 5;
         if (newDistance > prevDistance())
@@ -71,9 +95,9 @@ void QTouch3DInputHandler::touchEvent(QTouchEvent *event)
             zoomLevel = 500;
         else if (zoomLevel < 10)
             zoomLevel = 10;
-        scene()->camera()->setZoomLevel(zoomLevel);
+        scene()->activeCamera()->setZoomLevel(zoomLevel);
         setPrevDistance(newDistance);
-    } else if (!scene()->isSlicingActivated() && points.count() == 1) {
+    } else if (!scene()->isSlicingActive() && points.count() == 1) {
         if (event->type() == QEvent::TouchBegin) {
             // Tap-and-hold selection start
             d_ptr->m_startHoldPos = points.at(0).pos();
@@ -89,15 +113,20 @@ void QTouch3DInputHandler::touchEvent(QTouchEvent *event)
     }
 }
 
+/*!
+ * Override this to change handling of mouse press events.
+ * Mouse press event is given in the \a event and the mouse position in \a mousePos.
+ * \warning This method is subject to change or removal.
+ */
 void QTouch3DInputHandler::mousePressEvent(QMouseEvent *event, const QPoint &mousePos)
 {
     // TODO: This code needs revisiting with new Qt releases and possibly move to using touch events for these as well.
     if (Qt::LeftButton == event->button()) {
-        if (scene()->isSlicingActivated()) {
-            if (scene()->isInputInsideMainView(mousePos)) {
+        if (scene()->isSlicingActive()) {
+            if (scene()->isPointInPrimarySubView(mousePos)) {
                 setInputState(QDataVis::InputOnOverview);
                 //qDebug() << "Mouse pressed on overview";
-            } else if (scene()->isInputInsideSliceView(mousePos)) {
+            } else if (scene()->isPointInSecondarySubView(mousePos)) {
                 setInputState(QDataVis::InputOnSlice);
                 //qDebug() << "Mouse pressed on zoom";
             } else {
diff --git a/src/datavisualization/input/qtouch3dinputhandler.h b/src/datavisualization/input/qtouch3dinputhandler.h
index 2c4b67dd..d33807a6 100644
--- a/src/datavisualization/input/qtouch3dinputhandler.h
+++ b/src/datavisualization/input/qtouch3dinputhandler.h
@@ -20,6 +20,7 @@
 #define QTOUCH3DINPUTHANDLER_H
 
 #include <QtDataVisualization/q3dinputhandler.h>
+#include "q3dcamera.h"
 
 QT_DATAVISUALIZATION_BEGIN_NAMESPACE