css3-animations/Overview.src.html

Mon, 17 Dec 2012 18:30:07 -0800

author
Sylvain Galineau <sylvaing@microsoft.com>
date
Mon, 17 Dec 2012 18:30:07 -0800
changeset 7141
f06f034ec00d
parent 7140
f661fd2d5fbe
child 7176
5c2fe7da2fe7
permissions
-rw-r--r--

[css3-animations] Require one valid keyframe rule to run an animation; add a note on the validity of empty keyframes rules (bug 15251)

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

mercurial