From 31df163917b804a6f36fe053e69a15047256daf6 Mon Sep 17 00:00:00 2001 From: Michael Brasser Date: Thu, 22 Oct 2009 15:49:24 +1000 Subject: Start updating state and animation docs. --- demos/declarative/samegame/content/BoomBlock.qml | 2 +- doc/src/declarative/animation.qdoc | 157 ++++++++++++----------- doc/src/declarative/qmlreference.qdoc | 10 +- doc/src/declarative/qmlstates.qdoc | 59 +++++++++ doc/src/declarative/qtdeclarative.qdoc | 1 + examples/declarative/behaviours/SideRect.qml | 17 +++ examples/declarative/behaviours/behavior.qml | 72 +++++++++++ examples/declarative/behaviours/test.qml | 38 +++--- 8 files changed, 262 insertions(+), 94 deletions(-) create mode 100644 doc/src/declarative/qmlstates.qdoc create mode 100644 examples/declarative/behaviours/SideRect.qml create mode 100644 examples/declarative/behaviours/behavior.qml diff --git a/demos/declarative/samegame/content/BoomBlock.qml b/demos/declarative/samegame/content/BoomBlock.qml index a495cd0..34f6f56 100644 --- a/demos/declarative/samegame/content/BoomBlock.qml +++ b/demos/declarative/samegame/content/BoomBlock.qml @@ -21,7 +21,7 @@ Item { id:block } } opacity: 0 - opacity: Behavior { NumberAnimation { properties:"opacity"; duration: 200 } } + opacity: Behavior { NumberAnimation { duration: 200 } } anchors.fill: parent } diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index caf78d3..2d98322 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -44,35 +44,26 @@ \target qmlanimation \title QML Animation -QML supports three different forms of animation - basic property animation, -states and transitions and property behaviors. +Animation in QML is done by animating properties of objects. Properties of type +real, int, color, rect, point, and size can all be animated. -\section1 Property Animation +QML supports three different forms of animation - basic property animation, +transitions, and property behaviors. -Animation in QML is done by animating properties of objects. +\section1 Basic Property Animation -Any property of a recognizable type can be animated. Currently those types include: -\list -\o qreal -\o int -\o Most of QVariant's built-in types -\endlist +The simplest form of animation is directly using \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. -Animations can also involve numerous properties on numerous objects. - -Other Features: -\list -\o Support for a large set of parameterized easing curves. (based on the Penner easing equations) -\o Animation synchronization -\endlist - -The simplest form of animation is using \l NumberAnimation +A property animation can be specified as a value source. This is especially useful for repeating animations. The following example creates a bouncing effect: -\code +\qml Rectangle { id: rect - width: 120; height: 200; color: "white" + width: 120; height: 200; Image { id: img source: "qt-logo.png" @@ -87,64 +78,37 @@ Rectangle { } } } -\endcode +\endqml \image propanim.gif -\target states-transitions -\section1 States and Transitions - -\section2 States - -QML states describe user interface configurations, including: -\list -\o What UI elements are present -\o The properties of those elements (including how they behave) -\o What actions are available -\endlist - -A state can also be thought of as a set of batched changes from a default configuration. - -Examples of states in modern UI: -\list -\o A Contacts application has a 'View Contact' state and an 'Edit Contact' State. In the first state the information presented is static (using labels), and in the second it is editable (using editors). -\o A button has a pressed and unpressed state. When pressed the text moves down and to the right, and the button has a slightly darker appearance. -\endlist - -In QML: -\list -\o Any object can use states. -\o There is a default state. The default state can be explicitly set. -\o A state can affect other the properties of other objects, not just the object owning the state (and not just that object's children). -\endlist - -The following example shows a simple use of states. In the default state \c myrect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. +A property animation can also be specified as a resource that is manipulated from script. -\code -Item { - Rectangle { - id: myrect - width: 100 - height: 100 +\qml +PropertyAnimation { + id: animation + target: image + property: "scale" + from: 1; to: .5 +} +Image { + id: image + source: "image.png" + MouseRegion { + anchors.fill: parent + onPressed: animation.start() } - states: [ - State { - name: "moved" - PropertyChanges { - target: myrect - x: 50 - y: 50 - } - } - ] } -\endcode +\endqml + +Animations can be joined into a group using SequentialAnimation and ParallelAnimation. -\section2 Transitions +\target state-transitions +\section1 Transitions -QML transitions describe animations to perform when state changes occur. +QML transitions describe animations to perform when \l{qmlstates}{state} changes occur. -For the previous example, a transition could describe how \c myrect moved from its initial position to its new position: +For example, a transition could describe how an item moves from its initial position to its new position: \code transitions: [ @@ -158,7 +122,13 @@ transitions: [ ] \endcode -QML transitions can use selectors to determine which state changes a transition should apply to: +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 properties, 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. + +QML transitions also selectors to determine which state changes a transition should apply to: \code Transition { @@ -202,5 +172,48 @@ Transition { \section1 Property Behaviors -\note Property behaviors are currently experimental. +A property behavior specifies a default animation to run whenever the property's value changes. + +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. + +\qml +Rectangle { + id: redRect + color: "red" + width: 100; height: 100 + x: Behavior { NumberAnimation { duration: 300; easing: "InOutQuad" } } +} +\endqml + +To trigger this behavior, we could: +\list +\o Enter a state that changes x + +\qml +State { + name: "myState" + PropertyChanges { + target: redRect + x: 200 + ... + } +} +\endqml + +\o Update x from a script + +\qml +MouseRegion { + .... + onClicked: redRect.x = 24; +} +\endqml +\endlist + +If 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. + */ diff --git a/doc/src/declarative/qmlreference.qdoc b/doc/src/declarative/qmlreference.qdoc index 1498189..76269c3 100644 --- a/doc/src/declarative/qmlreference.qdoc +++ b/doc/src/declarative/qmlreference.qdoc @@ -65,13 +65,17 @@ \o \l {qmlexamples}{Examples} \endlist - Core QML Features: + \section1 Core QML Features: \list - \o \l {binding}{Data Binding} + \o \l {QML Documents} + \o \l {Property Binding} + \o \l {ECMAScript Blocks} + \o \l {Network Transparency} \o \l {qmlmodels}{Data Models} \o \l {anchor-layout}{Anchor-based Layout} + \o \l {qmlstates}{States} \o \l {qmlanimation}{Animation} - \o \l {qmlmodules}{Modules} + \o \l {qmlmodules.html}{Modules} \o \l {qmlfocus}{Keyboard Focus} \o \l {Extending types from QML} \endlist diff --git a/doc/src/declarative/qmlstates.qdoc b/doc/src/declarative/qmlstates.qdoc new file mode 100644 index 0000000..955f7de --- /dev/null +++ b/doc/src/declarative/qmlstates.qdoc @@ -0,0 +1,59 @@ +/*! +\page qmlstates.html +\target qmlstates +\title QML States + +QML states describe user interface configurations, including: +\list +\o What UI elements are present +\o The properties of those elements (including how they behave) +\o What actions are available +\endlist + +A state can also be thought of as a set of batched changes from a default configuration. + +Examples of states in modern UI: +\list +\o A Contacts application has a 'View Contact' state and an 'Edit Contact' State. In the first state the information presented is static (using labels), and in the second it is editable (using editors). +\o A button has a pressed and unpressed state. When pressed the text moves down and to the right, and the button has a slightly darker appearance. +\endlist + +In QML: +\list +\o Any object can use states. +\o There is a default state. The default state can be explicitly set. +\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 + +The following example shows a simple use of states. In the default state \c myrect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. + +\code +Item { + Rectangle { + id: myrect + width: 100 + height: 100 + } + states: [ + State { + name: "moved" + PropertyChanges { + target: myrect + x: 50 + y: 50 + } + } + ] +} +\endcode + +To animate state changes, you can use \l{state-transitions}{transitions}. + +Other things you can do in a state change: +\list +\o override signal handlers +\o change an item's parent +\o change an item's anchors +\o run some script + +*/ diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index e01b02d..7be98db 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -87,6 +87,7 @@ completely new applications. QML is fully \l {Extending QML}{extensible from C+ \o \l {Network Transparency} \o \l {qmlmodels}{Data Models} \o \l {anchor-layout}{Anchor-based Layout} +\o \l {qmlstates}{States} \o \l {qmlanimation}{Animation} \o \l {qmlmodules.html}{Modules} \o \l {qmlfocus}{Keyboard Focus} diff --git a/examples/declarative/behaviours/SideRect.qml b/examples/declarative/behaviours/SideRect.qml new file mode 100644 index 0000000..c7c7ebf --- /dev/null +++ b/examples/declarative/behaviours/SideRect.qml @@ -0,0 +1,17 @@ +import Qt 4.6 + +Rectangle { + id: myRect + + property string text + + color: "black" + width: 75; height: 50 + radius: 5 + border.width: 10; border.color: "white"; + MouseRegion { + anchors.fill: parent + hoverEnabled: true + onEntered: { focusRect.x = myRect.x; focusRect.y = myRect.y; focusRect.text = myRect.text } + } +} diff --git a/examples/declarative/behaviours/behavior.qml b/examples/declarative/behaviours/behavior.qml new file mode 100644 index 0000000..2732c0a --- /dev/null +++ b/examples/declarative/behaviours/behavior.qml @@ -0,0 +1,72 @@ +import Qt 4.6 + +Rectangle { + color: "black" + width: 400; height: 400 + + Rectangle { + color: "transparent" + anchors.centerIn: parent + width: 200; height: 200 + radius: 30 + border.width: 10; border.color: "white"; + + SideRect { + id: leftRect + anchors.verticalCenter: parent.verticalCenter + anchors.horizontalCenter: parent.left + text: "Left" + } + + SideRect { + id: rightRect + anchors.verticalCenter: parent.verticalCenter + anchors.horizontalCenter: parent.right + text: "Right" + } + + SideRect { + id: topRect + anchors.verticalCenter: parent.top + anchors.horizontalCenter: parent.horizontalCenter + text: "Top" + } + + SideRect { + id: bottomRect + anchors.verticalCenter: parent.bottom + anchors.horizontalCenter: parent.horizontalCenter + text: "Bottom" + } + + + Rectangle { + id: focusRect + + property string text + + color: "red" + width: 75; height: 50 + radius: 5 + border.width: 10; border.color: "white"; + x: 100-37; y: 100-25 + x: Behavior { NumberAnimation { duration: 300 } } + y: Behavior { NumberAnimation { duration: 300 } } + Text { + id: focusText + text: focusRect.text; + text: Behavior { + SequentialAnimation { + NumberAnimation { target: focusText; property: "opacity"; to: 0; duration: 150 } + PropertyAction {} + NumberAnimation { target: focusText; property: "opacity"; to: 1; duration: 150 } + } + } + anchors.centerIn: parent; + color: "white"; + font.pixelSize: 16 + font.bold: true + } + } + } +} diff --git a/examples/declarative/behaviours/test.qml b/examples/declarative/behaviours/test.qml index a15d05d..946559b 100644 --- a/examples/declarative/behaviours/test.qml +++ b/examples/declarative/behaviours/test.qml @@ -7,7 +7,7 @@ Rectangle { id: page MouseRegion { anchors.fill: parent - onClicked: { bluerect.parent = page; bluerect.x = mouseX; } + onClicked: { bluerect.parent = page; print(mouseX); bluerect.x = mouseX; } } MyRect { color: "green" @@ -57,25 +57,27 @@ Rectangle { height: 100 id: bluerect x: Behavior { - SequentialAnimation { - NumberAnimation { - target: bluerect - properties: "y" - from: 0 - to: 10 - easing: "easeOutBounce(amplitude:30)" - duration: 250 - } - NumberAnimation { - target: bluerect - properties: "y" - from: 10 - to: 0 - easing: "easeOutBounce(amplitude:30)" - duration: 250 + ParallelAnimation { + SequentialAnimation { + NumberAnimation { + target: bluerect + properties: "y" + from: 0 + to: 10 + easing: "easeOutBounce(amplitude:30)" + duration: 250 + } + NumberAnimation { + target: bluerect + properties: "y" + from: 10 + to: 0 + easing: "easeOutBounce(amplitude:30)" + duration: 250 + } } + NumberAnimation { duration: 500 } } - NumberAnimation { duration: 500 } } parent: Behavior { SequentialAnimation { -- cgit v0.12