From 2ae8e6f13f5bffd639a279c7e4aeb6b4d49810a1 Mon Sep 17 00:00:00 2001 From: Michael Brasser Date: Fri, 6 Nov 2009 15:08:33 +1000 Subject: Update animation docs. --- doc/src/declarative/animation.qdoc | 76 ++++++++++++++++++++++++++++------- src/declarative/util/qmlanimation.cpp | 18 ++++++--- 2 files changed, 75 insertions(+), 19 deletions(-) diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index ba45d81..1314493 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -81,6 +81,22 @@ Rectangle { \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, and explicitly +start the animation (usually via the \c running property). + +\qml +Rectangle { + id: rect + width: 200; height: 200; + Rectangle { + color: "red" + width: 50; height: 50 + x: NumberAnimation { to: 50; running: true } + } +} +\endqml + A property animation can also be specified as a resource that is manipulated from script. \qml @@ -100,12 +116,16 @@ Image { } \endqml +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. + Animations can be joined into a group using SequentialAnimation and ParallelAnimation. \target state-transitions \section1 Transitions -QML transitions describe animations to perform when \l{qmlstates}{state} changes occur. +QML transitions describe animations to perform when \l{qmlstates}{state} changes occur. A transition +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: @@ -123,11 +143,11 @@ transitions: [ As you can see from the above example, transitions make use of the same basic animation classes introduced above. However, you generally use a different set of properties when working with transitions. In the example, -no target or property has been specified. Instead, we have specified matchProperties, which acts as a selector to -determine which property changes to animate; in this case, we will animate any x,y properties that have -changed on any objects. +no \c target or \c property has been specified. Instead, we have specified \c matchProperties, +which (along with \c matchTargets) acts as a selector to determine which property changes to animate; +in this case, we will animate any x,y properties that have changed on any objects. -QML transitions also selectors to determine which state changes a transition should apply to: +QML transitions also have selectors to determine which state changes a transition should apply to: \code Transition { @@ -137,7 +157,9 @@ Transition { } \endcode -Transitions can happen in parallel, in sequence, or in any combination of the two: +Transitions can happen in parallel, in sequence, or in any combination of the two. By default, the top-level +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 { @@ -145,13 +167,8 @@ Transition { to: "MyState" reversible: true SequentialAnimation { - ColorAnimation { - property: "color" - duration: 1000 - } - PauseAnimation { - duration: 1000 - } + ColorAnimation { duration: 1000 } + PauseAnimation { duration: 1000 } ParallelAnimation { NumberAnimation { duration: 1000 @@ -169,9 +186,37 @@ Transition { } \endcode +To insert an explicit animation into your transition, you can use \target and \property as normal. + +\code +Transition { + from: "*" + to: "MyState" + reversible: true + SequentialAnimation { + NumberAnimation { + duration: 1000 + easing: "easeOutBounce" + // animate myItem's x and y if they have changed in the state + matchTargets: myItem + matchProperties: "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 + \section1 Property Behaviors -A property behavior specifies a default animation to run whenever the property's value changes. +A property behavior specifies a default animation to run whenever the property's value changes, regardless +of what caused the change. Unlike Transition, Behavior doesn't provide a way to indicate that a Behavior +should 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. @@ -185,6 +230,9 @@ Rectangle { } \endqml +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 diff --git a/src/declarative/util/qmlanimation.cpp b/src/declarative/util/qmlanimation.cpp index 7c5bc50..94cdadf 100644 --- a/src/declarative/util/qmlanimation.cpp +++ b/src/declarative/util/qmlanimation.cpp @@ -1507,6 +1507,8 @@ void QmlPropertyAnimationPrivate::convertVariant(QVariant &variant, int type) \code VariantAnimation { property: "size"; to: "20x20"; duration: 200 } \endcode + + \a qmlanimation.html */ QmlPropertyAnimation::QmlPropertyAnimation(QObject *parent) @@ -1795,16 +1797,20 @@ void QmlPropertyAnimation::setEasing(const QString &e) \qmlproperty Object PropertyAnimation::target This property holds an explicit target object to animate. - The exact effect of the \c target property depends on how the animation - is being used. Refer to the \l animation documentation for details. + target is used in conjunction with property to determine + what property should be animated. + + \sa property matchTargets */ /*! \qmlproperty string PropertyAnimation::property - This property holds an explicit property to animated. + This property holds an explicit property name to animate. - The exact effect of the \c property property depends on how the animation - is being used. Refer to the \l animation documentation for details. + property is used in conjunction with target to determine + what property should be animated. + + \sa target matchProperties */ /*! @@ -1833,6 +1839,8 @@ void QmlPropertyAnimation::setEasing(const QString &e) This property is typically used for an animation appearing as part of a Transition. By default, no property names will be matched. + + \sa matchTargets PropertyAction::matchTargets */ QString QmlPropertyAnimation::properties() const { -- cgit v0.12 From 3607c41b30bb93f62e1e85bc4f9ade145e1e8571 Mon Sep 17 00:00:00 2001 From: Michael Brasser Date: Fri, 6 Nov 2009 15:08:45 +1000 Subject: Doc. --- doc/src/declarative/elements.qdoc | 3 --- src/declarative/graphicsitems/qmlgraphicsgridview.cpp | 8 ++++---- src/declarative/graphicsitems/qmlgraphicsitem.cpp | 11 +++++++++++ src/declarative/graphicsitems/qmlgraphicsmouseregion.cpp | 6 +++--- 4 files changed, 18 insertions(+), 10 deletions(-) diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index 69535ce..81a6c96 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -187,11 +187,8 @@ The following table lists the QML elements provided by the Qt Declarative module \list \o \l Blur \o \l Colorize -\o \l Grayscale -\o \l Pixelize \o \l DropShadow \o \l Opacity -\o \l Bloom \o \l Particles \list \o \l ParticleMotionLinear diff --git a/src/declarative/graphicsitems/qmlgraphicsgridview.cpp b/src/declarative/graphicsitems/qmlgraphicsgridview.cpp index 7427266..f39f5c7 100644 --- a/src/declarative/graphicsitems/qmlgraphicsgridview.cpp +++ b/src/declarative/graphicsitems/qmlgraphicsgridview.cpp @@ -1154,7 +1154,7 @@ void QmlGraphicsGridView::keyPressEvent(QKeyEvent *event) } /*! - \qmlmethod GridView::moveCurrentIndexUp + \qmlmethod GridView::moveCurrentIndexUp() Move the currentIndex up one item in the view. The current index will wrap if keyNavigationWraps is true and it @@ -1177,7 +1177,7 @@ void QmlGraphicsGridView::moveCurrentIndexUp() } /*! - \qmlmethod GridView::moveCurrentIndexDown + \qmlmethod GridView::moveCurrentIndexDown() Move the currentIndex down one item in the view. The current index will wrap if keyNavigationWraps is true and it @@ -1200,7 +1200,7 @@ void QmlGraphicsGridView::moveCurrentIndexDown() } /*! - \qmlmethod GridView::moveCurrentIndexLeft + \qmlmethod GridView::moveCurrentIndexLeft() Move the currentIndex left one item in the view. The current index will wrap if keyNavigationWraps is true and it @@ -1223,7 +1223,7 @@ void QmlGraphicsGridView::moveCurrentIndexLeft() } /*! - \qmlmethod GridView::moveCurrentIndexRight + \qmlmethod GridView::moveCurrentIndexRight() Move the currentIndex right one item in the view. The current index will wrap if keyNavigationWraps is true and it diff --git a/src/declarative/graphicsitems/qmlgraphicsitem.cpp b/src/declarative/graphicsitems/qmlgraphicsitem.cpp index a46c2be..572aa98 100644 --- a/src/declarative/graphicsitems/qmlgraphicsitem.cpp +++ b/src/declarative/graphicsitems/qmlgraphicsitem.cpp @@ -1908,6 +1908,17 @@ void QmlGraphicsItem::setClip(bool c) */ /*! + \qmlproperty bool Item::visible + + Whether the item is visible. By default this is true. + + \note visible is not linked to actual visibility; if you item + goes off screen, or the opacity changes to 0, etc this will + not affect the visible property. +*/ + + +/*! This function is called to handle this item's changes in geometry from \a oldGeometry to \a newGeometry. If the two geometries are the same, it doesn't do anything. diff --git a/src/declarative/graphicsitems/qmlgraphicsmouseregion.cpp b/src/declarative/graphicsitems/qmlgraphicsmouseregion.cpp index 196cdf2..22c2c0a 100644 --- a/src/declarative/graphicsitems/qmlgraphicsmouseregion.cpp +++ b/src/declarative/graphicsitems/qmlgraphicsmouseregion.cpp @@ -146,19 +146,19 @@ void QmlGraphicsDrag::setYmax(qreal m) */ /*! - \qmlsignal MouseRegion::onEntered + \qmlsignal MouseRegion::onEntered() This handler is called when the mouse enters the mouse region. */ /*! - \qmlsignal MouseRegion::onExited + \qmlsignal MouseRegion::onExited() This handler is called when the mouse exists the mouse region. */ /*! - \qmlsignal MouseRegion::onPositionChanged(mouse) + \qmlsignal MouseRegion::onPositionChanged(MouseEvent mouse) This handler is called when the mouse position changes. -- cgit v0.12