/usr/share/qt5/doc/qtquick/qml-qtquick-viewtransition.html is in qtdeclarative5-doc-html 5.5.1-2ubuntu6.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qquickitemviewtransition.cpp -->
<title>ViewTransition QML Type | Qt Quick 5.5</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.5</li>
<li><a href="qtquick-index.html">Qt Quick</a></li>
<li><a href="qtquick-qmlmodule.html">QML Types</a></li>
<li>ViewTransition QML Type</li>
<li id="buildversion">Qt 5.5.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#properties">Attached Properties</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#view-transitions-a-simple-example">View transitions: a simple example</a></li>
<li class="level2"><a href="#using-the-viewtransition-attached-property">Using the ViewTransition attached property</a></li>
<li class="level2"><a href="#handling-interrupted-animations">Handling interrupted animations</a></li>
<li class="level2"><a href="#restrictions-regarding-scriptaction">Restrictions regarding ScriptAction</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">ViewTransition QML Type</h1>
<span class="subtitle"></span>
<!-- $$$ViewTransition-brief -->
<p>Specifies items under transition in a view <a href="#details">More...</a></p>
<!-- @@@ViewTransition -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Import Statement:</td><td class="memItemRight bottomAlign"> import QtQuick 2.5</td></tr></table></div><ul>
<li><a href="qml-qtquick-viewtransition-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="attached-properties"></a>
<h2 id="attached-properties">Attached Properties</h2>
<ul>
<li class="fn"><b><b><a href="qml-qtquick-viewtransition.html#destination-attached-prop">destination</a></b></b> : list</li>
<li class="fn"><b><b><a href="qml-qtquick-viewtransition.html#index-attached-prop">index</a></b></b> : list</li>
<li class="fn"><b><b><a href="qml-qtquick-viewtransition.html#item-attached-prop">item</a></b></b> : list</li>
<li class="fn"><b><b><a href="qml-qtquick-viewtransition.html#targetIndexes-attached-prop">targetIndexes</a></b></b> : list</li>
<li class="fn"><b><b><a href="qml-qtquick-viewtransition.html#targetItems-attached-prop">targetItems</a></b></b> : list</li>
</ul>
<!-- $$$ViewTransition-description -->
<a name="details"></a>
<h2 id="details">Detailed Description</h2>
</p>
<p>With <a href="qml-qtquick-listview.html">ListView</a> and <a href="qml-qtquick-gridview.html">GridView</a>, it is possible to specify transitions that should be applied whenever the items in the view change as a result of modifications to the view's model. They both have the following properties that can be set to the appropriate transitions to be run for various operations:</p>
<ul>
<li><code>populate</code> - the transition to apply to the items created initially for the view, or when the model changes</li>
<li><code>add</code> - the transition to apply to items that are added to the view after it has been created</li>
<li><code>remove</code> - the transition to apply to items that are removed from the view</li>
<li><code>move</code> - the transition to apply to items that are moved within the view (i.e. as a result of a move operation in the model)</li>
<li><code>displaced</code> - the generic transition to be applied to any items that are displaced by an add, move or remove operation</li>
<li><code>addDisplaced</code>, <code>removeDisplaced</code> and <code>moveDisplaced</code> - the transitions to be applied when items are displaced by add, move, or remove operations, respectively (these override the generic displaced transition if specified)</li>
</ul>
<p>For the <a href="qtquick-positioning-layouts.html#row">Row</a>, <a href="qtquick-positioning-layouts.html#column">Column</a>, <a href="qtquick-positioning-layouts.html#grid">Grid</a> and <a href="qtquick-positioning-layouts.html#flow">Flow</a> positioner types, which operate with collections of child items rather than data models, the following properties are used instead:</p>
<ul>
<li><code>populate</code> - the transition to apply to items that have been added to the positioner at the time of its creation</li>
<li><code>add</code> - the transition to apply to items that are added to or reparented to the positioner, or items that have become <a href="qml-qtquick-item.html#visible-prop">visible</a></li>
<li><code>move</code> - the transition to apply to items that have moved within the positioner, including when they are displaced due to the addition or removal of other items, or when items are otherwise rearranged within the positioner, or when items are repositioned due to the resizing of other items in the positioner</li>
</ul>
<p>View transitions have access to a <a href="qml-qtquick-viewtransition.html">ViewTransition</a> attached property that provides details of the items that are under transition and the operation that triggered the transition. Since view transitions are run once per item, these details can be used to customize each transition for each individual item.</p>
<p>The <a href="qml-qtquick-viewtransition.html">ViewTransition</a> attached property provides the following properties specific to the item to which the transition is applied:</p>
<ul>
<li><a href="qml-qtquick-viewtransition.html">ViewTransition</a>.item - the item that is under transition</li>
<li><a href="qml-qtquick-viewtransition.html">ViewTransition</a>.index - the index of this item</li>
<li><a href="qml-qtquick-viewtransition.html">ViewTransition</a>.destination - the (x,y) point to which this item is moving for the relevant view operation</li>
</ul>
<p>In addition, <a href="qml-qtquick-viewtransition.html">ViewTransition</a> provides properties specific to the items which are the target of the operation that triggered the transition:</p>
<ul>
<li><a href="qml-qtquick-viewtransition.html">ViewTransition</a>.<a href="qml-qtquick-viewtransition.html#targetIndexes-attached-prop">targetIndexes</a> - the indexes of the target items</li>
<li><a href="qml-qtquick-viewtransition.html">ViewTransition</a>.<a href="qml-qtquick-viewtransition.html#targetItems-attached-prop">targetItems</a> - the target items themselves</li>
</ul>
<p>(Note that for the <a href="qtquick-positioning-layouts.html#row">Row</a>, <a href="qtquick-positioning-layouts.html#column">Column</a>, <a href="qtquick-positioning-layouts.html#grid">Grid</a> and <a href="qtquick-positioning-layouts.html#flow">Flow</a> positioner types, the <code>move</code> transition only provides these two additional details when the transition is triggered by the addition of items to a positioner.)</p>
<p>View transitions can be written without referring to any of the attributes listed above. These attributes merely provide extra details that are useful for customising view transitions.</p>
<p>Following is an introduction to view transitions and the ways in which the <a href="qml-qtquick-viewtransition.html">ViewTransition</a> attached property can be used to augment view transitions.</p>
<a name="view-transitions-a-simple-example"></a>
<h3 >View transitions: a simple example</h3>
<p>Here is a basic example of the use of view transitions. The view below specifies transitions for the <code>add</code> and <code>displaced</code> properties, which will be run when items are added to the view:</p>
<pre class="qml"><span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">width</span>: <span class="number">240</span>; <span class="name">height</span>: <span class="number">320</span>
<span class="name">model</span>: <span class="name">ListModel</span> {}
<span class="name">delegate</span>: <span class="name">Rectangle</span> {
<span class="name">width</span>: <span class="number">100</span>; <span class="name">height</span>: <span class="number">30</span>
<span class="name">border</span>.width: <span class="number">1</span>
<span class="name">color</span>: <span class="string">"lightsteelblue"</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> {
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">text</span>: <span class="name">name</span>
}
}
<span class="name">add</span>: <span class="name">Transition</span> {
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">property</span>: <span class="string">"opacity"</span>; <span class="name">from</span>: <span class="number">0</span>; <span class="name">to</span>: <span class="number">1.0</span>; <span class="name">duration</span>: <span class="number">400</span> }
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">property</span>: <span class="string">"scale"</span>; <span class="name">from</span>: <span class="number">0</span>; <span class="name">to</span>: <span class="number">1.0</span>; <span class="name">duration</span>: <span class="number">400</span> }
}
<span class="name">displaced</span>: <span class="name">Transition</span> {
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">properties</span>: <span class="string">"x,y"</span>; <span class="name">duration</span>: <span class="number">400</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutBounce</span> }
}
<span class="name">focus</span>: <span class="number">true</span>
<span class="name">Keys</span>.onSpacePressed: <span class="name">model</span>.<span class="name">insert</span>(<span class="number">0</span>, { "name": <span class="string">"Item "</span> <span class="operator">+</span> <span class="name">model</span>.<span class="name">count</span> })
}</pre>
<p>When the space key is pressed, adding an item to the model, the new item will fade in and increase in scale over 400 milliseconds as it is added to the view. Also, any item that is displaced by the addition of a new item will animate to its new position in the view over 400 milliseconds, as specified by the <code>displaced</code> transition.</p>
<p>If five items were inserted in succession at index 0, the effect would be this:</p>
<p class="centerAlign"><img src="images/viewtransitions-basic.gif" alt="" /></p><p>Notice that the <a href="qml-qtquick-numberanimation.html">NumberAnimation</a> objects above do not need to specify a <code>target</code> to animate the appropriate item. Also, the <a href="qml-qtquick-numberanimation.html">NumberAnimation</a> in the <code>addTransition</code> does not need to specify the <code>to</code> value to move the item to its correct position in the view. This is because the view implicitly sets the <code>target</code> and <code>to</code> values with the correct item and final item position values if these properties are not explicitly defined.</p>
<p>At its simplest, a view transition may just animate an item to its new position following a view operation, just as the <code>displaced</code> transition does above, or animate some item properties, as in the <code>add</code> transition above. Additionally, a view transition may make use of the <a href="qml-qtquick-viewtransition.html">ViewTransition</a> attached property to customize animation behavior for different items. Following are some examples of how this can be achieved.</p>
<a name="using-the-viewtransition-attached-property"></a>
<h3 >Using the ViewTransition attached property</h3>
<p>As stated, the various <a href="qml-qtquick-viewtransition.html">ViewTransition</a> properties provide details specific to the individual item being transitioned as well as the operation that triggered the transition. In the animation above, five items are inserted in succession at index 0. When the fifth and final insertion takes place, adding "Item 4" to the view, the <code>add</code> transition is run once (for the inserted item) and the <code>displaced</code> transition is run four times (once for each of the four existing items in the view).</p>
<p>At this point, if we examined the <code>displaced</code> transition that was run for the bottom displaced item ("Item 0"), the <a href="qml-qtquick-viewtransition.html">ViewTransition</a> property values provided to this transition would be as follows:</p>
<div class="table"><table class="generic">
<thead><tr class="qt-style"><th >Property</th><th >Value</th><th >Explanation</th></tr></thead>
<tr valign="top" class="odd"><td ><a href="qml-qtquick-viewtransition.html">ViewTransition</a>.item</td><td >"Item 0" delegate instance</td><td >The "Item 0" <a href="qml-qtquick-rectangle.html">Rectangle</a> object itself</td></tr>
<tr valign="top" class="even"><td ><a href="qml-qtquick-viewtransition.html">ViewTransition</a>.index</td><td ><code>int</code> value of 4</td><td >The index of "Item 0" within the model following the add operation</td></tr>
<tr valign="top" class="odd"><td ><a href="qml-qtquick-viewtransition.html">ViewTransition</a>.destination</td><td >point value of (0, 120)</td><td >The position that "Item 0" is moving to</td></tr>
<tr valign="top" class="even"><td ><a href="qml-qtquick-viewtransition.html">ViewTransition</a>.<a href="qml-qtquick-viewtransition.html#targetIndexes-attached-prop">targetIndexes</a></td><td ><code>int</code> array, just contains the integer "0" (zero)</td><td >The index of "Item 4", the new item added to the view</td></tr>
<tr valign="top" class="odd"><td ><a href="qml-qtquick-viewtransition.html">ViewTransition</a>.<a href="qml-qtquick-viewtransition.html#targetItems-attached-prop">targetItems</a></td><td >object array, just contains the "Item 4" delegate instance</td><td >The "Item 4" <a href="qml-qtquick-rectangle.html">Rectangle</a> object - the new item added to the view</td></tr>
</table></div>
<p>The <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.<a href="qml-qtquick-viewtransition.html#targetIndexes-attached-prop">targetIndexes</a> and <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.<a href="qml-qtquick-viewtransition.html#targetItems-attached-prop">targetItems</a> lists provide the items and indexes of all delegate instances that are the targets of the relevant operation. For an add operation, these are all the items that are added into the view; for a remove, these are all the items removed from the view, and so on. (Note these lists will only contain references to items that have been created within the view or its cached items; targets that are not within the visible area of the view or within the item cache will not be accessible.)</p>
<p>So, while the <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.item, <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.index and <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.destination values vary for each individual transition that is run, the <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.<a href="qml-qtquick-viewtransition.html#targetIndexes-attached-prop">targetIndexes</a> and <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.<a href="qml-qtquick-viewtransition.html#targetItems-attached-prop">targetItems</a> values are the same for every <code>add</code> and <code>displaced</code> transition that is triggered by a particular add operation.</p>
<a name="delaying-animations-based-on-index"></a>
<h4 >Delaying animations based on index</h4>
<p>Since each view transition is run once for each item affected by the transition, the <a href="qml-qtquick-viewtransition.html">ViewTransition</a> properties can be used within a transition to define custom behavior for each item's transition. For example, the <a href="qml-qtquick-listview.html">ListView</a> in the previous example could use this information to create a ripple-type effect on the movement of the displaced items.</p>
<p>This can be achieved by modifying the <code>displaced</code> transition so that it delays the animation of each displaced item based on the difference between its index (provided by <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.index) and the first removed index (provided by <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.<a href="qml-qtquick-viewtransition.html#targetIndexes-attached-prop">targetIndexes</a>):</p>
<pre class="qml"> <span class="name">displaced</span>: <span class="name">Transition</span> {
<span class="name">id</span>: <span class="name">dispTrans</span>
<span class="type"><a href="qml-qtquick-sequentialanimation.html">SequentialAnimation</a></span> {
<span class="type"><a href="qml-qtquick-pauseanimation.html">PauseAnimation</a></span> {
<span class="name">duration</span>: (<span class="name">dispTrans</span>.<span class="name">ViewTransition</span>.<span class="name">index</span> <span class="operator">-</span>
<span class="name">dispTrans</span>.<span class="name">ViewTransition</span>.<span class="name">targetIndexes</span>[<span class="number">0</span>]) <span class="operator">*</span> <span class="number">100</span>
}
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">properties</span>: <span class="string">"x,y"</span>; <span class="name">duration</span>: <span class="number">400</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutBounce</span> }
}
}</pre>
<p>Each displaced item delays its animation by an additional 100 milliseconds, producing a subtle ripple-type effect when items are displaced by the add, like this:</p>
<p class="centerAlign"><img src="images/viewtransitions-delayedbyindex.gif" alt="" /></p><a name="animating-items-to-intermediate-positions"></a>
<h4 >Animating items to intermediate positions</h4>
<p>The <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.item property gives a reference to the item to which the transition is being applied. This can be used to access any of the item's attributes, custom <code>property</code> values, and so on.</p>
<p>Below is a modification of the <code>displaced</code> transition from the previous example. It adds a <a href="qml-qtquick-parallelanimation.html">ParallelAnimation</a> with nested <a href="qml-qtquick-numberanimation.html">NumberAnimation</a> objects that reference <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.item to access each item's <code>x</code> and <code>y</code> values at the start of their transitions. This allows each item to animate to an intermediate position relative to its starting point for the transition, before animating to its final position in the view:</p>
<pre class="qml"> <span class="name">displaced</span>: <span class="name">Transition</span> {
<span class="name">id</span>: <span class="name">dispTrans</span>
<span class="type"><a href="qml-qtquick-sequentialanimation.html">SequentialAnimation</a></span> {
<span class="type"><a href="qml-qtquick-pauseanimation.html">PauseAnimation</a></span> {
<span class="name">duration</span>: (<span class="name">dispTrans</span>.<span class="name">ViewTransition</span>.<span class="name">index</span> <span class="operator">-</span>
<span class="name">dispTrans</span>.<span class="name">ViewTransition</span>.<span class="name">targetIndexes</span>[<span class="number">0</span>]) <span class="operator">*</span> <span class="number">100</span>
}
<span class="type"><a href="qml-qtquick-parallelanimation.html">ParallelAnimation</a></span> {
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> {
<span class="name">property</span>: <span class="string">"x"</span>; <span class="name">to</span>: <span class="name">dispTrans</span>.<span class="name">ViewTransition</span>.<span class="name">item</span>.<span class="name">x</span> <span class="operator">+</span> <span class="number">20</span>
<span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutQuad</span>
}
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> {
<span class="name">property</span>: <span class="string">"y"</span>; <span class="name">to</span>: <span class="name">dispTrans</span>.<span class="name">ViewTransition</span>.<span class="name">item</span>.<span class="name">y</span> <span class="operator">+</span> <span class="number">50</span>
<span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutQuad</span>
}
}
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">properties</span>: <span class="string">"x,y"</span>; <span class="name">duration</span>: <span class="number">500</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutBounce</span> }
}
}</pre>
<p>Now, a displaced item will first move to a position of (20, 50) relative to its starting position, and then to its final, correct position in the view:</p>
<p class="centerAlign"><img src="images/viewtransitions-intermediatemove.gif" alt="" /></p><p>Since the final <a href="qml-qtquick-numberanimation.html">NumberAnimation</a> does not specify a <code>to</code> value, the view implicitly sets this value to the item's final position in the view, and so this last animation will move this item to the correct place. If the transition requires the final position of the item for some calculation, this is accessible through <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.destination.</p>
<p>Instead of using multiple NumberAnimations, you could use a <a href="qtquick-animation-example.html#pathanimation">PathAnimation</a> to animate an item over a curved path. For example, the <code>add</code> transition in the previous example could be augmented with a <a href="qtquick-animation-example.html#pathanimation">PathAnimation</a> as follows: to animate newly added items along a path:</p>
<pre class="qml"> <span class="name">add</span>: <span class="name">Transition</span> {
<span class="name">id</span>: <span class="name">addTrans</span>
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">property</span>: <span class="string">"opacity"</span>; <span class="name">from</span>: <span class="number">0</span>; <span class="name">to</span>: <span class="number">1.0</span>; <span class="name">duration</span>: <span class="number">400</span> }
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">property</span>: <span class="string">"scale"</span>; <span class="name">from</span>: <span class="number">0</span>; <span class="name">to</span>: <span class="number">1.0</span>; <span class="name">duration</span>: <span class="number">400</span> }
<span class="type"><a href="qml-qtquick-pathanimation.html">PathAnimation</a></span> {
<span class="name">duration</span>: <span class="number">1000</span>
<span class="name">path</span>: <span class="name">Path</span> {
<span class="name">startX</span>: <span class="name">addTrans</span>.<span class="name">ViewTransition</span>.<span class="name">destination</span>.<span class="name">x</span> <span class="operator">+</span> <span class="number">200</span>
<span class="name">startY</span>: <span class="name">addTrans</span>.<span class="name">ViewTransition</span>.<span class="name">destination</span>.<span class="name">y</span> <span class="operator">+</span> <span class="number">200</span>
<span class="type"><a href="qml-qtquick-pathcurve.html">PathCurve</a></span> { <span class="name">relativeX</span>: -<span class="number">100</span>; <span class="name">relativeY</span>: -<span class="number">50</span> }
<span class="type"><a href="qml-qtquick-pathcurve.html">PathCurve</a></span> { <span class="name">relativeX</span>: <span class="number">50</span>; <span class="name">relativeY</span>: -<span class="number">150</span> }
<span class="type"><a href="qml-qtquick-pathcurve.html">PathCurve</a></span> {
<span class="name">x</span>: <span class="name">addTrans</span>.<span class="name">ViewTransition</span>.<span class="name">destination</span>.<span class="name">x</span>
<span class="name">y</span>: <span class="name">addTrans</span>.<span class="name">ViewTransition</span>.<span class="name">destination</span>.<span class="name">y</span>
}
}
}
}</pre>
<p>This animates newly added items along a path. Notice that each path is specified relative to each item's final destination point, so that items inserted at different indexes start their paths from different positions:</p>
<p class="centerAlign"><img src="images/viewtransitions-pathanim.gif" alt="" /></p><a name="handling-interrupted-animations"></a>
<h3 >Handling interrupted animations</h3>
<p>A view transition may be interrupted at any time if a different view transition needs to be applied while the original transition is in progress. For example, say Item A is inserted at index 0 and undergoes an "add" transition; then, Item B is inserted at index 0 in quick succession before Item A's transition has finished. Since Item B is inserted before Item A, it will displace Item A, causing the view to interrupt Item A's "add" transition mid-way and start a "displaced" transition on Item A instead.</p>
<p>For simple animations that simply animate an item's movement to its final destination, this interruption is unlikely to require additional consideration. However, if a transition changes other properties, this interruption may cause unwanted side effects. Consider the first example on this page, repeated below for convenience:</p>
<pre class="qml"><span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">width</span>: <span class="number">240</span>; <span class="name">height</span>: <span class="number">320</span>
<span class="name">model</span>: <span class="name">ListModel</span> {}
<span class="name">delegate</span>: <span class="name">Rectangle</span> {
<span class="name">width</span>: <span class="number">100</span>; <span class="name">height</span>: <span class="number">30</span>
<span class="name">border</span>.width: <span class="number">1</span>
<span class="name">color</span>: <span class="string">"lightsteelblue"</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> {
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">text</span>: <span class="name">name</span>
}
}
<span class="name">add</span>: <span class="name">Transition</span> {
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">property</span>: <span class="string">"opacity"</span>; <span class="name">from</span>: <span class="number">0</span>; <span class="name">to</span>: <span class="number">1.0</span>; <span class="name">duration</span>: <span class="number">400</span> }
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">property</span>: <span class="string">"scale"</span>; <span class="name">from</span>: <span class="number">0</span>; <span class="name">to</span>: <span class="number">1.0</span>; <span class="name">duration</span>: <span class="number">400</span> }
}
<span class="name">displaced</span>: <span class="name">Transition</span> {
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">properties</span>: <span class="string">"x,y"</span>; <span class="name">duration</span>: <span class="number">400</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutBounce</span> }
}
<span class="name">focus</span>: <span class="number">true</span>
<span class="name">Keys</span>.onSpacePressed: <span class="name">model</span>.<span class="name">insert</span>(<span class="number">0</span>, { "name": <span class="string">"Item "</span> <span class="operator">+</span> <span class="name">model</span>.<span class="name">count</span> })
}</pre>
<p>If multiple items are added in rapid succession, without waiting for a previous transition to finish, this is the result:</p>
<p class="centerAlign"><img src="images/viewtransitions-interruptedbad.gif" alt="" /></p><p>Each newly added item undergoes an <code>add</code> transition, but before the transition can finish, another item is added, displacing the previously added item. Because of this, the <code>add</code> transition on the previously added item is interrupted and a <code>displaced</code> transition is started on the item instead. Due to the interruption, the <code>opacity</code> and <code>scale</code> animations have not completed, thus producing items with opacity and scale that are below 1.0.</p>
<p>To fix this, the <code>displaced</code> transition should additionally ensure the item properties are set to the end values specified in the <code>add</code> transition, effectively resetting these values whenever an item is displaced. In this case, it means setting the item opacity and scale to 1.0:</p>
<pre class="qml"> <span class="name">displaced</span>: <span class="name">Transition</span> {
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">properties</span>: <span class="string">"x,y"</span>; <span class="name">duration</span>: <span class="number">400</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutBounce</span> }
<span class="comment">// ensure opacity and scale values return to 1.0</span>
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">property</span>: <span class="string">"opacity"</span>; <span class="name">to</span>: <span class="number">1.0</span> }
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">property</span>: <span class="string">"scale"</span>; <span class="name">to</span>: <span class="number">1.0</span> }
}</pre>
<p>Now, when an item's <code>add</code> transition is interrupted, its opacity and scale are animated to 1.0 upon displacement, avoiding the erroneous visual effects from before:</p>
<p class="centerAlign"><img src="images/viewtransitions-interruptedgood.gif" alt="" /></p><p>The same principle applies to any combination of view transitions. An added item may be moved before its add transition finishes, or a moved item may be removed before its moved transition finishes, and so on; so, the rule of thumb is that every transition should handle the same set of properties.</p>
<a name="restrictions-regarding-scriptaction"></a>
<h3 >Restrictions regarding ScriptAction</h3>
<p>When a view transition is initialized, any property bindings that refer to the <a href="qml-qtquick-viewtransition.html">ViewTransition</a> attached property are evaluated in preparation for the transition. Due to the nature of the internal construction of a view transition, the attributes of the <a href="qml-qtquick-viewtransition.html">ViewTransition</a> attached property are only valid for the relevant item when the transition is initialized, and may not be valid when the transition is actually run.</p>
<p>Therefore, a <a href="qml-qtquick-scriptaction.html">ScriptAction</a> within a view transition should not refer to the <a href="qml-qtquick-viewtransition.html">ViewTransition</a> attached property, as it may not refer to the expected values at the time that the <a href="qml-qtquick-scriptaction.html">ScriptAction</a> is actually invoked. Consider the following example:</p>
<pre class="qml"><span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">width</span>: <span class="number">240</span>; <span class="name">height</span>: <span class="number">320</span>
<span class="name">model</span>: <span class="name">ListModel</span> {
<span class="name">Component</span>.onCompleted: {
<span class="keyword">for</span> (<span class="keyword">var</span> <span class="name">i</span>=<span class="number">0</span>; <span class="name">i</span><span class="operator"><</span><span class="number">8</span>; i++)
<span class="name">append</span>({"name": <span class="name">i</span>})
}
}
<span class="name">delegate</span>: <span class="name">Rectangle</span> {
<span class="name">width</span>: <span class="number">100</span>; <span class="name">height</span>: <span class="number">30</span>
<span class="name">border</span>.width: <span class="number">1</span>
<span class="name">color</span>: <span class="string">"lightsteelblue"</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> {
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">text</span>: <span class="name">name</span>
}
<span class="name">objectName</span>: <span class="name">name</span>
}
<span class="name">move</span>: <span class="name">Transition</span> {
<span class="name">id</span>: <span class="name">moveTrans</span>
<span class="type"><a href="qml-qtquick-sequentialanimation.html">SequentialAnimation</a></span> {
<span class="type"><a href="qml-qtquick-coloranimation.html">ColorAnimation</a></span> { <span class="name">property</span>: <span class="string">"color"</span>; <span class="name">to</span>: <span class="string">"yellow"</span>; <span class="name">duration</span>: <span class="number">400</span> }
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">properties</span>: <span class="string">"x,y"</span>; <span class="name">duration</span>: <span class="number">800</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutBack</span> }
<span class="type"><a href="qml-qtquick-scriptaction.html">ScriptAction</a></span> { <span class="name">script</span>: <span class="name">moveTrans</span>.<span class="name">ViewTransition</span>.<span class="name">item</span>.<span class="name">color</span> <span class="operator">=</span> <span class="string">"lightsteelblue"</span> }
}
}
<span class="name">displaced</span>: <span class="name">Transition</span> {
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">properties</span>: <span class="string">"x,y"</span>; <span class="name">duration</span>: <span class="number">400</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutBounce</span> }
}
<span class="name">focus</span>: <span class="number">true</span>
<span class="name">Keys</span>.onSpacePressed: <span class="name">model</span>.<span class="name">move</span>(<span class="number">5</span>, <span class="number">1</span>, <span class="number">3</span>)
}</pre>
<p>When the space key is pressed, three items are moved from index 5 to index 1. For each moved item, the <code>moveTransition</code> sequence presumably animates the item's color to "yellow", then animates it to its final position, then changes the item color back to "lightsteelblue" using a <a href="qml-qtquick-scriptaction.html">ScriptAction</a>. However, when run, the transition does not produce the intended result:</p>
<p class="centerAlign"><img src="images/viewtransitions-scriptactionbad.gif" alt="" /></p><p>Only the last moved item is returned to the "lightsteelblue" color; the others remain yellow. This is because the <a href="qml-qtquick-scriptaction.html">ScriptAction</a> is not run until after the transition has already been initialized, by which time the <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.item value has changed to refer to a different item; the item that the script had intended to refer to is not the one held by <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.item at the time the <a href="qml-qtquick-scriptaction.html">ScriptAction</a> is actually invoked.</p>
<p>In this instance, to avoid this issue, the view could set the property using a <a href="qml-qtquick-propertyaction.html">PropertyAction</a> instead:</p>
<pre class="qml"> <span class="name">move</span>: <span class="name">Transition</span> {
<span class="name">id</span>: <span class="name">moveTrans</span>
<span class="type"><a href="qml-qtquick-sequentialanimation.html">SequentialAnimation</a></span> {
<span class="type"><a href="qml-qtquick-coloranimation.html">ColorAnimation</a></span> { <span class="name">property</span>: <span class="string">"color"</span>; <span class="name">to</span>: <span class="string">"yellow"</span>; <span class="name">duration</span>: <span class="number">400</span> }
<span class="type"><a href="qml-qtquick-numberanimation.html">NumberAnimation</a></span> { <span class="name">properties</span>: <span class="string">"x,y"</span>; <span class="name">duration</span>: <span class="number">800</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">OutBack</span> }
<span class="comment">//ScriptAction { script: moveTrans.ViewTransition.item.color = "lightsteelblue" } BAD!</span>
<span class="type"><a href="qml-qtquick-propertyaction.html">PropertyAction</a></span> { <span class="name">property</span>: <span class="string">"color"</span>; <span class="name">value</span>: <span class="string">"lightsteelblue"</span> }
}
}</pre>
<p>When the transition is initialized, the <a href="qml-qtquick-propertyaction.html">PropertyAction</a> <code>target</code> will be set to the respective <a href="qml-qtquick-viewtransition.html">ViewTransition</a>.item for the transition and will later run with the correct item target as expected.</p>
<!-- @@@ViewTransition -->
<h2>Attached Property Documentation</h2>
<!-- $$$destination -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="destination-attached-prop"><td class="tblQmlPropNode"><p><a name="destination-attached-prop"></a><span class="name">ViewTransition.destination</span> : <span class="type">list</span></p></td></tr></table></div></div><div class="qmldoc"><p>This attached property holds the final destination position for the transitioned item within the view.</p>
<p>This property value is a point with <code>x</code> and <code>y</code> properties.</p>
</div></div><!-- @@@destination -->
<br/>
<!-- $$$index -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="index-attached-prop"><td class="tblQmlPropNode"><p><a name="index-attached-prop"></a><span class="name">ViewTransition.index</span> : <span class="type">list</span></p></td></tr></table></div></div><div class="qmldoc"><p>This attached property holds the index of the item that is being transitioned.</p>
<p>Note that if the item is being moved, this property holds the index that the item is moving to, not from.</p>
</div></div><!-- @@@index -->
<br/>
<!-- $$$item -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="item-attached-prop"><td class="tblQmlPropNode"><p><a name="item-attached-prop"></a><span class="name">ViewTransition.item</span> : <span class="type">list</span></p></td></tr></table></div></div><div class="qmldoc"><p>This attached property holds the item that is being transitioned.</p>
<p><b>Warning:</b> This item should not be kept and referred to outside of the transition as it may become invalid as the view changes.</p>
</div></div><!-- @@@item -->
<br/>
<!-- $$$targetIndexes -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="targetIndexes-attached-prop"><td class="tblQmlPropNode"><p><a name="targetIndexes-attached-prop"></a><span class="name">ViewTransition.targetIndexes</span> : <span class="type">list</span></p></td></tr></table></div></div><div class="qmldoc"><p>This attached property holds a list of the indexes of the items in view that are the target of the relevant operation.</p>
<p>The targets are the items that are the subject of the operation. For an add operation, these are the items being added; for a remove, these are the items being removed; for a move, these are the items being moved.</p>
<p>For example, if the transition was triggered by an insert operation that added two items at index 1 and 2, this targetIndexes list would have the value [1,2].</p>
<p><b>Note: </b>The targetIndexes list only contains the indexes of items that are actually in view, or will be in the view once the relevant operation completes.</p><p><b>See also </b><a href="qml-qtquick-viewtransition.html#targetItems-attached-prop">QtQuick::ViewTransition::targetItems</a>.</p>
</div></div><!-- @@@targetIndexes -->
<br/>
<!-- $$$targetItems -->
<div class="qmlitem"><div class="qmlproto"><div class="table"><table class="qmlname"><tr valign="top" class="odd" id="targetItems-attached-prop"><td class="tblQmlPropNode"><p><a name="targetItems-attached-prop"></a><span class="name">ViewTransition.targetItems</span> : <span class="type">list</span></p></td></tr></table></div></div><div class="qmldoc"><p>This attached property holds the list of items in view that are the target of the relevant operation.</p>
<p>The targets are the items that are the subject of the operation. For an add operation, these are the items being added; for a remove, these are the items being removed; for a move, these are the items being moved.</p>
<p>For example, if the transition was triggered by an insert operation that added two items at index 1 and 2, this targetItems list would contain these two items.</p>
<p><b>Note: </b>The targetItems list only contains items that are actually in view, or will be in the view once the relevant operation completes.</p><p><b>Warning:</b> The objects in this list should not be kept and referred to outside of the transition as the items may become invalid. The targetItems are only valid when the Transition is initially created; this also means they should not be used by <a href="qml-qtquick-scriptaction.html">ScriptAction</a> objects in the Transition, which are not evaluated until the transition is run.</p>
<p><b>See also </b><a href="qml-qtquick-viewtransition.html#targetIndexes-attached-prop">QtQuick::ViewTransition::targetIndexes</a>.</p>
</div></div><!-- @@@targetItems -->
<br/>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|