Merge branch '4.7' of git@scm.dev.nokia.troll.no:qt/oslo-staging-1 into 4.7

21 files changed, 437 insertions, 253 deletions

diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp
index 0eae136..25cf133 100644
--- a/src/declarative/util/qdeclarativeanimation.cpp
+++ b/src/declarative/util/qdeclarativeanimation.cpp
@@ -1774,7 +1774,7 @@ void QDeclarativePropertyAnimation::setTo(const QVariant &t)
 
     To specify an easing curve you need to specify at least the type. For some curves you can also specify
     amplitude, period and/or overshoot (more details provided after the table). The default easing curve is
-    Linear.
+    \c Easing.Linear.
 
     \qml
     PropertyAnimation { properties: "y"; easing.type: Easing.InOutElastic; easing.amplitude: 2.0; easing.period: 1.5 }
@@ -1951,15 +1951,15 @@ void QDeclarativePropertyAnimation::setTo(const QVariant &t)
         \o \inlineimage qeasingcurve-outinbounce.png
     \endtable
 
-    easing.amplitude is only applicable for bounce and elastic curves (curves of type
-    Easing.InBounce, Easing.OutBounce, Easing.InOutBounce, Easing.OutInBounce, Easing.InElastic,
-    Easing.OutElastic, Easing.InOutElastic or Easing.OutInElastic).
+    \c easing.amplitude is only applicable for bounce and elastic curves (curves of type
+    \c Easing.InBounce, \c Easing.OutBounce, \c Easing.InOutBounce, \c Easing.OutInBounce, \c Easing.InElastic,
+    \c Easing.OutElastic, \c Easing.InOutElastic or \c Easing.OutInElastic).
 
-    easing.overshoot is only applicable if type is: Easing.InBack, Easing.OutBack,
-    Easing.InOutBack or Easing.OutInBack.
+    \c easing.overshoot is only applicable if \c easing.type is: \c Easing.InBack, \c Easing.OutBack,
+    \c Easing.InOutBack or \c Easing.OutInBack.
 
-    easing.period is only applicable if type is: Easing.InElastic, Easing.OutElastic,
-    Easing.InOutElastic or Easing.OutInElastic.
+    \c easing.period is only applicable if easing.type is: \c Easing.InElastic, \c Easing.OutElastic,
+    \c Easing.InOutElastic or \c Easing.OutInElastic.
 
     See the \l {declarative/animation/easing}{easing} example for a demonstration of
     the different easing settings.
@@ -2045,8 +2045,9 @@ void QDeclarativePropertyAnimation::setProperties(const QString &prop)
     The singular forms are slightly optimized, so if you do have only a single target/property
     to animate you should try to use them.
 
-    In many cases these properties do not need to be explicitly specified -- they can be
-    inferred from the animation framework.
+    In many cases these properties do not need to be explicitly specified, as they can be
+    inferred from the animation framework:
+
     \table 80%
     \row
     \o Value Source / Behavior
@@ -2132,52 +2133,39 @@ QAbstractAnimation *QDeclarativePropertyAnimation::qtAnimation()
     return d->va;
 }
 
-struct PropertyUpdater : public QDeclarativeBulkValueUpdater
+void QDeclarativeAnimationPropertyUpdater::setValue(qreal v)
 {
-    QDeclarativeStateActions actions;
-    int interpolatorType;       //for Number/ColorAnimation
-    int prevInterpolatorType;   //for generic
-    QVariantAnimation::Interpolator interpolator;
-    bool reverse;
-    bool fromSourced;
-    bool fromDefined;
-    bool *wasDeleted;
-    PropertyUpdater() : prevInterpolatorType(0), wasDeleted(0) {}
-    ~PropertyUpdater() { if (wasDeleted) *wasDeleted = true; }
-    void setValue(qreal v)
-    {
-        bool deleted = false;
-        wasDeleted = &deleted;
-        if (reverse)    //QVariantAnimation sends us 1->0 when reversed, but we are expecting 0->1
-            v = 1 - v;
-        for (int ii = 0; ii < actions.count(); ++ii) {
-            QDeclarativeAction &action = actions[ii];
-
-            if (v == 1.)
-                QDeclarativePropertyPrivate::write(action.property, action.toValue, QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding);
-            else {
-                if (!fromSourced && !fromDefined) {
-                    action.fromValue = action.property.read();
-                    if (interpolatorType)
-                        QDeclarativePropertyAnimationPrivate::convertVariant(action.fromValue, interpolatorType);
-                }
-                if (!interpolatorType) {
-                    int propType = action.property.propertyType();
-                    if (!prevInterpolatorType || prevInterpolatorType != propType) {
-                        prevInterpolatorType = propType;
-                        interpolator = QVariantAnimationPrivate::getInterpolator(prevInterpolatorType);
-                    }
+    bool deleted = false;
+    wasDeleted = &deleted;
+    if (reverse)    //QVariantAnimation sends us 1->0 when reversed, but we are expecting 0->1
+        v = 1 - v;
+    for (int ii = 0; ii < actions.count(); ++ii) {
+        QDeclarativeAction &action = actions[ii];
+
+        if (v == 1.)
+            QDeclarativePropertyPrivate::write(action.property, action.toValue, QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding);
+        else {
+            if (!fromSourced && !fromDefined) {
+                action.fromValue = action.property.read();
+                if (interpolatorType)
+                    QDeclarativePropertyAnimationPrivate::convertVariant(action.fromValue, interpolatorType);
+            }
+            if (!interpolatorType) {
+                int propType = action.property.propertyType();
+                if (!prevInterpolatorType || prevInterpolatorType != propType) {
+                    prevInterpolatorType = propType;
+                    interpolator = QVariantAnimationPrivate::getInterpolator(prevInterpolatorType);
                 }
-                if (interpolator)
-                    QDeclarativePropertyPrivate::write(action.property, interpolator(action.fromValue.constData(), action.toValue.constData(), v), QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding);
             }
-            if (deleted)
-                return;
+            if (interpolator)
+                QDeclarativePropertyPrivate::write(action.property, interpolator(action.fromValue.constData(), action.toValue.constData(), v), QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding);
         }
-        wasDeleted = 0;
-        fromSourced = true;
+        if (deleted)
+            return;
     }
-};
+    wasDeleted = 0;
+    fromSourced = true;
+}
 
 void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions,
                                      QDeclarativeProperties &modified,
@@ -2207,7 +2195,7 @@ void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions
         props << d->defaultProperties.split(QLatin1Char(','));
     }
 
-    PropertyUpdater *data = new PropertyUpdater;
+    QDeclarativeAnimationPropertyUpdater *data = new QDeclarativeAnimationPropertyUpdater;
     data->interpolatorType = d->interpolatorType;
     data->interpolator = d->interpolator;
     data->reverse = direction == Backward ? true : false;
@@ -2786,7 +2774,7 @@ void QDeclarativeAnchorAnimation::transition(QDeclarativeStateActions &actions,
 {
     Q_UNUSED(modified);
     Q_D(QDeclarativeAnchorAnimation);
-    PropertyUpdater *data = new PropertyUpdater;
+    QDeclarativeAnimationPropertyUpdater *data = new QDeclarativeAnimationPropertyUpdater;
     data->interpolatorType = QMetaType::QReal;
     data->interpolator = d->interpolator;
 
diff --git a/src/declarative/util/qdeclarativeanimation_p.h b/src/declarative/util/qdeclarativeanimation_p.h
index e7cd8a8..3f8fbdd 100644
--- a/src/declarative/util/qdeclarativeanimation_p.h
+++ b/src/declarative/util/qdeclarativeanimation_p.h
@@ -384,7 +384,7 @@ Q_SIGNALS:
 };
 
 class QDeclarativeAnimationGroupPrivate;
-class QDeclarativeAnimationGroup : public QDeclarativeAbstractAnimation
+class Q_AUTOTEST_EXPORT QDeclarativeAnimationGroup : public QDeclarativeAbstractAnimation
 {
     Q_OBJECT
     Q_DECLARE_PRIVATE(QDeclarativeAnimationGroup)
diff --git a/src/declarative/util/qdeclarativeanimation_p_p.h b/src/declarative/util/qdeclarativeanimation_p_p.h
index 3b0f52e..b6d6bbb 100644
--- a/src/declarative/util/qdeclarativeanimation_p_p.h
+++ b/src/declarative/util/qdeclarativeanimation_p_p.h
@@ -96,7 +96,7 @@ private:
 };
 
 //performs an action of type QAbstractAnimationAction
-class QActionAnimation : public QAbstractAnimation
+class Q_AUTOTEST_EXPORT QActionAnimation : public QAbstractAnimation
 {
     Q_OBJECT
 public:
@@ -143,7 +143,7 @@ public:
 };
 
 //animates QDeclarativeBulkValueUpdater (assumes start and end values will be reals or compatible)
-class QDeclarativeBulkValueAnimator : public QVariantAnimation
+class Q_AUTOTEST_EXPORT QDeclarativeBulkValueAnimator : public QVariantAnimation
 {
     Q_OBJECT
 public:
@@ -378,6 +378,22 @@ public:
     QList<QDeclarativeItem*> targets;
 };
 
+class Q_AUTOTEST_EXPORT QDeclarativeAnimationPropertyUpdater : public QDeclarativeBulkValueUpdater
+{
+public:
+    QDeclarativeStateActions actions;
+    int interpolatorType;       //for Number/ColorAnimation
+    int prevInterpolatorType;   //for generic
+    QVariantAnimation::Interpolator interpolator;
+    bool reverse;
+    bool fromSourced;
+    bool fromDefined;
+    bool *wasDeleted;
+    QDeclarativeAnimationPropertyUpdater() : prevInterpolatorType(0), wasDeleted(0) {}
+    ~QDeclarativeAnimationPropertyUpdater() { if (wasDeleted) *wasDeleted = true; }
+    void setValue(qreal v);
+};
+
 QT_END_NAMESPACE
 
 #endif // QDECLARATIVEANIMATION_P_H
diff --git a/src/declarative/util/qdeclarativeconnections.cpp b/src/declarative/util/qdeclarativeconnections.cpp
index 808d196..b364821 100644
--- a/src/declarative/util/qdeclarativeconnections.cpp
+++ b/src/declarative/util/qdeclarativeconnections.cpp
@@ -72,7 +72,9 @@ public:
 /*!
     \qmlclass Connections QDeclarativeConnections
   \since 4.7
-    \brief A Connections object describes generalized connections to signals.
+    \brief A Connections element describes generalized connections to signals.
+
+    A Connections object creates a connection to a QML signal.
 
     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:
@@ -83,16 +85,16 @@ public:
     }
     \endqml
 
-    However, in some cases, it is not possible to connect to a signal in this
-    way, such as:
+    However, it is not possible to connect to a signal in this way in some 
+    cases, such as when:
 
     \list
-        \i multiple connections to the same signal
-        \i connections outside the scope of the signal sender
-        \i connections to targets not defined in QML
+        \i Multiple connections to the same signal are required
+        \i Creating connections outside the scope of the signal sender
+        \i Connecting to targets not defined in QML
     \endlist
 
-    When any of these are needed, the Connections object can be used instead.
+    When any of these are needed, the Connections element can be used instead.
 
     For example, the above code can be changed to use a Connections object,
     like this:
@@ -105,7 +107,7 @@ public:
     }
     \endqml
 
-    More generally, the Connections object can be a child of some other object than
+    More generally, the Connections object can be a child of some object other than
     the sender of the signal:
 
     \qml
@@ -141,7 +143,7 @@ QDeclarativeConnections::~QDeclarativeConnections()
     \qmlproperty Object Connections::target
     This property holds the object that sends the signal.
 
-    If not set at all, the target defaults to be the parent of the Connections.
+    If this property is not set, the \c target defaults to the parent of the Connection.
 
     If set to null, no connection is made and any signal handlers are ignored
     until the target is not null.
@@ -175,12 +177,11 @@ void QDeclarativeConnections::setTarget(QObject *obj)
 /*!
     \qmlproperty bool Connections::ignoreUnknownSignals
 
-    Normally, you will get a runtime error if you try to connect
-    to signals on an object which the object does not have.
+    Normally, a connection to a non-existent signal produces runtime errors.
 
-    By setting this flag to true, such errors are ignored. This is
-    useful if you intend to connect to different types of object, handling
-    a different set of signals for each.
+    If this property is set to \c true, such errors are ignored.
+    This is useful if you intend to connect to different types of objects, handling
+    a different set of signals for each object.
 */
 bool QDeclarativeConnections::ignoreUnknownSignals() const
 {
diff --git a/src/declarative/util/qdeclarativefontloader.cpp b/src/declarative/util/qdeclarativefontloader.cpp
index 3c2e239..83bdb17 100644
--- a/src/declarative/util/qdeclarativefontloader.cpp
+++ b/src/declarative/util/qdeclarativefontloader.cpp
@@ -79,18 +79,27 @@ public:
 /*!
     \qmlclass FontLoader QDeclarativeFontLoader
     \since 4.7
-    \brief This item allows using fonts by name or url.
+    \brief The FontLoader element allows fonts to be loaded by name or URL.
 
-    Example:
+    The FontLoader element is used to load fonts by name or URL. 
+    
+    The \l status indicates when the font has been loaded, which is useful 
+    for fonts loaded from remote sources.
+
+    For example:
     \qml
     import Qt 4.7
 
-    FontLoader { id: fixedFont; name: "Courier" }
-    FontLoader { id: webFont; source: "http://www.mysite.com/myfont.ttf" }
+    Column { 
+        FontLoader { id: fixedFont; name: "Courier" }
+        FontLoader { id: webFont; source: "http://www.mysite.com/myfont.ttf" }
 
-    Text { text: "Fixed-size font"; font.family: fixedFont.name }
-    Text { text: "Fancy font"; font.family: webFont.name }
+        Text { text: "Fixed-size font"; font.family: fixedFont.name }
+        Text { text: "Fancy font"; font.family: webFont.name }
+    }
     \endqml
+
+    \sa {declarative/text/fonts}{Fonts example}
 */
 QDeclarativeFontLoader::QDeclarativeFontLoader(QObject *parent)
     : QObject(*(new QDeclarativeFontLoaderPrivate), parent)
diff --git a/src/declarative/util/qdeclarativelistmodel.cpp b/src/declarative/util/qdeclarativelistmodel.cpp
index 7518eb7..ff83227 100644
--- a/src/declarative/util/qdeclarativelistmodel.cpp
+++ b/src/declarative/util/qdeclarativelistmodel.cpp
@@ -76,125 +76,41 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM
 
     For example:
 
-    \code
-    ListModel {
-        id: fruitModel
-        ListElement {
-            name: "Apple"
-            cost: 2.45
-        }
-        ListElement {
-            name: "Orange"
-            cost: 3.25
-        }
-        ListElement {
-            name: "Banana"
-            cost: 1.95
-        }
-    }
-    \endcode
+    \snippet doc/src/snippets/declarative/listmodel.qml 0
 
-    Roles (properties) must begin with a lower-case letter.The above example defines a
+    Roles (properties) must begin with a lower-case letter. The above example defines a
     ListModel containing three elements, with the roles "name" and "cost".
 
     Values must be simple constants - either strings (quoted), bools (true, false), numbers,
     or enum values (like Text.AlignHCenter).
 
     The defined model can be used in views such as ListView:
-    \code
-    Component {
-        id: fruitDelegate
-        Item {
-            width: 200; height: 50
-            Text { text: name }
-            Text { text: '$'+cost; anchors.right: parent.right }
-        }
-    }
 
-    ListView {
-        model: fruitModel
-        delegate: fruitDelegate
-        anchors.fill: parent
-    }
-    \endcode
+    \snippet doc/src/snippets/declarative/listmodel-simple.qml 0
+    \dots 8
+    \snippet doc/src/snippets/declarative/listmodel-simple.qml 1
+    \image listmodel.png
 
     It is possible for roles to contain list data.  In the example below we create a list of fruit attributes:
 
-    \code
-    ListModel {
-        id: fruitModel
-        ListElement {
-            name: "Apple"
-            cost: 2.45
-            attributes: [
-                ListElement { description: "Core" },
-                ListElement { description: "Deciduous" }
-            ]
-        }
-        ListElement {
-            name: "Orange"
-            cost: 3.25
-            attributes: [
-                ListElement { description: "Citrus" }
-            ]
-        }
-        ListElement {
-            name: "Banana"
-            cost: 1.95
-            attributes: [
-                ListElement { description: "Tropical" },
-                ListElement { description: "Seedless" }
-            ]
-        }
-    }
-    \endcode
+    \snippet doc/src/snippets/declarative/listmodel-nested.qml model
+
+    The delegate below displays all the fruit attributes:
+
+    \snippet doc/src/snippets/declarative/listmodel-nested.qml delegate
+    \image listmodel-nested.png
 
-    The delegate below will list all the fruit attributes:
-    \code
-    Component {
-        id: fruitDelegate
-        Item {
-            width: 200; height: 50
-            Text { id: name; text: name }
-            Text { text: '$'+cost; anchors.right: parent.right }
-            Row {
-                anchors.top: name.bottom
-                spacing: 5
-                Text { text: "Attributes:" }
-                Repeater {
-                    model: attributes
-                    Component { Text { text: description } }
-                }
-            }
-        }
-    }
-    \endcode
 
     \section2 Modifying list models
 
     The content of a ListModel may be created and modified using the clear(),
-    append(), and set() methods.  For example:
-
-    \code
-    Component {
-        id: fruitDelegate
-        Item {
-            width: 200; height: 50
-            Text { text: name }
-            Text { text: '$'+cost; anchors.right: parent.right }
-
-            // Double the price when clicked.
-            MouseArea {
-                anchors.fill: parent
-                onClicked: fruitModel.set(index, "cost", cost*2)
-            }
-        }
-    }
-    \endcode
+    append(), set() and setProperty() methods.  For example:
+    
+    \snippet doc/src/snippets/declarative/listmodel-modify.qml delegate
 
     When creating content dynamically, note that the set of available properties cannot be changed
-    except by first clearing the model - whatever properties are first added are then the
-    only permitted properties in the model.
+    except by first clearing the model. Whatever properties are first added to the model are then the
+    only permitted properties in the model until it is cleared.
 
 
     \section2 Using threaded list models with WorkerScript
@@ -214,11 +130,11 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM
     \snippet examples/declarative/threading/threadedlistmodel/dataloader.js 0
 
     The application's \tt Timer object periodically sends a message to the
-    worker script by calling \tt WorkerScript::sendMessage(). When this message
-    is received, \tt WorkerScript.onMessage() is invoked in
+    worker script by calling \l WorkerScript::sendMessage(). When this message
+    is received, \l {WorkerScript::onMessage}{WorkerScript.onMessage()} is invoked in
     \tt dataloader.js, which appends the current time to the list model.
 
-    Note the call to sync() from the \c WorkerScript.onMessage() handler.
+    Note the call to sync() from the \l {WorkerScript::onMessage}{WorkerScript.onMessage()} handler.
     You must call sync() or else the changes made to the list from the external
     thread will not be reflected in the list model in the main thread.
 
@@ -244,7 +160,7 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM
 
     In addition, the WorkerScript cannot add any list data to the model.
 
-    \sa {qmlmodels}{Data Models}, WorkerScript, QtDeclarative
+    \sa {qmlmodels}{Data Models}, {declarative/threading/threadedlistmodel}{Threaded ListModel example}, QtDeclarative
 */
 
 
@@ -454,7 +370,7 @@ void QDeclarativeListModel::insert(int index, const QScriptValue& valuemap)
     to the end of the list:
 
     \code
-        fruitModel.move(0,fruitModel.count-3,3)
+        fruitModel.move(0, fruitModel.count - 3, 3)
     \endcode
 
     \sa append()
diff --git a/src/declarative/util/qdeclarativepackage.cpp b/src/declarative/util/qdeclarativepackage.cpp
index 9617b86..b149120 100644
--- a/src/declarative/util/qdeclarativepackage.cpp
+++ b/src/declarative/util/qdeclarativepackage.cpp
@@ -48,17 +48,17 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \qmlclass Package QDeclarativePackage
-    \brief Package provides a collection of named items
+    \brief Package provides a collection of named items.
 
-    The Package class is currently used in conjunction with
+    The Package class is used in conjunction with
     VisualDataModel to enable delegates with a shared context
     to be provided to multiple views.
 
     Any item within a Package may be assigned a name via the
-    \e {Package.name} attached property.
+    \l{Package::name}{Package.name} attached property.
 
     The example below creates a Package containing two named items;
-    \e list and \e grid.  The third element in the package is parented to whichever
+    \e list and \e grid.  The third element in the package (the \l Rectangle) is parented to whichever
     delegate it should appear in.  This allows an item to move
     between views.
 
@@ -70,7 +70,12 @@ QT_BEGIN_NAMESPACE
 
     \snippet examples/declarative/modelviews/package/view.qml 0
 
-    \sa QtDeclarative
+    \sa {declarative/modelviews/package}{Package example}, QtDeclarative
+*/
+
+/*!
+    \qmlattachedproperty bool Package::name
+    This attached property holds the name of an item within a Package.
 */
 
 
diff --git a/src/declarative/util/qdeclarativepackage_p.h b/src/declarative/util/qdeclarativepackage_p.h
index 57d9c22..6b12ef7 100644
--- a/src/declarative/util/qdeclarativepackage_p.h
+++ b/src/declarative/util/qdeclarativepackage_p.h
@@ -50,12 +50,6 @@ QT_BEGIN_NAMESPACE
 
 QT_MODULE(Declarative)
 
-/*****************************************************************************
- *****************************************************************************
- XXX Experimental
- *****************************************************************************
-*****************************************************************************/
-
 class QDeclarativePackagePrivate;
 class QDeclarativePackageAttached;
 class Q_AUTOTEST_EXPORT QDeclarativePackage : public QObject
diff --git a/src/declarative/util/qdeclarativepropertychanges.cpp b/src/declarative/util/qdeclarativepropertychanges.cpp
index e98afeb..8e3ec82 100644
--- a/src/declarative/util/qdeclarativepropertychanges.cpp
+++ b/src/declarative/util/qdeclarativepropertychanges.cpp
@@ -91,7 +91,7 @@ QT_BEGIN_NAMESPACE
     \endqml
 
     By default, PropertyChanges will establish new bindings where appropriate.
-    For example, the following creates a new binding for myItem's height property.
+    For example, the following creates a new binding for myItem's \c height property.
 
     \qml
     PropertyChanges {
@@ -500,8 +500,8 @@ QDeclarativePropertyChanges::ActionList QDeclarativePropertyChanges::actions()
     If explicit is set to true, any potential bindings will be interpreted as
     once-off assignments that occur when the state is entered.
 
-    In the following example, the addition of explicit prevents myItem.width from
-    being bound to parent.width. Instead, it is assigned the value of parent.width
+    In the following example, the addition of explicit prevents \c myItem.width from
+    being bound to \c parent.width. Instead, it is assigned the value of \c parent.width
     at the time of the state change.
     \qml
     PropertyChanges {
diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp
index dc2b2cc..ae19a9c 100644
--- a/src/declarative/util/qdeclarativestate.cpp
+++ b/src/declarative/util/qdeclarativestate.cpp
@@ -136,12 +136,31 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje
     \since 4.7
     \brief The State element defines configurations of objects and properties.
 
-    A state is specified as a set of batched changes from the default configuration.
+    A \e state is a set of batched changes from the default configuration.
+
+    All items have a default state that defines the default configuration of objects
+    and property values. New states can be defined by adding State items to the \l {Item::states}{states} property to
+    allow items to switch between different configurations. These configurations
+    can, for example, be used to apply different sets of property values or execute
+    different scripts.
+
+    The following example displays a single Rectangle. In the default state, the rectangle
+    is colored black. In the "clicked" state, a PropertyChanges element changes the
+    rectangle's color to red. Clicking within the MouseArea toggles the rectangle's state
+    between the default state and the "clicked" state, thus toggling the color of the
+    rectangle between black and red.
+
+    \snippet doc/src/snippets/declarative/state.qml 0
+
+    Notice the default state is referred to using an empty string ("").
+
+    States are commonly used together with \l {state-transitions}{Transitions} to provide
+    animations when state changes occur.
 
     \note setting the state of an object from within another state of the same object is
     not allowed.
 
-    \sa {qmlstates}{States}, {state-transitions}{Transitions}, QtDeclarative
+    \sa {declarative/animation/states}{states example}, {qmlstates}{States}, {state-transitions}{Transitions}, QtDeclarative
 */
 
 /*!
@@ -173,7 +192,7 @@ QDeclarativeState::~QDeclarativeState()
 
 /*!
     \qmlproperty string State::name
-    This property holds the name of the state
+    This property holds the name of the state.
 
     Each state should have a unique name.
 */
@@ -187,6 +206,13 @@ void QDeclarativeState::setName(const QString &n)
 {
     Q_D(QDeclarativeState);
     d->name = n;
+    d->named = true;
+}
+
+bool QDeclarativeState::isNamed() const
+{
+    Q_D(const QDeclarativeState);
+    return d->named;
 }
 
 bool QDeclarativeState::isWhenKnown() const
@@ -197,12 +223,12 @@ bool QDeclarativeState::isWhenKnown() const
 
 /*!
     \qmlproperty bool State::when
-    This property holds when the state should be applied
+    This property holds when the state should be applied.
 
-    This should be set to an expression that evaluates to true when you want the state to
+    This should be set to an expression that evaluates to \c true when you want the state to
     be applied.
 
-    If multiple states in a group have \c when clauses that evaluate to true at the same time,
+    If multiple states in a group have \c when clauses that evaluate to \c true at the same time,
     the first matching state will be applied. For example, in the following snippet
     \c state1 will always be selected rather than \c state2 when sharedCondition becomes
     \c true.
@@ -229,7 +255,9 @@ void QDeclarativeState::setWhen(QDeclarativeBinding *when)
 
 /*!
     \qmlproperty string State::extend
-    This property holds the state that this state extends
+    This property holds the state that this state extends.
+
+    When a state extends another state, it inherits all the changes of that state.
 
     The state being extended is treated as the base state in regards to
     the changes specified by the extending state.
diff --git a/src/declarative/util/qdeclarativestate_p.h b/src/declarative/util/qdeclarativestate_p.h
index 37b24cb..2e2ce7b 100644
--- a/src/declarative/util/qdeclarativestate_p.h
+++ b/src/declarative/util/qdeclarativestate_p.h
@@ -146,6 +146,7 @@ public:
 
     QString name() const;
     void setName(const QString &);
+    bool isNamed() const;
 
     /*'when' is a QDeclarativeBinding to limit state changes oscillation
      due to the unpredictable order of evaluation of bound expressions*/
diff --git a/src/declarative/util/qdeclarativestate_p_p.h b/src/declarative/util/qdeclarativestate_p_p.h
index 4a2af0f..2ef9bb0 100644
--- a/src/declarative/util/qdeclarativestate_p_p.h
+++ b/src/declarative/util/qdeclarativestate_p_p.h
@@ -101,12 +101,13 @@ class QDeclarativeStatePrivate : public QObjectPrivate
 
 public:
     QDeclarativeStatePrivate()
-    : when(0), inState(false), group(0) {}
+    : when(0), named(false), inState(false), group(0) {}
 
     typedef QList<QDeclarativeSimpleAction> SimpleActionList;
 
     QString name;
     QDeclarativeBinding *when;
+    bool named;
 
     struct OperationGuard : public QDeclarativeGuard<QDeclarativeStateOperation>
     {
diff --git a/src/declarative/util/qdeclarativestategroup.cpp b/src/declarative/util/qdeclarativestategroup.cpp
index 9b042d7..67cd12e 100644
--- a/src/declarative/util/qdeclarativestategroup.cpp
+++ b/src/declarative/util/qdeclarativestategroup.cpp
@@ -91,8 +91,8 @@ public:
    \since 4.7
    \brief The StateGroup element provides state support for non-Item elements.
 
-   Item (and all dervied elements) provides built in support for states and transitions
-   via its state, states and transitions properties. StateGroup provides an easy way to
+   Item (and all derived elements) provides built in support for states and transitions
+   via its \l{Item::state}{state}, \l{Item::states}{states} and \l{Item::transitions}{transitions} properties. StateGroup provides an easy way to
    use this support in other (non-Item-derived) elements.
 
    \qml
@@ -263,7 +263,7 @@ void QDeclarativeStateGroup::componentComplete()
 
     for (int ii = 0; ii < d->states.count(); ++ii) {
         QDeclarativeState *state = d->states.at(ii);
-        if (state->name().isEmpty())
+        if (!state->isNamed())
             state->setName(QLatin1String("anonymousState") % QString::number(++d->unnamedCount));
     }
 
@@ -295,7 +295,7 @@ bool QDeclarativeStateGroupPrivate::updateAutoState()
     for (int ii = 0; ii < states.count(); ++ii) {
         QDeclarativeState *state = states.at(ii);
         if (state->isWhenKnown()) {
-            if (!state->name().isEmpty()) {
+            if (state->isNamed()) {
                 if (state->when() && state->when()->evaluate().toBool()) {
                     if (stateChangeDebug()) 
                         qWarning() << "Setting auto state due to:" 
diff --git a/src/declarative/util/qdeclarativestateoperations.cpp b/src/declarative/util/qdeclarativestateoperations.cpp
index 99f163e..51e6f99 100644
--- a/src/declarative/util/qdeclarativestateoperations.cpp
+++ b/src/declarative/util/qdeclarativestateoperations.cpp
@@ -172,6 +172,14 @@ void QDeclarativeParentChangePrivate::doChange(QDeclarativeItem *targetParent, Q
     items involved in the reparenting (i.e. items in the common ancestor tree
     for the original and new parent).
 
+    The example below displays a large red rectangle and a small blue rectangle, side by side. 
+    When the \c blueRect is clicked, it changes to the "reparented" state: its parent is changed to \c redRect and it is 
+    positioned at (10, 10) within the red rectangle, as specified in the ParentChange.
+
+    \snippet doc/src/snippets/declarative/parentchange.qml 0
+
+    \image parentchange.png
+
     You can specify at which point in a transition you want a ParentChange to occur by
     using a ParentAnimation.
 */
@@ -583,9 +591,9 @@ public:
     \qmlclass StateChangeScript QDeclarativeStateChangeScript
     \brief The StateChangeScript element allows you to run a script in a state.
 
-    StateChangeScripts are run when entering the state. You can use
-    ScriptAction to specify at which point in the transition
-    you want the StateChangeScript to be run.
+    A StateChangeScript is run upon entering a state. You can optionally use
+    ScriptAction to specify the point in the transition at which
+    the StateChangeScript should to be run.
 
     \qml
     State {
@@ -687,22 +695,18 @@ QString QDeclarativeStateChangeScript::typeName() const
     \qmlclass AnchorChanges QDeclarativeAnchorChanges
     \brief The AnchorChanges element allows you to change the anchors of an item in a state.
 
-    In the following example we change the top and bottom anchors of an item:
-    \qml
-    State {
-        name: "reanchored"
-        AnchorChanges {
-            target: content;
-            anchors.top: window.top;
-            anchors.bottom: window.bottom
-        }
-        PropertyChanges {
-            target: content;
-            anchors.topMargin: 3
-            anchors.bottomMargin: 3;
-        }
-    }
-    \endqml
+    The AnchorChanges element is used to modify the anchors of an item in a \l State.
+
+    AnchorChanges cannot be used to modify the margins on an item. For this, use
+    PropertyChanges intead.
+
+    In the following example we change the top and bottom anchors of an item
+    using AnchorChanges, and the top and bottom anchor margins using
+    PropertyChanges:
+
+    \snippet doc/src/snippets/declarative/anchorchanges.qml 0
+
+    \image anchorchanges.png
 
     AnchorChanges can be animated using AnchorAnimation.
     \qml
diff --git a/src/declarative/util/qdeclarativesystempalette.cpp b/src/declarative/util/qdeclarativesystempalette.cpp
index 6c62446..c334859 100644
--- a/src/declarative/util/qdeclarativesystempalette.cpp
+++ b/src/declarative/util/qdeclarativesystempalette.cpp
@@ -59,22 +59,25 @@ public:
 /*!
     \qmlclass SystemPalette QDeclarativeSystemPalette
     \since 4.7
-    \brief The SystemPalette item gives access to the Qt palettes.
-    \sa QPalette
+    \brief The SystemPalette element provides access to the Qt palettes.
 
-    Example:
-    \qml
-    SystemPalette { id: myPalette; colorGroup: Qt.Active }
+    The SystemPalette element provides access to the Qt application
+    palettes. This provides information about the standard colors used 
+    for application windows, buttons and other features. These colors
+    are grouped into three \e {color groups}: \c Active, \c Inactive,
+    and \c Disabled.  See the QPalette documentation for details about
+    color groups and the properties provided by SystemPalette.
 
-    Rectangle {
-        width: 640; height: 480
-        color: myPalette.window
-        Text {
-            anchors.fill: parent
-            text: "Hello!"; color: myPalette.windowText
-        }
-    }
-    \endqml
+    This can be used to color items in a way that provides a more
+    native look and feel.
+
+    The following example creates a palette from the \c Active color
+    group and uses this to color the window and text items
+    appropriately:
+
+    \snippet doc/src/snippets/declarative/systempalette.qml 0
+
+    \sa QPalette
 */
 QDeclarativeSystemPalette::QDeclarativeSystemPalette(QObject *parent)
     : QObject(*(new QDeclarativeSystemPalettePrivate), parent)
@@ -258,10 +261,15 @@ QColor QDeclarativeSystemPalette::highlightedText() const
 }
 
 /*!
-    \qmlproperty QDeclarativeSystemPalette::ColorGroup SystemPalette::colorGroup
+    \qmlproperty enumeration SystemPalette::colorGroup
+
+    The color group of the palette. This can be one of:
 
-    The color group of the palette. It can be Active, Inactive or Disabled.
-    Active is the default.
+    \list
+    \o SystemPalette.Active (default)
+    \o SystemPalette.Inactive
+    \o SystemPalette.Disabled
+    \endlist
 
     \sa QPalette::ColorGroup
 */
diff --git a/src/declarative/util/qdeclarativeview.cpp b/src/declarative/util/qdeclarativeview.cpp
index 6059ad6..0414e65 100644
--- a/src/declarative/util/qdeclarativeview.cpp
+++ b/src/declarative/util/qdeclarativeview.cpp
@@ -131,7 +131,7 @@ class QDeclarativeViewPrivate : public QGraphicsViewPrivate, public QDeclarative
     Q_DECLARE_PUBLIC(QDeclarativeView)
 public:
     QDeclarativeViewPrivate()
-        : root(0), declarativeItemRoot(0), graphicsWidgetRoot(0), component(0), resizeMode(QDeclarativeView::SizeViewToRootObject) {}
+        : root(0), declarativeItemRoot(0), graphicsWidgetRoot(0), component(0), resizeMode(QDeclarativeView::SizeViewToRootObject), initialSize(0,0) {}
     ~QDeclarativeViewPrivate() { delete root; }
     void execute();
     void itemGeometryChanged(QDeclarativeItem *item, const QRectF &newGeometry, const QRectF &oldGeometry);
@@ -150,6 +150,7 @@ public:
     QBasicTimer resizetimer;
 
     QDeclarativeView::ResizeMode resizeMode;
+    QSize initialSize;
     QElapsedTimer frameTimer;
 
     void init();
@@ -586,9 +587,11 @@ void QDeclarativeView::setRootObject(QObject *obj)
     }
 
     if (d->root) {
-        QSize initialSize = d->rootObjectSize();
-        if (initialSize != size()) {
-            resize(initialSize);
+        d->initialSize = d->rootObjectSize();
+        if (d->initialSize != size()) {
+            if (!(parentWidget() && parentWidget()->layout())) {
+                resize(d->initialSize);
+            }
         }
         d->initResize();
     }
@@ -638,6 +641,15 @@ QSize QDeclarativeView::sizeHint() const
 }
 
 /*!
+  Returns the initial size of the root object
+*/
+QSize QDeclarativeView::initialSize() const
+{
+    Q_D(const QDeclarativeView);
+    return d->initialSize;
+}
+
+/*!
   Returns the view's root \l {QGraphicsObject} {item}.
  */
 QGraphicsObject *QDeclarativeView::rootObject() const
diff --git a/src/declarative/util/qdeclarativeview.h b/src/declarative/util/qdeclarativeview.h
index e9cff32..cdcf134 100644
--- a/src/declarative/util/qdeclarativeview.h
+++ b/src/declarative/util/qdeclarativeview.h
@@ -90,6 +90,7 @@ public:
     QList<QDeclarativeError> errors() const;
 
     QSize sizeHint() const;
+    QSize initialSize() const;
 
 Q_SIGNALS:
     void sceneResized(QSize size); // ???
diff --git a/src/declarative/util/qdeclarativexmllistmodel.cpp b/src/declarative/util/qdeclarativexmllistmodel.cpp
index 4f9355b..4adef25 100644
--- a/src/declarative/util/qdeclarativexmllistmodel.cpp
+++ b/src/declarative/util/qdeclarativexmllistmodel.cpp
@@ -523,10 +523,13 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla
     A XmlListModel could create a model from this data, like this:
 
     \qml
+    import Qt 4.7
+
     XmlListModel {
         id: xmlModel
         source: "http://www.mysite.com/feed.xml"
         query: "/rss/channel/item"
+
         XmlRole { name: "title"; query: "title/string()" }
         XmlRole { name: "pubDate"; query: "pubDate/string()" }
     }
@@ -536,7 +539,7 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla
     a model item for each \c <item> in the XML document. 
     
     The XmlRole objects define the
-    model item attributes; here, each model item will have \c title and \c pubDate 
+    model item attributes. Here, each model item will have \c title and \c pubDate 
     attributes that match the \c title and \c pubDate values of its corresponding \c <item>.
     (See \l XmlRole::query for more examples of valid XPath expressions for XmlRole.)
 
@@ -672,11 +675,11 @@ void QDeclarativeXmlListModel::setSource(const QUrl &src)
 
 /*!
     \qmlproperty string XmlListModel::xml
-    This property holds XML text set directly.
+    This property holds the XML data for this model, if set.
 
     The text is assumed to be UTF-8 encoded.
 
-    If both source and xml are set, xml will be used.
+    If both \l source and \c xml are set, \c xml will be used.
 */
 QString QDeclarativeXmlListModel::xml() const
 {
@@ -733,6 +736,7 @@ void QDeclarativeXmlListModel::setQuery(const QString &query)
         source: "http://mysite.com/feed.xml"
         query: "/feed/entry"
         namespaceDeclarations: "declare default element namespace 'http://www.w3.org/2005/Atom';"
+
         XmlRole { name: "title"; query: "title/string()" }
     }
     \endqml
diff --git a/src/declarative/util/qlistmodelinterface.cpp b/src/declarative/util/qlistmodelinterface.cpp
new file mode 100644
index 0000000..98d6a5b
--- /dev/null
+++ b/src/declarative/util/qlistmodelinterface.cpp
@@ -0,0 +1,109 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtDeclaractive module 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$
+**
+****************************************************************************/
+
+#include "private/qlistmodelinterface_p.h"
+
+QT_BEGIN_NAMESPACE
+
+/*!
+  \internal
+  \class QListModelInterface
+  \brief The QListModelInterface class can be subclassed to provide C++ models to QDeclarativeGraphics Views
+
+  This class is comprised primarily of pure virtual functions which
+  you must implement in a subclass. You can then use the subclass
+  as a model for a QDeclarativeGraphics view, such as a QDeclarativeListView.
+*/
+
+/*! \fn QListModelInterface::QListModelInterface(QObject *parent)
+  Constructs a QListModelInterface with the specified \a parent.
+*/
+
+  /*! \fn QListModelInterface::QListModelInterface(QObjectPrivate &dd, QObject *parent)
+
+  \internal
+ */
+
+/*! \fn QListModelInterface::~QListModelInterface()
+  The destructor is virtual.
+ */
+
+/*! \fn int QListModelInterface::count() const
+  Returns the number of data entries in the model.
+*/
+
+/*! \fn QHash<int,QVariant> QListModelInterface::data(int index, const QList<int>& roles) const
+  Returns the data at the given \a index for the specifed \a roles.
+*/
+
+/*! \fn bool QListModelInterface::setData(int index, const QHash<int,QVariant>& values)
+  Sets the data at the given \a index. \a values is a mapping of
+  QVariant values to roles. Returns false.
+*/
+
+/*! \fn QList<int> QListModelInterface::roles() const
+  Returns the list of roles for which the list model interface
+  provides data.
+*/
+
+/*! \fn QString QListModelInterface::toString(int role) const
+  Returns a string description of the specified \a role.
+*/
+
+/*! \fn void QListModelInterface::itemsInserted(int index, int count)
+  Emit this signal when \a count items are inserted at \a index.
+ */
+
+/*! \fn void QListModelInterface::itemsRemoved(int index, int count)
+  Emit this signal when \a count items are removed at \a index.
+ */
+
+/*! \fn void QListModelInterface::itemsMoved(int from, int to, int count)
+  Emit this signal when \a count items are moved from index \a from
+  to index \a to.
+ */
+
+/*! \fn void QListModelInterface::itemsChanged(int index, int count, const QList<int> &roles)
+  Emit this signal when \a count items at \a index have had their
+  \a roles changed.
+ */
+
+QT_END_NAMESPACE
diff --git a/src/declarative/util/qlistmodelinterface_p.h b/src/declarative/util/qlistmodelinterface_p.h
new file mode 100644
index 0000000..07592ad
--- /dev/null
+++ b/src/declarative/util/qlistmodelinterface_p.h
@@ -0,0 +1,85 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtDeclarative module 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$
+**
+****************************************************************************/
+
+#ifndef QLISTMODELINTERFACE_H
+#define QLISTMODELINTERFACE_H
+
+#include <QtCore/QHash>
+#include <QtCore/QVariant>
+
+QT_BEGIN_HEADER
+
+QT_BEGIN_NAMESPACE
+
+QT_MODULE(Declarative)
+
+class Q_DECLARATIVE_EXPORT QListModelInterface : public QObject
+{
+    Q_OBJECT
+ public:
+    QListModelInterface(QObject *parent = 0) : QObject(parent) {}
+    virtual ~QListModelInterface() {}
+
+    virtual int count() const = 0;
+    virtual QHash<int,QVariant> data(int index, const QList<int>& roles = QList<int>()) const = 0;
+    virtual QVariant data(int index, int role) const = 0;
+    virtual bool setData(int index, const QHash<int,QVariant>& values)
+    { Q_UNUSED(index); Q_UNUSED(values); return false; }
+
+    virtual QList<int> roles() const = 0;
+    virtual QString toString(int role) const = 0;
+
+ Q_SIGNALS:
+    void itemsInserted(int index, int count);
+    void itemsRemoved(int index, int count);
+    void itemsMoved(int from, int to, int count);
+    void itemsChanged(int index, int count, const QList<int> &roles);
+
+ protected:
+    QListModelInterface(QObjectPrivate &dd, QObject *parent) 
+        : QObject(dd, parent) {}
+};
+
+
+QT_END_NAMESPACE
+
+QT_END_HEADER
+#endif //QTREEMODELINTERFACE_H
diff --git a/src/declarative/util/util.pri b/src/declarative/util/util.pri
index f20bba1..04cfc68 100644
--- a/src/declarative/util/util.pri
+++ b/src/declarative/util/util.pri
@@ -27,7 +27,8 @@ SOURCES += \
     $$PWD/qdeclarativebehavior.cpp \
     $$PWD/qdeclarativefontloader.cpp \
     $$PWD/qdeclarativestyledtext.cpp \
-    $$PWD/qdeclarativelistmodelworkeragent.cpp
+    $$PWD/qdeclarativelistmodelworkeragent.cpp \
+    $$PWD/qlistmodelinterface.cpp
 
 HEADERS += \
     $$PWD/qdeclarativeutilmodule_p.h\
@@ -61,7 +62,8 @@ HEADERS += \
     $$PWD/qdeclarativebehavior_p.h \
     $$PWD/qdeclarativefontloader_p.h \
     $$PWD/qdeclarativestyledtext_p.h \
-    $$PWD/qdeclarativelistmodelworkeragent_p.h
+    $$PWD/qdeclarativelistmodelworkeragent_p.h \
+    $$PWD/qlistmodelinterface_p.h
 
 contains(QT_CONFIG, xmlpatterns) {
     QT+=xmlpatterns