qmlstatemachine: Rename StateBase to State

As discussed with Brett Stottlmyer and Alan Alpert.

Add a section about the implications when importing both
QtQml.StateMachine
and QtQuick in one single QML file.

Change-Id: I8755f4b578e2a6ff4c2377c7a8a0b996ba9b7129
Reviewed-by: BogDan Vatra <bogdan@kde.org>
Reviewed-by: Simon Hausmann <simon.hausmann@digia.com>

13 files changed, 102 insertions, 71 deletions

diff --git a/src/qml/doc/snippets/qml/statemachine/basicstate.qml b/src/qml/doc/snippets/qml/statemachine/basicstate.qml
index dd9d100e9d..ccdd2b2ec1 100644
--- a/src/qml/doc/snippets/qml/statemachine/basicstate.qml
+++ b/src/qml/doc/snippets/qml/statemachine/basicstate.qml
@@ -39,15 +39,15 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0 as DSM
 
 Rectangle {
-    StateMachine {
+    DSM.StateMachine {
         id: stateMachine
         initialState: state
         running: true
-        StateBase {
+        DSM.State {
             id: state
         }
     }
diff --git a/src/qml/doc/snippets/qml/statemachine/finalstate.qml b/src/qml/doc/snippets/qml/statemachine/finalstate.qml
index d03a4bce40..5865436a52 100644
--- a/src/qml/doc/snippets/qml/statemachine/finalstate.qml
+++ b/src/qml/doc/snippets/qml/statemachine/finalstate.qml
@@ -39,22 +39,22 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0 as DSM
 
 Rectangle {
-    StateMachine {
+    DSM.StateMachine {
         id: stateMachine
         initialState: state
         running: true
-        StateBase {
+        DSM.State {
             id: state
-            TimeoutTransition {
+            DSM.TimeoutTransition {
                 targetState: finalState
                 timeout: 200
             }
         }
-        FinalState {
+        DSM.FinalState {
             id: finalState
         }
         onFinished: console.log("state finished")
diff --git a/src/qml/doc/snippets/qml/statemachine/guardcondition.qml b/src/qml/doc/snippets/qml/statemachine/guardcondition.qml
index f9ecf450bd..3d4badb350 100644
--- a/src/qml/doc/snippets/qml/statemachine/guardcondition.qml
+++ b/src/qml/doc/snippets/qml/statemachine/guardcondition.qml
@@ -39,23 +39,23 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0 as DSM
 
 Rectangle {
     Button {
         anchors.fill: parent
         id: button
-        StateMachine {
-            StateBase {
-                SignalTransition {
+        DSM.StateMachine {
+            DSM.State {
+                DSM.SignalTransition {
                     targetState: finalState
                     signal: button.mysignal
                     // the guard condition uses the mystr string argument from mysignal
                     guard: mystr == "test"
                 }
             }
-            FinalState {
+            DSM.FinalState {
                 id: finalState
             }
         }
@@ -66,4 +66,3 @@ Rectangle {
     }
 }
 //! [document]
-
diff --git a/src/qml/doc/snippets/qml/statemachine/historystate.qml b/src/qml/doc/snippets/qml/statemachine/historystate.qml
index 237cf57175..7559bfe06c 100644
--- a/src/qml/doc/snippets/qml/statemachine/historystate.qml
+++ b/src/qml/doc/snippets/qml/statemachine/historystate.qml
@@ -39,38 +39,38 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0 as DSM
 
 Rectangle {
     Button {
         anchors.fill: parent
         id: button
         text: "Press me"
-        StateMachine {
+        DSM.StateMachine {
             id: stateMachine
             initialState: parentState
             running: true
-            StateBase {
+            DSM.State {
                 id: parentState
                 initialState: child2
                 onEntered: console.log("parentState entered")
                 onExited: console.log("parentState exited")
-                StateBase {
+                DSM.State {
                     id: child1
                     onEntered: console.log("child1 entered")
                     onExited: console.log("child1 exited")
                 }
-                StateBase {
+                DSM.State {
                     id: child2
                     onEntered: console.log("child2 entered")
                     onExited: console.log("child2 exited")
                 }
-                HistoryState {
+                DSM.HistoryState {
                     id: historyState
                     defaultState: child1
                 }
-                SignalTransition {
+                DSM.SignalTransition {
                     targetState: historyState
 
                     // Clicking the button will cause the state machine to enter the child state
diff --git a/src/qml/doc/snippets/qml/statemachine/signaltransition.qml b/src/qml/doc/snippets/qml/statemachine/signaltransition.qml
index 7402ac089f..d00a103d7c 100644
--- a/src/qml/doc/snippets/qml/statemachine/signaltransition.qml
+++ b/src/qml/doc/snippets/qml/statemachine/signaltransition.qml
@@ -39,23 +39,23 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0 as DSM
 
 Rectangle {
-    StateMachine {
+    DSM.StateMachine {
         id: stateMachine
         initialState: state
         running: true
-        StateBase {
+        DSM.State {
             id: state
-            SignalTransition {
+            DSM.SignalTransition {
                 targetState: finalState
                 signal: button.clicked
                 guard: guardButton.checked
             }
         }
-        FinalState {
+        DSM.FinalState {
             id: finalState
         }
         onFinished: Qt.quit()
diff --git a/src/qml/doc/snippets/qml/statemachine/signaltransitionsignal.qml b/src/qml/doc/snippets/qml/statemachine/signaltransitionsignal.qml
index 44608fed36..90ebd70eb5 100644
--- a/src/qml/doc/snippets/qml/statemachine/signaltransitionsignal.qml
+++ b/src/qml/doc/snippets/qml/statemachine/signaltransitionsignal.qml
@@ -39,21 +39,21 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0 as DSM
 
 Rectangle {
     Button {
         anchors.fill: parent
         id: button
-        StateMachine {
-            StateBase {
-                SignalTransition {
+        DSM.StateMachine {
+            DSM.State {
+                DSM.SignalTransition {
                     targetState: finalState
                     signal: button.clicked
                 }
             }
-            FinalState {
+            DSM.FinalState {
                 id: finalState
             }
         }
diff --git a/src/qml/doc/snippets/qml/statemachine/simplestatemachine.qml b/src/qml/doc/snippets/qml/statemachine/simplestatemachine.qml
index f5c6923cd1..4e5ea9b65c 100644
--- a/src/qml/doc/snippets/qml/statemachine/simplestatemachine.qml
+++ b/src/qml/doc/snippets/qml/statemachine/simplestatemachine.qml
@@ -39,26 +39,26 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0 as DSM
 
 Rectangle {
     Button {
         anchors.fill: parent
         id: button
         text: "Finish state"
-        StateMachine {
+        DSM.StateMachine {
             id: stateMachine
             initialState: state
             running: true
-            StateBase {
+            DSM.State {
                 id: state
-                SignalTransition {
+                DSM.SignalTransition {
                     targetState: finalState
                     signal: button.clicked
                 }
             }
-            FinalState {
+            DSM.FinalState {
                 id: finalState
             }
             onFinished: Qt.quit()
diff --git a/src/qml/doc/snippets/qml/statemachine/statemachine-button-history.qml b/src/qml/doc/snippets/qml/statemachine/statemachine-button-history.qml
index 10595a9398..8f628232c1 100644
--- a/src/qml/doc/snippets/qml/statemachine/statemachine-button-history.qml
+++ b/src/qml/doc/snippets/qml/statemachine/statemachine-button-history.qml
@@ -39,8 +39,8 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0
 
 Rectangle {
 //![0]
@@ -71,7 +71,7 @@ Rectangle {
         // start the state machine
         running: true
 
-        StateBase {
+        State {
             id: s1
             // set the initial state
             initialState: s11
@@ -84,7 +84,7 @@ Rectangle {
             // do something when the state enters/exits
             onEntered: console.log("s1 entered")
             onExited: console.log("s1 exited")
-            StateBase {
+            State {
                 id: s11
                 // create a transition from s1 to s2 when the button is clicked
                 SignalTransition {
@@ -96,7 +96,7 @@ Rectangle {
                 onExited: console.log("s11 exited")
             }
 
-            StateBase {
+            State {
                 id: s12
                 // create a transition from s2 to s3 when the button is clicked
                 SignalTransition {
@@ -107,7 +107,7 @@ Rectangle {
                 onEntered: console.log("s12 entered")
                 onExited: console.log("s12 exited")
             }
-            StateBase {
+            State {
                 id: s13
                 // create a transition from s3 to s1 when the button is clicked
                 SignalTransition {
@@ -133,7 +133,7 @@ Rectangle {
             onEntered: console.log("s2 entered")
             onExited: console.log("s2 exited")
         }
-        StateBase {
+        State {
             id: s3
             SignalTransition {
                 targetState: s1h
diff --git a/src/qml/doc/snippets/qml/statemachine/statemachine-button-nested-ignore-quit.qml b/src/qml/doc/snippets/qml/statemachine/statemachine-button-nested-ignore-quit.qml
index 00f9cd3871..bf84b4cc90 100644
--- a/src/qml/doc/snippets/qml/statemachine/statemachine-button-nested-ignore-quit.qml
+++ b/src/qml/doc/snippets/qml/statemachine/statemachine-button-nested-ignore-quit.qml
@@ -39,8 +39,8 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0
 
 Rectangle {
     Row {
@@ -66,7 +66,7 @@ Rectangle {
         // start the state machine
         running: true
 
-        StateBase {
+        State {
             id: s1
             // set the initial state
             initialState: s11
@@ -79,7 +79,7 @@ Rectangle {
             // do something when the state enters/exits
             onEntered: console.log("s1 entered")
             onExited: console.log("s1 exited")
-            StateBase {
+            State {
                 id: s11
                 // create a transition from s11 to s12 when the button is clicked
                 SignalTransition {
@@ -92,7 +92,7 @@ Rectangle {
             }
 
 //![0]
-            StateBase {
+            State {
                 id: s12
                 // create a transition from s12 to s13 when the button is clicked
                 SignalTransition {
@@ -112,7 +112,7 @@ Rectangle {
             }
 //![0]
 
-            StateBase {
+            State {
                 id: s13
                 // create a transition from s13 to s11 when the button is clicked
                 SignalTransition {
diff --git a/src/qml/doc/snippets/qml/statemachine/statemachine-button-nested.qml b/src/qml/doc/snippets/qml/statemachine/statemachine-button-nested.qml
index 68bd57d85f..dfa093716f 100644
--- a/src/qml/doc/snippets/qml/statemachine/statemachine-button-nested.qml
+++ b/src/qml/doc/snippets/qml/statemachine/statemachine-button-nested.qml
@@ -39,8 +39,8 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0
 
 Rectangle {
 //![0]
@@ -67,7 +67,7 @@ Rectangle {
         // start the state machine
         running: true
 
-        StateBase {
+        State {
             id: s1
             // set the initial state
             initialState: s11
@@ -80,7 +80,7 @@ Rectangle {
             // do something when the state enters/exits
             onEntered: console.log("s1 entered")
             onExited: console.log("s1 exited")
-            StateBase {
+            State {
                 id: s11
                 // create a transition from s11 to s12 when the button is clicked
                 SignalTransition {
@@ -92,7 +92,7 @@ Rectangle {
                 onExited: console.log("s11 exited")
             }
 
-            StateBase {
+            State {
                 id: s12
                 // create a transition from s12 to s13 when the button is clicked
                 SignalTransition {
@@ -103,7 +103,7 @@ Rectangle {
                 onEntered: console.log("s12 entered")
                 onExited: console.log("s12 exited")
             }
-            StateBase {
+            State {
                 id: s13
                 // create a transition from s13 to s11 when the button is clicked
                 SignalTransition {
diff --git a/src/qml/doc/snippets/qml/statemachine/statemachine-button.qml b/src/qml/doc/snippets/qml/statemachine/statemachine-button.qml
index f2817ead8b..6c4ed846e5 100644
--- a/src/qml/doc/snippets/qml/statemachine/statemachine-button.qml
+++ b/src/qml/doc/snippets/qml/statemachine/statemachine-button.qml
@@ -39,8 +39,8 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0
 
 Rectangle {
 //![0]
@@ -60,7 +60,7 @@ Rectangle {
         // start the state machine
         running: true
 
-        StateBase {
+        State {
             id: s1
             // create a transition from s1 to s2 when the button is clicked
             SignalTransition {
@@ -72,7 +72,7 @@ Rectangle {
             onExited: console.log("s1 exited")
         }
 
-        StateBase {
+        State {
             id: s2
             // create a transition from s2 to s3 when the button is clicked
             SignalTransition {
@@ -83,7 +83,7 @@ Rectangle {
             onEntered: console.log("s2 entered")
             onExited: console.log("s2 exited")
         }
-        StateBase {
+        State {
             id: s3
             // create a transition from s3 to s1 when the button is clicked
             SignalTransition {
diff --git a/src/qml/doc/snippets/qml/statemachine/timeouttransition.qml b/src/qml/doc/snippets/qml/statemachine/timeouttransition.qml
index b15c99cd22..7b8fa77b13 100644
--- a/src/qml/doc/snippets/qml/statemachine/timeouttransition.qml
+++ b/src/qml/doc/snippets/qml/statemachine/timeouttransition.qml
@@ -39,8 +39,8 @@
 ****************************************************************************/
 
 //! [document]
-import QtQml.StateMachine 1.0
 import QtQuick 2.0
+import QtQml.StateMachine 1.0 as DSM
 
 Rectangle {
     Button {
@@ -49,18 +49,18 @@ Rectangle {
         text: "Finish state"
         enabled: !stateMachine.running
         onClicked: stateMachine.running = true
-        StateMachine {
+        DSM.StateMachine {
             id: stateMachine
             initialState: state
             running: true
-            StateBase {
+            DSM.State {
                 id: state
-                TimeoutTransition {
+                DSM.TimeoutTransition {
                     targetState: finalState
                     timeout: 1000
                 }
             }
-            FinalState {
+            DSM.FinalState {
                 id: finalState
             }
         }
diff --git a/src/qml/doc/src/statemachine.qdoc b/src/qml/doc/src/statemachine.qdoc
index 68c57055ca..f200f6f3c0 100644
--- a/src/qml/doc/src/statemachine.qdoc
+++ b/src/qml/doc/src/statemachine.qdoc
@@ -61,7 +61,39 @@
 
   \annotatedlist statemachine-qmltypes
 
-  \section1 A Simple Example
+  \section1 Using both QtQuick and QtQml.StateMachine imports
+
+  \warning If you're attempting to import both \l{QtQuick} and
+    \e{QtQml.StateMachine} in one single QML file, make sure to import
+    \e{QtQml.StateMachine} \e{last}. This way, the \e{State} type is provided
+    by the Declarative State Machine Framework and not by \l{QtQuick}:
+
+  \qml
+    import QtQuick 2.0
+    import QtQml.StateMachine 1.0
+
+    StateMachine {
+        State {
+            // okay, is of type QtQml.StateMachine.State
+        }
+    }
+  \endqml
+
+  Alternatively, you can import \e{QtQml.StateMachine} into a separate
+  namespace to avoid any ambiguity with QtQuick's \e{State} item:
+
+  \qml
+    import QtQuick 2.0
+    import QtQml.StateMachine 1.0 as DSM
+
+    DSM.StateMachine {
+        DSM.State {
+            // ...
+        }
+    }
+  \endqml
+
+  \section1 A Simple State Machine
 
   To demonstrate the core functionality of the State Machine API, let's look
   at an example: A state machine with three states, \c s1, \c s2 and \c
@@ -84,7 +116,7 @@
   The state machine defined in the previous section never finishes. In order
   for a state machine to be able to finish, it needs to have a top-level \e
   final state (FinalState object). When the state machine enters the top-level
-  final state, the machine emits the \l{StateBase::finished}{finished}
+  final state, the machine emits the \l{State::finished}{finished}
   signal and halts.
 
   All you need to do to introduce a final state in the graph is create a
@@ -191,13 +223,13 @@
   To create a parallel state group, set childMode to QState.ParallelStates.
 
   \qml
-    StateBase {
+    State {
         id: s1
         childMode: QState.ParallelStates
-        StateBase {
+        State {
             id: s11
         }
-        StateBase {
+        State {
             id: s12
         }
     }
@@ -221,18 +253,18 @@
   \section1 Exiting a Composite State
 
   A child state can be final (a FinalState object); when a final child state
-  is entered, the parent state emits the StateBase::finished signal. The
+  is entered, the parent state emits the State::finished signal. The
   following diagram shows a composite state \c s1 which does some processing
   before entering a final state:
 
     \image statemachine-finished.png
 
   When \c s1 's final state is entered, \c s1 will automatically emit
-  \l{StateBase::finished}{finished}. We use a signal transition to cause this event to
+  \l{State::finished}{finished}. We use a signal transition to cause this event to
   trigger a state change:
 
   \qml
-    StateBase {
+    State {
         id: s1
         SignalTransition {
             targetState: s2
@@ -251,7 +283,7 @@
   finished() signal, but with the consequence that implementation details of
   \c s1 are exposed and depended on).
 
-  For parallel state groups, the StateBase::finished signal is emitted when \e
+  For parallel state groups, the State::finished signal is emitted when \e
   all the child states have entered final states.
 
   \section1 Targetless Transitions
@@ -270,7 +302,7 @@
             id: stateMachine
             initialState: s1
             running: true
-            StateBase {
+            State {
                 id: s1
                 SignalTransition {
                     signal: button.clicked