[css-animations] Added marked-up definitions of property values to every property. Added a few issues.

Sat, 05 Apr 2014 10:59:13 -0700

author
Tab Atkins Jr. <jackalmage@gmail.com>
date
Sat, 05 Apr 2014 10:59:13 -0700
changeset 13676
3e45563964a5
parent 13675
fc5be523ecf9
child 13677
cd69f7e8600c

[css-animations] Added marked-up definitions of property values to every property. Added a few issues.

css-animations/Overview.bs file | annotate | diff | comparison | revisions
     1.1 --- a/css-animations/Overview.bs	Fri Apr 04 23:32:29 2014 -0700
     1.2 +++ b/css-animations/Overview.bs	Sat Apr 05 10:59:13 2014 -0700
     1.3 @@ -75,7 +75,7 @@
     1.4  
     1.5  	If at one point in time there are multiple animations specifying behavior
     1.6  	for the same property, the animation whose name occurs last in the value
     1.7 -	of ‘animation-name’ will override the other animations at that point.
     1.8 +	of 'animation-name' will override the other animations at that point.
     1.9  
    1.10  	An animation does not affect the computed value before the application of
    1.11  	the animation, before the animation delay has expired, and after the end of
    1.12 @@ -86,12 +86,12 @@
    1.13  		<figcaption>Computation of animated property values</figcaption>
    1.14  	</figure>
    1.15  
    1.16 -	 The diagram above shows how property values are computed. The intrinsic
    1.17 -	 style is shown at the top of the diagram. The computed value is derived
    1.18 -	 from intrinsic style at the times when an animation is not running and
    1.19 -	 also when an animation is delayed (see below for specification of animation
    1.20 -	 delay). During an animation, the computed style is derived from the
    1.21 -	 animated value.
    1.22 +	The diagram above shows how property values are computed. The intrinsic
    1.23 +	style is shown at the top of the diagram. The computed value is derived
    1.24 +	from intrinsic style at the times when an animation is not running and
    1.25 +	also when an animation is delayed (see below for specification of animation
    1.26 +	delay). During an animation, the computed style is derived from the
    1.27 +	animated value.
    1.28  
    1.29  	The start time of an animation is the latter of two moments: the time at
    1.30  	which the style is resolved that specifies the animation, or the time the
    1.31 @@ -322,13 +322,28 @@
    1.32  	Canonical order: per grammar
    1.33  	</pre>
    1.34  
    1.35 -	<dfn>&lt;single-animation-name></dfn> = none | <<IDENT>>
    1.36 +	<dfn>&lt;single-animation-name></dfn> = none | <<custom-ident>>
    1.37 +
    1.38 +	The values of 'animation-name' have the following meanings:
    1.39 +
    1.40 +	<dl dfn-type=value dfn-for=animation-name>
    1.41 +		<dt><dfn>none</dfn>
    1.42 +		<dd>
    1.43 +			No keyframes are specified at all, so there will be no animation.
    1.44 +			Any other animations properties specified for this animation have no effect.
    1.45 +
    1.46 +		<dt><dfn><<custom-ident>></dfn>
    1.47 +		<dd>
    1.48 +			The animation will use the keyframes with the name specified by the <<custom-ident>>,
    1.49 +			if they exist.
    1.50 +			If no such keyframes exist,
    1.51 +			there is no animation.
    1.52 +	</dl>
    1.53  
    1.54  <h3 id="animation-duration">
    1.55  The 'animation-duration' property</h3>
    1.56  
    1.57 -	The 'animation-duration' property defines the length of time that an animation takes to
    1.58 -	complete one cycle.
    1.59 +	The 'animation-duration' property defines duration of a single animation cycle.
    1.60  
    1.61  	<pre class='propdef'>
    1.62  	Name: animation-duration
    1.63 @@ -343,11 +358,19 @@
    1.64  	Canonical order: per grammar
    1.65  	</pre>
    1.66  
    1.67 -	The initial value is ''0s'', meaning that the animation takes no time. When the duration is ''0s''
    1.68 -	'animation-fill-mode' still applies, so an animation that fills backwards will show the value of
    1.69 -	the ''0%'' keyframe during any delay period, and an animation that fills forwards will retain the
    1.70 -	value specified at the ''100%'' keyframe, even if the animation was instantaneous. Also, animation
    1.71 -	events are still fired. A negative 'animation-duration' value renders the declaration invalid.
    1.72 +	<dl>
    1.73 +		<dt><dfn value for=animation-duration><<time>></dfn>
    1.74 +		<dd>
    1.75 +			The <<time>> specifies the length of time that an animation takes to complete one cycle.
    1.76 +			A negative <<time>> is invalid.
    1.77 +
    1.78 +			If the <<time>> is ''0s'', like the initial value,
    1.79 +			the keyframes of the animation have no effect,
    1.80 +			but the animation itself still occurs instantaneously.
    1.81 +			That is, 'animation-fill-mode' applies as normal,
    1.82 +			filling backwards or forwards as appropriate,
    1.83 +			and animation events still fire.
    1.84 +	</dl>
    1.85  
    1.86  <h3 id="animation-timing-function">
    1.87  The 'animation-timing-function' property</h3>
    1.88 @@ -369,24 +392,27 @@
    1.89  	Canonical order: per grammar
    1.90  	</pre>
    1.91  
    1.92 -	All the valid values of <dfn>&lt;single-timing-function></dfn> are defined by the 'transition-timing-function'
    1.93 -	property [[!CSS3-TRANSITIONS]].
    1.94 +	The values and meaning of <dfn>&lt;single-timing-function></dfn>
    1.95 +	are identical to those of <<single-transition-timing-function>> [[!CSS3-TRANSITIONS]].
    1.96  
    1.97 -	For a keyframed animation, the 'animation-timing-function' applies between keyframes, not over the
    1.98 -	entire animation. For example, in the case of an ''ease-in-out'' timing function, an animation will
    1.99 -	ease in at the start of the keyframe and ease out at the end of the keyframe. An 'animation-timing-function'
   1.100 -	defined within a keyframe block applies to that keyframe, otherwise the timing function specified for
   1.101 -	the animation is used. In addition, only the first value of the property applies when it is used in
   1.102 -	a keyframe block.
   1.103 +	The timing function specified applies to each iteration of the animation,
   1.104 +	not the entire animation in full.
   1.105 +	For example, if an animation has ''animation-timing-function: ease-in-out; animation-iteration-count: 2;'',
   1.106 +	it will ease in at the start,
   1.107 +	ease out as it approaches the end of its first iteration,
   1.108 +	ease in at the start of its second iteration,
   1.109 +	and ease out again as it approaches the end of the animation.
   1.110 +
   1.111 +	Note: Unlike other animation properties,
   1.112 +	'animation-timing-function' has an effect when specified on an individual keyframe.
   1.113 +	See <a section href="#timing-functions"></a> for more detail on this.
   1.114  
   1.115  <h3 id="animation-iteration-count">
   1.116  The 'animation-iteration-count' property</h3>
   1.117  
   1.118  	The 'animation-iteration-count' property specifies the number of times an animation cycle
   1.119  	is played. The initial value is ''1'', meaning the animation will play from beginning to end
   1.120 -	once. A value of ''infinite'' will cause the animation to repeat forever. Non-integer numbers
   1.121 -	will cause the animation to end part-way through a cycle. Negative values of
   1.122 -	'animation-iteration-count' are invalid. This property is often used in conjunction an
   1.123 +	once.  This property is often used in conjunction with an
   1.124  	'animation-direction' value of ''alternate'', which will cause the animation to play in
   1.125  	reverse on alternate cycles.
   1.126  
   1.127 @@ -405,6 +431,24 @@
   1.128  
   1.129  	<dfn>&lt;single-animation-iteration-count></dfn> = infinite | <<number>>
   1.130  
   1.131 +	<dl dfn-type=value dfn-for=animation-iteration-count>
   1.132 +		<dt><dfn>infinite</dfn>
   1.133 +		<dd>
   1.134 +			The animation will repeat forever.
   1.135 +
   1.136 +		<dt><dfn><<number>></dfn>
   1.137 +		<dd>
   1.138 +			The animation will repeat the specified number of times.
   1.139 +			If the number is not an integer,
   1.140 +			the animation will end partway through its last cycle.
   1.141 +			Negative numbers are invalid.
   1.142 +
   1.143 +			A value of ''0'' is valid and,
   1.144 +			similar to an 'animation-duration' of ''0s'',
   1.145 +			causes the animation to occur instantaneously.
   1.146 +	</dl>
   1.147 +
   1.148 +
   1.149  <h3 id="animation-direction">
   1.150  The 'animation-direction' property</h3>
   1.151  
   1.152 @@ -459,11 +503,6 @@
   1.153  The 'animation-play-state' property</h3>
   1.154  
   1.155  	The 'animation-play-state' property defines whether the animation is running or paused.
   1.156 -	A running animation can be paused by setting this property to ''paused''. To continue
   1.157 -	running a paused animation this property can be set to ''running''. A paused animation will
   1.158 -	continue to display the current value of the animation in a static state, as if the time
   1.159 -	of the animation is constant. When a paused animation is resumed, it restarts from the
   1.160 -	current value, not necessarily from the beginning of the animation.
   1.161  
   1.162  	<pre class='propdef'>
   1.163  	Name: animation-play-state
   1.164 @@ -480,19 +519,28 @@
   1.165  
   1.166  	<dfn>&lt;single-animation-play-state></dfn> = running | paused
   1.167  
   1.168 +	<dl dfn-type=value dfn-for=animation-play-state>
   1.169 +		<dt><dfn>running</dfn>
   1.170 +		<dd>
   1.171 +			While this property is set to ''running'',
   1.172 +			the animation proceeds as normal.
   1.173 +
   1.174 +		<dt><dfn>paused</dfn>
   1.175 +		<dd>
   1.176 +			While this property is set to ''paused'',
   1.177 +			the animation is paused.
   1.178 +			The animation continues to apply to the element with the progress it had made before being paused.
   1.179 +			When unpaused (set back to ''running''),
   1.180 +			it restarts from where it left off,
   1.181 +			as if the "clock" that controls the animation had stopped and started again.
   1.182 +	</dl>
   1.183 +
   1.184  <h3 id="animation-delay">
   1.185  The 'animation-delay' property</h3>
   1.186  
   1.187  	The 'animation-delay' property defines when the animation will start. It allows an animation
   1.188 -	to begin execution some time after it is applied. An 'animation-delay' value of ''0s'' means
   1.189 -	the animation will execute as soon as it is applied. Otherwise, the value specifies an offset
   1.190 -	from the moment the animation is applied, and the animation will delay execution by that offset.
   1.191 -
   1.192 -	If the value for 'animation-delay' is a negative time offset then the animation will execute the
   1.193 -	moment it is applied, but will appear to have begun execution at the specified offset. That is,
   1.194 -	the animation will appear to begin part-way through its play cycle. In the case where an animation
   1.195 -	has implied starting values and a negative 'animation-delay', the starting values are taken from
   1.196 -	the moment the animation is applied.
   1.197 +	to begin execution some time after it is applied,
   1.198 +	or to appear to have begun execution some time <em>before</em> it is applied.
   1.199  
   1.200  	<pre class='propdef'>
   1.201  	Name: animation-delay
   1.202 @@ -507,6 +555,24 @@
   1.203  	Canonical order: per grammar
   1.204  	</pre>
   1.205  
   1.206 +	<dl>
   1.207 +		<dt><dfn value for=animation-delay><<time>></dfn>
   1.208 +		<dd>
   1.209 +			The <<time>> defines how long of a delay there is between the start of the animation
   1.210 +			(when the animation is applied to the element via these properties)
   1.211 +			and when it begins executing.
   1.212 +			A delay of ''0s'' (the initial value) means that the animation will execute as soon as it is applied.
   1.213 +
   1.214 +			A negative delay is <strong>valid</strong>.
   1.215 +			Similar to a delay of ''0s'', it means that the animation executes immediately,
   1.216 +			but is automatically progressed by the absolute value of the delay,
   1.217 +			as if the animation had started the specified time in the past,
   1.218 +			and so it appears to start partway through its play-cycle already.
   1.219 +			If an animation's keyframes have an implied starting value,
   1.220 +			the values are taken from the time the animation starts,
   1.221 +			not some time in the past.
   1.222 +	</dl>
   1.223 +
   1.224  <h3 id="animation-fill-mode">
   1.225  The 'animation-fill-mode' property</h3>
   1.226  
   1.227 @@ -515,26 +581,8 @@
   1.228  	values between the time it is applied (the ‘animation-name’ property is set on an
   1.229  	element) and the time it begins execution (which is determined by the 'animation-delay'
   1.230  	property). Also, by default an animation does not affect property values after the
   1.231 -	animation ends (determined by the 'animation-duration' property). The 'animation-fill-mode'
   1.232 -	property can override this behavior.
   1.233 -
   1.234 -	If the value for 'animation-fill-mode' is ''backwards'', then the animation will apply
   1.235 -	the property values defined in the keyframe that will start the first iteration of the
   1.236 -	animation, during the period defined by 'animation-delay'. These are either the values
   1.237 -	of the ''from'' keyframe (when 'animation-direction' is ''normal'' or ''alternate'') or
   1.238 -	those of the ''to'' keyframe (when 'animation-direction' is ''reverse'' or
   1.239 -	''alternate-reverse'').
   1.240 -
   1.241 -	If the value for 'animation-fill-mode' is ''forwards'', then after the animation ends (as
   1.242 -	determined by its 'animation-iteration-count'), the animation will apply the property values
   1.243 -	for the time the animation ended. When 'animation-iteration-count' is an integer greater than
   1.244 -	zero, the values applied will be those for the end of the last completed iteration of the
   1.245 -	animation (rather than the values for the start of the iteration that would be next). When
   1.246 -	'animation-iteration-count' is zero, the values applied will be those that would start the
   1.247 -	first iteration (just as when 'animation-fill-mode' is ''backwards'').
   1.248 -
   1.249 -	If the value for 'animation-fill-mode' is ''both'', then the animation will follow the rules
   1.250 -	for both ''forwards'' and ''backwards''. That is, it will extend the animation in both directions.
   1.251 +	animation ends (determined by the 'animation-duration' and 'animation-iteration-count' properties).
   1.252 +	The 'animation-fill-mode'property can override this behavior.
   1.253  
   1.254  	<pre class='propdef'>
   1.255  	Name: animation-fill-mode
   1.256 @@ -551,6 +599,50 @@
   1.257  
   1.258  	<dfn>&lt;single-animation-fill-mode></dfn> = none | forwards | backwards | both
   1.259  
   1.260 +	<dl dfn-type=value dfn-for=animation-fill-mode>
   1.261 +		<dt><dfn>none</dfn>
   1.262 +		<dd>
   1.263 +			The animation has no effect when it is applied but not executing.
   1.264 +
   1.265 +		<dt><dfn>forwards</dfn>
   1.266 +		<dd>
   1.267 +			After the animation is done executing
   1.268 +			(has played the number of times specified by its 'animation-iteration-count' value)
   1.269 +			it continues to apply the values that it ended its last complete iteration with.
   1.270 +			This will be the values specified or implied for either its ''100%'' or ''0%'' keyframe,
   1.271 +			depending on the direction that the last complete iteration was executing in
   1.272 +			(per 'animation-direction').
   1.273 +			If the animation didn't complete an entire iteration
   1.274 +			(if the iteration count was ''0'' or a value less than 1)
   1.275 +			the values specified or implied for its ''0%'' keyframe are used.
   1.276 +
   1.277 +			Note: If 'animation-iteration-count' is a non-integer value,
   1.278 +			the animation will stop executing partway through its animation cycle,
   1.279 +			but a forwards fill will still apply the values of the ''100%'' keyframe,
   1.280 +			not whatever values were being applied at the time the animation stopped executing.
   1.281 +
   1.282 +			Issue: Why does it ignore the progress made by a non-integer iteration count?
   1.283 +
   1.284 +			Issue: What happens with ''animation-duration: 0; animation-iteration-count: infinite;''?
   1.285 +			The animation is instantaneous,
   1.286 +			but there is no "last complete iteration".
   1.287 +			In particular, you can't tell whether to use the 0% or 100% keyframe.
   1.288 +
   1.289 +		<dt><dfn>backwards</dfn>
   1.290 +		<dd>
   1.291 +			Before the animation has begun executing
   1.292 +			(during the period specified by 'animation-delay'),
   1.293 +			the animation applies the values that it will start the first iteration with.
   1.294 +			If the 'animation-direction' is ''normal'' or ''alternate'',
   1.295 +			the values specified or implied for its ''0%'' keyframe are used;
   1.296 +			if the 'animation-direction' is ''reverse'' or ''alternate-reverse'',
   1.297 +			the values specified or implied for its ''100%'' keyframe are used.
   1.298 +
   1.299 +		<dt><dfn>both</dfn>
   1.300 +		<dd>
   1.301 +			The effects of both ''forwards'' and ''backwards'' fill apply.
   1.302 +	</dl>
   1.303 +
   1.304  <h3 id="animation">
   1.305  The 'animation' shorthand property</h3>
   1.306  
   1.307 @@ -560,7 +652,6 @@
   1.308  	properties have lists of different lengths, a problem that cannot occur when they are defined using
   1.309  	only the 'animation' shorthand.)
   1.310  
   1.311 -
   1.312  	<pre class='propdef'>
   1.313  	Name: animation
   1.314  	Value: 	<<single-animation>>#
   1.315 @@ -611,6 +702,9 @@
   1.316  	Any animation for which both a valid keyframe rule and a non-zero duration are defined will run
   1.317  	and generate events; this includes animations with empty keyframe rules.
   1.318  
   1.319 +	Issue: This contradicts the 'animation-delay' section,
   1.320 +	which says that a ''0s'' duration animation still fires events.
   1.321 +
   1.322  	The time the animation has been running is sent with each event generated. This allows the event
   1.323  	handler to determine the current iteration of a looping animation or the current position of an
   1.324  	alternating animation. This time does not include any time the animation was in the ''paused''
   1.325 @@ -791,8 +885,8 @@
   1.326  <h4 id="interface-csskeyframesrule-appendrule">
   1.327  The <code>appendRule</code> method</h4>
   1.328  
   1.329 -	 The <dfn method for="CSSKeyFramesRule">appendRule()</dfn> method appends the passed
   1.330 -	 <a idl>CSSKeyframeRule</a> into the list at the passed key.
   1.331 +	The <dfn method for="CSSKeyFramesRule">appendRule()</dfn> method appends the passed
   1.332 +	<a idl>CSSKeyframeRule</a> into the list at the passed key.
   1.333  
   1.334  	Parameters:
   1.335  

mercurial