css3-animations/Overview.src.html

Thu, 12 Jul 2012 14:50:44 -0700

author
Sylvain Galineau <sylvaing@microsoft.com>
date
Thu, 12 Jul 2012 14:50:44 -0700
changeset 6222
cd865eec928e
parent 6220
94142ede215c
child 6384
b7f2a99e335d
permissions
-rw-r--r--

css3-animations ED: negative transition-duration values are invalid (bug 16806), handling of !important (bug 14792), fix property syntax defs, fix animation-delay referenced as 'foo' in prop index

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

mercurial