css3-animations/Overview.src.html

Tue, 19 Jun 2012 19:06:27 -0700

author
Sylvain Galineau <sylvaing@microsoft.com>
date
Tue, 19 Jun 2012 19:06:27 -0700
changeset 6047
ceac3feb170f
parent 5911
27544a0821fd
child 6082
1d5f04cd856a
permissions
-rw-r--r--

Fix typo in section 3 (missing 'a')

jackalmage@5911 1 <!DOCTYPE html>
dino@937 2 <html lang="en">
dino@937 3 <head>
jackalmage@5911 4 <title>CSS Animations</title>
jackalmage@5911 5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
jackalmage@5911 6 <link rel="stylesheet" type="text/css" href="../default.css">
jackalmage@5911 7 <link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
dino@937 8 </head>
dino@937 9
dino@937 10 <body>
dino@937 11
dino@937 12 <div class="head">
dino@937 13 <!--logo-->
dino@937 14
simon@2533 15 <h1>CSS Animations</h1>
dino@937 16
dino@937 17 <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>
dino@937 18 <dl>
jackalmage@5911 19 <dt>This version:
jackalmage@5911 20 <dd><a href="[VERSION]">http://dev.w3.org/csswg/css3-animations/</a>
jackalmage@5911 21 <!--http://www.w3.org/TR/[YEAR]/WD-[SHORTNAME]-[CDATE]/-->
jackalmage@5911 22 <dt>Latest version:
jackalmage@5911 23 <dd><a
jackalmage@5911 24 href="http://www.w3.org/TR/css3-animations/">[LATEST]</a>
jackalmage@5911 25 <dt>Editor's draft:
jackalmage@5911 26 <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
dbaron@3965 27
jackalmage@5911 28 <dt>Previous version:
jackalmage@5911 29 <dd><a href="http://www.w3.org/TR/2012/WD-css3-animations-20120403/">
jackalmage@5911 30 http://www.w3.org/TR/2012/WD-css3-animations-20120403/</a>
jackalmage@5911 31 <dt id="editors-list">Editors:
jackalmage@5911 32 <dd><a href="mailto:dino@apple.com">Dean Jackson</a> (<a
jackalmage@5911 33 href="http://www.apple.com/">Apple Inc</a>)
jackalmage@5911 34 <dd><a href="mailto:hyatt@apple.com">David Hyatt</a> (<a
jackalmage@5911 35 href="http://www.apple.com/">Apple Inc</a>)
jackalmage@5911 36 <dd><a href="mailto:cmarrin@apple.com">Chris Marrin</a> (<a
jackalmage@5911 37 href="http://www.apple.com/">Apple Inc</a>)
jackalmage@5911 38 <dd><a href="mailto:sylvaing@microsoft.com">Sylvain Galineau</a>
jackalmage@5911 39 (<a class=org href="http://www.microsoft.com/">Microsoft</a>)
jackalmage@5911 40 <dd class=vcard><a class=fn href="http://dbaron.org/">L. David Baron</a>
jackalmage@5911 41 (<a class=org href="http://www.mozilla.org/">Mozilla</a>)
dbaron@3965 42
jackalmage@5911 43 <dt>Issues list:
jackalmage@5911 44 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&amp;product=CSS&amp;component=Animations&amp;resolution=---&amp;cmdtype=doit">in Bugzilla</a>
dbaron@3965 45
jackalmage@5911 46 <dt>Discussion:
jackalmage@5911 47 <dd><a href="http://lists.w3.org/Archives/Public/www-style/">www-style@w3.org</a> with subject line &ldquo;<kbd>[[SHORTNAME]] <var>&hellip; message topic &hellip;</var></kbd>&rdquo;
dbaron@5229 48
jackalmage@5911 49 <dt>Test suite:
jackalmage@5911 50 <dd>none yet
dino@937 51 </dl>
dino@937 52
dino@937 53 <!--copyright-->
dino@937 54
dino@937 55 <hr title="Separator for header">
dino@937 56 </div>
dino@937 57
jackalmage@5911 58 <h2 class="no-num no-toc" id="abstract">
jackalmage@5911 59 Abstract</h2>
dino@937 60
jackalmage@5911 61 <p>
jackalmage@5911 62 This CSS module describes a way for authors to animate the values of CSS properties over time,
jackalmage@5911 63 using keyframes.
jackalmage@5911 64 The behavior of these keyframe animations can be controlled by specifying their duration,
jackalmage@5911 65 number of repeats,
jackalmage@5911 66 and repeating behavior.
dino@937 67
jackalmage@5911 68
jackalmage@5911 69 <h2 class="no-num no-toc" id="status">
jackalmage@5911 70 Status of this document</h2>
dino@937 71 <!--status-->
dino@937 72
dino@937 73
jackalmage@5911 74 <h2 class="no-num no-toc" id="contents">
jackalmage@5911 75 Table of contents</h2>
dino@937 76 <!--toc-->
dino@937 77
dino@937 78
jackalmage@5911 79 <h2 id="introduction">
jackalmage@5911 80 Introduction</h2>
dino@937 81
jackalmage@5911 82 <p><em>This section is not normative.</em>
dino@937 83
jackalmage@5911 84 <p>
jackalmage@5911 85 CSS Transitions [[CSS3-TRANSITIONS]]
jackalmage@5911 86 provide a way to interpolate CSS property values
jackalmage@5911 87 when they change as a result of underlying property changes.
jackalmage@5911 88 This provides an easy way to do simple animation,
jackalmage@5911 89 but the start and end states of the animation are controlled by the existing property values,
jackalmage@5911 90 and transitions provide little control to the author on how the animation progresses.
jackalmage@5911 91
jackalmage@5911 92 <p>
jackalmage@5911 93 This proposal introduces <dfn>defined animations</dfn>,
jackalmage@5911 94 in which the author can specify the changes in CSS properties over time as a set of keyframes.
jackalmage@5911 95 Animations are similar to transitions
jackalmage@5911 96 in that they change the presentational value of CSS properties over time.
jackalmage@5911 97 The principal difference is that
jackalmage@5911 98 while transitions trigger <em>implicitly</em> when property values change,
jackalmage@5911 99 animations are <em>explicitly</em> executed when the animation properties are applied.
jackalmage@5911 100 Because of this,
jackalmage@5911 101 animations require explicit values for the properties being animated.
jackalmage@5911 102 These values are specified using animation keyframes, described below.
jackalmage@5911 103
jackalmage@5911 104 <p>
jackalmage@5911 105 Many aspects of the animation can be controlled,
jackalmage@5911 106 including how many times the animation iterates,
jackalmage@5911 107 whether or not it alternates between the begin and end values,
jackalmage@5911 108 and whether or not the animation should be running or paused.
jackalmage@5911 109 An animation can also delay its start time.
simon@1671 110
simon@1719 111
jackalmage@5911 112 <h2 id="animations">
jackalmage@5911 113 Animations</h2>
simon@1719 114
jackalmage@5911 115 <p>
jackalmage@5911 116 CSS Animations affect computed property values.
jackalmage@5911 117 During the execution of an animation,
jackalmage@5911 118 the computed value for a property is controlled by the animation.
jackalmage@5911 119 This overrides the value specified in the normal styling system.
jackalmage@5911 120
simon@1719 121
jackalmage@5911 122 <p>
jackalmage@5911 123 If at one point in time there are multiple animations specifying behavior for the same property,
jackalmage@5911 124 the animation whose name occurs last in the value of 'animation-name'
jackalmage@5911 125 will override the other animations at that point.
jackalmage@5911 126
simon@1719 127
jackalmage@5911 128 <p>
jackalmage@5911 129 An animation does not affect the computed value before the application of the animation,
jackalmage@5911 130 before the animation delay has expired,
jackalmage@5911 131 and after the end of the animation.
jackalmage@5911 132
simon@1719 133
jackalmage@5911 134 <div class="figure">
jackalmage@5911 135 <img src="sandwich.png" alt="">
jackalmage@5911 136
jackalmage@5911 137 <p class="caption">
jackalmage@5911 138 Computation of animated property values
jackalmage@5911 139 </div>
simon@1719 140
jackalmage@5911 141 <p>
jackalmage@5911 142 The diagram above shows how property values are computed.
jackalmage@5911 143 The intrinsic style is shown at the top of the diagram.
jackalmage@5911 144 The computed value is derived from intrinsic style
jackalmage@5911 145 at the times when an animation is not running
jackalmage@5911 146 and also when an animation is delayed
jackalmage@5911 147 (see below for specification of animation delay).
jackalmage@5911 148 During an animation,
jackalmage@5911 149 the computed style is derived from the animated value.
jackalmage@5911 150
simon@1719 151
jackalmage@5911 152 <p>
jackalmage@5911 153 The start time of an animation is the latter of two moments:
jackalmage@5911 154 the time at which the style is resolved that specifies the animation,
jackalmage@5911 155 or the time the document's load event is fired.
jackalmage@5911 156 Therefore, an animation specified in the document style sheet
jackalmage@5911 157 will begin at the document load.
jackalmage@5911 158 An animation specified on an element by modifying the style after the document has loaded
jackalmage@5911 159 will start when the style is resolved.
jackalmage@5911 160 That may be immediately in the case of a pseudo style rule such as hover,
jackalmage@5911 161 or may be when the scripting engine returns control to the browser
jackalmage@5911 162 (in the case of style applied by script).
jackalmage@5911 163
simon@1719 164
jackalmage@5911 165 <p>
jackalmage@5911 166 An animation applies to an element
jackalmage@5911 167 if the element has a value for 'animation-name' that references a valid keyframes rule.
jackalmage@5911 168 Once an animation has started
jackalmage@5911 169 it continues until it ends
jackalmage@5911 170 or the 'animation-name' is removed.
jackalmage@5911 171 The values used for the keyframes and animation properties are snapshotted at the time the animation starts.
jackalmage@5911 172 Changing them during the execution of the animation has no effect.
jackalmage@5911 173 Note also that changing the value of 'animation-name' does not necessarily restart an animation
jackalmage@5911 174 (e.g., if a list of animations are applied and one is removed from the list,
jackalmage@5911 175 only that animation will stop;
jackalmage@5911 176 The other animations will continue).
jackalmage@5911 177 In order to restart an animation,
jackalmage@5911 178 it must be removed then reapplied.
jackalmage@5911 179
simon@1719 180
jackalmage@5911 181 <p>
jackalmage@5911 182 The end of the animation is defined by the combination of the
jackalmage@5911 183 'animation-duration',
jackalmage@5911 184 'animation-iteration-count' and
jackalmage@5911 185 'animation-fill-mode' properties.
jackalmage@5911 186
jackalmage@5911 187
jackalmage@5911 188 <div class="example">
jackalmage@5911 189 <pre>
jackalmage@5911 190 div {
jackalmage@5911 191 animation-name: diagonal-slide;
jackalmage@5911 192 animation-duration: 5s;
jackalmage@5911 193 animation-iteration-count: 10;
jackalmage@5911 194 }
simon@1719 195
jackalmage@5911 196 @keyframes diagonal-slide {
simon@1719 197
jackalmage@5911 198 from {
jackalmage@5911 199 left: 0;
jackalmage@5911 200 top: 0;
jackalmage@5911 201 }
simon@1719 202
jackalmage@5911 203 to {
jackalmage@5911 204 left: 100px;
jackalmage@5911 205 top: 100px;
jackalmage@5911 206 }
simon@1719 207
jackalmage@5911 208 }</pre>
simon@1719 209
jackalmage@5911 210 <p>
jackalmage@5911 211 This will produce an animation
jackalmage@5911 212 that moves an element from (0, 0) to (100px, 100px)
jackalmage@5911 213 over five seconds
jackalmage@5911 214 and repeats itself nine times
jackalmage@5911 215 (for a total of ten iterations).
jackalmage@5911 216 </div>
dino@937 217
jackalmage@5911 218 <h2 id="keyframes">
jackalmage@5911 219 Keyframes</h2>
jackalmage@5911 220 <p>
jackalmage@5911 221 Keyframes are used to specify the values for the animating properties
jackalmage@5911 222 at various points during the animation.
jackalmage@5911 223 The keyframes specify the behavior of one cycle of the animation;
jackalmage@5911 224 the animation may iterate one or more times.
jackalmage@5911 225
jackalmage@5911 226 <p>
jackalmage@5911 227 Keyframes are specified using a specialized CSS at-rule.
jackalmage@5911 228 A @keyframes rule consists of the keyword "@keyframes",
jackalmage@5911 229 followed by an identifier giving a name for the animation
jackalmage@5911 230 (which will be referenced using 'animation-name'),
jackalmage@5911 231 followed by a set of style rules
jackalmage@5911 232 (delimited by curly braces).
jackalmage@5911 233
jackalmage@5911 234 <p>
jackalmage@5911 235 The <dfn>keyframe selector</dfn> for a keyframe style rule
jackalmage@5911 236 consists of a comma-separated list of percentage values
jackalmage@5911 237 or the keywords 'from' or 'to'.
jackalmage@5911 238 The selector is used to specify the percentage along the duration of the animation that the keyframe represents.
jackalmage@5911 239 The keyframe itself is specified by the block of property values declared on the selector.
jackalmage@5911 240 The keyword 'from' is equivalent to the value ''0%''.
jackalmage@5911 241 The keyword 'to' is equivalent to the value ''100%''.
jackalmage@5911 242 <span class='note'>Note that the percentage unit specifier must be used on percentage values.
jackalmage@5911 243 Therefore, ''0'' is an invalid keyframe selector.</span>
jackalmage@5911 244
jackalmage@5911 245 <p>
jackalmage@5911 246 If a ''0%'' or ''from'' keyframe is not specified,
jackalmage@5911 247 then the user agent constructs a ''0%'' keyframe
jackalmage@5911 248 using the computed values of the properties being animated.
jackalmage@5911 249 If a ''100%'' or ''to'' keyframe is not specified,
jackalmage@5911 250 then the user agent constructs a ''100%'' keyframe
jackalmage@5911 251 using the computed values of the properties being animated.
jackalmage@5911 252
jackalmage@5911 253 <p>
jackalmage@5911 254 The <dfn>keyframe declaration</dfn> for a keyframe rule
jackalmage@5911 255 consists of properties and values.
jackalmage@5911 256 Properties that are unable to be animated are ignored in these rules,
jackalmage@5911 257 with the exception of 'animation-timing-function',
jackalmage@5911 258 the behavior of which is described below.
jackalmage@5911 259
jackalmage@5911 260 <p class="issue">
jackalmage@5911 261 Need to describe what happens if a property is not present in all keyframes.
jackalmage@5911 262
jackalmage@5911 263 <p>
jackalmage@5911 264 The @keyframes rule that is used by an animation
jackalmage@5911 265 will be the last one encountered in sorted rules order
jackalmage@5911 266 that matches the name of the animation specified by the 'animation-name' property.
jackalmage@5911 267 @keyframes rules do not cascade;
jackalmage@5911 268 therefore, an animation will never derive keyframes from more than one @keyframes rule.
jackalmage@5911 269
jackalmage@5911 270 <p>
jackalmage@5911 271 To determine the set of keyframes,
jackalmage@5911 272 all of the values in the selectors are sorted in increasing order by time.
jackalmage@5911 273 If there are any duplicates,
jackalmage@5911 274 then the last keyframe specified inside the @keyframes rule
jackalmage@5911 275 will be used to provide the keyframe information for that time.
jackalmage@5911 276 There is no cascading within a @keyframes rule if multiple keyframes specify the same keyframe selector values.
dino@937 277
jackalmage@5911 278 <p>
sylvaing@6047 279 If a property is not specified for a keyframe,
jackalmage@5911 280 or is specified but invalid,
jackalmage@5911 281 the animation of that property proceeds as if that keyframe did not exist.
jackalmage@5911 282 Conceptually,
jackalmage@5911 283 it is as if a set of keyframes is constructed for each property that is present in any of the keyframes,
jackalmage@5911 284 and an animation is run independently for each property.
jackalmage@5911 285
jackalmage@5911 286 <div class="example">
jackalmage@5911 287 <pre>
jackalmage@5911 288 @keyframes wobble {
jackalmage@5911 289 0% {
jackalmage@5911 290 left: 100px;
jackalmage@5911 291 }
dino@937 292
jackalmage@5911 293 40% {
jackalmage@5911 294 left: 150px;
jackalmage@5911 295 }
dino@937 296
jackalmage@5911 297 60% {
jackalmage@5911 298 left: 75px;
jackalmage@5911 299 }
dino@937 300
jackalmage@5911 301 100% {
jackalmage@5911 302 left: 100px;
jackalmage@5911 303 }
jackalmage@5911 304 }</pre>
dino@937 305
jackalmage@5911 306 <p>
jackalmage@5911 307 Four keyframes are specified for the animation named "wobble".
jackalmage@5911 308 In the first keyframe,
jackalmage@5911 309 shown at the beginning of the animation cycle,
jackalmage@5911 310 the value of the 'left' property being animated is ''100px''.
jackalmage@5911 311 By 40% of the animation duration,
jackalmage@5911 312 'left' has animated to ''150px''.
jackalmage@5911 313 At 60% of the animation duration,
jackalmage@5911 314 'left' has animated back to ''75px''.
jackalmage@5911 315 At the end of the animation cycle,
jackalmage@5911 316 the value of 'left' has returned to ''100px''.
jackalmage@5911 317 The diagram below shows the state of the animation if it were given a duration of ''10s''.
jackalmage@5911 318
jackalmage@5911 319 <div class="figure">
jackalmage@5911 320 <img src="animation1.png" alt="">
jackalmage@5911 321
jackalmage@5911 322 <p class="caption">
jackalmage@5911 323 Animations states specified by keyframes
jackalmage@5911 324 </div>
jackalmage@5911 325 </div>
dino@937 326
jackalmage@5911 327 <p>
jackalmage@5911 328 The following is the grammar for the keyframes rule.
jackalmage@5911 329
jackalmage@5911 330 <pre>
jackalmage@5911 331 keyframes_rule: KEYFRAMES_SYM S+ IDENT S* '{' S* keyframes_blocks '}' S*;
dino@937 332
jackalmage@5911 333 keyframes_blocks: [ keyframe_selector '{' S* declaration? [ ';' S* declaration? ]* '}' S* ]* ;
dbaron@4123 334
jackalmage@5911 335 keyframe_selector: [ FROM_SYM | TO_SYM | PERCENTAGE ] S* [ ',' S* [ FROM_SYM | TO_SYM | PERCENTAGE ] S* ]*;
dbaron@4123 336
jackalmage@5911 337 @{K}{E}{Y}{F}{R}{A}{M}{E}{S} {return KEYFRAMES_SYM;}
jackalmage@5911 338 {F}{R}{O}{M} {return FROM_SYM;}
jackalmage@5911 339 {T}{O} {return TO_SYM;}</pre>
dino@937 340
dino@937 341
jackalmage@5911 342 <h3 id="timing-functions">
jackalmage@5911 343 Timing functions for keyframes</h3>
dino@937 344
jackalmage@5911 345 <p>
jackalmage@5911 346 A keyframe style rule may also declare the timing function that is to be used
jackalmage@5911 347 as the animation moves to the next keyframe.
jackalmage@5911 348
jackalmage@5911 349 <div class="example">
jackalmage@5911 350 <pre>
jackalmage@5911 351 @keyframes bounce {
dino@937 352
jackalmage@5911 353 from {
jackalmage@5911 354 top: 100px;
jackalmage@5911 355 animation-timing-function: ease-out;
jackalmage@5911 356 }
dino@937 357
jackalmage@5911 358 25% {
jackalmage@5911 359 top: 50px;
jackalmage@5911 360 animation-timing-function: ease-in;
jackalmage@5911 361 }
dino@937 362
jackalmage@5911 363 50% {
jackalmage@5911 364 top: 100px;
jackalmage@5911 365 animation-timing-function: ease-out;
jackalmage@5911 366 }
dino@937 367
jackalmage@5911 368 75% {
jackalmage@5911 369 top: 75px;
jackalmage@5911 370 animation-timing-function: ease-in;
jackalmage@5911 371 }
dino@937 372
jackalmage@5911 373 to {
jackalmage@5911 374 top: 100px;
jackalmage@5911 375 }
dbaron@5370 376
jackalmage@5911 377 }</pre>
dino@937 378
jackalmage@5911 379 <p>
jackalmage@5911 380 Five keyframes are specified for the animation named "bounce".
jackalmage@5911 381 Between the first and second keyframe
jackalmage@5911 382 (i.e., between 0% and 25%)
jackalmage@5911 383 an ''ease-out'' timing function is used.
jackalmage@5911 384 Between the second and third keyframe
jackalmage@5911 385 (i.e., between 25% and 50%)
jackalmage@5911 386 an ''ease-in'' timing function is used.
jackalmage@5911 387 And so on.
jackalmage@5911 388 The effect will appear as an element that moves up the page ''50px'',
jackalmage@5911 389 slowing down as it reaches its highest point
jackalmage@5911 390 then speeding up as it falls back to ''100px''.
jackalmage@5911 391 The second half of the animation behaves in a similar manner,
jackalmage@5911 392 but only moves the element ''25px'' up the page.
jackalmage@5911 393 </div>
jackalmage@5911 394
jackalmage@5911 395 <p>
jackalmage@5911 396 A timing function specified on the "to" or 100% keyframe is ignored.
dino@937 397
jackalmage@5911 398 <p>
jackalmage@5911 399 See the 'animation-timing-function' property for more information.
dino@937 400
dino@937 401
jackalmage@5911 402 <h3 id="animation-name-property">
jackalmage@5911 403 The 'animation-name' Property</h3>
dino@937 404
jackalmage@5911 405 <p>
jackalmage@5911 406 The 'animation-name' property defines a list of animations that apply.
jackalmage@5911 407 Each name is used to select the keyframe at-rule
jackalmage@5911 408 that provides the property values for the animation.
jackalmage@5911 409 If the name does not match any keyframe at-rule,
jackalmage@5911 410 there are no properties to be animated
jackalmage@5911 411 and the animation will not execute.
jackalmage@5911 412 Furthermore,
jackalmage@5911 413 if the animation name is ''none''
jackalmage@5911 414 then there will be no animation.
jackalmage@5911 415 This can be used to override any animations coming from the cascade.
jackalmage@5911 416 If multiple animations are attempting to modify the same property,
jackalmage@5911 417 then the animation closest to the end of the list of names wins.
jackalmage@5911 418
jackalmage@5911 419 <p id="list-matching">
jackalmage@5911 420 Each animation listed by name
jackalmage@5911 421 should have a corresponding value for the other animation properties listed below.
jackalmage@5911 422 If the lists of values for the other animation properties do not have the same length,
jackalmage@5911 423 the length of the 'animation-name' list
jackalmage@5911 424 determines the number of items in each list examined when starting transitions.
jackalmage@5911 425 The lists are matched up from the first value:
jackalmage@5911 426 excess values at the end are not used.
jackalmage@5911 427 If one of the other properties doesn't have enough comma-separated values to match the number of values of 'animation-name',
jackalmage@5911 428 the UA must calculate its used value by repeating the list of values until there are enough.
jackalmage@5911 429 This truncation or repetition does not affect the computed value.
jackalmage@5911 430 <span class="note">Note: This is analogous to the behavior of the 'background-*'properties,
jackalmage@5911 431 with 'background-image' analogous to 'animation-name'.</span>
jackalmage@5911 432
dino@937 433
jackalmage@5911 434 <table class=propdef>
jackalmage@5911 435 <tr>
jackalmage@5911 436 <th>Name:</th>
jackalmage@5911 437 <td><dfn>animation-name</dfn>
jackalmage@5911 438 <tr>
jackalmage@5911 439 <th><a href="#values">Value</a>:
jackalmage@5911 440 <td>[ none | &lt;user-ident> ]#
jackalmage@5911 441 <tr>
jackalmage@5911 442 <th>Initial:
jackalmage@5911 443 <td>''none''
jackalmage@5911 444 <tr>
jackalmage@5911 445 <th>Applies To:
jackalmage@5911 446 <td>all elements
jackalmage@5911 447 <tr>
jackalmage@5911 448 <th>Inherited:
jackalmage@5911 449 <td>no
jackalmage@5911 450 <tr>
jackalmage@5911 451 <th>Computed Value:
jackalmage@5911 452 <td>As specified
jackalmage@5911 453 <tr>
jackalmage@5911 454 <th>Media:
jackalmage@5911 455 <td>visual
jackalmage@5911 456 <tr>
jackalmage@5911 457 <th>Animatable:
jackalmage@5911 458 <td>no
jackalmage@5911 459 <tr>
jackalmage@5911 460 <th>Canonical Order:
jackalmage@5911 461 <td><abbr title="follows order of property value definition">per grammar</abbr>
jackalmage@5911 462 </table>
dino@937 463
jackalmage@5911 464 <!--
jackalmage@5911 465 <p>
jackalmage@5911 466 It is possible for elements to have multiple animations running that change the same property or properties. In this case the animations combine in a manner defined by the property. For example, animations on 'opacity' will add together and animations on 'transform' will have their transformation matrices multiplied.
jackalmage@5911 467
jackalmage@5911 468 <div class="example">
jackalmage@5911 469 <p style="display:none">
jackalmage@5911 470 Example(s):
jackalmage@5911 471
jackalmage@5911 472 <pre>
jackalmage@5911 473 @keyframes 'border-bloat' {
jackalmage@5911 474 from {
jackalmage@5911 475 border-width: 0;
jackalmage@5911 476 }
jackalmage@5911 477 to {
jackalmage@5911 478 border-width: 10px;
jackalmage@5911 479 }
jackalmage@5911 480 }
dino@937 481
jackalmage@5911 482 @keyframes 'border-diet' {
jackalmage@5911 483 from {
jackalmage@5911 484 border-width: 4px;
jackalmage@5911 485 }
jackalmage@5911 486 to {
jackalmage@5911 487 border-width: 2px;
jackalmage@5911 488 }
jackalmage@5911 489 }
dino@937 490
jackalmage@5911 491 div {
jackalmage@5911 492 animation-name: 'border-bloat', 'border-diet';
jackalmage@5911 493 animation-duration: 10s, 4s;
jackalmage@5911 494 }
jackalmage@5911 495 </pre>
jackalmage@5911 496 <p>
jackalmage@5911 497 The above example has two animations executing on the same property, 'border-width'. The animations are additive. That is, the
jackalmage@5911 498 resulting value for the property will be the addition of the values from the
jackalmage@5911 499 two animations.
jackalmage@5911 500
jackalmage@5911 501 <p>
jackalmage@5911 502 At time '0s' the element's border will be 4px wide (0px from 'border-bloat' plus 4px from 'border-diet').
jackalmage@5911 503 At time '4s' the element's border will be 6px wide (4px from 'border-bloat' plus 2px from 'border-diet').
jackalmage@5911 504 At time '10s' the element's border will be 10px wide (10px from 'border-bloat' and no addition from
jackalmage@5911 505 'border-diet' as it is no longer executing).
jackalmage@5911 506
jackalmage@5911 507 </div>
jackalmage@5911 508 -->
dino@937 509
dino@937 510
jackalmage@5911 511 <h3 id="animation-duration-property">
jackalmage@5911 512 The 'animation-duration' Property</h3>
dino@937 513
jackalmage@5911 514 <p>
jackalmage@5911 515 The 'animation-duration' property defines the length of time that an animation takes to complete one cycle.
dino@937 516
jackalmage@5911 517
jackalmage@5911 518 <table class=propdef>
jackalmage@5911 519 <tr>
jackalmage@5911 520 <th>Name:</th>
jackalmage@5911 521 <td><dfn>animation-duration</dfn>
jackalmage@5911 522 <tr>
jackalmage@5911 523 <th><a href="#values">Value</a>:
jackalmage@5911 524 <td>&lt;time>#
jackalmage@5911 525 <tr>
jackalmage@5911 526 <th>Initial:
jackalmage@5911 527 <td>''0s''
jackalmage@5911 528 <tr>
jackalmage@5911 529 <th>Applies To:
jackalmage@5911 530 <td>all elements
jackalmage@5911 531 <tr>
jackalmage@5911 532 <th>Inherited:
jackalmage@5911 533 <td>no
jackalmage@5911 534 <tr>
jackalmage@5911 535 <th>Computed Value:
jackalmage@5911 536 <td>as specified
jackalmage@5911 537 <tr>
jackalmage@5911 538 <th>Media:
jackalmage@5911 539 <td>visual
jackalmage@5911 540 <tr>
jackalmage@5911 541 <th>Animatable:
jackalmage@5911 542 <td>no
jackalmage@5911 543 <tr>
jackalmage@5911 544 <th>Canonical Order:
jackalmage@5911 545 <td><abbr title="follows order of property value definition">per grammar</abbr>
jackalmage@5911 546 </table>
jackalmage@5911 547
jackalmage@5911 548 <p>
jackalmage@5911 549 The initial value is ''0s'',
jackalmage@5911 550 meaning that the animation takes no time.
jackalmage@5911 551 A negative value for 'animation-duration' is treated as ''0s''.
jackalmage@5911 552 In this case 'animation-fill-mode' still applies,
jackalmage@5911 553 so an animation that fills backwards
jackalmage@5911 554 will show the value of the 0% keyframe during any delay period,
jackalmage@5911 555 and an animation that fills forwards will retain the value specified at the 100% keyframe,
jackalmage@5911 556 even if the animation was instantaneous.
jackalmage@5911 557 Also, animation events are still fired.
jackalmage@5911 558
jackalmage@5911 559
jackalmage@5911 560 <h3 id="animation-timing-function-property">
jackalmage@5911 561 The 'animation-timing-function' Property</h3>
jackalmage@5911 562
jackalmage@5911 563 <p>
jackalmage@5911 564 The 'animation-timing-function' property describes how the animation will progress over one cycle of its duration.
jackalmage@5911 565 See the 'transition-timing-function' property [[!CSS3-TRANSITIONS]] for a complete description of timing function calculation.
jackalmage@5911 566
jackalmage@5911 567 <table class=propdef>
jackalmage@5911 568 <tr>
jackalmage@5911 569 <th>Name:</th>
jackalmage@5911 570 <td><dfn>animation-timing-function</dfn>
jackalmage@5911 571 <tr>
jackalmage@5911 572 <th><a href="#values">Value</a>:
jackalmage@5911 573 <td>[
jackalmage@5911 574 ease | linear | ease-in | ease-out | ease-in-out |
jackalmage@5911 575 step-start | step-end |
jackalmage@5911 576 steps(&lt;number> [, [ start | end ] ]) |
jackalmage@5911 577 cubic-bezier(&lt;number>, &lt;number>, &lt;number>, &lt;number>)
jackalmage@5911 578 ]#
jackalmage@5911 579 <tr>
jackalmage@5911 580 <th>Initial:
jackalmage@5911 581 <td>''ease''
jackalmage@5911 582 <tr>
jackalmage@5911 583 <th>Applies To:
jackalmage@5911 584 <td>all elements
jackalmage@5911 585 <tr>
jackalmage@5911 586 <th>Inherited:
jackalmage@5911 587 <td>no
jackalmage@5911 588 <tr>
jackalmage@5911 589 <th>Computed Value:
jackalmage@5911 590 <td>as specified
jackalmage@5911 591 <tr>
jackalmage@5911 592 <th>Media:
jackalmage@5911 593 <td>visual
jackalmage@5911 594 <tr>
jackalmage@5911 595 <th>Animatable:
jackalmage@5911 596 <td>no
jackalmage@5911 597 <tr>
jackalmage@5911 598 <th>Canonical Order:
jackalmage@5911 599 <td><abbr title="follows order of property value definition">per grammar</abbr>
jackalmage@5911 600 </table>
jackalmage@5911 601
jackalmage@5911 602 <p>
jackalmage@5911 603 For a keyframed animation,
jackalmage@5911 604 the 'animation-timing-function' applies between keyframes,
jackalmage@5911 605 not over the entire animation.
jackalmage@5911 606 For example,
jackalmage@5911 607 in the case of an ''ease-in-out'' timing function,
jackalmage@5911 608 an animation will ease in at the start of the keyframe
jackalmage@5911 609 and ease out at the end of the keyframe.
jackalmage@5911 610 An 'animation-timing-function' defined within a keyframe block applies to that keyframe,
jackalmage@5911 611 otherwise the timing function specified for the animation is used.
jackalmage@5911 612
jackalmage@5911 613
jackalmage@5911 614 <h3 id="animation-iteration-count-property">
jackalmage@5911 615 The 'animation-iteration-count' Property</h3>
jackalmage@5911 616
jackalmage@5911 617 <p>
jackalmage@5911 618 The 'animation-iteration-count' property specifies the number of times an animation cycle is played.
jackalmage@5911 619 The initial value is ''1'',
jackalmage@5911 620 meaning the animation will play from beginning to end once.
jackalmage@5911 621 A value of ''infinite'' will cause the animation to repeat forever.
jackalmage@5911 622 Non-integer numbers will cause the animation to end part-way through a cycle.
jackalmage@5911 623 Negative values of 'animation-iteration-count' are invalid.
jackalmage@5911 624 This property is often used in conjunction an 'animation-direction' value of ''alternate'',
jackalmage@5911 625 which will cause the animation to play in reverse on alternate cycles.
jackalmage@5911 626
jackalmage@5911 627 <table class=propdef>
jackalmage@5911 628 <tr>
jackalmage@5911 629 <th>Name:</th>
jackalmage@5911 630 <td><dfn>animation-iteration-count</dfn>
jackalmage@5911 631 <tr>
jackalmage@5911 632 <th><a href="#values">Value</a>:
jackalmage@5911 633 <td>[ infinite | &lt;number> ]#
jackalmage@5911 634 <tr>
jackalmage@5911 635 <th>Initial:
jackalmage@5911 636 <td>''1''
jackalmage@5911 637 <tr>
jackalmage@5911 638 <th>Applies To:
jackalmage@5911 639 <td>all elements
jackalmage@5911 640 <tr>
jackalmage@5911 641 <th>Inherited:
jackalmage@5911 642 <td>no
jackalmage@5911 643 <tr>
jackalmage@5911 644 <th>Computed Value:
jackalmage@5911 645 <td>as specified
jackalmage@5911 646 <tr>
jackalmage@5911 647 <th>Media:
jackalmage@5911 648 <td>visual
jackalmage@5911 649 <tr>
jackalmage@5911 650 <th>Animatable:
jackalmage@5911 651 <td>no
jackalmage@5911 652 <tr>
jackalmage@5911 653 <th>Canonical Order:
jackalmage@5911 654 <td><abbr title="follows order of property value definition">per grammar</abbr>
jackalmage@5911 655 </table>
jackalmage@5911 656
jackalmage@5911 657
jackalmage@5911 658 <h3 id="animation-direction-property">
jackalmage@5911 659 The 'animation-direction' Property</h3>
jackalmage@5911 660
jackalmage@5911 661 <p>
jackalmage@5911 662 The 'animation-direction' property defines whether or not the animation should play in reverse on some or all cycles.
jackalmage@5911 663 When an animation is played in reverse the timing functions are also reversed.
jackalmage@5911 664 For example, when played in reverse an ease-in animation would appear to be an ease-out animation.
jackalmage@5911 665
jackalmage@5911 666 <table class=propdef>
jackalmage@5911 667 <tr>
jackalmage@5911 668 <th>Name:</th>
jackalmage@5911 669 <td><dfn>animation-direction</dfn>
jackalmage@5911 670 <tr>
jackalmage@5911 671 <th><a href="#values">Value</a>:
jackalmage@5911 672 <td>[ normal | reverse | alternate | alternate-reverse ]#
jackalmage@5911 673 <tr>
jackalmage@5911 674 <th>Initial:
jackalmage@5911 675 <td>''normal''
jackalmage@5911 676 <tr>
jackalmage@5911 677 <th>Applies To:
jackalmage@5911 678 <td>all elements
jackalmage@5911 679 <tr>
jackalmage@5911 680 <th>Inherited:
jackalmage@5911 681 <td>no
jackalmage@5911 682 <tr>
jackalmage@5911 683 <th>Computed Value:
jackalmage@5911 684 <td>as specified
jackalmage@5911 685 <tr>
jackalmage@5911 686 <th>Media:
jackalmage@5911 687 <td>visual
jackalmage@5911 688 <tr>
jackalmage@5911 689 <th>Animatable:
jackalmage@5911 690 <td>no
jackalmage@5911 691 <tr>
jackalmage@5911 692 <th>Canonical Order:
jackalmage@5911 693 <td><abbr title="follows order of property value definition">per grammar</abbr>
jackalmage@5911 694 </table>
jackalmage@5911 695
jackalmage@5911 696 <dl>
jackalmage@5911 697 <dt><dfn>normal</dfn>
jackalmage@5911 698 <dd>
jackalmage@5911 699 All iterations of the animation are played as specified.
jackalmage@5911 700
jackalmage@5911 701 <dt><dfn>reverse</dfn>
jackalmage@5911 702 <dd>
jackalmage@5911 703 All iterations of the animation are played in the reverse direction from the way they were specified.
jackalmage@5911 704
jackalmage@5911 705 <dt><dfn>alternate</dfn>
jackalmage@5911 706 <dd>
jackalmage@5911 707 The animation cycle iterations that are odd counts are played in the normal direction,
jackalmage@5911 708 and the animation cycle iterations that are even counts are played in a reverse direction.
jackalmage@5911 709
jackalmage@5911 710 <dt><dfn>alternate-reverse</dfn>
jackalmage@5911 711 <dd>
jackalmage@5911 712 The animation cycle iterations that are odd counts are played in the reverse direction,
jackalmage@5911 713 and the animation cycle iterations that are even counts are played in a normal direction.
jackalmage@5911 714 </dl>
jackalmage@5911 715
jackalmage@5911 716 <p class='note'>
jackalmage@5911 717 Note that for the purpose of determining whether an iteration is even or odd,
jackalmage@5911 718 iterations start counting from 1.
jackalmage@5911 719
jackalmage@5911 720
jackalmage@5911 721 <h3 id="animation-play-state-property">
jackalmage@5911 722 The 'animation-play-state' Property</h3>
jackalmage@5911 723
jackalmage@5911 724 <p>
jackalmage@5911 725 The 'animation-play-state' property defines whether the animation is running or paused.
jackalmage@5911 726 A running animation can be paused by setting this property to ''paused''.
jackalmage@5911 727 To continue running a paused animation this property can be set to ''running''.
jackalmage@5911 728 A paused animation will continue to display the current value of the animation in a static state,
jackalmage@5911 729 as if the time of the animation is constant.
jackalmage@5911 730 When a paused animation is resumed,
jackalmage@5911 731 it restarts from the current value,
jackalmage@5911 732 not necessarily from the beginning of the animation.
jackalmage@5911 733
jackalmage@5911 734 <table class=propdef>
jackalmage@5911 735 <tr>
jackalmage@5911 736 <th>Name:</th>
jackalmage@5911 737 <td><dfn>animation-play-state</dfn>
jackalmage@5911 738 <tr>
jackalmage@5911 739 <th><a href="#values">Value</a>:
jackalmage@5911 740 <td>[ running | paused ]#
jackalmage@5911 741 <tr>
jackalmage@5911 742 <th>Initial:
jackalmage@5911 743 <td>''running''
jackalmage@5911 744 <tr>
jackalmage@5911 745 <th>Applies To:
jackalmage@5911 746 <td>all elements
jackalmage@5911 747 <tr>
jackalmage@5911 748 <th>Inherited:
jackalmage@5911 749 <td>no
jackalmage@5911 750 <tr>
jackalmage@5911 751 <th>Computed Value:
jackalmage@5911 752 <td>as specified
jackalmage@5911 753 <tr>
jackalmage@5911 754 <th>Media:
jackalmage@5911 755 <td>visual
jackalmage@5911 756 <tr>
jackalmage@5911 757 <th>Animatable:
jackalmage@5911 758 <td>no
jackalmage@5911 759 <tr>
jackalmage@5911 760 <th>Canonical Order:
jackalmage@5911 761 <td><abbr title="follows order of property value definition">per grammar</abbr>
jackalmage@5911 762 </table>
jackalmage@5911 763
jackalmage@5911 764
jackalmage@5911 765 <h3 id="animation-delay-property">
jackalmage@5911 766 The 'animation-delay' Property</h3>
jackalmage@5911 767
jackalmage@5911 768 <p>
jackalmage@5911 769 The 'animation-delay' property defines when the animation will start.
jackalmage@5911 770 It allows an animation to begin execution some time after it is applied.
jackalmage@5911 771 An 'animation-delay' value of ''0s'' means the animation will execute as soon as it is applied.
jackalmage@5911 772 Otherwise, the value specifies an offset from the moment the animation is applied,
jackalmage@5911 773 and the animation will delay execution by that offset.
jackalmage@5911 774
jackalmage@5911 775 <p>
jackalmage@5911 776 If the value for 'animation-delay' is a negative time offset
jackalmage@5911 777 then the animation will execute the moment it is applied,
jackalmage@5911 778 but will appear to have begun execution at the specified offset.
jackalmage@5911 779 That is, the animation will appear to begin part-way through its play cycle.
jackalmage@5911 780 In the case where an animation has implied starting values and a negative 'animation-delay',
jackalmage@5911 781 the starting values are taken from the moment the animation is applied.
jackalmage@5911 782
jackalmage@5911 783 <table class=propdef>
jackalmage@5911 784 <tr>
jackalmage@5911 785 <th>Name:</th>
jackalmage@5911 786 <td><dfn>foo</dfn>
jackalmage@5911 787 <tr>
jackalmage@5911 788 <th><a href="#values">animation-delay</a>:
jackalmage@5911 789 <td>&lt;time>#
jackalmage@5911 790 <tr>
jackalmage@5911 791 <th>Initial:
jackalmage@5911 792 <td>''0s''
jackalmage@5911 793 <tr>
jackalmage@5911 794 <th>Applies To:
jackalmage@5911 795 <td>all elements
jackalmage@5911 796 <tr>
jackalmage@5911 797 <th>Inherited:
jackalmage@5911 798 <td>no
jackalmage@5911 799 <tr>
jackalmage@5911 800 <th>Computed Value:
jackalmage@5911 801 <td>as specified
jackalmage@5911 802 <tr>
jackalmage@5911 803 <th>Media:
jackalmage@5911 804 <td>visual
jackalmage@5911 805 <tr>
jackalmage@5911 806 <th>Animatable:
jackalmage@5911 807 <td>no
jackalmage@5911 808 <tr>
jackalmage@5911 809 <th>Canonical Order:
jackalmage@5911 810 <td><abbr title="follows order of property value definition">per grammar</abbr>
jackalmage@5911 811 </table>
jackalmage@5911 812
jackalmage@5911 813
jackalmage@5911 814 <h3 id="animation-fill-mode-property">
jackalmage@5911 815 The 'animation-fill-mode' Property</h3>
jackalmage@5911 816
jackalmage@5911 817 <p>
jackalmage@5911 818 The 'animation-fill-mode' property defines what values are applied by the animation outside the time it is executing.
jackalmage@5911 819 By default, an animation will not affect property values
jackalmage@5911 820 between the time it is applied
jackalmage@5911 821 (the 'animation-name' property is set on an element)
jackalmage@5911 822 and the time it begins execution
jackalmage@5911 823 (which is determined by the 'animation-delay' property).
jackalmage@5911 824 Also, by default an animation does not affect property values after the animation ends
jackalmage@5911 825 (determined by the 'animation-duration' property).
jackalmage@5911 826 The 'animation-fill-mode' property can override this behavior.
jackalmage@5911 827
jackalmage@5911 828 <p>
jackalmage@5911 829 If the value for 'animation-fill-mode' is ''backwards'',
jackalmage@5911 830 then the animation will apply the property values defined in its 0% or 'from' keyframe
jackalmage@5911 831 as soon as the animation is applied,
jackalmage@5911 832 during the period defined by 'animation-delay'.
jackalmage@5911 833
jackalmage@5911 834 <p>
jackalmage@5911 835 If the value for 'animation-fill-mode' is ''forwards'',
jackalmage@5911 836 then the animation will apply the property values defined in its last executing keyframe
jackalmage@5911 837 after the final iteration of the animation,
jackalmage@5911 838 until the animation style is removed.
jackalmage@5911 839 The last executing keyframe is the 'to' or '100%' keyframe,
jackalmage@5911 840 unless the animation has 'animation-direction' set to ''alternate''
jackalmage@5911 841 and both a finite and even iteration count,
jackalmage@5911 842 in which case it is the 'from' or '0%' keyframe.
jackalmage@5911 843
jackalmage@5911 844 <p>
jackalmage@5911 845 If the value for 'animation-fill-mode' is ''both'',
jackalmage@5911 846 then the animation will follow the rules for both 'forwards' and 'backwards'.
jackalmage@5911 847 That is, it will extend the animation properties in both directions.
jackalmage@5911 848
jackalmage@5911 849 <table class=propdef>
jackalmage@5911 850 <tr>
jackalmage@5911 851 <th>Name:</th>
jackalmage@5911 852 <td><dfn>animation-fill-mode</dfn>
jackalmage@5911 853 <tr>
jackalmage@5911 854 <th><a href="#values">Value</a>:
jackalmage@5911 855 <td>[ none | forwards | backwards | both ]#
jackalmage@5911 856 <tr>
jackalmage@5911 857 <th>Initial:
jackalmage@5911 858 <td>''none''
jackalmage@5911 859 <tr>
jackalmage@5911 860 <th>Applies To:
jackalmage@5911 861 <td>all elements
jackalmage@5911 862 <tr>
jackalmage@5911 863 <th>Inherited:
jackalmage@5911 864 <td>no
jackalmage@5911 865 <tr>
jackalmage@5911 866 <th>Computed Value:
jackalmage@5911 867 <td>as specified
jackalmage@5911 868 <tr>
jackalmage@5911 869 <th>Media:
jackalmage@5911 870 <td>visual
jackalmage@5911 871 <tr>
jackalmage@5911 872 <th>Animatable:
jackalmage@5911 873 <td>no
jackalmage@5911 874 <tr>
jackalmage@5911 875 <th>Canonical Order:
jackalmage@5911 876 <td><abbr title="follows order of property value definition">per grammar</abbr>
jackalmage@5911 877 </table>
jackalmage@5911 878
jackalmage@5911 879
jackalmage@5911 880 <h3 id="animation-shorthand-property">
jackalmage@5911 881 The 'animation' Shorthand Property
jackalmage@5911 882
jackalmage@5911 883 <p>
jackalmage@5911 884 The 'animation' shorthand property combines seven of the animation properties into a single property.
jackalmage@5911 885
jackalmage@5911 886 <p>
jackalmage@5911 887 Note that order is important in this property.
jackalmage@5911 888 The first value that can be parsed as a <var>&lt;time></var> is assigned to the 'animation-duration'.
jackalmage@5911 889 The second value that can be parsed as a <var>&lt;time></var> is assigned to 'animation-delay'.
jackalmage@5911 890
jackalmage@5911 891 <p class="issue">
jackalmage@5911 892 An alternative proposal is to accept the font shorthand approach
jackalmage@5911 893 of using a "/" character between the values of the same type.
jackalmage@5911 894 e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
jackalmage@5911 895
jackalmage@5911 896 <table class=propdef>
jackalmage@5911 897 <tr>
jackalmage@5911 898 <th>Name:</th>
jackalmage@5911 899 <td><dfn>animation</dfn>
jackalmage@5911 900 <tr>
jackalmage@5911 901 <th><a href="#values">Value</a>:
jackalmage@5911 902 <td>[ &lt;'animation-name'> ||
jackalmage@5911 903 &lt;'animation-duration'> ||
jackalmage@5911 904 &lt;'animation-timing-function'> ||
jackalmage@5911 905 &lt;'animation-delay'> ||
jackalmage@5911 906 &lt;'animation-iteration-count'> ||
jackalmage@5911 907 &lt;'animation-direction'> ||
jackalmage@5911 908 &lt;'animation-fill-mode'> ]#
jackalmage@5911 909 <tr>
jackalmage@5911 910 <th>Initial:
jackalmage@5911 911 <td>see individual properties
jackalmage@5911 912 <tr>
jackalmage@5911 913 <th>Applies To:
jackalmage@5911 914 <td>all elements
jackalmage@5911 915 <tr>
jackalmage@5911 916 <th>Inherited:
jackalmage@5911 917 <td>see individual properties
jackalmage@5911 918 <tr>
jackalmage@5911 919 <th>Computed Value:
jackalmage@5911 920 <td>see individual properties
jackalmage@5911 921 <tr>
jackalmage@5911 922 <th>Media:
jackalmage@5911 923 <td>visual
jackalmage@5911 924 <tr>
jackalmage@5911 925 <th>Animatable:
jackalmage@5911 926 <td>no
jackalmage@5911 927 <tr>
jackalmage@5911 928 <th>Canonical Order:
jackalmage@5911 929 <td><abbr title="follows order of property value definition">per grammar</abbr>
jackalmage@5911 930 </table>
jackalmage@5911 931
jackalmage@5911 932
jackalmage@5911 933 <h2 id="animation-events">
jackalmage@5911 934 Animation Events</h2>
jackalmage@5911 935
jackalmage@5911 936 <p>
jackalmage@5911 937 Several animation related events are available through the <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html">DOM Event system</a>.
jackalmage@5911 938 The start and end of an animation,
jackalmage@5911 939 and the end of each iteration of an animation,
jackalmage@5911 940 all generate DOM events.
jackalmage@5911 941 An element can have multiple properties being animated simultaneously.
jackalmage@5911 942 This can occur either with a single 'animation-name' value
jackalmage@5911 943 with keyframes containing multiple properties,
jackalmage@5911 944 or with multiple 'animation-name' values.
jackalmage@5911 945 For the purposes of events,
jackalmage@5911 946 each 'animation-name' specifies a single animation.
jackalmage@5911 947 Therefore an event will be generated for each 'animation-name' value
jackalmage@5911 948 and not necessarily for each property being animated.
jackalmage@5911 949
jackalmage@5911 950 <p>
jackalmage@5911 951 The time the animation has been running is sent with each event generated.
jackalmage@5911 952 This allows the event handler to determine the current iteration of a looping animation
jackalmage@5911 953 or the current position of an alternating animation.
jackalmage@5911 954 This time does not include any time the animation was in the ''paused'' play state.
jackalmage@5911 955
jackalmage@5911 956
jackalmage@5911 957 <h3 id='AnimationEvent-interface'>
jackalmage@5911 958 Interface <code>AnimationEvent</code>
jackalmage@5911 959
jackalmage@5911 960 <p>
jackalmage@5911 961 The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
jackalmage@5911 962
jackalmage@5911 963
jackalmage@5911 964 <h4 id='AnimationEvent-IDL'>
jackalmage@5911 965 IDL Definition</h4>
jackalmage@5911 966
jackalmage@5911 967 <pre class='idl'>
jackalmage@5911 968 interface AnimationEvent : Event {
jackalmage@5911 969 readonly attribute DOMString animationName;
jackalmage@5911 970 readonly attribute float elapsedTime;
jackalmage@5911 971 void initAnimationEvent(in DOMString typeArg,
jackalmage@5911 972 in boolean canBubbleArg,
jackalmage@5911 973 in boolean cancelableArg,
jackalmage@5911 974 in DOMString animationNameArg,
jackalmage@5911 975 in float elapsedTimeArg);
jackalmage@5911 976 };</pre>
jackalmage@5911 977
jackalmage@5911 978
jackalmage@5911 979 <h4 id='AnimationEvent-attributes'>
jackalmage@5911 980 Attributes</h4>
jackalmage@5911 981
jackalmage@5911 982 <dl>
jackalmage@5911 983 <dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
jackalmage@5911 984 <dd>
jackalmage@5911 985 The value of the 'animation-name' property of the animation that fired the event.
jackalmage@5911 986
jackalmage@5911 987 <dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
jackalmage@5911 988 <dd>
jackalmage@5911 989 The amount of time the animation has been running,
jackalmage@5911 990 in seconds,
jackalmage@5911 991 when this event fired,
jackalmage@5911 992 excluding any time the animation was paused.
jackalmage@5911 993 For an "animationstart" event,
jackalmage@5911 994 the elapsedTime is zero unless there was a negative value for 'animation-delay',
jackalmage@5911 995 in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
jackalmage@5911 996 </dl>
jackalmage@5911 997
jackalmage@5911 998
jackalmage@5911 999 <h4 id='AnimationEvent-initAnimationMethod'>
jackalmage@5911 1000 The <code>initAnimationEvent</code> method</h4>
jackalmage@5911 1001
jackalmage@5911 1002 <p>
jackalmage@5911 1003 The <dfn>initAnimationEvent</dfn> method is used to initialize the value of an <code>AnimationEvent</code>
jackalmage@5911 1004 created through the <a href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-DocumentEvent'><code>DocumentEvent</code></a> interface.
jackalmage@5911 1005 This method may only be called before the <code>AnimationEvent</code> has been dispatched
jackalmage@5911 1006 via the <code>dispatchEvent</code> method,
jackalmage@5911 1007 though it may be called multiple times during that phase if necessary.
jackalmage@5911 1008 If called multiple times,
jackalmage@5911 1009 the final invocation takes precedence.
jackalmage@5911 1010
jackalmage@5911 1011 <p>
jackalmage@5911 1012 Parameters:
jackalmage@5911 1013
jackalmage@5911 1014 <dl>
jackalmage@5911 1015 <dt><code>typeArg</code> of type <code>DOMString</code>
jackalmage@5911 1016 <dd>
jackalmage@5911 1017 Specifies the event type.
jackalmage@5911 1018
jackalmage@5911 1019 <dt><code>canBubbleArg</code> of type <code>boolean</code>
jackalmage@5911 1020 <dd>
jackalmage@5911 1021 Specifies whether or not the event can bubble.<br>
jackalmage@5911 1022
jackalmage@5911 1023 <dt><code>cancelableArg</code> of type <code>boolean</code>
jackalmage@5911 1024 <dd>
jackalmage@5911 1025 Specifies whether or not the event's default action can be prevented.
jackalmage@5911 1026
jackalmage@5911 1027 <dt><code>animationNameArg</code> of type <code>DOMString</code>
jackalmage@5911 1028 <dd>
jackalmage@5911 1029 Specifies the <a href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-Event'><code>Event</code></a>'s animation name.<br>
jackalmage@5911 1030
jackalmage@5911 1031 <dt><code>elapsedTimeArg</code> of type <code>float</code>
jackalmage@5911 1032 <dd>
jackalmage@5911 1033 Specifies the amount of time,
jackalmage@5911 1034 in seconds,
jackalmage@5911 1035 the animation has been running at the time of initialization.
jackalmage@5911 1036 </dl>
jackalmage@5911 1037
jackalmage@5911 1038 <p>
jackalmage@5911 1039 No Return Value
jackalmage@5911 1040
jackalmage@5911 1041 <p>
jackalmage@5911 1042 No Exceptions
jackalmage@5911 1043
jackalmage@5911 1044 <h3 id='AnimationEvent-types'>
jackalmage@5911 1045 Types of <code>AnimationEvent</code></h3>
jackalmage@5911 1046
jackalmage@5911 1047 <p>
jackalmage@5911 1048 The different types of Animation events that can occur are:
jackalmage@5911 1049
jackalmage@5911 1050 <dl>
jackalmage@5911 1051 <dt><dfn>animationstart</dfn>
jackalmage@5911 1052 <dd>
jackalmage@5911 1053 The <code>animationstart</code> event occurs at the start of the animation.
jackalmage@5911 1054 If there is an 'animation-delay'
jackalmage@5911 1055 then this event will fire once the delay period has expired.
jackalmage@5911 1056 A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
jackalmage@5911 1057
jackalmage@5911 1058 <ul>
jackalmage@5911 1059 <li>Bubbles: Yes
jackalmage@5911 1060 <li>Cancelable: No
jackalmage@5911 1061 <li>Context Info: animationName
jackalmage@5911 1062 </ul>
jackalmage@5911 1063
jackalmage@5911 1064 <dt><dfn>animationend</dfn>
jackalmage@5911 1065 <dd>
jackalmage@5911 1066 The <code>animationend</code> event occurs when the animation finishes.
jackalmage@5911 1067
jackalmage@5911 1068 <ul>
jackalmage@5911 1069 <li>Bubbles: Yes
jackalmage@5911 1070 <li>Cancelable: No
jackalmage@5911 1071 <li>Context Info: animationName, elapsedTime
jackalmage@5911 1072 </ul>
jackalmage@5911 1073
jackalmage@5911 1074 <dt><dfn>animationiteration</dfn>
jackalmage@5911 1075 <dd>
jackalmage@5911 1076 The <code>animationiteration</code> event occurs at the end of each iteration of an animation,
jackalmage@5911 1077 except when an <code>animationend</code> event would fire at the same time.
jackalmage@5911 1078 This means that this event does not occur for animations with an iteration count of one or less.
jackalmage@5911 1079
jackalmage@5911 1080 <ul>
jackalmage@5911 1081 <li>Bubbles: Yes
jackalmage@5911 1082 <li>Cancelable: No
jackalmage@5911 1083 <li>Context Info: animationName, elapsedTime
jackalmage@5911 1084 </ul>
jackalmage@5911 1085 </dl>
jackalmage@5911 1086
jackalmage@5911 1087
jackalmage@5911 1088 <h2 id="dom-interfaces">
jackalmage@5911 1089 DOM Interfaces</h2>
jackalmage@5911 1090
jackalmage@5911 1091 <p>
jackalmage@5911 1092 CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
jackalmage@5911 1093
jackalmage@5911 1094
jackalmage@5911 1095 <h3 id='CSSRule-interface'>
jackalmage@5911 1096 Interface <code>CSSRule</code></h3>
jackalmage@5911 1097
jackalmage@5911 1098 <p>
jackalmage@5911 1099 The following 2 rule types are added to the <dfn>CSSRule</dfn> interface.
jackalmage@5911 1100 They provide identification for the new keyframe and keyframes rules.
jackalmage@5911 1101
jackalmage@5911 1102
jackalmage@5911 1103 <h4 id='CSSRule-IDL'>
jackalmage@5911 1104 IDL Definition</h4>
jackalmage@5911 1105
jackalmage@5911 1106 <pre class='idl'>
jackalmage@5911 1107 interface CSSRule {
jackalmage@5911 1108 ...
jackalmage@5911 1109 const unsigned short KEYFRAMES_RULE = 7;
jackalmage@5911 1110 const unsigned short KEYFRAME_RULE = 8;
jackalmage@5911 1111 ...
jackalmage@5911 1112 };</pre>
jackalmage@5911 1113
jackalmage@5911 1114
jackalmage@5911 1115 <h3 id='CSSKeyframeRule-interface'>
jackalmage@5911 1116 Interface <code>CSSKeyframeRule</code></3h>
jackalmage@5911 1117 <p>
jackalmage@5911 1118 The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
jackalmage@5911 1119
jackalmage@5911 1120
jackalmage@5911 1121 <h4 id='CSSKeyframeRule-IDL'>
jackalmage@5911 1122 IDL Definition</h4>
jackalmage@5911 1123
jackalmage@5911 1124 <pre class='idl'>
jackalmage@5911 1125 interface CSSKeyframeRule : CSSRule {
jackalmage@5911 1126 attribute DOMString keyText;
jackalmage@5911 1127 readonly attribute CSSStyleDeclaration style;
jackalmage@5911 1128 };</pre>
jackalmage@5911 1129
jackalmage@5911 1130
jackalmage@5911 1131 <h4 id='CSSKeyframeRule-attributes'>
jackalmage@5911 1132 Attributes</h4>
jackalmage@5911 1133
jackalmage@5911 1134 <dl>
jackalmage@5911 1135 <dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
jackalmage@5911 1136 <dd>
jackalmage@5911 1137 This attribute represents the key
jackalmage@5911 1138 as the string representation of a floating point number between 0 and 1.
jackalmage@5911 1139 If the value in the CSS style is ''from''
jackalmage@5911 1140 this value will be 0,
jackalmage@5911 1141 and if the value in the CSS style is ''to''
jackalmage@5911 1142 this value will be 1.
jackalmage@5911 1143
jackalmage@5911 1144 <dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
jackalmage@5911 1145 <dd>
jackalmage@5911 1146 This attribute represents the style associated with this keyframe.
jackalmage@5911 1147 </dl>
jackalmage@5911 1148
jackalmage@5911 1149
jackalmage@5911 1150 <h3 id='CSSKeyframesRule-interface'>
jackalmage@5911 1151 Interface <code>CSSKeyframesRule</code></h3>
jackalmage@5911 1152
jackalmage@5911 1153 <p>
jackalmage@5911 1154 The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
jackalmage@5911 1155
jackalmage@5911 1156
jackalmage@5911 1157 <h4 id='CSSKeyframesRule-IDL'>
jackalmage@5911 1158 IDL Definition</h4>
jackalmage@5911 1159
jackalmage@5911 1160 <pre class='idl'>
jackalmage@5911 1161 interface CSSKeyframesRule : CSSRule {
jackalmage@5911 1162 attribute DOMString name;
jackalmage@5911 1163 readonly attribute CSSRuleList cssRules;
jackalmage@5911 1164
jackalmage@5911 1165 void appendRule(in DOMString rule);
jackalmage@5911 1166 void deleteRule(in DOMString key);
jackalmage@5911 1167 CSSKeyframeRule findRule(in DOMString key);
jackalmage@5911 1168 };</pre>
jackalmage@5911 1169
jackalmage@5911 1170
jackalmage@5911 1171 <h4 id='CSSKeyframesRule-attributes'>
jackalmage@5911 1172 Attributes</h4>
jackalmage@5911 1173
jackalmage@5911 1174 <dl>
jackalmage@5911 1175 <dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
jackalmage@5911 1176 <dd>
jackalmage@5911 1177 This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
jackalmage@5911 1178
jackalmage@5911 1179 <dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
jackalmage@5911 1180 <dd>
jackalmage@5911 1181 This attribute gives access to the keyframes in the list.
jackalmage@5911 1182
jackalmage@5911 1183
jackalmage@5911 1184 <h4 id='CSSKeyframesRule-appendRule'>
jackalmage@5911 1185 The <code>appendRule</code> method</h4>
jackalmage@5911 1186
jackalmage@5911 1187 <p>
jackalmage@5911 1188 The <dfn>appendRule</dfn> method appends the passed CSSKeyframeRule into the list at the passed key.
jackalmage@5911 1189
jackalmage@5911 1190 <p>
jackalmage@5911 1191 Parameters:
jackalmage@5911 1192
jackalmage@5911 1193 <dl>
jackalmage@5911 1194 <dt><code>rule</code> of type <code>DOMString</code>
jackalmage@5911 1195
jackalmage@5911 1196 <dd>
jackalmage@5911 1197 The rule to be appended,
jackalmage@5911 1198 expressed in the same syntax as one entry in the ''@keyframes'' rule.
jackalmage@5911 1199 </dl>
jackalmage@5911 1200
jackalmage@5911 1201 <p>
jackalmage@5911 1202 No Return Value
jackalmage@5911 1203
jackalmage@5911 1204 <p>
jackalmage@5911 1205 No Exceptions
jackalmage@5911 1206
jackalmage@5911 1207
jackalmage@5911 1208 <h4 id='CSSKeyframesRules-deleteRule'>
jackalmage@5911 1209 The <code>deleteRule</code> method</h4>
jackalmage@5911 1210
jackalmage@5911 1211 <p>
jackalmage@5911 1212 The <dfn>deleteRule</dfn> method deletes the CSSKeyframeRule with the passed key.
jackalmage@5911 1213 If a rule with this key does not exist,
jackalmage@5911 1214 the method does nothing.
jackalmage@5911 1215
jackalmage@5911 1216 <p>
jackalmage@5911 1217 Parameters:
jackalmage@5911 1218
jackalmage@5911 1219 <dl>
jackalmage@5911 1220 <dt><code>key</code> of type <code>DOMString</code>
jackalmage@5911 1221 <dd>
jackalmage@5911 1222 The key which describes the rule to be deleted.
jackalmage@5911 1223 The key must resolve to a number between 0 and 1,
jackalmage@5911 1224 or the rule is ignored.
jackalmage@5911 1225 </dl>
jackalmage@5911 1226
jackalmage@5911 1227 <p>
jackalmage@5911 1228 No Return Value
jackalmage@5911 1229
jackalmage@5911 1230 <p>
jackalmage@5911 1231 No Exceptions
jackalmage@5911 1232
jackalmage@5911 1233
jackalmage@5911 1234 <h4 id='CSSKeyframesRule-findRule'>
jackalmage@5911 1235 The <code>findRule</code> method</h4>
jackalmage@5911 1236
jackalmage@5911 1237 <p>
jackalmage@5911 1238 The <code>findRule</code> method returns the rule with a key matching the passed key.
jackalmage@5911 1239 If no such rule exists,
jackalmage@5911 1240 a null value is returned.
jackalmage@5911 1241
jackalmage@5911 1242 <p>
jackalmage@5911 1243 Parameters:
jackalmage@5911 1244
jackalmage@5911 1245 <dl>
jackalmage@5911 1246 <dt><code>key</code> of type <code>DOMString</code>
jackalmage@5911 1247 <dd>
jackalmage@5911 1248 The key which described the rule to find.
jackalmage@5911 1249 The key must resolve to a number between 0 and 1,
jackalmage@5911 1250 or the rule is ignored.
jackalmage@5911 1251 </dl>
jackalmage@5911 1252
jackalmage@5911 1253 <p>
jackalmage@5911 1254 Return Value:
jackalmage@5911 1255
jackalmage@5911 1256 <dl>
jackalmage@5911 1257 <dt><code>CSSKeyframeRule</code>
jackalmage@5911 1258 <dd>
jackalmage@5911 1259 The found rule.
jackalmage@5911 1260 </dl>
jackalmage@5911 1261
jackalmage@5911 1262 <p>
jackalmage@5911 1263 No Exceptions
jackalmage@5911 1264
dino@937 1265
dbaron@5304 1266 <h2 id="acknowledgments">Acknowledgments</h2>
dbaron@5304 1267
dbaron@5304 1268 <p>Thanks especially to the feedback from
dbaron@5312 1269 Tab Atkins,
dbaron@5312 1270 Estelle Weyl,
dbaron@5304 1271 and all the rest of the
jackalmage@5911 1272 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
dbaron@5304 1273
dino@937 1274 <h2>References</h2>
dino@937 1275
dino@937 1276 <h3 class="no-num">Normative references</h3>
dino@937 1277 <!--normative-->
dino@937 1278
dino@937 1279 <h3 class="no-num">Other references</h3>
dino@937 1280 <!--informative-->
dino@937 1281
dino@937 1282
dino@937 1283
dino@937 1284 <h2 class="no-num">Property index</h2>
dino@937 1285 <!-- properties -->
dino@937 1286
dino@937 1287
dino@937 1288
dino@937 1289 <h2 class="no-num" id="index">Index</h2>
dino@937 1290 <!--index-->
dino@937 1291
dino@937 1292 </body>
dino@937 1293 </html>
dino@937 1294 <!-- Keep this comment at the end of the file
dino@937 1295 Local variables:
dino@937 1296 mode: sgml
jackalmage@5911 1297 sgml-declaration:"~/SGML/HTML4.decl"
dino@937 1298 sgml-default-doctype-name:"html"
dino@937 1299 sgml-minimize-attributes:t
jackalmage@5911 1300 sgml-nofill-elements:("pre" "style" "br")
jackalmage@5911 1301 sgml-live-element-indicator:t
jackalmage@5911 1302 sgml-omittag:nil
jackalmage@5911 1303 sgml-shorttag:nil
jackalmage@5911 1304 sgml-namecase-general:t
jackalmage@5911 1305 sgml-general-insert-case:lower
jackalmage@5911 1306 sgml-always-quote-attributes:t
jackalmage@5911 1307 sgml-indent-step:nil
jackalmage@5911 1308 sgml-indent-data:t
jackalmage@5911 1309 sgml-parent-document:nil
jackalmage@5911 1310 sgml-exposed-tags:nil
jackalmage@5911 1311 sgml-local-catalogs:nil
jackalmage@5911 1312 sgml-local-ecat-files:nil
dino@937 1313 End:
jackalmage@5911 1314 -->

mercurial