Document Qt3DSBehavior type

Change-Id: I1c3caa96d19e2089eff061fd7943a533f6f8832c
Task-number: QT3DS-410
Reviewed-by: Mats Honkamaa <mats.honkamaa@qt.io>
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@qt.io>
Reviewed-by: Pasi Keränen <pasi.keranen@qt.io>

3 files changed, 224 insertions, 62 deletions

diff --git a/doc/src/05-runtime/1-event-processing.qdoc b/doc/src/05-runtime/1-event-processing.qdoc
index 8cbae5ee..6bf57259 100644
--- a/doc/src/05-runtime/1-event-processing.qdoc
+++ b/doc/src/05-runtime/1-event-processing.qdoc
@@ -32,47 +32,6 @@
 \page runtime-event-processing.html
 \ingroup qt3dstudio-runtime
 
-\omit
-There are three different event systems in
-the Qt 3D Studio Runtime:
-
-\list
-\li
-  \e{External Events} arrive from outside the
-  system (e.g. from the CAN bus, a keyboard, a game controller) via
-  plugins that expose a queue of events each frame to your application.
-  These events must be explicitly received and handled by your
-  application.
-\li
-  \e{State Machine Events} occur within each
-  state machine running in your application, possibly causing the state
-  machine to possibly change states.
-\li
-  \l{presentation-events}{Presentation Events} occur within each
-  presentation (e.g. touch events, slide changes, Lua script), bubbling
-  up the scene graph of elements within the presentation.
-\endlist
-
-\target external-events
-\section1 External Events
-
-\list
-\li
-  \e{TODO: document the handling of events, with an example App.lua
-  with links to the Lua functions and also to the reference for writing
-  plugins.}
-\endlist
-
-\target state-machine-events
-\section1 State Machine Events
-
-\list
-\li
-  \e{TODO: document the firing of events on state machines, with
-  links to the Lua functions.}
-\endlist
-\endomit
-
 \target presentation-events
 \section1 Presentation Events
 
@@ -136,13 +95,10 @@ runtime, a piece of logic gets created representing this action. When
 the onSelect event is fired and later processed, the interested logic
 will be notified and the slide change will occur.
 
-\omit
-TODO: Needs to be rewritten?
-Note that behavior event registrations (created with Lua's
+\note Behavior event registrations (created with \l {Qt3DSBehavior}{QML Behavior}
 registerForEvent) work similarly to the logic described above. If a
-script registers explicitly for a certain event and in the handler calls
+behavior registers explicitly for a certain event and in the handler calls
 goToSlide, essentially the same things happen.
-\endomit
 
 \section3 Changing Properties
 
@@ -154,40 +110,34 @@ will result in changed properties if a master object inside of Studio
 has one or more of its properties unlinked from the master slide and
 that property is changed per-slide.
 
-\omit
-\section3 Executing Script
+\section3 Executing Behavior Callbacks
 
-Processing an event can result in arbitrary script code being executed.
-An event registration can be created by using the registerForEvent
+Processing an event can result in arbitrary QML Behavior callback code
+being executed. An event registration can be created by using the registerForEvent
 function to listen for a specific event on a specific element. The
 registration also has a callback function associated with it and when
-that specific event targeting that element is processed, the script
+that specific event targeting that element is processed, the behavior
 callback function will be executed.
 
-Of course, script can inspect and change properties on various elements,
-affect slide changes, fire more events, etc. Being able to respond to
-events being processed really empowers scripting.
-\endomit
+Of course, behavior can inspect and change properties on various elements,
+affect slide changes, fire more events, etc.
 
-\omit
-TODO: Needs to be rewritten.
 \section3 Firing More Events (Cascading)
 
 There are two ways a presentation may fire an event in response to
-another event. The first way is through script as described above, and
+another event. The first way is through behaviors as described above, and
 the second way is through the action palette.
 
 Behaviors in Studio can have arbitrary Custom Events associated with
 them by adding these custom events in the header section of the
-behavior's .lua file. When a behavior with one or more Custom Events is
+behavior's .qml file. When a behavior with one or more Custom Events is
 the target of an action in the action palette Studio will offer the Fire
 Event action. By using this action, arbitrary cascading events can be
-set up to fire by pointing and clicking. (as opposed to scripting).
+set up to fire by pointing and clicking.
 
-It's worth repeating that these cascading events will all be processed
+\note These cascading events will all be processed
 in the same frame. The event processor doesn't stop processing events
 until there are none left to process.
-\endomit
 
 \section2 How Your Application (C++) Interacts with Event Processing
 
diff --git a/doc/src/06-qml-reference/Qt3DSBehavior.qdoc b/doc/src/06-qml-reference/Qt3DSBehavior.qdoc
new file mode 100644
index 00000000..a40602d2
--- /dev/null
+++ b/doc/src/06-qml-reference/Qt3DSBehavior.qdoc
@@ -0,0 +1,208 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 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 Qt3DSBehavior
+    \brief Behavior Integration
+
+    Qt 3D Studio supports writing custom behavior scripts using QML. It enables
+    interacting with the runtime using the Qt3DSBehavior QML class exposed to each
+    behavior script.
+
+    In QML behavior script, the integration to Qt 3D Studio is established by using
+    the metadata tag system similar to the \l {file-formats-effects.html}{effect}
+    and \l {file-formats-material.html}{material} files.
+
+    \badcode
+[[
+<Property name="somePropertyName" ... />
+
+<Handler name="someHandlerName" ... />
+
+<Event name="onSomeEvent" ... />
+...
+]]
+    \endcode
+
+    Secondly, the QML behavior script needs access to the QML module.
+    \badcode
+import QtStudio3D.Behavior 1.0
+    \endcode
+
+    Finally, the Qt3DSBehavior type needs to be implemented in the qml script.
+    \badcode
+Qt3DSBehavior {
+    id: mybehavior
+
+    function onInitialize() {
+        ...
+    }
+
+    function onActivate() {
+        ...
+    }
+
+    function onUpdate() {
+        ...
+    }
+
+    function onDeactivate() {
+        ...
+    }
+
+    function someHandlerName() {
+        ...
+        fireEvent("onSomeEvent")
+    }
+}
+    \endcode
+*/
+
+/*!
+    \qmlmethod float Qt3DSBehavior::getDeltaTime()
+
+    Returns the delta time between this and previous frame in milliseconds.
+*/
+
+/*!
+    \qmlmethod float Qt3DSBehavior::getAttribute(string attribute)
+
+    Returns the value of the given \a attribute.
+*/
+
+/*!
+    \qmlmethod void Qt3DSBehavior::setAttribute(string attribute, var value)
+
+    Sets the \a value of the given \a attribute.
+*/
+
+/*!
+    \qmlmethod void Qt3DSBehavior::setAttribute(string handle, string attribute, var value)
+
+    Sets the \a value of the given \a attribute for a given \a handle.
+*/
+
+/*!
+    \qmlmethod void Qt3DSBehavior::fireEvent(string event)
+
+    Fires the given \a event.
+*/
+
+/*!
+    \qmlmethod void Qt3DSBehavior::registerForEvent(string event, QJSValue function)
+
+    Registers the script for an \a event with the handler \a function.
+*/
+
+/*!
+    \qmlmethod void Qt3DSBehavior::registerForEvent(string handle, string event, QJSValue function)
+
+    Registers the script for an \a event with the handler \a function for a given \a handle.
+*/
+
+/*!
+    \qmlmethod void Qt3DSBehavior::unregisterForEvent(string event)
+
+    Unregisters the script from an \a event.
+*/
+
+/*!
+    \qmlmethod void Qt3DSBehavior::unregisterForEvent(string handle, string event)
+
+    Unregisters the script from an \a event for a given \a handle.
+*/
+
+/*!
+    \qmlmethod vector2d Qt3DSBehavior::getMousePosition()
+
+    Returns the current position of the mouse in presentation coordinates.
+*/
+
+/*!
+    \qmlmethod matrix4 Qt3DSBehavior::calculateGlobalTransform(string handle)
+
+    Returns the current global transformation of the element specified by the
+    \a handle or parent element if the handle is empty string.
+*/
+
+/*!
+    \qmlmethod vector3d Qt3DSBehavior::lookAt(vector3d target)
+
+    Returns the rotation angles of the look at \a target.
+*/
+
+/*!
+    \qmlmethod string Qt3DSBehavior::getParent(string handle)
+
+    Returns the parent of the given \a handle or parent element if the handle is
+    empty string.
+*/
+
+/*!
+    \qmlmethod vector3d Qt3DSBehavior::matrixToEuler(matrix4 matrix)
+
+    Returns the euler angles extracted from the \a matrix rotations.
+*/
+
+/*!
+    \qmlsignal void Qt3DSBehavior::onInitialize()
+
+    This signal is emitted when the script becomes active the first time.
+    If multiple behaviors match this, the signal for parent elements will
+    occur before their children/descendants. \note Each behavior will
+    only have its \c{onInitialize} signaled once, even if it is deactivated and
+    later reactivated.
+ */
+
+/*!
+    \qmlsignal void Qt3DSBehavior::onActivate()
+
+    This signal is emitted when the script becomes active.
+    Any behaviors which were not active last frame that are active
+    this frame will have their \c{onActivate} signaled. If
+    multiple behaviors match this, the signal for parent elements will
+    occur before their descendants.
+ */
+
+/*!
+    \qmlsignal void Qt3DSBehavior::onDeactivate()
+
+    This signal is emitted when the script becomes inactive.
+    Any behaviors which were active last frame that are not active
+    this frame will have their \c{onDeactivate} signaled. If
+    multiple behaviors match this, the signal for parent elements will
+    occur before their descendants.
+ */
+
+/*!
+    \qmlsignal void Qt3DSBehavior::onUpdate()
+
+    This signal is emitted on each frame when the script is active.
+    Any behaviors that are active this frame will have their
+    \c{onUpdate} signaled. If multiple behaviors match this, the signal
+    for parent elements will occur before their descendants.
+ */
diff --git a/doc/src/06-qml-reference/qml-index.qdoc b/doc/src/06-qml-reference/qml-index.qdoc
index 97fabb75..fb1f4a3a 100644
--- a/doc/src/06-qml-reference/qml-index.qdoc
+++ b/doc/src/06-qml-reference/qml-index.qdoc
@@ -44,6 +44,10 @@ import QtStudio3D 1.0
 
 \generatelist {qmltypesbymodule QtStudio3D}
 
+\section1 QML Behavior Script
+
+\l Qt3DSBehavior
+
 \section1 Additional Information
 
 //! [toc]