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

16 files changed, 121 insertions, 68 deletions

diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc
index 60dc0e6..1456eae9 100644
--- a/doc/src/declarative/advtutorial.qdoc
+++ b/doc/src/declarative/advtutorial.qdoc
@@ -47,7 +47,7 @@ This tutorial goes step-by-step through creating a full application using just Q
 It is assumed that you already know basic QML (such as from doing the simple tutorial) and the focus is on showing
 how to turn that knowledge into a complete and functioning application.
 
-This tutorial involves a significant amount of javascript to implement the game logic. An understanding of javascript is helpful to understand the javascript parts of this tutorial, but if you don't understand javascript you can still get a feel for how to integrate QML elements with backend logic which creates and controls them. From the QML perspective, there is little difference between integrating with backend logic written in C++ and backend logic written in javascript.
+This tutorial involves a significant amount of JavaScript to implement the game logic. An understanding of JavaScript is helpful to understand the JavaScript parts of this tutorial, but if you don't understand JavaScript you can still get a feel for how to integrate QML elements with backend logic which creates and controls them. From the QML perspective, there is little difference between integrating with backend logic written in C++ and backend logic written in JavaScript.
 
 In this tutorial we recreate, step by step, the Same Game demo in $QTDIR/demos/declarative/samegame.qml.
 The results of the individual steps are in the $QTDIR/examples/declarative/tutorials/samegame directory.
diff --git a/doc/src/declarative/advtutorial2.qdoc b/doc/src/declarative/advtutorial2.qdoc
index 40a760d..dcc7c70 100644
--- a/doc/src/declarative/advtutorial2.qdoc
+++ b/doc/src/declarative/advtutorial2.qdoc
@@ -93,7 +93,7 @@ To hook this code up to the \e{New Game} button, you alter it as below:
 
 \snippet declarative/tutorials/samegame/samegame2/samegame.qml 1
 
-We have just replaced the \c{onClicked: print("Implement me!")} with \c{onClicked: initBoard()}.
+We have just replaced the \c{onClicked: console.log("Implement me!")} with \c{onClicked: initBoard()}.
 Note that in order to have the function available, you'll need to include the script in the main file,
 by adding a script element to it.
 
diff --git a/doc/src/declarative/advtutorial4.qdoc b/doc/src/declarative/advtutorial4.qdoc
index aaa7293..96e72fc 100644
--- a/doc/src/declarative/advtutorial4.qdoc
+++ b/doc/src/declarative/advtutorial4.qdoc
@@ -126,7 +126,7 @@ if they exit this dialog without entering it they have a way to opt out of posti
 
 \snippet declarative/tutorials/samegame/samegame4/content/samegame.js 2
 
-For offline storage, we use the HTML 5 offline storage javascript API to maintain a persistant SQL database unique to this application. This first line in this function calls the function for the web-based high scores, described later, if it has been setup. Next we create an offline storage database for the high scores using openDatabase and prepare the data and SQL query that we want to use to save it. The offline storage API uses SQL queries for data manipulation and retrival, and in the db.transaction call we use three SQL queries to initialize the database (if necessary), and then add to and retrieve high scores. To use the returned data, we turn it into a string with one line per row returned, and show a dialog containing that string. For a more detailed explanation of the offline storage API in QML, consult the global object documentation.
+For offline storage, we use the HTML 5 offline storage JavaScript API to maintain a persistant SQL database unique to this application. This first line in this function calls the function for the web-based high scores, described later, if it has been setup. Next we create an offline storage database for the high scores using openDatabase and prepare the data and SQL query that we want to use to save it. The offline storage API uses SQL queries for data manipulation and retrival, and in the db.transaction call we use three SQL queries to initialize the database (if necessary), and then add to and retrieve high scores. To use the returned data, we turn it into a string with one line per row returned, and show a dialog containing that string. For a more detailed explanation of the offline storage API in QML, consult the global object documentation.
 
 This is one way of storing and displaying high scores locally, but not the only way. A more complex alternative would have been to create a high score dialog component, and pass the results to it for processing and display (instead of resusing the Dialog). This would allow a more themable dialog that could present the high scores better. If your QML is the UI for a C++ application, you could also have passed the score to a C++ function to store it locally in a variety of ways, including a simple format without SQL or in another SQL database.
 
@@ -141,7 +141,7 @@ if the player entered their name we can send the data to the web service in the
 
 \snippet declarative/tutorials/samegame/samegame4/content/samegame.js 1
 
-This is the same \c XMLHttpRequest() as you'll find in browser javascript, and can be used in the same way to dynamically get XML
+This is the same \c XMLHttpRequest() as you'll find in browser JavaScript, and can be used in the same way to dynamically get XML
 or QML from the web service to display the high scores. We don't worry about the response in this case, we just post the high
 score data to the web server. If it had returned a QML file (or a URL to a QML file) you could instantiate it in much the same
 way as you did the blocks.
diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc
index 503b881..4766236 100644
--- a/doc/src/declarative/anchor-layout.qdoc
+++ b/doc/src/declarative/anchor-layout.qdoc
@@ -44,7 +44,7 @@
 \target anchor-layout
 \title Anchor-based Layout in QML
 
-In addition to the more traditional \l Grid, \l Row, and \l Column, QML also provides a way to layout items using the concept of anchors. Each item can be thought of as having a set of 6 invisible "anchor lines": \e left, \e horizontalCenter, \e right, \e top, \e verticalCenter, and \e bottom.
+In addition to the more traditional \l Grid, \l Row, and \l Column, QML also provides a way to layout items using the concept of \e anchors. Each item can be thought of as having a set of 6 invisible "anchor lines": \e left, \e horizontalCenter, \e right, \e top, \e verticalCenter, and \e bottom.
 
 \image edges_qml.png
 
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/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc
index 7df87c5..b383836 100644
--- a/doc/src/declarative/declarativeui.qdoc
+++ b/doc/src/declarative/declarativeui.qdoc
@@ -46,11 +46,12 @@
 \brief The Qt Declarative module provides a declarative framework for building
 highly dynamic, custom user interfaces.
 
-Qt Declarative aids programmers and designers in building the animation rich,
-highly fluid user interfaces that are becoming common in portable consumer
-electronics devices, such as mobile phones, media players, set-top boxes and
-netbooks.  The Qt Declarative module provides an engine for interpreting the
-declarative QML language, and a rich set of \l {QML Elements}{QML elements} that can be used
+Qt Declarative UI provides a declarative framework for building highly dynamic, custom
+user interfaces.  Declarative UI helps programmers and designers collaborate to build 
+the animation rich, fluid user interfaces that are becoming common in portable 
+consumer devices, such as mobile phones, media players, set-top boxes and netbooks.  
+The Qt Declarative module provides an engine for interpreting the declarative QML 
+language, and a rich set of \l {QML Elements}{QML elements} that can be used
 from QML.
 
 QML is an extension to \l {http://www.ecma-international.org/publications/standards/Ecma-262.htm}
@@ -85,12 +86,12 @@ completely new applications.  QML is fully \l {Extending QML}{extensible from C+
 \o \l {ECMAScript Blocks}
 \o \l {QML Scope}
 \o \l {Network Transparency}
-\o \l {qmlmodels}{Data Models}
-\o \l {anchor-layout}{Anchor-based Layout}
-\o \l {qmlstates}{States}
+\o \l {Data Models}
+\o \l {anchor-layout.html}{Anchor-based Layout}
+\o \l {qmlstates.html}{States}
 \o \l {qmlanimation.html}{Animation}
 \o \l {qmlmodules.html}{Modules}
-\o \l {qmlfocus}{Keyboard Focus}
+\o \l {qmlfocus.html}{Keyboard Focus}
 \o \l {Extending types from QML}
 \endlist
 
diff --git a/doc/src/declarative/ecmascriptblocks.qdoc b/doc/src/declarative/ecmascriptblocks.qdoc
index 815c68c..6ee5a8e 100644
--- a/doc/src/declarative/ecmascriptblocks.qdoc
+++ b/doc/src/declarative/ecmascriptblocks.qdoc
@@ -168,7 +168,7 @@ is illegal in QML.
 // Illegal modification of undeclared variable
 a = 1;
 for (var ii = 1; ii < 10; ++ii) a = a * ii;
-print("Result: " + a);
+    console.log("Result: " + a);
 \endcode
 
 It can be trivially modified to this legal code.
@@ -176,7 +176,7 @@ It can be trivially modified to this legal code.
 \code
 var a = 1;
 for (var ii = 1; ii < 10; ++ii) a = a * ii;
-print("Result: " + a);
+    console.log("Result: " + a);
 \endcode
 
 Any attempt to modify the global object - either implicitly or explicitly - will 
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/examples.qdoc b/doc/src/declarative/examples.qdoc
index 7950f66..3288e17 100644
--- a/doc/src/declarative/examples.qdoc
+++ b/doc/src/declarative/examples.qdoc
@@ -43,33 +43,31 @@
 \page qmlexamples.html
 \title QML Examples and Walkthroughs
 
-\section1 Running Examples
+\section1 Running Examples and Demos
 
-A \l {qmlviewer}{viewer} application is included that allows you to quickly explore many of the
-examples. It has some useful options, revealed by:
+You can find many simple examples in the \c examples/declarative
+sub-directory that show how to use various aspects of QML. In addition, the
+\c demos/declarative sub-directory contains more sophisticated demos of large
+applications. These demos are intended to show integrated functionality
+rather than being instructive on specifice elements.
+
+To run the examples and demos, use the included \l {qmlviewer}{qmlviewer}
+application. It has some useful options, revealed by:
 
 \code
     bin/qmlviewer -help
 \endcode
 
-There are several illustrative QML examples available.  From your build
-directory,
+For example, from your build directory, run:
 
 \code
-    bin/qmlviewer $QT_SOURCE_DIR/demos/declarative/flickr/flickr-desktop.qml
+    bin/qmlviewer $QTDIR/demos/declarative/flickr/flickr-desktop.qml
 \endcode
 or
 \code
-    bin/qmlviewer $QT_SOURCE_DIR/demos/declarative/samegame/samegame.qml
+    bin/qmlviewer $QTDIR/demos/declarative/samegame/samegame.qml
 \endcode
 
-Many other simple examples can be found under the \c examples/declarative sub
-directory.  Some can be run directly using the viewer like those above, and
-others require you to build and run an executable.  More sophisticated demos of
-large applications can be found under the \c demos/declarative sub directory.
-These are intended to show more integrated functionality rather than to be
-instructive on specific elements.
-
 \section1 Examples
 
 These will be documented, and demonstrate how to achieve various things in QML.
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 7a9de60..056b8ab 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
@@ -843,7 +845,7 @@ This example adds a new method that behaves like a child:
 \code
 Item {
     function say(text) {
-        print("You said " + text);
+        console.log("You said " + text);
     }
 }
 \endcode
diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc
index 8061a7c..46bfc38 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:
@@ -65,7 +67,7 @@ item and thus subsequently be \l {QEvent::ignore()}{ignored}.
 \code
 Item {
     Item {
-        Keys.onPressed: if (event.key == Qt.Key_A) { print('Key A was pressed'); event.accepted = true }
+        Keys.onPressed: if (event.key == Qt.Key_A) { console.log('Key A was pressed'); event.accepted = true }
         Rectangle {}
     }
 }
@@ -305,7 +307,7 @@ Rectangle {
             Text {
                 focus: true
                 text: name
-                Keys.onReturnPressed: print(name)
+                Keys.onReturnPressed: console.log(name)
             }
         }
     }
diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc
index e3c8b9a..3eadec2 100644
--- a/doc/src/declarative/globalobject.qdoc
+++ b/doc/src/declarative/globalobject.qdoc
@@ -182,7 +182,7 @@ such as ListView, \l Repeater and \l Loader.
         sprite = component.createObject();
         if(sprite == 0){
             // Error Handling
-            print(component.errorsString());
+            console.log(component.errorsString());
         }else{
             sprite.parent = page;
             sprite.x = 200;
diff --git a/doc/src/declarative/qmlintro.qdoc b/doc/src/declarative/qmlintro.qdoc
index 78462db..76d915f 100644
--- a/doc/src/declarative/qmlintro.qdoc
+++ b/doc/src/declarative/qmlintro.qdoc
@@ -311,7 +311,7 @@ any visual Item, for example:
 \code
 Item {
     focus: true
-    Keys.onSelectPressed: print("Selected")
+    Keys.onSelectPressed: console.log("Selected")
 }
 \endcode
 
@@ -323,7 +323,7 @@ and click:
 
 \code
 MouseRegion {
-    onPressed: print("mouse button pressed")
+    onPressed: console.log("mouse button pressed")
 }
 \endcode
 
@@ -335,7 +335,7 @@ the MouseRegion onPressed signal handler has a \e mouse parameter:
 \code
 MouseRegion {
     acceptedButtons: Qt.LeftButton | Qt.RightButton
-    onPressed: if (mouse.button == Qt.RightButton) print("Right mouse button pressed")
+    onPressed: if (mouse.button == Qt.RightButton) console.log("Right mouse button pressed")
 }
 \endcode
 
diff --git a/doc/src/declarative/qmlstates.qdoc b/doc/src/declarative/qmlstates.qdoc
index ddb0fc8..abf3c93 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,51 @@ 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, thus moving the rectangle.
 
-\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
+
+State changes can be animated using \l{state-transitions}{Transitions}.
+
+For example, adding this code to the above \c {Item {}} element animates the transition to the "moved" state:
+
+\qml
+    transitions: [
+        Transition {
+            NumberAnimation { matchProperties: "x,y"; duration: 500 }
+        }
+    ]
+\endqml
+
+See \l{state-transitions}{Transitions} for more information.
 
-To animate state changes, you can use \l{state-transitions}{transitions}.
 
 Other things you can do in a state change:
 \list
diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index 5947429..6a94b6e 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -47,4 +47,21 @@
 \brief The Qt Declarative module provides a declarative framework for building
 highly dynamic, custom user interfaces.
 
+To include the definitions of the module's classes, use the
+following directive:
+
+\code
+#include <QtDeclarative>
+\endcode
+
+To link against the module, add this line to your \l qmake \c
+.pro file:
+
+\code
+QT += declarative
+\endcode
+
+For more information on the Qt Declarative module, see the
+\l{declarativeui.html}{Declarative UI} documentation.
+
 */
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