Skip to content

Commit de06a7b

Browse files
birtlesbirtles
committed
[css-animations-2][css-transitions-2] Clarify event dispatch and elapsedTime
As discussed in #68.
1 parent bf6a926 commit de06a7b

File tree

2 files changed

+212
-42
lines changed

2 files changed

+212
-42
lines changed

‎css-animations-2/Overview.bs

+160-38
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,30 @@
99
padding: 0.2em 1em;
1010
border: 1px solid black;
1111
}
12+
table.play-state-transitions th {
13+
text-align: center;
14+
}
1215
table.play-state-transitions th.rowgroup {
1316
transform: rotate(-180deg);
1417
writing-mode: vertical-lr;
1518
padding-left: 5px;
1619
}
20+
21+
table.event-state-transitions {
22+
width: 100%;
23+
border-spacing: 0px;
24+
border-collapse: collapse;
25+
}
26+
table.event-state-transitions th:first-child {
27+
width: 30%;
28+
}
29+
table.event-state-transitions th {
30+
text-align: center;
31+
}
32+
table.event-state-transitions td {
33+
padding: 0.2em 1em;
34+
border: 1px solid black;
35+
}
1736
</style>
1837

1938
<pre class='metadata'>
@@ -39,14 +58,22 @@ urlPrefix: https://w3c.github.io/web-animations/; type: method; for: Animation;
3958
urlPrefix: https://w3c.github.io/web-animations/; type: method; for: KeyframeEffectReadOnly; spec: web-animations
4059
text: getFrames()
4160
urlPrefix: https://w3c.github.io/web-animations/; type: dfn; spec: web-animations
61+
text: active duration
62+
text: active phase
63+
text: after phase
4264
text: animation
43-
text: animation playback rate
4465
text: animation class
66+
text: animation effect
67+
text: animation playback rate
68+
text: before phase
4569
text: composite operation
4670
text: current iteration
4771
text: current time
4872
text: global animation list
4973
text: idle play state
74+
text: idle phase
75+
text: iteration duration
76+
text: iteration start
5077
text: pause an animation
5178
text: play an animation
5279
text: sampling
@@ -379,47 +406,142 @@ The <em>additional</em> types of animation events that can occur are:
379406
380407
Note, this is a more general description of event dispatch than that of CSS
381408
Animations Level 1 [[CSS3-ANIMATIONS]] since it must account for the
382-
possibility of animations being seeked using the Web Animations API
409+
possibility of animations being seeked or reversed using the Web Animations API
383410
[[WEB-ANIMATIONS]].
384411
385-
For the purpose of determining which events to dispatch, an animation can
386-
be considered to be in one of four mutually-exclusive <dfn
387-
lt="event state">event states</dfn> determined using the following procedure:
388-
389-
1. If the animation is <a lt="idle play state">idle</a> or has no <a>target
390-
effect</a> it is <dfn>idle</dfn>.
391-
1. Otherwise, if the animation has a <a>current time</a> less than the
392-
<a>start delay</a> of its <a>target effect</a>, or, if the animation's
393-
<a lt="animation playback rate">playback rate</a> is less than zero and
394-
it has a <a>current time</a> less than <em>or equal</em> to the
395-
<a>start delay</a> of its <a>target effect</a>, it is
396-
<dfn>left-active</dfn>.
397-
1. Otherwise, if the animation has a <a>current time</a> greater than its
398-
<a>target effect end</a>, or, if the animation's
399-
<a lt="animation playback rate">playback rate</a> is greater than or equal
400-
to zero and it has a <a>current time</a> greater than <em>or equal</em> to
401-
its <a>target effect end</a>, it is <dfn>right-active</dfn>.
402-
1. Otherwise, it is <dfn>active</dfn>.
403-
404-
Each time the animation is <a lt="sampling">sampled</a>, the events to
405-
dispatch are determined by comparing the <a>event state</a> before and
412+
For the purpose of determining which events to dispatch, the
413+
[[web-animations#animation-effect-phases-and-states|phases]] defined in
414+
the Web Animations model are used. These definitions apply to an <a>animation
415+
effect</a>, however, for the purpose of dispatching events, we consider a
416+
CSS Animation to have the same phase as its <a>target effect</a>. For example,
417+
a CSS Animation is in the <a>before phase</a> if its <a>target effect</a>
418+
is in the <a>before phase</a>. A CSS Animation that does not have a <a>target
419+
effect</a> is considered to be in the <a>idle phase</a>.
420+
421+
Similarly, subsequent references to the <a>start delay</a>, <a>active
422+
duration</a>, <a>current iteration</a>, <a>iteration start</a>, and
423+
<a>iteration duration</a> of a CSS animation should be understood to refer
424+
to the corresponding properties of the animation's <a>target effect</a>.
425+
426+
For calculating the {{AnimationEvent/elapsedTime}} of each event, the following
427+
definitions are used:
428+
429+
* <dfn>interval start</dfn> =
430+
<code>max(min(-<a>start delay</a>, <a>active duration</a>), 0)</code>
431+
* <dfn>interval end</dfn> =
432+
<code>max(min(<a>target effect end</a> - <a>start delay</a>,
433+
<a>active duration</a>), 0)</code>
434+
435+
Each time an animation is <a lt="sampling">sampled</a>, the events to
436+
dispatch are determined by comparing the animation's phase before and
406437
after the sample as follows:
407438
408-
: not <a>active</a> &rarr; <a>active</a>
409-
:: <a idl>animationstart</a>
410-
: <a>left-active</a> &rarr; <a>right-active</a>
411-
: <a>right-active</a> &rarr; <a>left-active</a>
412-
:: <a idl>animationstart</a>, <a idl>animationend</a>
413-
: <a>active</a> &rarr; <a>left-active</a>
414-
: <a>active</a> &rarr; <a>right-active</a>
415-
:: <a idl>animationend</a>
416-
: <a>active</a> &rarr; <a>active</a>
417-
:: <a idl>animationiteration</a> <em>if</em> there has been a change to the
418-
<a>current iteration</a> of the animation's <a>target effect</a>.
419-
: not <a>idle</a> &rarr; <a>idle</a>
420-
:: <a idl>animationcancel</a>
421-
422-
Issue: Define the value of <code>elapsedTime</code> for each case.
439+
<table class="event-state-transitions">
440+
<thead>
441+
<tr>
442+
<th>Change</th>
443+
<th>Events dispatched</th>
444+
<th><dfn>Elapsed time</dfn> (ms)</th>
445+
</tr>
446+
</thead>
447+
<tbody>
448+
<tr>
449+
<td><a lt="idle phase">idle</a> &rarr;
450+
<a lt="active phase">active</a></td>
451+
<td><a idl>animationstart</a></td>
452+
<td>If the <a>animation playback rate</a> is &ge; 0,
453+
use the <a>interval start</a>, otherwise use the
454+
<a>interval end</a>.
455+
</td>
456+
</tr>
457+
<tr>
458+
<td><a lt="before phase">before</a> &rarr;
459+
<a lt="active phase">active</a></td>
460+
<td><a idl>animationstart</a></td>
461+
<td><a>interval start</a></td>
462+
</tr>
463+
<tr>
464+
<td><a lt="after phase">after</a> &rarr;
465+
<a lt="active phase">active</a></td>
466+
<td><a idl>animationstart</a></td>
467+
<td><a>interval end</a></td>
468+
</tr>
469+
<tr>
470+
<td rowspan="2"><a lt="before phase">before</a> &rarr;
471+
<a lt="after phase">after</a> <a
472+
href="#multiple-events-note">&#x66d;</a></td>
473+
<td><a idl>animationstart</a></td>
474+
<td><a>interval start</a></td>
475+
</tr>
476+
<tr>
477+
<td><a idl>animationend</a></td>
478+
<td><a>interval end</a></td>
479+
</tr>
480+
<tr>
481+
<td rowspan="2"><a lt="after phase">after</a> &rarr;
482+
<a lt="before phase">before</a> <a
483+
href="#multiple-events-note">&#x66d;</a></td>
484+
<td><a idl>animationstart</a></td>
485+
<td><a>interval end</a></td>
486+
</tr>
487+
<tr>
488+
<td><a idl>animationend</a></td>
489+
<td><a>interval start</a></td>
490+
</tr>
491+
<tr>
492+
<td><a lt="active phase">active</a> &rarr;
493+
<a lt="before phase">before</a></td>
494+
<td><a idl>animationend</a></td>
495+
<td><a>interval start</a></td>
496+
</tr>
497+
<tr>
498+
<td><a lt="active phase">active</a> &rarr;
499+
<a lt="after phase">after</a></td>
500+
<td><a idl>animationend</a></td>
501+
<td><a>interval end</a></td>
502+
</tr>
503+
<tr>
504+
<td><a lt="active phase">active</a> &rarr;
505+
<a lt="active phase">active</a>
506+
<em>and</em>
507+
the <a>current iteration</a> of the animation's <a>target effect</a>
508+
has changed since the previous sample
509+
</td>
510+
<td><a idl>animationiteration</a></td>
511+
<td>(See below)
512+
<a href="#animation-iteration-elapsed-time">&dagger;</a></td>
513+
</tr>
514+
<tr>
515+
<td>Not <a lt="idle phase">idle</a> &rarr;
516+
<a lt="idle phase">idle</a></td>
517+
<td><a idl>animationcancel</a></td>
518+
<td>0</td>
519+
</tr>
520+
</tbody>
521+
</table>
522+
523+
<p id="multiple-events-note">&#x66d; Where multiple events are listed for
524+
a state change, all events are dispatched in the order listed and in immediate
525+
succession.</p>
526+
527+
<p id="animation-iteration-elapsed-time">&dagger; The <a>elapsed time</a> for
528+
an <a idl>animationiteration</a> event is defined as follows:</p>
529+
530+
1. Let <var>previous current iteration</var> be the <a>current iteration</a>
531+
from the previous sample.
532+
533+
1. If <var>previous current iteration</var> is greater than <a>current
534+
iteration</a>, let <var>iteration boundary</var> be <code><a>current
535+
iteration</a> + 1</code>, otherwise let it be <a>current iteration</a>.
536+
537+
1. The <a>elapsed time</a> is the result of evaluating
538+
<code>(<var>iteration boundary</var> - <a>iteration start</a>) &times;
539+
<a>iteration duration</a>)</code>.
540+
541+
Since the <a>elapsed time</a> defined in the table and procedure above is
542+
expressed in milliseconds, it must be divided by 1,000 to produce a value in
543+
seconds before being assigned to the {{AnimationEvent/elapsedTime}} member of
544+
the {{AnimationEvent}}.
423545
424546
# DOM Interfaces # {#interface-dom}
425547

‎css-transitions-2/Overview.bs

+52-4
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,15 @@ Ignored Terms: translate, rotate, scale
1616
urlPrefix: https://w3c.github.io/web-animations/; type: interface; spec: web-animations
1717
text: Animation
1818
urlPrefix: https://w3c.github.io/web-animations/; type: dfn; spec: web-animations
19+
text: active duration
1920
text: animation
2021
text: animation class
2122
text: global animation list
2223
text: idle play state
24+
text: start delay
25+
text: target effect
26+
urlPrefix: https://drafts.csswg.org/css-animations-2/; type: dfn; spec: css-animations-2
27+
text: interval end
2328
</pre>
2429
<pre class=link-defaults>
2530
spec:css-transitions-1; type:value; text:all
@@ -133,6 +138,12 @@ to the <a>global animation list</a> at the moment they are constructed.
133138
<dt><dfn>transitionrun</dfn>
134139
<dd>
135140
The <a idl>transitionrun</a> event occurs when a transition is created (i.e., when it is added to the set of <a>running transitions</a>).
141+
The {{AnimationEvent/elapsedTime}} in this case is equal to the value
142+
defined for the <a idl>transitionstart</a> event.
143+
144+
Issue: Is there some more useful value we could provide here for the
145+
<code>elapsedTime</code>?
146+
136147
<ul>
137148
<li>Bubbles: Yes</li>
138149
<li>Cancelable: No</li>
@@ -141,24 +152,61 @@ to the <a>global animation list</a> at the moment they are constructed.
141152
<dt><dfn>transitionstart</dfn>
142153
<dd>
143154
The <a idl>transitionstart</a> event occurs when a transition's delay
144-
phase ends. If the transition has a negative 'transition-delay', the
145-
event will have an elapsedTime equal to the absolute value of the delay.
155+
phase ends.
156+
The {{AnimationEvent/elapsedTime}} in this case is the result of
157+
calculating
158+
<code>max(min(-<a>start delay</a>, <a>active duration</a>), 0)
159+
/ 1000</code>
160+
where the <a>start delay</a> and <a>active duration</a> values refer
161+
to the values defined for the transition's <a>target effect</a>.
162+
163+
Note: This calculation is roughly equivalent to saying,
164+
&ldquo;The <code>elapsedTime</code> is zero unless there is
165+
a negative 'transition-delay', in which cse the <code>elapsedTime</code>
166+
is the absolute value of the 'transition-delay'.&rdquo;
167+
However, it produces more useful results in some edge cases such as
168+
when the there is a negative delay greater in magnitude than the
169+
total duration of the animation.
170+
146171
<ul>
147172
<li>Bubbles: Yes</li>
148173
<li>Cancelable: No</li>
149174
<li>Context Info: propertyName, elapsedTime, pseudoElement</li>
150175
</ul>
151176
<dt><dfn>transitioncancel</dfn>
152177
<dd>
153-
The <a idl>transitioncancel</a> event occurs when a transition is <a data-lt="cancel">cancelled</a>.
178+
The <a idl>transitioncancel</a> event occurs when a transition is <a lt="cancel">cancelled</a>.
179+
The {{AnimationEvent/elapsedTime}} in this case is zero.
180+
181+
Issue: Is there some more useful value we could provide here for the
182+
<code>elapsedTime</code>?
183+
(We could, for example, return the current time at the moment the
184+
transition was cancelled so that the author can tell if the transition
185+
had just started or was close to finishing and perhaps behave differently
186+
in each case.
187+
Doing that, however, would require implementations to store
188+
additional state for each transition which would be unfortunate if
189+
this is not a common use case.)
190+
154191
<ul>
155192
<li>Bubbles: Yes</li>
156193
<li>Cancelable: No</li>
157194
<li>Context Info: propertyName, elapsedTime, pseudoElement</li>
158195
</ul>
159196
</dl>
160197

161-
Issue: Define precisely the value of elapsedTime for each of these events.
198+
<div class="issue">
199+
200+
We should define the dispatch of events more generally in light of
201+
possible modifications to a transition's playback using the Web Animations API
202+
like we do for CSS Animations (see the section on
203+
[[css-animations-2#event-dispatch|event dispatch]]).
204+
205+
As part of this, we should clarify the calculation of the
206+
{{AnimationEvent/elapsedTime}} member for <a idl>transitionend</a> events to
207+
use the same <a>interval end</a> value defined for CSS Animations.
208+
209+
</div>
162210

163211
# DOM Interfaces # {#interface-dom}
164212

0 commit comments

Comments
 (0)