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