diff options
35 files changed, 1105 insertions, 422 deletions
diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 6e98949..c320898 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -46,14 +46,14 @@ Animation in QML is done by animating properties of objects. Properties of type real, int, color, rect, point, size, and vector3d can all be animated. -QML supports three main forms of animation - basic property animation, +QML supports three main 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 +The simplest form of animation is a \l PropertyAnimation, which can animate all of the property types listed above. If the property you are animating is a number or color, you can alternatively use NumberAnimation or ColorAnimation. These elements don't add any additional functionality, but will help enforce type correctness and are slightly more efficient. @@ -62,61 +62,23 @@ A property animation can be specified as a value source using the \e Animation \ for repeating animations. The following example creates a bouncing effect: -\qml -Rectangle { - id: rect - width: 120; height: 200; - Image { - id: img - source: "qt-logo.png" - x: 60-img.width/2 - y: 0 - SequentialAnimation on y { - loops: Animation.Infinite - NumberAnimation { to: 200-img.height; easing.type: Easing.OutBounce; duration: 2000 } - PauseAnimation { duration: 1000 } - NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 } - } - } -} -\endqml +\snippet doc/src/snippets/declarative/animation.qml property-anim-1 \image propanim.gif When you assign an animation as a value source, you do not need to specify \c property -or \c target; they are automatically selected for you. You do, however, need to specify \c to. +or \c target values; they are automatically selected for you. You do, however, need to specify a \c to value. An animation specified as a value source will be \c running by default. -\qml -Rectangle { - id: rect - width: 200; height: 200; - Rectangle { - color: "red" - width: 50; height: 50 - NumberAnimation on x { to: 50 } - } -} -\endqml +For example, here is a rectangle that uses a \l NumberAnimation value source to animate the movement +from its current position to an \c x value of 50. The animation starts immediately, and only the \c to +property is required: + +\snippet doc/src/snippets/declarative/animation.qml property-anim-2 A property animation can also be specified as a resource that is manipulated from script. -\qml -PropertyAnimation { - id: animation - target: image - property: "scale" - from: 1; to: .5 -} -Image { - id: image - source: "image.png" - MouseArea { - anchors.fill: parent - onPressed: animation.start() - } -} -\endqml +\snippet doc/src/snippets/declarative/animation.qml property-anim-3 As can be seen, when an animation is used like this (as opposed to as a value source) you will need to explicitly set the \c target and \c property to animate. @@ -131,50 +93,20 @@ can only be triggered by a state change. For example, a transition could describe how an item moves from its initial position to its new position: -\code -transitions: [ - Transition { - NumberAnimation { - properties: "x,y" - easing.type: Easing.OutBounce - duration: 200 - } - } -] -\endcode +\snippet doc/src/snippets/declarative/animation.qml transitions-1 As can be seen, transitions make use of the same basic animation classes introduced above. In the above example we have specified that we want to animate the \c x and \c y properties, but have not -specified the objects to animate or the \c to values. By default these values are supplied by the framework -- +specified the objects to animate or the \c to values. By default these values are supplied by the framework; the animation will animate any \c targets whose \c x and \c y have changed, and the \c to values will be those defined in the end state. You can always supply explicit values to override these implicit values when needed. -\code -Transition { - from: "*" - to: "MyState" - reversible: true - SequentialAnimation { - NumberAnimation { - duration: 1000 - easing.type: Easing.OutBounce - // animate myItem's x and y if they have changed in the state - target: myItem - properties: "x,y" - } - NumberAnimation { - duration: 1000 - // animate myItem2's y to 200, regardless of what happens in the state - target: myItem2 - property: "y" - to: 200 - } - } -} -\endcode +\snippet doc/src/snippets/declarative/animation.qml transitions-2 QML transitions have selectors to determine which state changes a transition should apply to. The following transition will only be triggered when we enter into the \c "details" state. +(The "*" value is a wildcard value that specifies the transition should be applied when changing +from \e any state to the "details" state.) \code Transition { @@ -188,30 +120,7 @@ Transitions can happen in parallel, in sequence, or in any combination of the tw animations in a transition will happen in parallel. The following example shows a rather complex transition making use of both sequential and parallel animations: -\code -Transition { - from: "*" - to: "MyState" - reversible: true - SequentialAnimation { - ColorAnimation { duration: 1000 } - PauseAnimation { duration: 1000 } - ParallelAnimation { - NumberAnimation { - duration: 1000 - easing.type: Easing.OutBounce - targets: box1 - properties: "x,y" - } - NumberAnimation { - duration: 1000 - targets: box2 - properties: "x,y" - } - } - } -} -\endcode +\snippet doc/src/snippets/declarative/animation.qml transitions-3 \section1 Property Behaviors @@ -219,24 +128,15 @@ A \l{Behavior}{property behavior} specifies a default animation to run whenever of what caused the change. The \c enabled property can be used to force a \l Behavior to only apply under certain circumstances. -In the following snippet, we specify that we want the x position of redRect to be animated -whenever it changes. The animation will last 300 milliseconds and use an InOutQuad easing curve. +In the following snippet, we specify that we want the \c x position of \c redRect to be animated +whenever it changes. The animation will last 300 milliseconds and use an \l{PropertyAnimation::easing.type}{Easing.InOutQuad} easing curve. -\qml -Rectangle { - id: redRect - color: "red" - width: 100; height: 100 - Behavior on x { NumberAnimation { duration: 300; easing.type: Easing.InOutQuad } } -} -\endqml +\snippet doc/src/snippets/declarative/animation.qml behavior Like using an animation as a value source, when used in a Behavior and animation does not need to specify a \c target or \c property. -To trigger this behavior, we could: -\list -\o Enter a state that changes x +To trigger this behavior, we could enter a state that changes \c x: \qml State { @@ -249,7 +149,7 @@ State { } \endqml -\o Update x from a script +Or, update \c x from a script: \qml MouseArea { @@ -257,11 +157,10 @@ MouseArea { onClicked: redRect.x = 24; } \endqml -\endlist -If x were bound to another property, triggering the binding would also trigger the behavior. +If \c x were bound to another property, triggering the binding would also trigger the behavior. -If a state change has a transition animation matching a property with a Behavior, the transition animation -will override the Behavior for that state change. +If a state change has a transition animation matching a property with a \l Behavior, the transition animation +will override the \l Behavior for that state change. */ diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index aa48bcb..31fa948 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -211,6 +211,4 @@ The following table lists the QML elements provided by the \l {QtDeclarative}{Qt \endlist \endtable -\o - */ diff --git a/doc/src/declarative/pics/anchorchanges.png b/doc/src/declarative/pics/anchorchanges.png Binary files differnew file mode 100644 index 0000000..4973e4e --- /dev/null +++ b/doc/src/declarative/pics/anchorchanges.png diff --git a/doc/src/declarative/pics/listmodel-nested.png b/doc/src/declarative/pics/listmodel-nested.png Binary files differnew file mode 100644 index 0000000..ee7ffba --- /dev/null +++ b/doc/src/declarative/pics/listmodel-nested.png diff --git a/doc/src/declarative/pics/listmodel.png b/doc/src/declarative/pics/listmodel.png Binary files differnew file mode 100644 index 0000000..7ab1771 --- /dev/null +++ b/doc/src/declarative/pics/listmodel.png diff --git a/doc/src/declarative/pics/parentchange.png b/doc/src/declarative/pics/parentchange.png Binary files differnew file mode 100644 index 0000000..93206fb --- /dev/null +++ b/doc/src/declarative/pics/parentchange.png diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index fd0c677..43b5c31 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -70,58 +70,30 @@ 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 +To define a state for an item, add a \l State element to the \l{Item::states}{states} property. To +change the current state of an \l Item, set the \l{Item::state}{state} property to the name +of the required state. + 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 area changes the state from the default state to the 'moved' state, thus moving the rectangle. -\qml -Item { - id: myItem - - Rectangle { - id: myRect - width: 100 - height: 100 - color: "red" - } - - states: [ - State { - name: "moved" - PropertyChanges { - target: myRect - x: 50 - y: 50 - } - } - ] - - MouseArea { - anchors.fill: parent - onClicked: myItem.state = 'moved' - } -} -\endqml +\snippet doc/src/snippets/declarative/states.qml 0 +\snippet doc/src/snippets/declarative/states.qml 1 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: +For example, adding this code to the above \c Item element animates the transition to the "moved" state: -\qml - transitions: [ - Transition { - NumberAnimation { properties: "x,y"; duration: 500 } - } - ] -\endqml +\snippet doc/src/snippets/declarative/states.qml transitions See \l{state-transitions}{Transitions} for more information. Other things you can do in a state change: \list -\o override signal handlers with PropertyChanges -\o change an item's visual parent with ParentChange -\o change an item's anchors with AnchorChanges -\o run some script with StateChangeScript +\o Override signal handlers with PropertyChanges +\o Change an item's visual parent with ParentChange +\o Change an item's anchors with AnchorChanges +\o Run some script with StateChangeScript \endlist */ diff --git a/doc/src/snippets/declarative/anchorchanges.qml b/doc/src/snippets/declarative/anchorchanges.qml new file mode 100644 index 0000000..993618b --- /dev/null +++ b/doc/src/snippets/declarative/anchorchanges.qml @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Rectangle { + id: window + width: 120; height: 120 + color: "black" + + Rectangle { id: myRect; width: 50; height: 50; color: "red" } + + states: State { + name: "reanchored" + + AnchorChanges { + target: myRect + anchors.top: window.top + anchors.bottom: window.bottom + } + PropertyChanges { + target: myRect + anchors.topMargin: 10 + anchors.bottomMargin: 10 + } + } + + MouseArea { anchors.fill: parent; onClicked: window.state = "reanchored" } +} +//![0] + diff --git a/doc/src/snippets/declarative/animation.qml b/doc/src/snippets/declarative/animation.qml new file mode 100644 index 0000000..65acd36 --- /dev/null +++ b/doc/src/snippets/declarative/animation.qml @@ -0,0 +1,181 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +import Qt 4.7 + +Row { + +//![property-anim-1] +Rectangle { + id: rect + width: 120; height: 200 + + Image { + id: img + source: "pics/qt.png" + x: 60 - img.width/2 + y: 0 + + SequentialAnimation on y { + loops: Animation.Infinite + NumberAnimation { to: 200 - img.height; easing.type: Easing.OutBounce; duration: 2000 } + PauseAnimation { duration: 1000 } + NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 } + } + } +} +//![property-anim-1] + +//![property-anim-2] +Rectangle { + width: 200; height: 200 + + Rectangle { + color: "red" + width: 50; height: 50 + NumberAnimation on x { to: 50 } + } +} +//![property-anim-2] + + +Item { +//![property-anim-3] +PropertyAnimation { + id: animation + target: image + property: "scale" + from: 1; to: 0.5 +} + +Image { + id: image + source: "pics/qt.png" + MouseArea { + anchors.fill: parent + onPressed: animation.start() + } +} +//![property-anim-3] +} + + +//![transitions-1] +transitions: [ + Transition { + NumberAnimation { + properties: "x,y" + easing.type: Easing.OutBounce + duration: 200 + } + } +] +//![transitions-1] + + +//![transitions-2] +Transition { + from: "*" + to: "MyState" + reversible: true + + SequentialAnimation { + NumberAnimation { + duration: 1000 + easing.type: Easing.OutBounce + + // animate myItem's x and y if they have changed in the state + target: myItem + properties: "x,y" + } + + NumberAnimation { + duration: 1000 + + // animate myItem2's y to 200, regardless of what happens in the state + target: myItem2 + property: "y" + to: 200 + } + } +} +//![transitions-2] + + +//![transitions-3] +Transition { + from: "*" + to: "MyState" + reversible: true + + SequentialAnimation { + ColorAnimation { duration: 1000 } + PauseAnimation { duration: 1000 } + + ParallelAnimation { + NumberAnimation { + duration: 1000 + easing.type: Easing.OutBounce + targets: box1 + properties: "x,y" + } + NumberAnimation { + duration: 1000 + targets: box2 + properties: "x,y" + } + } + } +} +//![transitions-3] + +//![behavior] +Rectangle { + id: redRect + color: "red" + width: 100; height: 100 + + Behavior on x { + NumberAnimation { duration: 300; easing.type: Easing.InOutQuad } + } +} +//![behavior] + +} diff --git a/doc/src/snippets/declarative/createQmlObject.qml b/doc/src/snippets/declarative/createQmlObject.qml index f2ac6e6..f274e40 100644 --- a/doc/src/snippets/declarative/createQmlObject.qml +++ b/doc/src/snippets/declarative/createQmlObject.qml @@ -42,7 +42,7 @@ import Qt 4.7 Rectangle { - id: targetItem + id: parentItem property QtObject newObject width: 100 @@ -51,7 +51,7 @@ Rectangle { function createIt() { //![0] newObject = Qt.createQmlObject('import Qt 4.7; Rectangle {color: "red"; width: 20; height: 20}', - targetItem, "dynamicSnippet1"); + parentItem, "dynamicSnippet1"); //![0] } diff --git a/doc/src/snippets/declarative/listmodel-nested.qml b/doc/src/snippets/declarative/listmodel-nested.qml new file mode 100644 index 0000000..4ae43ff --- /dev/null +++ b/doc/src/snippets/declarative/listmodel-nested.qml @@ -0,0 +1,103 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +import Qt 4.7 + +Rectangle { + width: 200; height: 200 + + +//![model] +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" } + ] + } +} +//![model] + +//![delegate] +Component { + id: fruitDelegate + Item { + width: 200; height: 50 + Text { id: nameField; text: name } + Text { text: '$' + cost; anchors.left: nameField.right } + Row { + anchors.top: nameField.bottom + spacing: 5 + Text { text: "Attributes:" } + Repeater { + model: attributes + Text { text: description } + } + } + } +} +//![delegate] + +ListView { + width: 200; height: 200 + model: fruitModel + delegate: fruitDelegate +} + +} diff --git a/doc/src/snippets/declarative/listmodel-simple.qml b/doc/src/snippets/declarative/listmodel-simple.qml new file mode 100644 index 0000000..00b8cb0 --- /dev/null +++ b/doc/src/snippets/declarative/listmodel-simple.qml @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Rectangle { + width: 200; height: 200 + + ListModel { + id: fruitModel +//![0] + ListElement { + name: "Apple" + cost: 2.45 + } + ListElement { + name: "Orange" + cost: 3.25 + } + ListElement { + name: "Banana" + cost: 1.95 + } +//![1] + } + + Component { + id: fruitDelegate + Row { + spacing: 10 + Text { text: name } + Text { text: '$' + cost } + } + } + + ListView { + anchors.fill: parent + model: fruitModel + delegate: fruitDelegate + } +} +//![1] diff --git a/doc/src/snippets/declarative/listmodel.qml b/doc/src/snippets/declarative/listmodel.qml new file mode 100644 index 0000000..91b8230 --- /dev/null +++ b/doc/src/snippets/declarative/listmodel.qml @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +ListModel { + id: fruitModel + + ListElement { + name: "Apple" + cost: 2.45 + } + ListElement { + name: "Orange" + cost: 3.25 + } + ListElement { + name: "Banana" + cost: 1.95 + } +} +//![0] diff --git a/doc/src/snippets/declarative/parentchange.qml b/doc/src/snippets/declarative/parentchange.qml new file mode 100644 index 0000000..7f5718a --- /dev/null +++ b/doc/src/snippets/declarative/parentchange.qml @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Rectangle { + width: 200 + height: 100 + + Rectangle { + id: redRect + width: 100; height: 100 + color: "red" + } + + Rectangle { + id: blueRect + x: redRect.width + width: 50; height: 50 + color: "blue" + + states: State { + name: "reparented" + ParentChange { target: blueRect; parent: redRect; x: 10; y: 10 } + } + + MouseArea { anchors.fill: parent; onClicked: blueRect.state = "reparented" } + } +} +//![0] + diff --git a/doc/src/snippets/declarative/state.qml b/doc/src/snippets/declarative/state.qml new file mode 100644 index 0000000..a99c2e2 --- /dev/null +++ b/doc/src/snippets/declarative/state.qml @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Rectangle { + id: myRect + width: 100; height: 100 + color: "black" + + states: [ + State { + name: "clicked" + PropertyChanges { + target: myRect + color: "red" + } + } + ] + + MouseArea { + anchors.fill: parent + onClicked: { + if (myRect.state == "") // i.e. the default state + myRect.state = "clicked"; + else + myRect.state = ""; + } + } +} +//![0] diff --git a/doc/src/snippets/declarative/states.qml b/doc/src/snippets/declarative/states.qml new file mode 100644 index 0000000..c3b1796 --- /dev/null +++ b/doc/src/snippets/declarative/states.qml @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Item { + id: myItem + width: 200; height: 200 + + Rectangle { + id: myRect + width: 100; height: 100 + color: "red" + } + + states: [ + State { + name: "moved" + PropertyChanges { + target: myRect + x: 50 + y: 50 + } + } + ] + + MouseArea { + anchors.fill: parent + onClicked: myItem.state = 'moved' + } +//![0] + +//![transitions] +transitions: [ + Transition { + NumberAnimation { properties: "x,y"; duration: 500 } + } +] +//![transitions] + +//![1] +} +//![1] diff --git a/doc/src/snippets/declarative/visualdatamodel.qml b/doc/src/snippets/declarative/visualdatamodel.qml new file mode 100644 index 0000000..cdde513 --- /dev/null +++ b/doc/src/snippets/declarative/visualdatamodel.qml @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +Rectangle { + width: 200; height: 100 + + VisualDataModel { + id: visualModel + model: ListModel { + ListElement { name: "Apple" } + ListElement { name: "Orange" } + } + delegate: Rectangle { + height: 25 + width: 100 + Text { text: "Name: " + name} + } + } + + ListView { + anchors.fill: parent + model: visualModel + } +} +//![0] diff --git a/doc/src/snippets/declarative/visualdatamodel_rootindex/main.cpp b/doc/src/snippets/declarative/visualdatamodel_rootindex/main.cpp new file mode 100644 index 0000000..f77061e --- /dev/null +++ b/doc/src/snippets/declarative/visualdatamodel_rootindex/main.cpp @@ -0,0 +1,63 @@ +myModel/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +#include <QDeclarativeView> +#include <QDeclarativeContext> + +#include <QApplication> +#include <QDirModel> + +//![0] +int main(int argc, char ** argv) +{ + QApplication app(argc, argv); + + QDeclarativeView view; + + QDirModel model; + view.rootContext()->setContextProperty("dirModel", &model); + + view.setSource(QUrl::fromLocalFile("view.qml")); + view.show(); + + return app.exec(); +} +//![0] + diff --git a/doc/src/snippets/declarative/visualdatamodel_rootindex/view.qml b/doc/src/snippets/declarative/visualdatamodel_rootindex/view.qml new file mode 100644 index 0000000..e623faa --- /dev/null +++ b/doc/src/snippets/declarative/visualdatamodel_rootindex/view.qml @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +//![0] +import Qt 4.7 + +ListView { + id: view + width: 300 + height: 400 + + model: VisualDataModel { + model: dirModel + + delegate: Rectangle { + width: 200; height: 25 + Text { text: filePath } + + MouseArea { + anchors.fill: parent + onClicked: { + if (hasModelChildren) + view.model.rootIndex = view.model.modelIndex(index) + } + } + } + } +} +//![0] diff --git a/doc/src/snippets/declarative/visualdatamodel_rootindex/visualdatamodel_rootindex.pro b/doc/src/snippets/declarative/visualdatamodel_rootindex/visualdatamodel_rootindex.pro new file mode 100644 index 0000000..fec070c --- /dev/null +++ b/doc/src/snippets/declarative/visualdatamodel_rootindex/visualdatamodel_rootindex.pro @@ -0,0 +1,4 @@ +TEMPLATE = app +QT += gui declarative + +SOURCES += main.cpp diff --git a/src/declarative/graphicsitems/qdeclarativeitem.cpp b/src/declarative/graphicsitems/qdeclarativeitem.cpp index bef09bb..7ab280e 100644 --- a/src/declarative/graphicsitems/qdeclarativeitem.cpp +++ b/src/declarative/graphicsitems/qdeclarativeitem.cpp @@ -726,7 +726,7 @@ void QDeclarativeKeyNavigationAttached::keyReleased(QKeyEvent *event, bool post) The signal properties have a \l KeyEvent parameter, named \e event which contains details of the event. If a key is handled \e event.accepted should be set to true to prevent the - event from propagating up the item heirarchy. + event from propagating up the item hierarchy. \code Item { diff --git a/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp b/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp index 2a88a80..e133adb 100644 --- a/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp +++ b/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp @@ -113,16 +113,18 @@ public: \since 4.7 \brief The VisualItemModel allows items to be provided to a view. - The children of the VisualItemModel are provided in a model which - can be used in a view. Note that no delegate should be - provided to a view since the VisualItemModel contains the - visual delegate (items). + A VisualItemModel contains the visual items to be used in a view. + When a VisualItemModel is used in a view, the view does not require + a delegate since the VisualItemModel already contains the visual + delegate (items). An item can determine its index within the model via the \c VisualItemModel.index attached property. The example below places three colored rectangles in a ListView. \code + import Qt 4.7 + Rectangle { VisualItemModel { id: itemModel @@ -607,30 +609,15 @@ QDeclarativeVisualDataModelData *QDeclarativeVisualDataModelPrivate::data(QObjec A VisualDataModel encapsulates a model and the delegate that will be instantiated for items in the model. - It is usually not necessary to create a VisualDataModel directly, - since the QML views will create one internally. + It is usually not necessary to create VisualDataModel elements. + However, it can be useful for manipulating and accessing the \l modelIndex + when a QAbstractItemModel subclass is used as the + model. Also, VisualDataModel is used together with \l Package to + provide delegates to multiple views. The example below illustrates using a VisualDataModel with a ListView. - \code - VisualDataModel { - id: visualModel - model: myModel - delegate: Component { - Rectangle { - height: 25 - width: 100 - Text { text: "Name:" + name} - } - } - } - ListView { - width: 100 - height: 100 - anchors.fill: parent - model: visualModel - } - \endcode + \snippet doc/src/snippets/declarative/visualdatamodel.qml 0 */ QDeclarativeVisualDataModel::QDeclarativeVisualDataModel() @@ -805,56 +792,22 @@ void QDeclarativeVisualDataModel::setDelegate(QDeclarativeComponent *delegate) /*! \qmlproperty QModelIndex VisualDataModel::rootIndex - QAbstractItemModel provides a heirachical tree of data, whereas + QAbstractItemModel provides a hierarchical tree of data, whereas QML only operates on list data. \c rootIndex allows the children of any node in a QAbstractItemModel to be provided by this model. This property only affects models of type QAbstractItemModel. - \code - // main.cpp - - int main(int argc, char ** argv) - { - QApplication app(argc, argv); - - QDeclarativeView view; - - QDirModel model; - view.rootContext()->setContextProperty("myModel", &model); + For example, here is a simple interactive file system browser. + When a directory name is clicked, the view's \c rootIndex is set to the + QModelIndex node of the clicked directory, thus updating the view to show + the new directory's contents. - view.setSource(QUrl("qrc:view.qml")); - view.show(); - - return app.exec(); - } - - #include "main.moc" - \endcode - - \code - // view.qml - import Qt 4.7 - - ListView { - id: view - width: 200 - height: 200 - model: VisualDataModel { - model: myModel - delegate: Component { - Rectangle { - height: 25; width: 200 - Text { text: filePath } - MouseArea { - anchors.fill: parent; - onClicked: if (hasModelChildren) view.model.rootIndex = view.model.modelIndex(index) - } - } - } - } - } - \endcode + \c main.cpp: + \snippet doc/src/snippets/declarative/visualdatamodel_rootindex/main.cpp 0 + + \c view.qml: + \snippet doc/src/snippets/declarative/visualdatamodel_rootindex/view.qml 0 \sa modelIndex(), parentModelIndex() */ @@ -886,7 +839,7 @@ void QDeclarativeVisualDataModel::setRootIndex(const QVariant &root) /*! \qmlmethod QModelIndex VisualDataModel::modelIndex(int index) - QAbstractItemModel provides a heirachical tree of data, whereas + QAbstractItemModel provides a hierarchical tree of data, whereas QML only operates on list data. This function assists in using tree models in QML. @@ -906,7 +859,7 @@ QVariant QDeclarativeVisualDataModel::modelIndex(int idx) const /*! \qmlmethod QModelIndex VisualDataModel::parentModelIndex() - QAbstractItemModel provides a heirachical tree of data, whereas + QAbstractItemModel provides a hierarchical tree of data, whereas QML only operates on list data. This function assists in using tree models in QML. @@ -1000,10 +953,10 @@ QDeclarativeVisualDataModel::ReleaseFlags QDeclarativeVisualDataModel::release(Q The \a parts property selects a VisualDataModel which creates delegates from the part named. This is used in conjunction with - the Package element. + the \l Package element. For example, the code below selects a model which creates - delegates named \e list from a Package: + delegates named \e list from a \l Package: \code VisualDataModel { diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp index 9847079..55ee783 100644 --- a/src/declarative/qml/qdeclarativecomponent.cpp +++ b/src/declarative/qml/qdeclarativecomponent.cpp @@ -78,7 +78,7 @@ class QByteArray; \since 4.7 \brief The Component element encapsulates a QML component description. - Components are reusable, encapsulated Qml element with a well-defined interface. + Components are reusable, encapsulated QML elements with well-defined interfaces. They are often defined in \l {qdeclarativedocuments.html}{Component Files}. The \e Component element allows defining components within a QML file. @@ -547,16 +547,18 @@ QDeclarativeComponent::QDeclarativeComponent(QDeclarativeComponentPrivate &dd, Q /*! \qmlmethod object Component::createObject(parent) - Returns an object instance from this component, or null if object creation fails. + + Creates and returns an object instance of this component that will have the given + \a parent. Returns null if object creation fails. The object will be created in the same context as the one in which the component was created. This function will always return null when called on components which were not created in QML. - Note that if the returned object is to be displayed, its \c parent must be set to - an existing item in a scene, or else the object will not be visible. The parent - argument is required to help you avoid this, you must explicitly pass in null if - you wish to create an object without setting a parent. + If you wish to create an object without setting a parent, specify \c null for + the \a parent value. Note that if the returned object is to be displayed, you + must provide a valid \a parent value or set the returned object's \l{Item::parent}{parent} + property, or else the object will not be visible. */ /*! diff --git a/src/declarative/qml/qdeclarativecontext.cpp b/src/declarative/qml/qdeclarativecontext.cpp index 6a13f15..2221d78 100644 --- a/src/declarative/qml/qdeclarativecontext.cpp +++ b/src/declarative/qml/qdeclarativecontext.cpp @@ -116,7 +116,7 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() All properties added explicitly by QDeclarativeContext::setContextProperty() take precedence over the context object's properties. - Contexts form a hierarchy. The root of this heirarchy is the QDeclarativeEngine's + Contexts form a hierarchy. The root of this hierarchy is the QDeclarativeEngine's \l {QDeclarativeEngine::rootContext()}{root context}. A component instance can access the data in its own context, as well as all its ancestor contexts. Data can be made available to all instances by modifying the diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp index 39b0802..0715624 100644 --- a/src/declarative/qml/qdeclarativeengine.cpp +++ b/src/declarative/qml/qdeclarativeengine.cpp @@ -191,7 +191,7 @@ when the property has one of the following types: \o \c vector3d - use \l{Qt::vector3d()}{Qt.vector3d()} \endlist -There are also string based constructors for these types, see \l{qdeclarativebasictypes.html}{QML Basic Types}. +There are also string based constructors for these types. See \l{qdeclarativebasictypes.html}{QML Basic Types} for more information. \section1 Date/Time Formatters @@ -1054,8 +1054,9 @@ or \c null if there was an error in creating the component. Call \l {Component::createObject()}{Component.createObject()} on the returned component to create an object instance of the component. -Here is an example. Remember that QML files that might be loaded -over the network cannot be expected to be ready immediately. +Here is an example. Notice it checks whether the component \l{Component::status}{status} is +\c Component.Ready before calling \l {Component::createObject()}{createObject()} +in case the QML file is loaded over a network and thus is not ready immediately. \snippet doc/src/snippets/declarative/componentCreation.js 0 \codeline @@ -1095,12 +1096,12 @@ QScriptValue QDeclarativeEnginePrivate::createComponent(QScriptContext *ctxt, QS /*! \qmlmethod object Qt::createQmlObject(string qml, object parent, string filepath) -Returns a new object created from the given \a string of QML with the specified \a parent, +Returns a new object created from the given \a string of QML which will have the specified \a parent, or \c null if there was an error in creating the object. If \a filepath is specified, it will be used for error reporting for the created object. -Example (where \c targetItem is the id of an existing QML item): +Example (where \c parentItem is the id of an existing QML item): \snippet doc/src/snippets/declarative/createQmlObject.qml 0 diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp index 1447532..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 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/qdeclarativelistmodel.cpp b/src/declarative/util/qdeclarativelistmodel.cpp index 7518eb7..78a3207 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. @@ -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..9245fc2 100644 --- a/src/declarative/util/qdeclarativepackage.cpp +++ b/src/declarative/util/qdeclarativepackage.cpp @@ -48,9 +48,9 @@ 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. @@ -58,7 +58,7 @@ QT_BEGIN_NAMESPACE \e {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,7 @@ QT_BEGIN_NAMESPACE \snippet examples/declarative/modelviews/package/view.qml 0 - \sa QtDeclarative + \sa {declarative/modelviews/package}{Package example}, QtDeclarative */ 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 eca90a4..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. */ @@ -204,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. @@ -236,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/qdeclarativestategroup.cpp b/src/declarative/util/qdeclarativestategroup.cpp index 1e530a1..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 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/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/tests/auto/declarative/examples/tst_examples.cpp b/tests/auto/declarative/examples/tst_examples.cpp index da115a7..cff0b46 100644 --- a/tests/auto/declarative/examples/tst_examples.cpp +++ b/tests/auto/declarative/examples/tst_examples.cpp @@ -85,6 +85,7 @@ tst_examples::tst_examples() // Add directories you want excluded here + excludedDirs << "doc/src/snippets/declarative/visualdatamodel_rootindex"; #ifdef QT_NO_WEBKIT excludedDirs << "examples/declarative/modelviews/webview"; |
