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

14 files changed, 214 insertions, 48 deletions

diff --git a/doc/src/declarative/cppitem.qdoc b/doc/src/declarative/cppitem.qdoc
index 4543156..38da0fb 100644
--- a/doc/src/declarative/cppitem.qdoc
+++ b/doc/src/declarative/cppitem.qdoc
@@ -94,7 +94,7 @@ You can create a new type of QML item by:
 To add a new type, you first must add a new C++ class derived from QFxItem.
 You may of course extend existing QFxItem subclasses.
 
-One existing subclass is QFxPainted, which provides
+One existing subclass is QFxPaintedItem, which provides
 a simple cached-image painting model.
 
 \section2 Reimplementing paint functions
@@ -105,11 +105,11 @@ Two alternative painters are available, offering
 different levels of performance and functionality:
 QPainter, GLPainter.
 
-You can choose to subclass QFxPainted rather than QFxItem,
+You can choose to subclass QFxPaintedItem rather than QFxItem,
 and then implement the virtual method:
 
 \code
-    void paint(QPainter *painter);
+    void drawContents(QPainter *painter, const QRect &rect);
 \endcode
 
 This paints into an offscreen pixmap which is then painted to the display (transformed,
diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc
index bfaf4ab..ca17fda 100644
--- a/doc/src/declarative/elements.qdoc
+++ b/doc/src/declarative/elements.qdoc
@@ -37,6 +37,7 @@ The following table lists the QML elements provided by the Qt Declarative module
 \o \l ScriptAction
 \o \l Transition
 \o \l Follow
+\o \l EaseFollow
 \o \l Behavior
 \endlist
 
@@ -100,7 +101,6 @@ The following table lists the QML elements provided by the Qt Declarative module
 \o \l Loader
 \o \l Repeater
 \o \l SystemPalette
-\o \l ComponentInstance
 \o \l GraphicsObjectContainer
 \endlist
 
diff --git a/doc/src/declarative/pics/qml-context-object.png b/doc/src/declarative/pics/qml-context-object.png
new file mode 100644
index 0000000..1b91aff
--- /dev/null
+++ b/doc/src/declarative/pics/qml-context-object.png
diff --git a/doc/src/declarative/pics/qml-context-tree.png b/doc/src/declarative/pics/qml-context-tree.png
new file mode 100644
index 0000000..6bba5f4
--- /dev/null
+++ b/doc/src/declarative/pics/qml-context-tree.png
diff --git a/doc/src/declarative/pics/qml-context.png b/doc/src/declarative/pics/qml-context.png
new file mode 100644
index 0000000..bdf2ecd
--- /dev/null
+++ b/doc/src/declarative/pics/qml-context.png
diff --git a/doc/src/declarative/qmlforcpp.qdoc b/doc/src/declarative/qmlforcpp.qdoc
index 5838df7..ab456e5 100644
--- a/doc/src/declarative/qmlforcpp.qdoc
+++ b/doc/src/declarative/qmlforcpp.qdoc
@@ -15,6 +15,8 @@
     either for the first time at startup or subsequently thereafter - the 
     property is automatically updated with the new value.
 
+    \tableofcontents
+
     \section1 Loading and using QML Files
 
     QmlComponent is used to load a QML file and to create object instances.
diff --git a/doc/src/declarative/qmlformat.qdoc b/doc/src/declarative/qmlformat.qdoc
index 9cfebf0..f16adca 100644
--- a/doc/src/declarative/qmlformat.qdoc
+++ b/doc/src/declarative/qmlformat.qdoc
@@ -16,21 +16,148 @@ Much of a QML file consists of valid ECMAScript \e {Statement}s.  Except where c
 by ECMAScript, C++ or QObject prevented it, the syntactic extensions introduced by QML are designed
 to look similar and fit well with existing ECMAScript syntax and concepts.  
 
+\section1 QML engine
+
+The \l {QmlEngine}{QML engine} executes a \l {QmlComponent}{QML document} in a 
+\l {QmlContext}{QML context} to produce a \l {QObject}{QML object}.  A single QML 
+document may be executed in one or many contexts to produce many QML objects.  A single 
+QML document may be executed many times in the same context to produce many QML objects.
+
+The QML engine provides the environment in which QML documents, contexts and objects
+exist.  It must exist before any of these structures can be created.  If the engine is removed,
+existing documents, contexts and objects are invalidated, but not destroyed.  An invalid
+
+\list
+\i \e {QML document} can no longer be used to create QML objects.
+\i \e {QML context} can no longer host QML objects, new context properties cannot be added
+and existing context properties cannot be modified.
+\i \e {QML object} will no longer evaluate bindings or scripts.
+\endlist
+
+A QML document is a block of QML source code.  QML documents generally correspond to files stored 
+on a disk or network resource, but can be constructed directly from text data.  Syntactically a QML
+document is self contained; QML does \bold {not} have a preprocessor that modifies the document 
+before presentation to the compiler.  Type references within a QML document are resolved based 
+exclusively on the import statements present in the document.
+
+A simple QML document looks like this:
+
+\table
+\row
+\o
+\code
+import Qt 4.6
+
+Rectangle {
+    id: MyRect
+    width: 100; height: 100
+    color: background
+}
+\endcode
+\endtable
+
+To instantiate a QML object, a QML document is executed in a QML context.  QML contexts are used by
+programmers to pass data to a QML document.  QML documents may include property bindings or 
+ECMAScript blocks that can contain variable references that need to be resolved.  Each property 
+binding and ECMAScript block has an associated QML context that is used to resolve these references
+that is determined by the QML context in which the document is executed.  The example document above
+contains one variable reference, \c background.  
+
+Each QML context defines a scope for variable resolution and each may define local, named context
+properties.  A QML context may also have a \l {QmlContext::addDefaultObject()}{default object}, 
+which is an object whose properties are searched \e after the context properties when resolving a 
+variable name.  QML contexts form a tree, starting from a root context that is provided by the QML 
+engine.  When resolving variable references, the QML contexts are searched starting from the
+QML objects containing context upwards towards the root context.
+
+Consider the following QML context tree.  If the example QML document is executed in \c Context1, 
+the \c background variable will resolve to \c Context1's context property.  If the document is 
+executed in \c Context2, the \c background variable will resolve to the root context's context 
+property.
+
+\image qml-context-tree.png
+
+While QML contexts can be created explicitly by the programmer to pass data into QML objects,
+the QML engine also creates a new implicit QML context for every object it instantiates.
+Property bindings and ECMAScript blocks in the document are associated with this QML engine 
+created context.  Object ids that are defined in the document are added as context properties, and 
+their value is set to reference the appropriate object, and the instantiated QML object is set as
+the context's default object.  The following diagram shows the result of executing a simple QML 
+document.
+
+\image qml-context-object.png
+
+The blue rectangle in the diagram represents a property binding.  Associated with each property 
+binding is the QML context to which it belongs, the object property to which it is bound and a
+\e {scope object}.  The scope object is usually, but not always, the object to which the bound 
+property belongs.  The context properties, context default objects and the scope object are all 
+involved when resolving a variable name in a binding.  The following pseudo code describes the
+algorithm used:
+
+\table
+\row
+\o
+\code
+if (scopeObject.hasProperty(name))
+    return scopeObject.property(name)
+
+foreach (context in contextChain) {
+    if (context.hasContextProperty(name)
+        return context.contextProperty(name)
+
+    if (context.defaultObject.hasProperty(name))
+        return context.defaultObject.property(name)
+}
+\endcode
+\endtable
+
+QML supports two categories of types: \e builtin types and \e composite types.  Builtin types are
+those written in C++ and registered with the QML engine.  Builtin types form the most basic 
+building blocks of QML.  Composite types are constructed by composing other builtin or composite 
+types, property bindings and ECMAScript blocks together into a brand new type using the QML 
+language.  Using a composite type is identical to using a builtin type.
+
+For example, Qt 4.6 includes a builtin type called \c Image that shows a bitmap image.  The 
+\c Image type has \c width and \c height properties that control the size of the displayed image.
+A simple composite type, that will be called \c SquareImage can be built that adds a \c size 
+property that sets both the width and the height.
+
+\table
+\row
+\o
+\code
+import Qt 4.6
+Image {
+    property int size
+    width: size 
+    height: size 
+}
+\endcode
+\endtable
+
+To the QML engine, a composite type is just another QML document.  When a composite type is
+used the engine instantiates it just as it would any other document - by creating a new implicit
+QML context and the object tree described by the document.  The diagram below shows the 
+\c SquareImage composite type used from within another QML document.  When instantiated, the
+\c SquareImage object is created in its own QML context.  Any property bindings specified in the
+\c SquareImage composite type document are associated with this context.  Property bindings created
+in the outer document, however, are associated with its context, even those that are applied to the
+created \c SquareImage object.  That is, the \c size, \c source, \c width and \c height property
+bindings all share a common \e {scope object}, but are owned by two different QML contexts.  The
+difference in containing context results in the \c Root variable resolving differently in the 
+different property bindings.
+
+\image qml-context.png
+
+\section1 Syntax
+
 \section2 Commenting
 
 The commenting rules in QML are the same as for ECMAScript.  Both \e {MultiLineComment} blocks and \e {SingleLineComment}'s are supported.
 
-\section1 Definitions
-
-\e {QML interpreter}: QmlEngine
-
-\e {QML execution context}: QmlContext
+\section2 QML Document
 
-\e {inherited characteristic}
-
-\section1 QML Document
-
-\section2 Syntax
+\section3 Syntax
 
 \e {QMLDocument} \bold {:}
 
@@ -69,22 +196,16 @@ The commenting rules in QML are the same as for ECMAScript.  Both \e {MultiLineC
 \e {DecimalLiteral} \bold {but not} with \e {ExponentPart}
 \endquotation
 
-\section2 Semantics
-
-A QML document is the unit in which QML code may be passed to the QML interpreter.  A QML document
-is syntactically self contained.  QML documents are evaluated by the QML interpreter in a QML 
-execution context to produce a single instantiated object of the type specified by 
-\e {QMLObjectDefinition}.
+\section3 Semantics
 
 The \e {QMLImportList} is used to statically resolve type references used within the enclosing 
-QML document.  The import list is \bold {not} an \e {inherited characteristic}; its scope of 
-influence is limited to structures logically contained by the document.
+QML document.  
 
 An import statement is used to bring a set of types into scope for a QML document.
 
-\section1 Object Definition
+\section2 Object Definition
 
-\section2 Syntax
+\section3 Syntax
 
 \e {QMLObjectDefinition} \bold {:}
 \quotation
@@ -125,11 +246,11 @@ An import statement is used to bring a set of types into scope for a QML documen
 
 \endquotation
 
-\section2 Semantics
+\section3 Semantics
 
-\section1 Object Extension
+\section2 Object Extension
 
-\section2 Syntax
+\section3 Syntax
 
 \e {QMLObjectExtensionDefinition} \bold {:}
 \quotation
@@ -171,14 +292,14 @@ An import statement is used to bring a set of types into scope for a QML documen
 \quotation
 \e {FunctionDeclaration} \bold {but not} \e {Identifier} \sub {opt}
 \endquotation
-\section2 Semantics
+\section3 Semantics
 
-\section1 Binding Expression
+\section2 Binding Expression
 
-\section2 Syntax
+\section3 Syntax
 
 \e {QMLBindingExpression} \bold {:}
 
-\section2 Semantics
+\section3 Semantics
 
 */
diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index 1b7644c..460819a 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -80,7 +80,7 @@
 
     QML Reference:
     \list
-    \o \l {QML Format}
+    \o \l {QML Format Reference}
     \o \l {elements}{QML Elements}
     \endlist
 
diff --git a/doc/src/frameworks-technologies/gestures.qdoc b/doc/src/frameworks-technologies/gestures.qdoc
index 317bb31..7929331 100644
--- a/doc/src/frameworks-technologies/gestures.qdoc
+++ b/doc/src/frameworks-technologies/gestures.qdoc
@@ -81,7 +81,7 @@
 
     \table
     \header \o New State                \o Description              \o QGesture Actions on Entering this State
-    \row    \o Qt::NoGesture        \o Initial value            \o emit \l {QGesture::cancelled()}{cancelled()}
+    \row    \o Qt::NoGesture        \o Initial value            \o emit \l {QGesture::canceled()}{canceled()}
     \row    \o Qt::GestureStarted   \o A continuous gesture has started \o emit \l{QGesture::started()}{started()} and emit \l{QGesture::triggered()}{triggered()}
     \row    \o Qt::GestureUpdated   \o A gesture continues      \o emit \l{QGesture::triggered()}{triggered()}
     \row    \o Qt::GestureFinished  \o A gesture has finished.  \o emit \l{QGesture::finished()}{finished()}
@@ -130,13 +130,13 @@
     then the gesture is considered to have finished whether or not the
     appropriate touch or mouse event has occurred. Also if a large jump in
     the position of the event occurs, as calculated by the \l {QPoint::manhattanLength()}{manhattanLength()}
-    call, then the gesture is cancelled by calling \l{QGesture::reset()}{reset()}
+    call, then the gesture is canceled by calling \l{QGesture::reset()}{reset()}
     which tidies up  and uses \l{QGesture::updateState()}{updateState()} to
-    change state to NoGesture which will result in the \l{QGesture::cancelled()}{cancelled()}
+    change state to NoGesture which will result in the \l{QGesture::canceled()}{canceled()}
     signal being emitted by the recognizer.
 
     ImageWidget handles the signals by connecting the slots to the signals,
-    although \c cancelled() is not connected here.
+    although \c canceled() is not connected here.
 
     \snippet doc/src/snippets/gestures/imageviewer/imagewidget.cpp  imagewidget-connect
 
diff --git a/doc/src/snippets/code/src_corelib_io_qfileinfo.cpp b/doc/src/snippets/code/src_corelib_io_qfileinfo.cpp
index f01757a..d2096cf 100644
--- a/doc/src/snippets/code/src_corelib_io_qfileinfo.cpp
+++ b/doc/src/snippets/code/src_corelib_io_qfileinfo.cpp
@@ -72,9 +72,9 @@ info1.size();               // returns 743
 info1.symLinkTarget();      // returns "C:/Pretty++/untabify"
 
 QFileInfo info2(info1.symLinkTarget());
-info1.isSymLink();          // returns false
-info1.absoluteFilePath();   // returns "C:/Pretty++/untabify"
-info1.size();               // returns 63942
+info2.isSymLink();          // returns false
+info2.absoluteFilePath();   // returns "C:/Pretty++/untabify"
+info2.size();               // returns 63942
 
 #endif
 //! [1]
diff --git a/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp b/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp
index 128799f..8933ef3 100644
--- a/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp
+++ b/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp
@@ -1,3 +1,44 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the test suite of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
 //! [simple state machine]
 QPushButton button;
 
diff --git a/doc/src/snippets/declarative/listview/highlight.qml b/doc/src/snippets/declarative/listview/highlight.qml
index 29f41bf..97eac45 100644
--- a/doc/src/snippets/declarative/listview/highlight.qml
+++ b/doc/src/snippets/declarative/listview/highlight.qml
@@ -15,7 +15,7 @@ Rectangle {
         Item {
             id: Wrapper
             width: 180; height: 40
-            VerticalLayout {
+            Column {
                 x: 5; y: 5
                 Text { text: '<b>Name:</b> ' + name }
                 Text { text: '<b>Number:</b> ' + number }
@@ -32,10 +32,10 @@ Rectangle {
         Rectangle {
             width: 180; height: 40
             color: "lightsteelblue"; radius: 5
-            y: Follow {
-                source: List.current.y
+            y: SpringFollow {
+                source: List.currentItem.y
                 spring: 3
-                damping: 0.1
+                damping: 0.2
             }
         }
     }
@@ -44,7 +44,7 @@ Rectangle {
         width: parent.height; height: parent.height
         model: ContactModel; delegate: Delegate
         highlight: Highlight
-        autoHighlight: false
+        highlightFollowsCurrentItem: false
         focus: true
     }
 //! [1]
diff --git a/doc/src/tutorials/declarative.qdoc b/doc/src/tutorials/declarative.qdoc
index 7780988..48beabd 100644
--- a/doc/src/tutorials/declarative.qdoc
+++ b/doc/src/tutorials/declarative.qdoc
@@ -392,7 +392,7 @@
     the contact field.
 
     There are also two other ways to reuse components in QML.  A component
-    can be reused from within the same QML file using Component and ComponentInstance
+    can be reused from within the same QML file using Component and Loader
     elements.  The next code snippet produces three red rounded rectangles
     within a large blue rectangle.
 
diff --git a/doc/src/widgets-and-layouts/stylesheet.qdoc b/doc/src/widgets-and-layouts/stylesheet.qdoc
index 354050d..c137d6a 100644
--- a/doc/src/widgets-and-layouts/stylesheet.qdoc
+++ b/doc/src/widgets-and-layouts/stylesheet.qdoc
@@ -230,9 +230,11 @@
         \o \c{QPushButton[flat="false"]}
         \o Matches instances of QPushButton that are not
            \l{QPushButton::}{flat}. You may use this selector to test
-           for any Qt property specified using Q_PROPERTY(). In
-           addition, the special \c class property is supported, for
-           the name of the class.
+           for any Qt \l{Qt's Property System}{property} that supports
+           QVariant::toString() (see the \l{QVariant::}{toString()}
+           function documentation for details). In addition, the
+           special \c class property is supported, for the name of the
+           class.
 
            This selector may also be used to test dynamic properties.
            For more information on customization using dynamic properties,