Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add TextTrackCue ctor & cue + cuebackground attributes #9771

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add TextTrackCue ctor & cue + cuebackground attributes #9771

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
69001aa
Add TextTrackCue ctor & cue + cuebackground attrs
marcoscaceres Sep 21, 2023
9c2aa7c
add example, fix more xrefs
marcoscaceres Oct 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
264 changes: 263 additions & 1 deletion source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2880,6 +2880,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#datacloneerror">"<code>DataCloneError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#encodingerror">"<code>EncodingError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#notallowederror">"<code>NotAllowedError</code>"</dfn></li>
<li><dfn data-x-href="https://webidl.spec.whatwg.org/#invalidnodetypeerror">"<code>InvalidNodeTypeError</code>"</dfn></li>
</ul>

<p>When this specification requires a user agent to <dfn>create a <code>Date</code> object</dfn>
Expand Down Expand Up @@ -3185,7 +3186,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li>The <dfn data-x="finding flattened slottables" data-x-href="https://dom.spec.whatwg.org/#find-flattened-slotables">find flattened slottables</dfn> algorithm</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#slottable-manual-slot-assignment">manual slot assignment</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#assign-a-slot">assign a slot</dfn> algorithm</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-node-pre-insert">pre-insert</dfn>, <dfn data-x="concept-node-insert" data-x-href="https://dom.spec.whatwg.org/#concept-node-insert">insert</dfn>, <dfn data-x="concept-node-append" data-x-href="https://dom.spec.whatwg.org/#concept-node-append">append</dfn>, <dfn data-x="concept-node-replace" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace">replace</dfn>, <dfn data-x="concept-node-replace-all" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace-all">replace all</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#string-replace-all">string replace all</dfn>, <dfn data-x="concept-node-remove" data-x-href="https://dom.spec.whatwg.org/#concept-node-remove">remove</dfn>, and <dfn data-x="concept-node-adopt" data-x-href="https://dom.spec.whatwg.org/#concept-node-adopt">adopt</dfn> algorithms for nodes</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-node-pre-insert">pre-insert</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#concept-node-ensure-pre-insertion-validity">ensure pre-insertion validity</dfn>, <dfn data-x="concept-node-insert" data-x-href="https://dom.spec.whatwg.org/#concept-node-insert">insert</dfn>, <dfn data-x="concept-node-append" data-x-href="https://dom.spec.whatwg.org/#concept-node-append">append</dfn>, <dfn data-x="concept-node-replace" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace">replace</dfn>, <dfn data-x="concept-node-replace-all" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace-all">replace all</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#string-replace-all">string replace all</dfn>, <dfn data-x="concept-node-remove" data-x-href="https://dom.spec.whatwg.org/#concept-node-remove">remove</dfn>, and <dfn data-x="concept-node-adopt" data-x-href="https://dom.spec.whatwg.org/#concept-node-adopt">adopt</dfn> algorithms for nodes</li>
<li>The <dfn data-x="concept-tree-descendant" data-x-href="https://dom.spec.whatwg.org/#concept-tree-descendant">descendant</dfn> concept</li>
<li>The <dfn data-x="concept-node-insert-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-insert-ext">insertion steps</dfn>,
<dfn data-x="concept-node-remove-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-remove-ext">removing steps</dfn>,
Expand Down Expand Up @@ -3271,6 +3272,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li><dfn data-x-href="https://dom.spec.whatwg.org/#abortsignal-aborted" data-x="AbortSignal-aborted">aborted</dfn></li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#abortcontroller-signal-abort">signal abort</dfn></li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-element-attributes-get-by-name">get an attribute by name</dfn> algorithm</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#exclusive-text-node" data-x="exclusive Text node">exclusive <code>Text</code> node</dfn> concept</li>
</ul>

<p>The following features are defined in <cite>UI Events</cite>: <ref>UIEVENTS</ref></p>
Expand Down Expand Up @@ -11684,6 +11686,10 @@ interface <dfn interface>HTMLElement</dfn> : <span>Element</span> {
[<span>CEReactions</span>] attribute boolean <span data-x="dom-translate">translate</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-dir">dir</span>;

// <span>TextTrackCue</span> related
[<span>CEReactions</span>] attribute boolean <span data-x="dom-cuebackground">cuebackground</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-cue">cue</span>;

// <span>user interaction</span>
[<span>CEReactions</span>] attribute (boolean or unrestricted double or DOMString)? <span data-x="dom-hidden">hidden</span>;
[<span>CEReactions</span>] attribute boolean <span data-x="dom-inert">inert</span>;
Expand Down Expand Up @@ -12941,6 +12947,8 @@ https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%
<li><code data-x="attr-autocapitalize">autocapitalize</code></li>
marcoscaceres marked this conversation as resolved.
Show resolved Hide resolved
<li><code data-x="attr-fe-autofocus">autofocus</code></li>
<li><code data-x="attr-contenteditable">contenteditable</code></li>
<li><code data-x="attr-cue">cue</code></li>
<li><code data-x="attr-cuebackground">cuebackground</code></li>
<li><code data-x="attr-dir">dir</code></li>
<li><code data-x="attr-draggable">draggable</code></li>
<li><code data-x="attr-enterkeyhint">enterkeyhint</code></li>
Expand Down Expand Up @@ -39074,6 +39082,32 @@ interface <dfn interface>VideoTrack</dfn> {
<p>An arbitrary string.</p>
</dd>

<dt>A <dfn export>text track cue fragment</dfn>
<dd>
<p>A <code>DocumentFragment</code> that is the content of the cue and is composed of one ore
more of the <span>allowed text track cue elements</span> and <span data-x="exclusive Text
node">exclusive <code>Text</code> nodes</span>.</p>
</dd>

<dt><dfn>Allowed text track cue elements</dfn></dt>
<dd>
<p>The <code data-x="">b</code>, <code data-x="">br</code>, <code data-x="">i</code>, <code
data-x="">div</code>, <code data-x="">p</code>, <code data-x="">rb</code>, <code
data-x="">rt</code>, <code data-x="">rtc</code>, <code data-x="">ruby</code>, and the <code
data-x="">span</code> element.</p>
<dd>

<dt><dfn>Cue background</dfn></dt>
<dd>
<p>One or more of the <span>allowed text track cue elements</span> in a <span>text track cue
fragment</span> that has a <code data-x="attr-cuebackground">cuebackground</code>
attribute.</p>
<p class="note">
A <span>cue background</span> can be selected and styles via the CSS <code
data-x="">::cuebackground</code> pseudo-element.
</p>
</dd>

<dt><dfn data-x="text track cue start time">A start time</dfn>
<dd>
<p>The time, in seconds and fractions of a second, that describes the beginning of the range of
Expand All @@ -39099,6 +39133,7 @@ interface <dfn interface>VideoTrack</dfn> {
example, WebVTT has a <span>text track cue writing direction</span> and so forth.
<ref>WEBVTT</ref></p>
</dd>

</dl>

<p>An <dfn data-x="unbounded text track cue">unbounded text track cue</dfn> is a text track cue
Expand Down Expand Up @@ -40124,6 +40159,7 @@ interface <dfn interface>TextTrackCueList</dfn> {

<pre><code class="idl">[Exposed=Window]
interface <dfn interface>TextTrackCue</dfn> : <span>EventTarget</span> {
<span data-x="dom-TextTrackCue">constructor</span>(double startTime, double endTime, DocumentFragment cueFragment);
readonly attribute <span>TextTrack</span>? <span data-x="dom-TextTrackCue-track">track</span>;

attribute DOMString <span data-x="dom-TextTrackCue-id">id</span>;
Expand All @@ -40136,6 +40172,10 @@ interface <dfn interface>TextTrackCue</dfn> : <span>EventTarget</span> {
};</code></pre>

<dl class="domintro">
<dt><code data-x=""><var>cue</var> = new <span subdfn data-x="dom-TextTrackCue">TextTrackCue</span>(startTime, endTime, cueFragment)</code></dt>
<dd>
<p>Creates a <code>TextTrackCue</code> instance with the given parameters.</p>
</dd>
<dt><code data-x=""><var>cue</var>.<span subdfn data-x="dom-TextTrackCue-track">track</span></code></dt>
<dd>
<p>Returns the <code>TextTrack</code> object to which this <span>text track cue</span> belongs,
Expand Down Expand Up @@ -40175,6 +40215,122 @@ interface <dfn interface>TextTrackCue</dfn> : <span>EventTarget</span> {
</dl>

<div w-nodev>
<p>The <dfn constructor for="TextTrackCue"><code
data-x="dom-TextTrackCue">TextTrackCue(<var>startTime</var>, <var>endTime</var>,
<var>cueFragment</var>)</code></dfn> constructor runs the following steps:</p>

<ol>
<li><p>If <var>cueFragment</var> first child is null or a <code>Text</code> node, then throw an
<span>"<code>InvalidNodeTypeError</code>"</span> <code>DOMException</code>.</p></li>
<li>
<p>For each <var>child</var> in <var>cueFragment</var>'s children:</p>
<ol>
<li><p><span data-x="ensure cue descendant">Ensure <var>child</var> is an allowed cue
descendant</span>.</p></li>
</ol>
</li>
<li><p>Let <var>fragment</var> be a newly created <code>DocumentFragment</code> using
<span>this</span>'s <span>relevant global object</span>'s <span
data-x="concept-document-window">associated <code>Document</code></span>.</li>
<li>
<p>Let <var>clones</var> be a clone of <var>cueFragment</var>, with the clone children flag set
to true.</p> <p class="note">This is to prevent mutation of the <var>cueFragment</var> after
construction.</p>
</li>
<li>
<p><span data-x="concept-node-append">Append</span> <var>clones</var> into <var>fragment</var>.
Rethrow any exceptions.</p> <p class="note"><span data-x="concept-node-append">Append</span>
runs the <span>ensure pre-insertion validity</span> algorithm, which can throw.</p>
</li>
<li><p><span data-x="assure cue elements">Assure the required elements for cue</span> passing
<var>fragment</var> and a new map «[ "cuebackground" → null, "cue" → null ]». Rethrow any
exceptions.</p></li>
<li><p>Set <span>this</span>'s <span>text track cue fragment</span> to
<var>fragment</var>.</p></li>
<li><p>Set <span>this</span>'s <span>text track cue start time</span> to
<var>startTime</var>.</p></li>
<li><p> Set <span>this</span>'s <span>text track cue end time</span> to
<var>endTime</var>.</p></li>
<li><p> Return <span>this</span>.</p></li>
</ol>

<p>To <dfn data-x="ensure cue descendant">ensure <code>Node</code> <var>node</var> is an allowed
cue descendant</dfn>, run these steps:</p>
<ol>
<li><p>If <var>node</var> is not an <span>exclusive <code>Text</code> node</span> or is not an
<code>Element</code>, then throw <span>"<code>InvalidNodeTypeError</code>"</span>
<code>DOMException</code>.</p></li>
<li>
<p>If <var>node</var> is an <code>Element</code>:</p>
<ol>
<li><p>If <var>node</var>'s namespace is not in the <span>HTML namespace</span>, then throw
<span>"<code>InvalidNodeTypeError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>node</var> is not one of the <span>allowed text track cue elements</span>, then
throw <span>"<code>InvalidNodeTypeError</code>"</span> <code>DOMException</code>.</p></li>
<li>
<p>For each <var>child</var> of node in tree order:
<ol>
<li><p><span data-x="ensure cue descendant">Ensure <var>child</var> is an allowed cue
descendant</span>.</p></li>
</ol>
</li>
</ol>
</li>
</ol>

<p>To <dfn data-x="assure cue elements">Assure the required elements for cue</dfn> with
<code>Node</code> <var>node</var>, and <span data-x="ordered map">map</span>
<var>requiredElements</var>:</p>
<ol>
<li>
<p>If <var>node</var> is a <code>DocumentFragment</code>:</p>
<ol>
<li>
<p>For each <var>child</var> of <var>node</var> in tree order:</p>
<ol>
<li><p><span data-x="assure cue elements">Assure the required elements for cue</span>
passing <var>child</var> and <var>requiredElements</var>.</p></li>
</ol>
</li>
<li><p>If <var>requiredElements</var>["cue"] is null or
<var>requiredElements</var>["cuebackground"] is null, then throw an
<span>"<code>InvalidNodeTypeError</code>"</span> <code>DOMException</code>.</p></li>
</ol>
</li>
<li>
<p>If <var>node</var> is an <code>Element</code>:</p>
<ol>
<li>
<p>If <var>requiredElements</var>["cuebackground"] is null:</p>
<ol>
<li><p>Set <var>requiredElements</var>["cuebackground"] to the result of getting an
attribute in the <span>HTML namespace</span>, "cuebackground", <var>node</var>.</p></li>
</ol>
</li>
<li>
<p>If <var>requiredElements</var>["cue"] is null:</p>
<ol>
<li><p>Let <var>cue</var> be the result of getting an attribute in the <span>HTML
namespace</span>, "cue", <var>node</var>.</p></li>
<li>
<p>If <var>cue</var> is not null:</p>
<ol>
<li><p>Let <var>backgroundCue</var> be
<var>requiredElements</var>["cuebackground"].</p></li>
<li><p>If <var>backgroundCue</var> is null, then throw a
<span>"<code>HierarchyRequestError</code>"</span> <code>DOMException</code>.</p></li>
<li><p>If <var>backgroundCue</var> is not an inclusive ancestor of <var>cue</var>, then
throw a <span>"<code>HierarchyRequestError</code>"</span>
<code>DOMException</code>.</p></li>
<li><p>Set <var>requiredElements</var>["cue"] to <var>cue</var> and break.</p></li>
</ol>
</li>
</ol>
</li>
</ol>
</li>
<li><p>If <var>node</var> is an any other type, continue.</p></li>
</ol>

<p>The <dfn attribute for="TextTrackCue"><code data-x="dom-TextTrackCue-track">track</code></dfn>
attribute, on getting, must return the <code>TextTrack</code> object of the <span>text
Expand Down Expand Up @@ -40219,6 +40375,7 @@ interface <dfn interface>TextTrackCue</dfn> : <span>EventTarget</span> {
unset otherwise.</p>



<h6 id="cue-events">Event handlers for objects of the text track APIs</h6>

<p>The following are the <span>event handlers</span> that (and their corresponding <span
Expand Down Expand Up @@ -40264,6 +40421,83 @@ interface <dfn interface>TextTrackCue</dfn> : <span>EventTarget</span> {



<h6>The <dfn data-x="attr-cue"><code>cue</code></dfn> and <dfn
data-x="attr-cuebackground"><code>cuebackground</code></dfn> attributes</h6>

<p class="note">
The <code data-x="attr-cue">cue</code> and <code data-x="attr-cue">cuebackround</code>
attibutes are intended for use in the creation of a <span>text track cue fragment</span>,
where they serve as pseudo-elements. As such, they use in docuemnt will generally have no effect.
</p>

<div class="example">

<p>The following shows a typical usage scenario for
<code data-x="attr-cue">cue</code> and <code data-x="attr-cue">cuebackround</code>.</p>


<pre><code class="js">// Get a reference to a video element.
const videoElement = document.getElementById("someVideoElement");

// Create a new text track.
const textTrack = videoElement.addTextTrack("captions", "English", "en");
textTrack.mode = "showing";

// Create a new cue fragment.
const cueFragment = document.createDocumentFragment();
const div = document.createElement("div");
div.cuebackground = true;
div.innerHTML = "This is a &lt;span cue class='important'>cue&lt;/span>.";
cueFragment.appendChild(div);
const cue = new TextTrackCue(0, 30, cueFragment);

// Now add the cue to the text track.
textTrack.addCue(cue);
</code></pre>

<p>
And then the `::cue` and ::`cuebackground` pseudo-elements can be used
to style the cue:
</p>
<pre><code class="css">::cue {
color: white;
font-size: 1.5em;
font-weight: bold;
}

::cue.important {
text-decoration: wavy;
}

::cuebackground {
background-color: black;
opacity: 0.5;
}</code></pre>

</div>

<p>When the <code data-x="attr-cue">cue</code> content attribute is present, the element serves as a
<span>text track cue</span>. A <span>text track cue fragment</span> must contain one or
more <span data-x="text track cue">text track cues</span>.</p>

<p>The <dfn data-x="dom-cue">cue</dfn> IDL attribute must <span>reflect</span> the content
attribute of the same name.</p>

<p>When the <code data-x="attr-cuebackground">cuebackground</code> attribute is present, the
element serves as <span>cue background</span> for a <span>text track cue</span>.</p>

<p>The <dfn data-x="dom-cuebackground">cuebackground</dfn> IDL attribute must
<span>reflect</span> the content attribute of the same name.</p>

<p>The <code data-x="attr-cue">cue</code> and <code
data-x="attr-cuebackground">cuebackground</code> attributes must each be present at least once
in a <span>text track cue fragment</span>.</p>

<p class="note">The <code data-x="attr-cue">cue</code> and <code
data-x="attr-cuebackground">cuebackground</code> can be present on the same element.</p>



<h6>Best practices for metadata text tracks</h6>

<!-- NON-NORMATIVE SECTION -->
Expand Down Expand Up @@ -136085,6 +136319,34 @@ interface <dfn interface>External</dfn> {
<code data-x="attr-media-crossorigin">video</code>
<td> How the element handles crossorigin requests
<td> "<code data-x="attr-crossorigin-anonymous-keyword">anonymous</code>"; "<code data-x="attr-crossorigin-use-credentials-keyword">use-credentials</code>"
<tr>
<th> <code data-x="">cue</code>
<td> <code data-x="attr-cue">b</code>
<code data-x="attr-cue">br</code>
<code data-x="attr-cue">i</code>
<code data-x="attr-cue">div</code>
<code data-x="attr-cue">p</code>
<code data-x="attr-cue">rb</code>
<code data-x="attr-cue">rt</code>
<code data-x="attr-cue">rtc</code>
<code data-x="attr-cue">ruby</code>
<code data-x="attr-cue">span</code>
<td> The element serve as a <span>text track cue</span>
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">cuebackground</code>
<td> <code data-x="attr-cuebackground">b</code>
<code data-x="attr-cuebackground">br</code>
<code data-x="attr-cuebackground">i</code>
<code data-x="attr-cuebackground">div</code>
<code data-x="attr-cuebackground">p</code>
<code data-x="attr-cuebackground">rb</code>
<code data-x="attr-cuebackground">rt</code>
<code data-x="attr-cuebackground">rtc</code>
<code data-x="attr-cuebackground">ruby</code>
<code data-x="attr-cuebackground">span</code>
<td> The element serve as a <span>cue background</span>
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">data</code>
<td> <code data-x="attr-object-data">object</code>
Expand Down
Loading