Add QML type and C++ class for data input

QML type is DataInput. C++ class is Q3DSDataInput.

Task-number: QT3DS-387
Change-Id: I7f871ae3e1149adee7859fdb8f844e8f90837264
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>

6 files changed, 178 insertions, 2 deletions

diff --git a/doc/src/06-qml-reference/DataInput.qdoc b/doc/src/06-qml-reference/DataInput.qdoc
new file mode 100644
index 00000000..124c1588
--- /dev/null
+++ b/doc/src/06-qml-reference/DataInput.qdoc
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qt 3D Studio.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \qmltype DataInput
+    \inqmlmodule QtStudio3D
+    \brief Control type for data inputs in a Qt 3D Studio presentation.
+    \since QtStudio3D 1.1
+
+    This type is a convenience type for controlling a data input in a presentation.
+
+    \sa Studio3D, Presentation
+*/
+
+/*!
+    \qmlproperty string DataInput::name
+
+    Specifies the name of the controlled data input element in the presentation.
+    This property must be set as part of DataInput declaration.
+*/
+
+/*!
+    \qmlproperty variant DataInput::value
+
+    Specifies the value of the controlled data input element in the presentation.
+    The changes to the value property are queued and handled asynchronously before the
+    next frame is displayed.
+
+    The value of this property only accounts for changes done via the same DataInput instance.
+    If the value of the same data input in the presentation is changed elsewhere,
+    for example via presentation scripting, those changes are not reflected in
+    the value of this property.
+*/
diff --git a/doc/src/06-qml-reference/Presentation.qdoc b/doc/src/06-qml-reference/Presentation.qdoc
index 606c90b0..77a2262e 100644
--- a/doc/src/06-qml-reference/Presentation.qdoc
+++ b/doc/src/06-qml-reference/Presentation.qdoc
@@ -167,6 +167,13 @@
 */
 
 /*!
+    \qmlmethod void Presentation::setDataInputValue(string name, variant value)
+    \since QtStudio3D 1.1
+
+    Sets the \a value of a data input element \a name in the presentation.
+*/
+
+/*!
     \qmlsignal Presentation::slideEntered(string elementPath, int index, string name)
 
     This signal is emitted when a slide is entered in the presentation.
diff --git a/doc/src/06-qml-reference/Studio3D.qdoc b/doc/src/06-qml-reference/Studio3D.qdoc
index 48757f27..07fbbd67 100644
--- a/doc/src/06-qml-reference/Studio3D.qdoc
+++ b/doc/src/06-qml-reference/Studio3D.qdoc
@@ -105,8 +105,8 @@
 */
 
 /*!
-    \qmlsignal bool Studio3D::presentationReady
-    \since 1.1
+    \qmlsignal Studio3D::presentationReady()
+    \since QtStudio3D 1.1
 
     This signal is emitted when the viewer has been initialized and the presentation is ready to
     be shown. The difference to \c running property is that the viewer has to be visible for
diff --git a/doc/src/12-cpp-reference/Q3DSDataInput.qdoc b/doc/src/12-cpp-reference/Q3DSDataInput.qdoc
new file mode 100644
index 00000000..a16bdc0a
--- /dev/null
+++ b/doc/src/12-cpp-reference/Q3DSDataInput.qdoc
@@ -0,0 +1,81 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qt 3D Studio.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \class Q3DSDataInput
+    \inheaderfile q3dsdatainput.h
+    \inmodule QtStudio3D
+    \since QtStudio3D 1.1
+    \brief Control class for data inputs in a Qt 3D Studio presentation.
+
+    This class is a convenience class for controlling a data input in a presentation.
+
+    \sa Q3DSPresentation
+*/
+
+/*!
+    \fn Q3DSDataInput::Q3DSDataInput(const QString &name, QObject *parent = nullptr)
+
+    Constructs a Q3DSDataInput instance and initializes the \a name.
+    An optional \a parent object can be specified.
+*/
+
+/*!
+    \fn Q3DSDataInput::Q3DSDataInput(Q3DSPresentation *presentation, const QString &name,
+                                     QObject *parent = nullptr)
+
+    Constructs a Q3DSDataInput instance and initializes the \a name.
+    The constructed instance is automatically \l{Q3DSPresentation::registerDataInput}{registered}
+    for the \a presentation.
+    An optional \a parent object can be specified.
+*/
+
+/*!
+    \fn Q3DSDataInput::Q3DSDataInput(Q3DSDataInputPrivate *d, Q3DSPresentation *presentation,
+                                     const QString &name, QObject *parent = nullptr)
+    \internal
+*/
+
+/*!
+    \property Q3DSDataInput::name
+
+    Specifies the name of the controlled data input element in the presentation.
+    This property must be set before the data input is registered to a presentation.
+
+    \sa Q3DSPresentation::registerDataInput()
+*/
+
+/*!
+    \property Q3DSDataInput::value
+
+    Specifies the value of the controlled data input element in the presentation.
+
+    The value of this property only accounts for changes done via the same Q3DSDataInput instance.
+    If the value of the same data input in the presentation is changed elsewhere,
+    for example via presentation scripting, those changes are not reflected in
+    the value of this property.
+*/
diff --git a/doc/src/12-cpp-reference/Q3DSPresentation.qdoc b/doc/src/12-cpp-reference/Q3DSPresentation.qdoc
index 02fa7a55..12b45acd 100644
--- a/doc/src/12-cpp-reference/Q3DSPresentation.qdoc
+++ b/doc/src/12-cpp-reference/Q3DSPresentation.qdoc
@@ -79,6 +79,29 @@
 */
 
 /*!
+    \fn void Q3DSPresentation::registerDataInput(Q3DSDataInput *dataInput)
+
+    \since QtStudio3D 1.1
+    Registers a \a dataInput for the presentation. The registered \a dataInput can be used to manage
+    the corresponding data input in the presentation.
+*/
+
+/*!
+    \fn void Q3DSPresentation::unregisterDataInput(Q3DSDataInput *dataInput)
+    \since QtStudio3D 1.1
+
+    Unregisters a \a dataInput from the presentation.
+*/
+
+/*!
+    \fn Q3DSElement *Q3DSPresentation::registeredDataInput(const QString &name) const
+    \since QtStudio3D 1.1
+
+    Returns a pointer to a registered data input with \a name. If no data input with given name
+    is registered, a null pointer is returned.
+*/
+
+/*!
     \fn void Q3DSPresentation::goToSlide(const QString &elementPath, unsigned int index)
 
     Requests a time context (a Scene or a Component element) to change to a specific slide by
@@ -193,6 +216,13 @@
 */
 
 /*!
+    \fn void Q3DSPresentation::setDataInputValue(const QString &name, const QVariant &value)
+    \since QtStudio3D 1.1
+
+    Sets the \a value of a data input element \a name in the presentation.
+*/
+
+/*!
     \fn void Q3DSPresentation::slideEntered(const QString &elementPath, unsigned int index, const QString &name)
 
     This signal is emitted when a slide is entered in the presentation.
diff --git a/doc/src/examples-index.qdoc b/doc/src/examples-index.qdoc
index 7b456a81..4955b7e7 100644
--- a/doc/src/examples-index.qdoc
+++ b/doc/src/examples-index.qdoc
@@ -39,6 +39,7 @@ folder in the installation folder.
 \list
      \li \l {Qt 3D Studio: Dynamic Keyframes Example}
      \li \l {Qt 3D Studio: QML Streamer Example}
+     \li \l {Qt 3D Studio: QML DataInput Example}
 \endlist
 
 \section1 More Examples