Merge branch 'kinetic-declarativeui' of git@scm.dev.nokia.troll.no:qt/kinetic into kinetic-declarativeui

10 files changed, 107 insertions, 73 deletions

diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index d05a444..bf5907d 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -49,6 +49,8 @@ real, int, color, rect, point, and size can all be animated.
 QML supports three different forms of animation - basic property animation,
 transitions, and property behaviors.
 
+\tableofcontents
+
 \section1 Basic Property Animation
 
 The simplest form of animation is directly using \l PropertyAnimation, which can animate all of the property
diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc
index a8376eb..492a8ea 100644
--- a/doc/src/declarative/example-slideswitch.qdoc
+++ b/doc/src/declarative/example-slideswitch.qdoc
@@ -131,4 +131,7 @@ In order for the the knob to move smoothly we add a transition that will animate
 
 For more information on transitions see \l{state-transitions}{QML Transitions}.
 
+\section1 Usage
+The switch can be used in a QML file, like this:
+\snippet examples/declarative/slideswitch/slideswitch.qml 0
 */
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 7a9de60..0233aa7 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -531,7 +531,7 @@ in the bind engine for allowing an object to access the binding directly.
 
 If a binding is assigned to a property with a type of QmlBinding
 pointer (ie. \c {QmlBinding *}), each time the binding value changes,
-a QmlBinding instance is assigned to that property.  The QmlBinding instance 
+a QmlBinding instance is assigned to that property.  The QmlBinding instance
 allows the object to read the binding and to evaluate the binding's current value.
 
 \section1 Extension Objects
@@ -548,16 +548,16 @@ directly, if this is either not possible or is complicated by some other
 concerns, extension objects allow limited extension possibilities without
 direct modifications.
 
-Extension objects are used to add additional properties to an existing type.  
-Extension objects can only add properties, not signals or methods.  An extended 
-type definition allows the programmer to supply an additional type - known as the 
-extension type - when registering the target class whose properties are 
+Extension objects are used to add additional properties to an existing type.
+Extension objects can only add properties, not signals or methods.  An extended
+type definition allows the programmer to supply an additional type - known as the
+extension type - when registering the target class whose properties are
 transparently merged with the original target class when used from within QML.
 
-An extension class is a regular QObject, with a constructor that takes a QObject 
-pointer.  When needed (extension classes are delay created until the first extended 
-property is accessed) the extension class is created and the target object is 
-passed in as the parent.  When an extended property on the original is accessed, 
+An extension class is a regular QObject, with a constructor that takes a QObject
+pointer.  When needed (extension classes are delay created until the first extended
+property is accessed) the extension class is created and the target object is
+passed in as the parent.  When an extended property on the original is accessed,
 the appropriate property on the extension object is used instead.
 
 When an extended type is installed, one of the
@@ -565,22 +565,22 @@ When an extended type is installed, one of the
     #define QML_DEFINE_EXTENDED_TYPE(URI, VMAJ, VFROM, VTO, QmlName,T, ExtendedT)
     #define QML_DEFINE_EXTENDED_NOCREATE_TYPE(T, ExtendedT)
 \endcode
-macros should be used instead of the regular \c QML_DEFINE_TYPE or 
-\c QML_DEFINE_NOCREATE_TYPE.  The arguments are identical to the corresponding 
-non-extension object macro, except for the ExtendedT parameter which is the type 
+macros should be used instead of the regular \c QML_DEFINE_TYPE or
+\c QML_DEFINE_NOCREATE_TYPE.  The arguments are identical to the corresponding
+non-extension object macro, except for the ExtendedT parameter which is the type
 of the extension object.
 
 \section1 Optimization
 
-Often to develop high performance elements it is helpful to know more about the 
-status of the QML engine. For example, it might be beneficial to delay 
-initializing some costly data structures until after all the properties have been 
+Often to develop high performance elements it is helpful to know more about the
+status of the QML engine. For example, it might be beneficial to delay
+initializing some costly data structures until after all the properties have been
 set.
 
 The QML engine defines an interface class called QmlParserStatus, which contains a
-number of virtual methods that are invoked at various stages during component 
-instantiation.  To receive these notifications, an element implementation inherits 
-QmlParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro.  
+number of virtual methods that are invoked at various stages during component
+instantiation.  To receive these notifications, an element implementation inherits
+QmlParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro.
 
 For example,
 
@@ -636,7 +636,7 @@ declaring a new property, and the corresponding C++ type.
 \row \o variant \o QVariant
 \endtable
 
-QML supports two methods for adding a new property to a type - a new property
+QML supports two methods for adding a new property to a type: a new property
 definition, and a property alias.
 
 \section2 Property definitions
@@ -691,6 +691,7 @@ controls the color of the inner rectangle.
     }
 \endcode
 
+\target qml-property-aliases
 \section2 Property aliases
 
 Property aliases are a more advanced form of property declaration.  Unlike a
@@ -714,11 +715,12 @@ binding, the alias reference syntax is highly restricted.
 
 An alias reference takes one of the following forms
 \code
-    <Id>.<property>
-    <Id>
+    <id>.<property>
+    <id>
 \endcode
-where <Id> must refer to an object id within the same component as the type
-declaring the alias, and, optionally, <property> refers to a property on that object.  
+
+where <id> must refer to an object id within the same component as the type
+declaring the alias, and, optionally, <property> refers to a property on that object.
 
 Here is the property definition example rewritten to use property aliases.
 \code
diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc
index 8061a7c..924f590 100644
--- a/doc/src/declarative/focus.qdoc
+++ b/doc/src/declarative/focus.qdoc
@@ -49,6 +49,8 @@ focused QML \l Item.  To facilitate the construction of reusable components
 and to address some of the cases unique to fluid user interfaces, the QML items add a
 \e scope based extension to Qt's traditional keyboard focus model.
 
+\tableofcontents
+
 \section1 Key Handling Overview
 
 When the user presses or releases a key, the following occurs:
diff --git a/doc/src/declarative/qmlstates.qdoc b/doc/src/declarative/qmlstates.qdoc
index ddb0fc8..245a57f 100644
--- a/doc/src/declarative/qmlstates.qdoc
+++ b/doc/src/declarative/qmlstates.qdoc
@@ -3,6 +3,8 @@
 \target qmlstates
 \title QML States
 
+\section1 Overview
+
 QML states typically describe user interface configurations, including:
 \list
 \o What UI elements are present
@@ -14,10 +16,12 @@ A state can also be thought of as a set of batched changes from a default config
 
 Examples of states in modern UI:
 \list
-\o A Contacts application has a 'View Contact' state and an 'Edit Contact' State. In the first state the information presented is static (using labels), and in the second it is editable (using editors).
-\o A button has a pressed and unpressed state. When pressed the text moves down and to the right, and the button has a slightly darker appearance.
+\o An Address Book application with a 'View Contact' state and an 'Edit Contact' State. In the first state the contact information presented is read-only (using labels), and in the second it is editable (using editors).
+\o A button with a pressed and unpressed state. When pressed the text moves slightly down and to the right, and the button has a slightly darker appearance.
 \endlist
 
+\section1 States in QML
+
 In QML:
 \list
 \o Any object can use states.
@@ -25,29 +29,38 @@ In QML:
 \o A state can affect the properties of other objects, not just the object owning the state (and not just that object's children).
 \endlist
 
-The following example shows a simple use of states. In the default state \c myrect is positioned at 0,0. In the 'moved' state it is positioned at 50,50.
+Here is an example of using states. In the default state \c myRect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. Clicking within the mouse region changes the state from the default state to the 'moved' state.
 
-\code
+\qml
 Item {
+    id: myItem
+
     Rectangle {
-        id: myrect
+        id: myRect
         width: 100
         height: 100
+        color: "red"
     }
+
     states: [
         State {
             name: "moved"
             PropertyChanges {
-                target: myrect
+                target: myRect
                 x: 50
                 y: 50
             }
         }
     ]
+
+    MouseRegion {
+        anchors.fill: parent
+        onClicked: myItem.state = 'moved'
+    }
 }
-\endcode
+\endqml
 
-To animate state changes, you can use \l{state-transitions}{transitions}.
+State changes can be animated using \l{state-transitions}{transitions}.
 
 Other things you can do in a state change:
 \list
diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc
index f7f25f5..ef30f94 100644
--- a/doc/src/declarative/scope.qdoc
+++ b/doc/src/declarative/scope.qdoc
@@ -43,6 +43,8 @@
 \page qmlscope.html
 \title QML Scope
 
+\tableofcontents
+
 \l {Property Binding}s and \l {ECMAScript Blocks} are executed in a scope chain automatically 
 established by QML when a component instance is constructed.  QML is a \e {dynamically scoped} 
 language.  Different object instances instantiated from the same component can exist in 
diff --git a/examples/declarative/slideswitch/slideswitch.qml b/examples/declarative/slideswitch/slideswitch.qml
index 9b46cd1..396749f 100644
--- a/examples/declarative/slideswitch/slideswitch.qml
+++ b/examples/declarative/slideswitch/slideswitch.qml
@@ -5,7 +5,7 @@ Rectangle {
     color: "white"
     width: 400; height: 250
 
-    Switch {
-        anchors.centerIn: parent
-    }
+//![0]
+    Switch { anchors.centerIn: parent; on: false }
+//![0]
 }
diff --git a/examples/declarative/tutorials/helloworld/Cell.qml b/examples/declarative/tutorials/helloworld/Cell.qml
index ab6e565..c38b40e 100644
--- a/examples/declarative/tutorials/helloworld/Cell.qml
+++ b/examples/declarative/tutorials/helloworld/Cell.qml
@@ -8,7 +8,7 @@ Item {
     property alias color: rectangle.color
 //![4]
 //![5]
-    signal clicked(string color)
+    signal clicked(color color)
 //![5]
 
     width: 40; height: 25
diff --git a/src/declarative/qml/qmlscript.cpp b/src/declarative/qml/qmlscript.cpp
index 7242498..eb0b858 100644
--- a/src/declarative/qml/qmlscript.cpp
+++ b/src/declarative/qml/qmlscript.cpp
@@ -43,12 +43,13 @@
 
 /*!
     \qmlclass Script QmlScript
-    \brief The Script element adds JavaScript snippets.
+    \brief The Script element provides a way to add JavaScript code snippets in QML.
     \ingroup group_utility
 
-    QmlScript is used to add convenient JavaScript "glue" methods to
-    your Qt Declarative application or component. While you can have any JavaScript code
-    within a QmlScript, it is best to limit yourself to defining functions.
+    The Script element is used to add convenient JavaScript "glue" methods to
+    your Qt Declarative application or component. 
+
+    An example: 
 
     \qml
     Script {
@@ -60,23 +61,27 @@
     MouseRegion { onClicked: debugMyComponent() }
     \endqml
 
-    \note QmlScript executes JavaScript as soon as it is specified.
-    When defining a component, this may be before the execution context is
-    fully specified.  As a result some properties or items may not be
-    accessible. By limiting your JavaScript to defining functions that are
-    only executed later once the context is fully defined, this problem is
-    avoided.
+    \note While it is possible to use any JavaScript code within a Script element,
+    it is recommended that the code be limited to defining functions. The Script
+    element executes JavaScript as soon as it is specified, so
+    when defining a component, this may be done before the execution context is
+    fully specified.  As a result, some properties or items may not be
+    accessible. You can avoid this problem by limiting your JavaScript to
+    defining functions that are only executed later once the context is fully
+    defined.
+
+    \sa {ECMAScript Blocks}
 */
 
 /*!
     \qmlproperty string Script::script
     \default
-    JavaScript code to execute.
+    The JavaScript code to be executed.
 */
 
 /*!
     \qmlproperty url Script::source
 
-    Setting this property causes the Script element to read JavaScript code from
-    the file specified.
+    Specifies a source file containing JavaScript code. This can be used instead
+    of providing inline JavaScript code in the Script element.
 */
diff --git a/src/declarative/util/qmlconnection.cpp b/src/declarative/util/qmlconnection.cpp
index b1771d4..3e72ab8 100644
--- a/src/declarative/util/qmlconnection.cpp
+++ b/src/declarative/util/qmlconnection.cpp
@@ -65,7 +65,18 @@ public:
     \qmlclass Connection QmlConnection
     \brief A Connection object describes generalized connections to signals.
 
-    JavaScript-in-HTML style signal properties do not allow:
+    When connecting to signals in QML, the usual way is to create an
+    "on<Signal>" handler that reacts when a signal is received, like this:
+
+    \qml
+    MouseRegion {
+        onClicked: { foo(x+123,y+456) }
+    }
+    \endqml
+
+    However, in some cases, it is not possible to connect to a signal in this
+    way. For example, JavaScript-in-HTML style signal properties do not allow:
+
     \list
         \i connecting to signals with the same name but different parameters
         \i conformance checking that parameters are correctly named
@@ -74,39 +85,33 @@ public:
         \i signals in classes with coincidentally-named on<Signal> properties
     \endlist
 
-    When any of these is needed, the Connection object can be used instead.
-    Where a signal could be connected like this:
+    When any of these are needed, the Connection object can be used instead.
 
-    \qml
-MouseRegion {
-    onClicked: { foo(x+123,y+456) }
-}
-    \endqml
-
-    An equivalent binding can be made with a Connection object:
+    For example, the above code can be changed to use a Connection object,
+    like this:
 
     \qml
-MouseRegion {
-    Connection {
-        signal: "clicked(x,y)"
-        script: { foo(x+123,y+456) }
+    MouseRegion {
+        Connection {
+            signal: "clicked(x,y)"
+            script: { foo(x+123,y+456) }
+        }
     }
-}
     \endqml
 
     More generally, the Connection object can be a child of some other object than
     the sender of the signal, and the script is the default attribute:
 
     \qml
-MouseRegion {
-    id: mr
-}
-...
-Connection {
-    sender: mr
-    signal: "clicked(x,y)"
-    script: { foo(x+123,y+456) }
-}
+    MouseRegion {
+        id: mr
+    }
+    ...
+    Connection {
+        sender: mr
+        signal: "clicked(x,y)"
+        script: { foo(x+123,y+456) }
+    }
     \endqml
 */
 
@@ -249,7 +254,7 @@ void QmlConnection::setScript(const QmlScriptString& script)
     \qmlproperty string Connection::signal
     This property holds the signal from the sender to which the script is attached.
 
-    The signal must have its formal parameter names given in parentheses:
+    The signal's formal parameter names must be given in parentheses:
 
     \qml
 Connection {