diff options
17 files changed, 805 insertions, 122 deletions
diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index b44e6f2..e02575d 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -208,7 +208,10 @@ Models can be defined in C++ and then made available to QML. This is useful for exposing existing C++ data models or otherwise complex datasets to QML. A C++ model class can be defined as a QStringList, a QList<QObject*> or a -QAbstractItemModel. +QAbstractItemModel. The first two are useful for exposing simpler datasets, +while QAbstractItemModel provides a more flexible solution for more complex +models. + \section2 QStringList @@ -268,7 +271,10 @@ the model by calling QDeclarativeContext::setContextProperty() again. \section2 QAbstractItemModel -A model can be defined by subclassing QAbstractItemModel. +A model can be defined by subclassing QAbstractItemModel. This is the +best approach if you have a more complex model that cannot be supported +by the other approaches. A QAbstractItemModel can also automatically +notify a QML view when the model data has changed. The roles of a QAbstractItemModel subclass can be exposed to QML by calling QAbstractItemModel::setRoleNames(). The default role names set by Qt are: @@ -305,6 +311,12 @@ roles: \snippet examples/declarative/modelviews/abstractitemmodel/view.qml 0 +QML views are automatically updated when the model changes. Remember the model +must follow the standard rules for model changes and notify the view when +the model has changed by using QAbstractItemModel::dataChanged(), +QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for +more information. + The complete example is available in Qt's \l {declarative/modelviews/abstractitemmodel}{examples/declarative/modelviews/abstractitemmodel} directory. QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML diff --git a/doc/src/snippets/declarative/coloranimation.qml b/doc/src/snippets/declarative/coloranimation.qml new file mode 100644 index 0000000..4e35f22 --- /dev/null +++ b/doc/src/snippets/declarative/coloranimation.qml @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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: 100; height: 100 + color: "red" + + ColorAnimation on color { to: "yellow"; duration: 1000 } +} +//![0] + diff --git a/doc/src/snippets/declarative/numberanimation.qml b/doc/src/snippets/declarative/numberanimation.qml new file mode 100644 index 0000000..57d23b1 --- /dev/null +++ b/doc/src/snippets/declarative/numberanimation.qml @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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: 100; height: 100 + color: "red" + + NumberAnimation on x { to: 50; duration: 1000 } +} +//![0] + diff --git a/doc/src/snippets/declarative/propertyanimation.qml b/doc/src/snippets/declarative/propertyanimation.qml new file mode 100644 index 0000000..059cde5 --- /dev/null +++ b/doc/src/snippets/declarative/propertyanimation.qml @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** 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 { + +//![transition] +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + states: State { + name: "moved" + PropertyChanges { target: rect; x: 50 } + } + + transitions: Transition { + PropertyAnimation { properties: "x,y"; easing.type: Easing.InOutQuad } + } +} +//![transition] + +//![behavior] +Rectangle { + width: 100; height: 100 + color: "red" + + Behavior on x { PropertyAnimation {} } + + MouseArea { anchors.fill: parent; onClicked: parent.x = 50 } +} +//![behavior] + +//![propertyvaluesource] +Rectangle { + width: 100; height: 100 + color: "red" + + SequentialAnimation on x { + loops: Animation.Infinite + PropertyAnimation { to: 50 } + PropertyAnimation { to: 0 } + } +} +//![propertyvaluesource] + +//![standalone] +Rectangle { + id: theRect + width: 100; height: 100 + color: "red" + + // this is a standalone animation, it's not running by default + PropertyAnimation { id: animation; target: theRect; property: "width"; to: 30; duration: 500 } + + MouseArea { anchors.fill: parent; onClicked: animation.running = true } +} +//![standalone] + + +} diff --git a/doc/src/snippets/declarative/smoothedanimation.qml b/doc/src/snippets/declarative/smoothedanimation.qml new file mode 100644 index 0000000..20c90b5 --- /dev/null +++ b/doc/src/snippets/declarative/smoothedanimation.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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//![0] +import Qt 4.7 + +Rectangle { + width: 800; height: 600 + color: "blue" + + Rectangle { + width: 60; height: 60 + x: rect1.x - 5; y: rect1.y - 5 + color: "green" + + Behavior on x { SmoothedAnimation { velocity: 200 } } + Behavior on y { SmoothedAnimation { velocity: 200 } } + } + + Rectangle { + id: rect1 + width: 50; height: 50 + color: "red" + } + + focus: true + Keys.onRightPressed: rect1.x = rect1.x + 100 + Keys.onLeftPressed: rect1.x = rect1.x - 100 + Keys.onUpPressed: rect1.y = rect1.y - 100 + Keys.onDownPressed: rect1.y = rect1.y + 100 +} +//![0] diff --git a/doc/src/snippets/declarative/springanimation.qml b/doc/src/snippets/declarative/springanimation.qml new file mode 100644 index 0000000..b73a9d2 --- /dev/null +++ b/doc/src/snippets/declarative/springanimation.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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//![0] +import Qt 4.7 + +Rectangle { + width: 300; height: 300 + + Rectangle { + id: rect + width: 50; height: 50 + color: "red" + + Behavior on x { SpringAnimation { spring: 2; damping: 0.2 } } + Behavior on y { SpringAnimation { spring: 2; damping: 0.2 } } + } + + MouseArea { + anchors.fill: parent + onClicked: { + rect.x = mouse.x + rect.y = mouse.y + } + } +} +//![0] + diff --git a/doc/src/snippets/declarative/state.qml b/doc/src/snippets/declarative/state.qml index a99c2e2..af6b103 100644 --- a/doc/src/snippets/declarative/state.qml +++ b/doc/src/snippets/declarative/state.qml @@ -44,26 +44,13 @@ import Qt 4.7 Rectangle { id: myRect width: 100; height: 100 - color: "black" + color: "red" - states: [ - State { - name: "clicked" - PropertyChanges { - target: myRect - color: "red" - } - } - ] + MouseArea { id: mouseArea; anchors.fill: parent } - MouseArea { - anchors.fill: parent - onClicked: { - if (myRect.state == "") // i.e. the default state - myRect.state = "clicked"; - else - myRect.state = ""; - } + states: State { + name: "hidden"; when: mouseArea.pressed + PropertyChanges { target: myRect; opacity: 0 } } } //![0] diff --git a/doc/src/snippets/declarative/transition-from-to.qml b/doc/src/snippets/declarative/transition-from-to.qml new file mode 100644 index 0000000..615de17 --- /dev/null +++ b/doc/src/snippets/declarative/transition-from-to.qml @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** 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 + +//![0] +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + MouseArea { id: mouseArea; anchors.fill: parent } + + states: State { + name: "brighter"; when: mouseArea.pressed + PropertyChanges { target: rect; color: "yellow" } + } + + transitions: Transition { + ColorAnimation { duration: 1000 } + } +} +//![0] + + diff --git a/doc/src/snippets/declarative/transition-reversible.qml b/doc/src/snippets/declarative/transition-reversible.qml new file mode 100644 index 0000000..8a7b69a --- /dev/null +++ b/doc/src/snippets/declarative/transition-reversible.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$ +** +****************************************************************************/ +import Qt 4.7 + +//![0] +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + MouseArea { id: mouseArea; anchors.fill: parent } + + states: State { + name: "brighter" + when: mouseArea.pressed + PropertyChanges { target: rect; color: "yellow"; x: 50 } + } + + transitions: Transition { + SequentialAnimation { + PropertyAnimation { property: "x"; duration: 1000 } + ColorAnimation { duration: 1000 } + } + } +} +//![0] + diff --git a/doc/src/snippets/declarative/transition.qml b/doc/src/snippets/declarative/transition.qml new file mode 100644 index 0000000..b884750 --- /dev/null +++ b/doc/src/snippets/declarative/transition.qml @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** 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: rect + width: 100; height: 100 + color: "red" + + states: State { + name: "moved" + PropertyChanges { target: rect; x: 50; y: 50 } + } + + transitions: Transition { + PropertyAnimation { properties: "x,y"; easing.type: Easing.InOutQuad } + } +} +//![0] + diff --git a/examples/declarative/modelviews/abstractitemmodel/model.cpp b/examples/declarative/modelviews/abstractitemmodel/model.cpp index d0e0971..940a44d 100644 --- a/examples/declarative/modelviews/abstractitemmodel/model.cpp +++ b/examples/declarative/modelviews/abstractitemmodel/model.cpp @@ -67,7 +67,9 @@ AnimalModel::AnimalModel(QObject *parent) void AnimalModel::addAnimal(const Animal &animal) { + beginInsertRows(QModelIndex(), rowCount(), rowCount()); m_animals << animal; + endInsertRows(); } int AnimalModel::rowCount(const QModelIndex & parent) const { diff --git a/src/declarative/graphicsitems/qdeclarativeborderimage.cpp b/src/declarative/graphicsitems/qdeclarativeborderimage.cpp index 44c206b..4881248 100644 --- a/src/declarative/graphicsitems/qdeclarativeborderimage.cpp +++ b/src/declarative/graphicsitems/qdeclarativeborderimage.cpp @@ -149,6 +149,8 @@ QDeclarativeBorderImage::~QDeclarativeBorderImage() \endqml The URL may be absolute, or relative to the URL of the component. + + \sa QDeclarativeImageProvider */ void QDeclarativeBorderImage::setSource(const QUrl &url) { diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp index 5005746..88ec5ba 100644 --- a/src/declarative/util/qdeclarativeanimation.cpp +++ b/src/declarative/util/qdeclarativeanimation.cpp @@ -634,13 +634,23 @@ QAbstractAnimation *QDeclarativePauseAnimation::qtAnimation() \inherits PropertyAnimation \brief The ColorAnimation element allows you to animate color changes. - \code - ColorAnimation { from: "white"; to: "#c0c0c0"; duration: 100 } - \endcode + ColorAnimation defines an animation to be applied when a color value + changes. + + Here is a ColorAnimation applied to the \c color property of a \l Rectangle + as a property value source: + + \snippet doc/src/snippets/declarative/coloranimation.qml 0 + + Like any other animation element, a NumberAnimation can be applied in a + number of ways, including transitions, behaviors and property value + sources. The \l PropertyAnimation documentation shows a variety of methods + for creating animations. When used in a transition, ColorAnimation will by default animate - all properties of type color that are changing. If a property or properties - are explicitly set for the animation, then those will be used instead. + all properties of type color that have changed. If a \l{PropertyAnimation::}{property} + or \l{PropertyAnimation::}{properties} are explicitly set for the animation, + then those are used instead. \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} */ @@ -665,6 +675,17 @@ QDeclarativeColorAnimation::~QDeclarativeColorAnimation() /*! \qmlproperty color ColorAnimation::from This property holds the starting color. + + For example, the following animation is not applied until a color value + has reached "#c0c0c0": + + Item { + states: [ ... ] + + transition: Transition { + NumberAnimation { from: "#c0c0c0"; duration: 2000 } + } + } */ QColor QDeclarativeColorAnimation::from() const { @@ -1098,11 +1119,22 @@ void QDeclarativePropertyAction::transition(QDeclarativeStateActions &actions, \inherits PropertyAnimation \brief The NumberAnimation element allows you to animate changes in properties of type qreal. - For example, to animate a set of properties over 200ms, from their values in the start state to - their values in the end state of the transition: - \code - NumberAnimation { properties: "x,y,scale"; duration: 200 } - \endcode + NumberAnimation defines an animation to be applied when a numerical value + changes. + + Here is a NumberAnimation applied to the \c x property of a \l Rectangle + as a property value source: + + \snippet doc/src/snippets/declarative/numberanimation.qml 0 + + Like any other animation element, a NumberAnimation can be applied in a + number of ways, including transitions, behaviors and property value + sources. The \l PropertyAnimation documentation shows a variety of methods + for creating animations. + + Note that NumberAnimation may not animate smoothly if there are irregular + changes in the number value that it is tracking. If this is the case, use + SmoothedAnimation instead. \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} */ @@ -1137,9 +1169,23 @@ void QDeclarativeNumberAnimation::init() /*! \qmlproperty real NumberAnimation::from - This property holds the starting value. - If not set, then the value defined in the start state of the transition. + This property holds the starting number value. + + For example, the following animation is not applied until the \c x value + has reached 100: + + Item { + states: [ ... ] + + transition: Transition { + NumberAnimation { properties: "x"; from: 100; duration: 200 } + } + } + + If this value is not set, it defaults to the value defined in the start + state of the \l Transition. */ + qreal QDeclarativeNumberAnimation::from() const { Q_D(const QDeclarativePropertyAnimation); @@ -1153,8 +1199,10 @@ void QDeclarativeNumberAnimation::setFrom(qreal f) /*! \qmlproperty real NumberAnimation::to - This property holds the ending value. - If not set, then the value defined in the end state of the transition or Behavior. + This property holds the ending number value. + + If this value is not set, it defaults to the value defined in the end + state of the \l Transition or \l Behavior. */ qreal QDeclarativeNumberAnimation::to() const { @@ -1199,7 +1247,9 @@ QDeclarativeVector3dAnimation::~QDeclarativeVector3dAnimation() /*! \qmlproperty real Vector3dAnimation::from This property holds the starting value. - If not set, then the value defined in the start state of the transition. + + If this value is not set, it defaults to the value defined in the start + state of the \l Transition. */ QVector3D QDeclarativeVector3dAnimation::from() const { @@ -1215,7 +1265,9 @@ void QDeclarativeVector3dAnimation::setFrom(QVector3D f) /*! \qmlproperty real Vector3dAnimation::to This property holds the ending value. - If not set, then the value defined in the end state of the transition or Behavior. + + If this value is not set, it defaults to the value defined in the end + state of the \l Transition or \l Behavior. */ QVector3D QDeclarativeVector3dAnimation::to() const { @@ -1320,8 +1372,21 @@ QDeclarativeRotationAnimation::~QDeclarativeRotationAnimation() /*! \qmlproperty real RotationAnimation::from - This property holds the starting value. - If not set, then the value defined in the start state of the transition. + This property holds the starting number value. + + For example, the following animation is not applied until the \c angle value + has reached 100: + + Item { + states: [ ... ] + + transition: Transition { + RotationAnimation { properties: "angle"; from: 100; duration: 2000 } + } + } + + If this value is not set, it defaults to the value defined in the start + state of the \l Transition. */ qreal QDeclarativeRotationAnimation::from() const { @@ -1337,7 +1402,9 @@ void QDeclarativeRotationAnimation::setFrom(qreal f) /*! \qmlproperty real RotationAnimation::to This property holds the ending value. - If not set, then the value defined in the end state of the transition or Behavior. + + If this value is not set, it defaults to the value defined in the end + state of the \l Transition or \l Behavior. */ qreal QDeclarativeRotationAnimation::to() const { @@ -1620,51 +1687,49 @@ void QDeclarativePropertyAnimationPrivate::convertVariant(QVariant &variant, int \inherits Animation \brief The PropertyAnimation element allows you to animate property changes. - PropertyAnimation provides a way to animate changes to a property's value. It can - be used in many different situations: + PropertyAnimation provides a way to animate changes to a property's value. + + It can be used to define animations in a number of ways: + \list - \o In a Transition + \o In a \l Transition + + For example, to animate any objects that have changed their \c x or \c y properties + as a result of a state change, using an \c InOutQuad easing curve: + + \snippet doc/src/snippets/declarative/propertyanimation.qml transition + + + \o In a \l Behavior + + For example, to animate all changes to a rectangle's \c x property: + + \snippet doc/src/snippets/declarative/propertyanimation.qml behavior - Animate any objects that have changed their x or y properties in the target state using - an InOutQuad easing curve: - \qml - Transition { PropertyAnimation { properties: "x,y"; easing.type: Easing.InOutQuad } } - \endqml - \o In a Behavior - Animate all changes to a rectangle's x property. - \qml - Rectangle { - Behavior on x { PropertyAnimation {} } - } - \endqml \o As a property value source - Repeatedly animate the rectangle's x property. - \qml - Rectangle { - SequentialAnimation on x { - loops: Animation.Infinite - PropertyAnimation { to: 50 } - PropertyAnimation { to: 0 } - } - } - \endqml + For example, to repeatedly animate the rectangle's \c x property: + + \snippet doc/src/snippets/declarative/propertyanimation.qml propertyvaluesource + + \o In a signal handler - Fade out \c theObject when clicked: + For example, to fade out \c theObject when clicked: \qml MouseArea { anchors.fill: theObject onClicked: PropertyAnimation { target: theObject; property: "opacity"; to: 0 } } \endqml + \o Standalone - Animate \c theObject's size property over 200ms, from its current size to 20-by-20: - \qml - PropertyAnimation { target: theObject; property: "size"; to: "20x20"; duration: 200 } - \endqml + For example, to animate \c rect's \c width property over 500ms, from its current width to 30: + + \snippet doc/src/snippets/declarative/propertyanimation.qml standalone + \endlist Depending on how the animation is used, the set of properties normally used will be diff --git a/src/declarative/util/qdeclarativesmoothedanimation.cpp b/src/declarative/util/qdeclarativesmoothedanimation.cpp index 5d47c30..e0d1097 100644 --- a/src/declarative/util/qdeclarativesmoothedanimation.cpp +++ b/src/declarative/util/qdeclarativesmoothedanimation.cpp @@ -272,33 +272,8 @@ void QSmoothedAnimation::init() with both a velocity of 200 and a duration of 8000 set. The follow example shows one rectangle tracking the position of another. -\code -import Qt 4.7 - -Rectangle { - width: 800; height: 600; color: "blue" - - Rectangle { - color: "green" - width: 60; height: 60; - x: rect1.x - 5; y: rect1.y - 5; - Behavior on x { SmoothedAnimation { velocity: 200 } } - Behavior on y { SmoothedAnimation { velocity: 200 } } - } - - Rectangle { - id: rect1 - color: "red" - width: 50; height: 50; - } - focus: true - Keys.onRightPressed: rect1.x = rect1.x + 100 - Keys.onLeftPressed: rect1.x = rect1.x - 100 - Keys.onUpPressed: rect1.y = rect1.y - 100 - Keys.onDownPressed: rect1.y = rect1.y + 100 -} -\endcode + \snippet doc/src/snippets/declarative/smoothedanimation.qml 0 The default velocity of SmoothedAnimation is 200 units/second. Note that if the range of the value being animated is small, then the velocity will need to be adjusted @@ -307,6 +282,11 @@ Rectangle { set to a value such as 0.5 units/second. Animating from 0 to 1.0 with a velocity of 0.5 will take 2000 ms to complete. + Like any other animation element, a SmoothedAnimation can be applied in a + number of ways, including transitions, behaviors and property value + sources. The \l PropertyAnimation documentation shows a variety of methods + for creating animations. + \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} */ @@ -388,11 +368,13 @@ void QDeclarativeSmoothedAnimation::transition(QDeclarativeStateActions &actions Sets how the SmoothedAnimation behaves if an animation direction is reversed. - If reversing mode is \c SmoothedAnimation.Eased, the animation will smoothly decelerate, and - then reverse direction. If the reversing mode is \c SmoothedAnimation.Immediate, the - animation will immediately begin accelerating in the reverse direction, - begining with a velocity of 0. If the reversing mode is \c SmoothedAnimation.Sync, the - property is immediately set to the target value. + Possible values are: + + \list + \o SmoothedAnimation.Eased (default) - the animation will smoothly decelerate, and then reverse direction + \o SmoothedAnimation.Immediate - the animation will immediately begin accelerating in the reverse direction, begining with a velocity of 0 + \o SmoothedAnimation.Sync - the property is immediately set to the target value + \endlist */ QDeclarativeSmoothedAnimation::ReversingMode QDeclarativeSmoothedAnimation::reversingMode() const { diff --git a/src/declarative/util/qdeclarativespringanimation.cpp b/src/declarative/util/qdeclarativespringanimation.cpp index 4cf2fc0..be0af6d 100644 --- a/src/declarative/util/qdeclarativespringanimation.cpp +++ b/src/declarative/util/qdeclarativespringanimation.cpp @@ -207,14 +207,24 @@ void QDeclarativeSpringAnimationPrivate::updateMode() \qmlclass SpringAnimation QDeclarativeSpringAnimation \since 4.7 - \brief The SpringAnimation element allows a property to track a value in a spring-like motion + \brief The SpringAnimation element allows a property to track a value in a spring-like motion. SpringAnimation mimics the oscillatory behavior of a spring, with the appropriate \l spring constant to control the acceleration and the \l damping to control how quickly the effect dies away. You can also limit the maximum \l velocity of the animation. + The following \l Rectangle moves to the position of the mouse using a + SpringAnimation when the mouse is clicked: + \snippet doc/src/snippets/declarative/springanimation.qml 0 + + Like any other animation element, a SpringAnimation can be applied in a + number of ways, including transitions, behaviors and property value + sources. The \l PropertyAnimation documentation shows a variety of methods + for creating animations. + + \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}, {declarative/toys/clocks}{Clocks example} */ QDeclarativeSpringAnimation::QDeclarativeSpringAnimation(QObject *parent) @@ -244,6 +254,11 @@ qreal QDeclarativeSpringAnimation::to() const /*! \qmlproperty real SpringAnimation::to + + This property holds the value at which the animation will end. + + If not set, the animation will continue until it reaches the + value that is being tracked. */ void QDeclarativeSpringAnimation::setTo(qreal value) @@ -266,6 +281,11 @@ qreal QDeclarativeSpringAnimation::from() const /*! \qmlproperty real SpringAnimation::from + + This property holds the value from which the animation will begin. + + If not set, the animation will start regardless of the + value being tracked. */ void QDeclarativeSpringAnimation::setFrom(qreal value) @@ -325,10 +345,12 @@ void QDeclarativeSpringAnimation::setSpring(qreal spring) /*! \qmlproperty real SpringAnimation::damping - This property holds the spring damping constant + This property holds the spring damping value. + + This value describes how quickly a sprung follower comes to rest. - The damping constant describes how quickly a sprung follower comes to rest. - Useful range is 0 - 1.0 + The useful range is 0 - 1.0. The lower the value, the faster the + follower comes to rest. */ qreal QDeclarativeSpringAnimation::damping() const { @@ -348,7 +370,7 @@ void QDeclarativeSpringAnimation::setDamping(qreal damping) /*! \qmlproperty real SpringAnimation::epsilon - This property holds the spring epsilon + This property holds the spring epsilon. The epsilon is the rate and amount of change in the value which is close enough to 0 to be considered equal to zero. This will depend on the usage of the value. diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp index ae19a9c..9f4cc39 100644 --- a/src/declarative/util/qdeclarativestate.cpp +++ b/src/declarative/util/qdeclarativestate.cpp @@ -144,7 +144,7 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje 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 + The following example displays a single \l 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 @@ -157,7 +157,7 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje 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 + \note Setting the state of an object from within another state of the same object is not allowed. \sa {declarative/animation/states}{states example}, {qmlstates}{States}, {state-transitions}{Transitions}, QtDeclarative @@ -194,7 +194,7 @@ QDeclarativeState::~QDeclarativeState() \qmlproperty string State::name This property holds the name of the state. - Each state should have a unique name. + Each state should have a unique name within its item. */ QString QDeclarativeState::name() const { @@ -226,7 +226,23 @@ bool QDeclarativeState::isWhenKnown() const This property holds when the state should be applied. This should be set to an expression that evaluates to \c true when you want the state to - be applied. + be applied. For example, the following \l Rectangle changes in and out of the "hidden" + state when the \l MouseArea is pressed: + + \qml + Rectangle { + id: myRect + width: 100; height: 100 + color: "red" + + MouseArea { id: mouseArea; anchors.fill: parent } + + states: State { + name: "hidden"; when: mouseArea.pressed + PropertyChanges { target: myRect; opacity: 0 } + } + } + \endqml 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 diff --git a/src/declarative/util/qdeclarativetransition.cpp b/src/declarative/util/qdeclarativetransition.cpp index 38ed97e..34e1e2b 100644 --- a/src/declarative/util/qdeclarativetransition.cpp +++ b/src/declarative/util/qdeclarativetransition.cpp @@ -56,6 +56,30 @@ QT_BEGIN_NAMESPACE \since 4.7 \brief The Transition element defines animated transitions that occur on state changes. + A Transition defines the animations to be applied when a \l State change occurs. + + For example, the following \l Rectangle has two states: the default state, and + an added "moved" state. In the "moved state, the rectangle's position changes + to (50, 50). The added \l Transition specifies that when the rectangle + changes between the default and the "moved" state, any changes + to the \c x and \c y properties should be animated, using an \c Easing.InOutQuad. + + \snippet doc/src/snippets/declarative/transition.qml 0 + + Items can have multiple transitions, if + + To specify multiple transitions, specify \l Item::transitions as a list: + + \qml + Item { + ... + transitions: [ + Transition { ... } + Transition { ... } + ] + } + |endqml + \sa {declarative/animation/states}{states example}, {qmlstates}{States}, {state-transitions}{Transitions}, {QtDeclarative} */ @@ -171,18 +195,31 @@ void QDeclarativeTransition::prepare(QDeclarativeStateOperation::ActionList &act /*! \qmlproperty string Transition::from \qmlproperty string Transition::to - These properties are selectors indicating which state changes should trigger the transition. - from is used in conjunction with to to determine when a transition should - be applied. By default from and to are both "*" (any state). In the following example, - the transition is applied when changing from state1 to state2. - \code - Transition { - from: "state1" - to: "state2" - ... + These properties indicate the state changes that trigger the transition. + + The default values for these properties is "*" (that is, any state). + + For example, the following transition has not set the \c to and \c from + properties, so the animation is always applied when changing between + the two states (i.e. when the mouse is pressed and released). + + \snippet doc/src/snippets/declarative/transition-from-to.qml 0 + + If the transition was changed to this: + + \qml + transitions: Transition { + to: "brighter" + ColorAnimation { duration: 1000 } + } } - \endcode + \endqml + + The animation would only be applied when changing from the default state to + the "brighter" state (i.e. when the mouse is pressed, but not on release). + + \sa reversible */ QString QDeclarativeTransition::fromState() const { @@ -205,6 +242,24 @@ void QDeclarativeTransition::setFromState(const QString &f) This property holds whether the transition should be automatically reversed when the conditions that triggered this transition are reversed. The default value is false. + + By default, transitions run in parallel and are applied to all state + changes if the \l from and \l to states have not been set. In this + situation, the transition is automatically applied when a state change + is reversed, and it is not necessary to set this property to reverse + the transition. + + However, if a SequentialAnimation is used, or if the \l from or \l to + properties have been set, this property will need to be set to reverse + a transition when a state change is reverted. For example, the following + transition applies a sequential animation when the mouse is pressed, + and reverses the sequence of the animation when the mouse is released: + + \snippet doc/src/snippets/declarative/transition-reversible.qml 0 + + If the transition did not set the \c to and \c reversible values, then + on the mouse release, the transition would play the PropertyAnimation + before the ColorAnimation instead of reversing the sequence. */ bool QDeclarativeTransition::reversible() const { @@ -241,12 +296,27 @@ void QDeclarativeTransition::setToState(const QString &t) /*! \qmlproperty list<Animation> Transition::animations \default + This property holds a list of the animations to be run for this transition. + \qml + Transition { + PropertyAnimation { ... } + NumberAnimation { ... } + } + \endqml + The top-level animations are run in parallel. To run them sequentially, - you can create a single SequentialAnimation which contains all the animations, - and assign that to animations the animations property. - \default + define them within a SequentialAnimation: + + \qml + Transition { + SequentialAnimation { + PropertyAnimation { ... } + NumberAnimation { ... } + } + } + \endqml */ QDeclarativeListProperty<QDeclarativeAbstractAnimation> QDeclarativeTransition::animations() { |