css3-animations/Overview.src.html

Thu, 28 Jun 2012 11:43:37 -0700

author
L. David Baron <dbaron@dbaron.org>
date
Thu, 28 Jun 2012 11:43:37 -0700
changeset 6082
1d5f04cd856a
parent 6047
ceac3feb170f
child 6083
341cb156c7cd
permissions
-rw-r--r--

Untabify the <pre> elements and regenerate so that we end up with pretty much the same result as before.

     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</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.
   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 | &lt;user-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>#
   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 		A negative value for 'animation-duration' is treated as ''0s''. 
   552 		In this case 'animation-fill-mode' still applies, 
   553 		so an animation that fills backwards 
   554 		will show the value of the 0% keyframe during any delay period, 
   555 		and an animation that fills forwards will retain the value specified at the 100% keyframe, 
   556 		even if the animation was instantaneous. 
   557 		Also, animation events are still fired.
   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 				  ease | linear | ease-in | ease-out | ease-in-out | 
   575 				  step-start | step-end |
   576 				  steps(&lt;number> [, [ start | end ] ]) |
   577 				  cubic-bezier(&lt;number>, &lt;number>, &lt;number>, &lt;number>)
   578 				]#
   579 		<tr>
   580 			<th>Initial:
   581 			<td>''ease''
   582 		<tr>
   583 			<th>Applies To:
   584 			<td>all elements
   585 		<tr>
   586 			<th>Inherited:
   587 			<td>no
   588 		<tr>
   589 			<th>Computed Value:
   590 			<td>as specified
   591 		<tr>
   592 			<th>Media:
   593 			<td>visual
   594 		<tr>
   595 			<th>Animatable:
   596 			<td>no
   597 		<tr>
   598 			<th>Canonical Order:
   599 			<td><abbr title="follows order of property value definition">per grammar</abbr>
   600 	</table>
   602 	<p>
   603 		For a keyframed animation, 
   604 		the 'animation-timing-function' applies between keyframes, 
   605 		not over the entire animation. 
   606 		For example, 
   607 		in the case of an ''ease-in-out'' timing function, 
   608 		an animation will ease in at the start of the keyframe 
   609 		and ease out at the end of the keyframe. 
   610 		An 'animation-timing-function' defined within a keyframe block applies to that keyframe, 
   611 		otherwise the timing function specified for the animation is used.
   614 <h3 id="animation-iteration-count-property">
   615 The 'animation-iteration-count' Property</h3>
   617 	<p>
   618 		The 'animation-iteration-count' property specifies the number of times an animation cycle is played. 
   619 		The initial value is ''1'', 
   620 		meaning the animation will play from beginning to end once. 
   621 		A value of ''infinite'' will cause the animation to repeat forever. 
   622 		Non-integer numbers will cause the animation to end part-way through a cycle. 
   623 		Negative values of 'animation-iteration-count' are invalid. 
   624 		This property is often used in conjunction an 'animation-direction' value of ''alternate'', 
   625 		which will cause the animation to play in reverse on alternate cycles.
   627 	<table class=propdef>
   628 		<tr>
   629 			<th>Name:</th>
   630 			<td><dfn>animation-iteration-count</dfn>
   631 		<tr>
   632 			<th><a href="#values">Value</a>:
   633 			<td>[ infinite | &lt;number> ]#
   634 		<tr>
   635 			<th>Initial:
   636 			<td>''1''
   637 		<tr>
   638 			<th>Applies To:
   639 			<td>all elements
   640 		<tr>
   641 			<th>Inherited:
   642 			<td>no
   643 		<tr>
   644 			<th>Computed Value:
   645 			<td>as specified
   646 		<tr>
   647 			<th>Media:
   648 			<td>visual
   649 		<tr>
   650 			<th>Animatable:
   651 			<td>no
   652 		<tr>
   653 			<th>Canonical Order:
   654 			<td><abbr title="follows order of property value definition">per grammar</abbr>
   655 	</table>
   658 <h3 id="animation-direction-property">
   659 The 'animation-direction' Property</h3>
   661 	<p>
   662 		The 'animation-direction' property defines whether or not the animation should play in reverse on some or all cycles.  
   663 		When an animation is played in reverse the timing functions are also reversed. 
   664 		For example, when played in reverse an ease-in animation would appear to be an ease-out animation.
   666 	<table class=propdef>
   667 		<tr>
   668 			<th>Name:</th>
   669 			<td><dfn>animation-direction</dfn>
   670 		<tr>
   671 			<th><a href="#values">Value</a>:
   672 			<td>[ normal | reverse | alternate | alternate-reverse ]#
   673 		<tr>
   674 			<th>Initial:
   675 			<td>''normal''
   676 		<tr>
   677 			<th>Applies To:
   678 			<td>all elements
   679 		<tr>
   680 			<th>Inherited:
   681 			<td>no
   682 		<tr>
   683 			<th>Computed Value:
   684 			<td>as specified
   685 		<tr>
   686 			<th>Media:
   687 			<td>visual
   688 		<tr>
   689 			<th>Animatable:
   690 			<td>no
   691 		<tr>
   692 			<th>Canonical Order:
   693 			<td><abbr title="follows order of property value definition">per grammar</abbr>
   694 	</table>
   696 	<dl>
   697 		<dt><dfn>normal</dfn>
   698 		<dd>
   699 			All iterations of the animation are played as specified.
   701 		<dt><dfn>reverse</dfn>
   702 		<dd>
   703 			All iterations of the animation are played in the reverse direction from the way they were specified.
   705 		<dt><dfn>alternate</dfn>
   706 		<dd>
   707 			The animation cycle iterations that are odd counts are played in the normal direction, 
   708 			and the animation cycle iterations that are even counts are played in a reverse direction.
   710 		<dt><dfn>alternate-reverse</dfn>
   711 		<dd>
   712 			The animation cycle iterations that are odd counts are played in the reverse direction, 
   713 			and the animation cycle iterations that are even counts are played in a normal direction.
   714 	</dl>
   716 	<p class='note'>
   717 		Note that for the purpose of determining whether an iteration is even or odd,
   718 		iterations start counting from 1.
   721 <h3 id="animation-play-state-property">
   722 The 'animation-play-state' Property</h3>
   724 	<p>
   725 		The 'animation-play-state' property defines whether the animation is running or paused. 
   726 		A running animation can be paused by setting this property to ''paused''. 
   727 		To continue running a paused animation this property can be set to ''running''. 
   728 		A paused animation will continue to display the current value of the animation in a static state, 
   729 		as if the time of the animation is constant. 
   730 		When a paused animation is resumed, 
   731 		it restarts from the current value, 
   732 		not necessarily from the beginning of the animation.
   734 	<table class=propdef>
   735 		<tr>
   736 			<th>Name:</th>
   737 			<td><dfn>animation-play-state</dfn>
   738 		<tr>
   739 			<th><a href="#values">Value</a>:
   740 			<td>[ running | paused ]#
   741 		<tr>
   742 			<th>Initial:
   743 			<td>''running''
   744 		<tr>
   745 			<th>Applies To:
   746 			<td>all elements
   747 		<tr>
   748 			<th>Inherited:
   749 			<td>no
   750 		<tr>
   751 			<th>Computed Value:
   752 			<td>as specified
   753 		<tr>
   754 			<th>Media:
   755 			<td>visual
   756 		<tr>
   757 			<th>Animatable:
   758 			<td>no
   759 		<tr>
   760 			<th>Canonical Order:
   761 			<td><abbr title="follows order of property value definition">per grammar</abbr>
   762 	</table>
   765 <h3 id="animation-delay-property">
   766 The 'animation-delay' Property</h3>
   768 	<p>
   769 		The 'animation-delay' property defines when the animation will start. 
   770 		It allows an animation to begin execution some time after it is applied. 
   771 		An 'animation-delay' value of ''0s'' means the animation will execute as soon as it is applied. 
   772 		Otherwise, the value specifies an offset from the moment the animation is applied, 
   773 		and the animation will delay execution by that offset.
   775 	<p>
   776 		If the value for 'animation-delay' is a negative time offset 
   777 		then the animation will execute the moment it is applied, 
   778 		but will appear to have begun execution at the specified offset. 
   779 		That is, the animation will appear to begin part-way through its play cycle. 
   780 		In the case where an animation has implied starting values and a negative 'animation-delay', 
   781 		the starting values are taken from the moment the animation is applied.
   783 	<table class=propdef>
   784 		<tr>
   785 			<th>Name:</th>
   786 			<td><dfn>foo</dfn>
   787 		<tr>
   788 			<th><a href="#values">animation-delay</a>:
   789 			<td>&lt;time>#
   790 		<tr>
   791 			<th>Initial:
   792 			<td>''0s''
   793 		<tr>
   794 			<th>Applies To:
   795 			<td>all elements
   796 		<tr>
   797 			<th>Inherited:
   798 			<td>no
   799 		<tr>
   800 			<th>Computed Value:
   801 			<td>as specified
   802 		<tr>
   803 			<th>Media:
   804 			<td>visual
   805 		<tr>
   806 			<th>Animatable:
   807 			<td>no
   808 		<tr>
   809 			<th>Canonical Order:
   810 			<td><abbr title="follows order of property value definition">per grammar</abbr>
   811 	</table>
   814 <h3 id="animation-fill-mode-property">
   815 The 'animation-fill-mode' Property</h3>
   817 	<p>
   818 		The 'animation-fill-mode' property defines what values are applied by the animation outside the time it is executing. 
   819 		By default, an animation will not affect property values 
   820 		between the time it is applied 
   821 		(the 'animation-name' property is set on an element) 
   822 		and the time it begins execution 
   823 		(which is determined by the 'animation-delay' property). 
   824 		Also, by default an animation does not affect property values after the animation ends 
   825 		(determined by the 'animation-duration' property). 
   826 		The 'animation-fill-mode' property can override this behavior.
   828 	<p>
   829 		If the value for 'animation-fill-mode' is ''backwards'', 
   830 		then the animation will apply the property values defined in its 0% or 'from' keyframe 
   831 		as soon as the animation is applied, 
   832 		during the period defined by 'animation-delay'.
   834 	<p>
   835 		If the value for 'animation-fill-mode' is ''forwards'', 
   836 		then the animation will apply the property values defined in its last executing keyframe 
   837 		after the final iteration of the animation, 
   838 		until the animation style is removed. 
   839 		The last executing keyframe is the 'to' or '100%' keyframe, 
   840 		unless the animation has 'animation-direction' set to ''alternate'' 
   841 		and both a finite and even iteration count, 
   842 		in which case it is the 'from' or '0%' keyframe.
   844 	<p>
   845 		If the value for 'animation-fill-mode' is ''both'', 
   846 		then the animation will follow the rules for both 'forwards' and 'backwards'. 
   847 		That is, it will extend the animation properties in both directions.
   849 	<table class=propdef>
   850 		<tr>
   851 			<th>Name:</th>
   852 			<td><dfn>animation-fill-mode</dfn>
   853 		<tr>
   854 			<th><a href="#values">Value</a>:
   855 			<td>[ none | forwards | backwards | both ]#
   856 		<tr>
   857 			<th>Initial:
   858 			<td>''none''
   859 		<tr>
   860 			<th>Applies To:
   861 			<td>all elements
   862 		<tr>
   863 			<th>Inherited:
   864 			<td>no
   865 		<tr>
   866 			<th>Computed Value:
   867 			<td>as specified
   868 		<tr>
   869 			<th>Media:
   870 			<td>visual
   871 		<tr>
   872 			<th>Animatable:
   873 			<td>no
   874 		<tr>
   875 			<th>Canonical Order:
   876 			<td><abbr title="follows order of property value definition">per grammar</abbr>
   877 	</table>
   880 <h3 id="animation-shorthand-property">
   881 The 'animation' Shorthand Property
   883 	<p>
   884 		The 'animation' shorthand property combines seven of the animation properties into a single property.
   886 	<p>
   887 		Note that order is important in this property. 
   888 		The first value that can be parsed as a <var>&lt;time></var> is assigned to the 'animation-duration'. 
   889 		The second value that can be parsed as a <var>&lt;time></var> is assigned to 'animation-delay'.
   891 	<p class="issue">
   892 		An alternative proposal is to accept the font shorthand approach 
   893 		of using a "/" character between the values of the same type. 
   894 		e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
   896 	<table class=propdef>
   897 		<tr>
   898 			<th>Name:</th>
   899 			<td><dfn>animation</dfn>
   900 		<tr>
   901 			<th><a href="#values">Value</a>:
   902 			<td>[ &lt;'animation-name'> || 
   903 				&lt;'animation-duration'> ||
   904 				&lt;'animation-timing-function'> ||
   905 				&lt;'animation-delay'> ||
   906 				&lt;'animation-iteration-count'> ||
   907 				&lt;'animation-direction'> ||
   908 				&lt;'animation-fill-mode'> ]#
   909 		<tr>
   910 			<th>Initial:
   911 			<td>see individual properties
   912 		<tr>
   913 			<th>Applies To:
   914 			<td>all elements
   915 		<tr>
   916 			<th>Inherited:
   917 			<td>see individual properties
   918 		<tr>
   919 			<th>Computed Value:
   920 			<td>see individual properties
   921 		<tr>
   922 			<th>Media:
   923 			<td>visual
   924 		<tr>
   925 			<th>Animatable:
   926 			<td>no
   927 		<tr>
   928 			<th>Canonical Order:
   929 			<td><abbr title="follows order of property value definition">per grammar</abbr>
   930 	</table>
   933 <h2 id="animation-events">
   934 Animation Events</h2>
   936 	<p>
   937 		Several animation related events are available through the <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html">DOM Event system</a>. 
   938 		The start and end of an animation, 
   939 		and the end of each iteration of an animation, 
   940 		all generate DOM events. 
   941 		An element can have multiple properties being animated simultaneously. 
   942 		This can occur either with a single 'animation-name' value 
   943 		with keyframes containing multiple properties, 
   944 		or with multiple 'animation-name' values. 
   945 		For the purposes of events, 
   946 		each 'animation-name' specifies a single animation. 
   947 		Therefore an event will be generated for each 'animation-name' value 
   948 		and not necessarily for each property being animated.
   950 	<p>
   951 		The time the animation has been running is sent with each event generated. 
   952 		This allows the event handler to determine the current iteration of a looping animation 
   953 		or the current position of an alternating animation. 
   954 		This time does not include any time the animation was in the ''paused'' play state.
   957 <h3 id='AnimationEvent-interface'>
   958 Interface <code>AnimationEvent</code>
   960 	<p>
   961 		The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
   964 <h4 id='AnimationEvent-IDL'>
   965 IDL Definition</h4>
   967 	<pre class='idl'>
   968 interface AnimationEvent : Event {
   969   readonly attribute DOMString          animationName;
   970   readonly attribute float              elapsedTime;
   971   void               initAnimationEvent(in DOMString typeArg, 
   972                                         in boolean canBubbleArg, 
   973                                         in boolean cancelableArg, 
   974                                         in DOMString animationNameArg,
   975                                         in float elapsedTimeArg);
   976 };</pre>
   979 <h4 id='AnimationEvent-attributes'>
   980 Attributes</h4>
   982 	<dl>
   983 		<dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
   984 		<dd>
   985 			The value of the 'animation-name' property of the animation that fired the event.
   987 		<dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
   988 		<dd>
   989 			The amount of time the animation has been running, 
   990 			in seconds, 
   991 			when this event fired, 
   992 			excluding any time the animation was paused. 
   993 			For an "animationstart" event, 
   994 			the elapsedTime is zero unless there was a negative value for 'animation-delay', 
   995 			in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
   996 	</dl>
   999 <h4 id='AnimationEvent-initAnimationMethod'>
  1000 The <code>initAnimationEvent</code> method</h4>
  1002 	<p>
  1003 		The <dfn>initAnimationEvent</dfn> method is used to initialize the value of an <code>AnimationEvent</code> 
  1004 		created through the <a href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-DocumentEvent'><code>DocumentEvent</code></a> interface. 
  1005 		This method may only be called before the <code>AnimationEvent</code> has been dispatched 
  1006 		via the <code>dispatchEvent</code> method, 
  1007 		though it may be called multiple times during that phase if necessary. 
  1008 		If called multiple times, 
  1009 		the final invocation takes precedence.
  1011 	<p>
  1012 		Parameters:
  1014 	<dl>
  1015 		<dt><code>typeArg</code> of type <code>DOMString</code>
  1016 		<dd>
  1017 			Specifies the event type.
  1019 		<dt><code>canBubbleArg</code> of type <code>boolean</code>
  1020 		<dd>
  1021 			Specifies whether or not the event can bubble.<br>
  1023 		<dt><code>cancelableArg</code> of type <code>boolean</code>
  1024 		<dd>
  1025 			Specifies whether or not the event's default action can be prevented.
  1027 		<dt><code>animationNameArg</code> of type <code>DOMString</code>
  1028 		<dd>
  1029 			Specifies the <a href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-Event'><code>Event</code></a>'s animation name.<br>
  1031 		<dt><code>elapsedTimeArg</code> of type <code>float</code>
  1032 		<dd>
  1033 			Specifies the amount of time, 
  1034 			in seconds, 
  1035 			the animation has been running at the time of initialization.
  1036 	</dl>
  1038 	<p>
  1039 		No Return Value
  1041 	<p>
  1042 		No Exceptions
  1044 <h3 id='AnimationEvent-types'>
  1045 Types of <code>AnimationEvent</code></h3>
  1047 	<p>
  1048 		The different types of Animation events that can occur are:
  1050 	<dl>
  1051 		<dt><dfn>animationstart</dfn>
  1052 		<dd>
  1053 			The <code>animationstart</code> event occurs at the start of the animation. 
  1054 			If there is an 'animation-delay' 
  1055 			then this event will fire once the delay period has expired. 
  1056 			A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
  1058 			<ul>
  1059 				<li>Bubbles: Yes
  1060 				<li>Cancelable: No
  1061 				<li>Context Info: animationName
  1062 			</ul>
  1064 		<dt><dfn>animationend</dfn>
  1065 		<dd>
  1066 			The <code>animationend</code> event occurs when the animation finishes.
  1068 			<ul>
  1069 				<li>Bubbles: Yes
  1070 				<li>Cancelable: No
  1071 				<li>Context Info: animationName, elapsedTime
  1072 			</ul>
  1074 		<dt><dfn>animationiteration</dfn>
  1075 		<dd>
  1076 			The <code>animationiteration</code> event occurs at the end of each iteration of an animation, 
  1077 			except when an <code>animationend</code> event would fire at the same time.  
  1078 			This means that this event does not occur for animations with an iteration count of one or less.
  1080 			<ul>
  1081 				<li>Bubbles: Yes
  1082 				<li>Cancelable: No
  1083 				<li>Context Info: animationName, elapsedTime
  1084 			</ul>
  1085 	</dl>
  1088 <h2 id="dom-interfaces">
  1089 DOM Interfaces</h2>
  1091 	<p>
  1092 		CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
  1095 <h3 id='CSSRule-interface'>
  1096 Interface <code>CSSRule</code></h3>
  1098 	<p>
  1099 		The following 2 rule types are added to the <dfn>CSSRule</dfn> interface. 
  1100 		They provide identification for the new keyframe and keyframes rules.
  1103 <h4 id='CSSRule-IDL'>
  1104 IDL Definition</h4>
  1106 	<pre class='idl'>
  1107 interface CSSRule {
  1108   ...
  1109   const unsigned short KEYFRAMES_RULE = 7;
  1110   const unsigned short KEYFRAME_RULE = 8;
  1111   ...
  1112 };</pre>
  1115 <h3 id='CSSKeyframeRule-interface'>
  1116 Interface <code>CSSKeyframeRule</code></3h>
  1117 	<p>
  1118 		The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
  1121 <h4 id='CSSKeyframeRule-IDL'>
  1122 IDL Definition</h4>
  1124 	<pre class='idl'>
  1125 interface CSSKeyframeRule : CSSRule {
  1126            attribute DOMString           keyText;
  1127   readonly attribute CSSStyleDeclaration style;
  1128 };</pre>
  1131 <h4 id='CSSKeyframeRule-attributes'>
  1132 Attributes</h4>
  1134 	<dl>
  1135 		<dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
  1136 		<dd>
  1137 			This attribute represents the key 
  1138 			as the string representation of a floating point number between 0 and 1. 
  1139 			If the value in the CSS style is ''from''
  1140 			this value will be 0, 
  1141 			and if the value in the CSS style is ''to'' 
  1142 			this value will be 1.
  1144 		<dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
  1145 		<dd>
  1146 			This attribute represents the style associated with this keyframe.
  1147 	</dl>
  1150 <h3 id='CSSKeyframesRule-interface'>
  1151 Interface <code>CSSKeyframesRule</code></h3>
  1153 	<p>
  1154 		The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
  1157 <h4 id='CSSKeyframesRule-IDL'>
  1158 IDL Definition</h4>
  1160 	<pre class='idl'>
  1161 interface CSSKeyframesRule : CSSRule {
  1162            attribute DOMString   name;
  1163   readonly attribute CSSRuleList cssRules;
  1165   void            appendRule(in DOMString rule);
  1166   void            deleteRule(in DOMString key);
  1167   CSSKeyframeRule findRule(in DOMString key);
  1168 };</pre>
  1171 <h4 id='CSSKeyframesRule-attributes'>
  1172 Attributes</h4>
  1174 	<dl>
  1175 		<dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
  1176 		<dd>
  1177 			This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
  1179 		<dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
  1180 		<dd>
  1181 			This attribute gives access to the keyframes in the list.
  1184 <h4 id='CSSKeyframesRule-appendRule'>
  1185 The <code>appendRule</code> method</h4>
  1187 	<p>
  1188 		The <dfn>appendRule</dfn> method appends the passed CSSKeyframeRule into the list at the passed key.
  1190 	<p>
  1191 		Parameters:
  1193 	<dl>
  1194 		<dt><code>rule</code> of type <code>DOMString</code>
  1196 		<dd>
  1197 			The rule to be appended, 
  1198 			expressed in the same syntax as one entry in the ''@keyframes'' rule.
  1199 	</dl>
  1201 	<p>
  1202 		No Return Value
  1204 	<p>
  1205 		No Exceptions
  1208 <h4 id='CSSKeyframesRules-deleteRule'>
  1209 The <code>deleteRule</code> method</h4>
  1211 	<p>
  1212 		The <dfn>deleteRule</dfn> method deletes the CSSKeyframeRule with the passed key. 
  1213 		If a rule with this key does not exist, 
  1214 		the method does nothing.
  1216 	<p>
  1217 		Parameters:
  1219 	<dl>
  1220 		<dt><code>key</code> of type <code>DOMString</code>
  1221 		<dd>
  1222 			The key which describes the rule to be deleted. 
  1223 			The key must resolve to a number between 0 and 1, 
  1224 			or the rule is ignored.
  1225 	</dl>
  1227 	<p>
  1228 		No Return Value
  1230 	<p>
  1231 		No Exceptions
  1234 <h4 id='CSSKeyframesRule-findRule'>
  1235 The <code>findRule</code> method</h4>
  1237 	<p>
  1238 		The <code>findRule</code> method returns the rule with a key matching the passed key. 
  1239 		If no such rule exists, 
  1240 		a null value is returned.
  1242 	<p>
  1243 		Parameters:
  1245 	<dl>
  1246 		<dt><code>key</code> of type <code>DOMString</code>
  1247 		<dd>
  1248 			The key which described the rule to find. 
  1249 			The key must resolve to a number between 0 and 1, 
  1250 			or the rule is ignored.
  1251 	</dl>
  1253 	<p>
  1254 		Return Value:
  1256 	<dl>
  1257 		<dt><code>CSSKeyframeRule</code>
  1258 		<dd>
  1259 			The found rule.
  1260 	</dl>
  1262 	<p>
  1263 		No Exceptions
  1266 <h2 id="acknowledgments">Acknowledgments</h2>
  1268 <p>Thanks especially to the feedback from
  1269 Tab Atkins,
  1270 Estelle Weyl,
  1271 and all the rest of the
  1272 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
  1274 <h2>References</h2>
  1276 <h3 class="no-num">Normative references</h3>
  1277 <!--normative-->
  1279 <h3 class="no-num">Other references</h3>
  1280 <!--informative-->
  1284 <h2 class="no-num">Property index</h2>
  1285 <!-- properties -->
  1289 <h2 class="no-num" id="index">Index</h2>
  1290 <!--index-->
  1292 </body>
  1293 </html>
  1294 <!-- Keep this comment at the end of the file
  1295 Local variables:
  1296 mode: sgml
  1297 sgml-declaration:"~/SGML/HTML4.decl"
  1298 sgml-default-doctype-name:"html"
  1299 sgml-minimize-attributes:t
  1300 sgml-nofill-elements:("pre" "style" "br")
  1301 sgml-live-element-indicator:t
  1302 sgml-omittag:nil
  1303 sgml-shorttag:nil
  1304 sgml-namecase-general:t
  1305 sgml-general-insert-case:lower
  1306 sgml-always-quote-attributes:t
  1307 sgml-indent-step:nil
  1308 sgml-indent-data:t
  1309 sgml-parent-document:nil
  1310 sgml-exposed-tags:nil
  1311 sgml-local-catalogs:nil
  1312 sgml-local-ecat-files:nil
  1313 End:
  1314 -->

mercurial