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 a lang IDL Attribute to CanvasTextDrawingStyles, and clarify "direction" on same #10873

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Add a lang IDL Attribute to CanvasTextDrawingStyles, and clarify "direction" on same #10873

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eba506c
Add the lang IDL attribute to CanvasTextDrawingStyles
schenney-chromium Dec 18, 2024
caa22ca
Merge branch 'whatwg:main' into main
schenney-chromium Dec 18, 2024
488b95b
Fix Developer info
schenney-chromium Dec 18, 2024
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
113 changes: 106 additions & 7 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65274,6 +65274,7 @@ interface mixin <dfn interface>CanvasPathDrawingStyles</dfn> {

interface mixin <dfn interface>CanvasTextDrawingStyles</dfn> {
// text
attribute DOMString <span data-x="dom-context-2d-lang">lang</span>; // (default: "inherit")
attribute DOMString <span data-x="dom-context-2d-font">font</span>; // (default 10px sans-serif)
attribute <span>CanvasTextAlign</span> <span data-x="dom-context-2d-textAlign">textAlign</span>; // (default: "start")
attribute <span>CanvasTextBaseline</span> <span data-x="dom-context-2d-textBaseline">textBaseline</span>; // (default: "alphabetic")
Expand Down Expand Up @@ -65738,6 +65739,7 @@ context.fillRect(100,0,50,50); // only this square remains</code></pre>
data-x="dom-context-2d-shadowOffsetX">shadowOffsetX</code>, <code
data-x="dom-context-2d-shadowOffsetY">shadowOffsetY</code>, <code
data-x="dom-context-2d-shadowBlur">shadowBlur</code>, <code
data-x="dom-context-2d-lang">lang</code>, <code
data-x="dom-context-2d-font">font</code>, <code
data-x="dom-context-2d-textAlign">textAlign</code>, <code
data-x="dom-context-2d-textBaseline">textBaseline</code>, <code
Expand Down Expand Up @@ -66232,6 +66234,20 @@ transform. ack Shaun Morris. -->
<h6>Text styles</h6>

<dl class="domintro">
<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-lang">lang</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-lang">lang</span> [ = <var>value</var> ]</code></dt>
<dd>
<p>Returns the current language setting.</p>

<p>Can be set, to change the language used when resolving fonts. The syntax and valid values
are the same as those for the <span data-x="attr-lang">lang</span> element attribute, or the
value "inherit".</p>

<p>The default is "inherit", which uses the <span data-x="attr-lang">lang</span> of the
<code>canvas</code> element, or the Document associated with a Worker when there is no
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose "Worker" is a typo here? Probably meant to say OffscreenCanvas?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that would be easier for developers to understand. I was basically using the final step in the algorithm to look it up, but that's an implementation thing.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it though? Having the worker side have to look up for the attached document's current lang would introduce a lot of timing issues. (Though, since I'm not even sure a Document has such an attribute I can't tell if it can change dynamically). But anyway this doesn't seem to match what's being defined afterward.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's hard to write a concise description of what inherit means here, so I am going for something that clearly conveys the intent without unnecessary details. Is your concern about clearly saying when the value will be looked up? I can see race conditions if the Document and worker are in different threads, but I can't see documents changing their language very often. (Maybe they do when the user agent translates the page - I will have to look at that.) Although I am also probably being too lax about accurate developer documentation. I'll take a stab at re-wording it for the next round.

<code>canvas</code> element, or a user-agent default language when neither source exists.</p>
</dd>

<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-font">font</span> [ = <var>value</var> ]</code></dt>
<dt><code data-x=""><var>styles</var>.<span data-x="dom-context-2d-font">font</span> [ = <var>value</var> ]</code></dt>
<dd>
Expand Down Expand Up @@ -66410,15 +66426,56 @@ worker.postMessage(offscreenCanvas, [offscreenCanvas]);</code></pre>
Notice that the font is only loaded inside the worker, and not in the document context.</p>
</div>

<p>The choice of fonts and glyphs within a font may vary according to the <dfn
attribute for="CanvasTextDrawingStyles"><code data-x="dom-context-2d-lang">lang</code></dfn>
IDL attribute. On setting, <code data-x="dom-context-2d-lang">lang</code> must be
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it be mentioned explicitly that if the string used for setting is invalid, then the stored value in the context doesn't change? For most other CanvasTextDrawingStyles it isn't needed as they are defined using IDL enums, but for the attributes that need parsing, like letterSpacing, the setter steps are outlined and therefore it's clear that an invalid value results in the attribute not being changed.

a <span data-x="attr-lang">valid BCP 47 language tag</span> or the string "inherit".
To determine the <dfn data-x="dom-context-2d-lang-used-value">used value</dfn>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: It's a bit confusing to have this algo so close to the setter step. (Actually inside of it since there is no rendered return). It makes it look like it's called at that time only and thus doesn't make "inherit" dynamic.

Copy link
Contributor Author

@schenney-chromium schenney-chromium Dec 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. I'll move it.

for <code data-x="dom-context-2d-lang">lang</code>, use the following steps:</p>

<ol>
<li><p>If <var>object</var>'s <code data-x="dom-context-2d-lang">lang</code> value is
"inherit", then</p>
<ol>
<li><p>If <var>object</var>'s <span>font style source object</span> is a <code>canvas</code>
element, then return the element's <span data-x="attr-lang">lang atribute
value</span>.</p></li>

<li>
<p>Otherwise, <var>object</var>'s <span>font style source object</span> is an
<code>OffscreenCanvas</code> object:</p>

<ol>
<li><p>Let <var>global</var> be <var>object</var>'s <span>relevant global
object</span>.</p></li>

<li><p>If <var>global</var> is a <code>Window</code> object, then return the
<span data-x="attr-lang">lang attribute</span> from <var>global</var>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>

<li><p>Otherwise, return a user-agent-defined default lang.</p></li>
</ol>
</li>
</ol>
<li><p>Otherwise, the <span>used value</span> is the <code data-x="dom-context-2d-lang">lang</code>
value.</p></li>
</ol>

<p>The <code data-x="dom-context-2d-lang">lang</code> IDL attribute, on getting, must return
the current value.</p>

<p>The <dfn attribute for="CanvasTextDrawingStyles"><code
data-x="dom-context-2d-font">font</code></dfn> IDL attribute, on setting, must be <span
data-x="parse something according to a CSS grammar">parsed as a CSS &lt;'font'> value</span> (but
without supporting property-independent style sheet syntax like 'inherit'), and the resulting font
must be assigned to the context, with the <span>'line-height'</span> component forced to 'normal',
with the <span>'font-size'</span> component converted to <span data-x="'px'">CSS pixels</span>,
and with system fonts being computed to explicit values. If the new value is syntactically
incorrect (including using property-independent style sheet syntax like 'inherit' or 'initial'),
then it must be ignored, without assigning a new font value. <ref>CSS</ref></p>
must be assigned to the context, with the primary language set to the <span
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is "primary language" here the same as CSS's content language?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was intending it to mean the "primary language" as used in https://html.spec.whatwg.org/multipage/dom.html#the-lang-and-xml:lang-attributes. The solution is to convert that linked reference to a definition and then refer to the definition in the canvas change.

data-x="dom-context-2d-lang-used-value">used-value</span> for <code
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this work to define the used value here? What if I don't ever set the font attribute, but set the lang one. Will my default sans-serif font be able to get this used value?
Would it work better if it was called in text preparation algo instead?

+Nit: might be better as "used value" (without the "-") for easing search in page

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will take a look at what happens in Chromium for a non-defined font, but regardless I will update this to make it clear what happens when there is no defined font. And yes to moving it to the text preparation algorithm (and the direction resolution) because it does indeed need to be dynamic. I was wondering about the right way to ensure that dynamic changes were handled, and you've answered my question.

data-x="dom-context-2d-lang">lang</code>, with the <span>'line-height'</span>
component forced to 'normal', with the <span>'font-size'</span> component converted to <span
data-x="'px'">CSS pixels</span>, and with system fonts being computed to explicit values. If the
new value is syntactically incorrect (including using property-independent style sheet syntax
like 'inherit' or 'initial'), then it must be ignored, without assigning a new font value.
<ref>CSS</ref></p>

<p>Font family names must be interpreted in the context of the <span>font style source
object</span> when the font is to be used; any fonts embedded using <code
Expand Down Expand Up @@ -66624,8 +66681,49 @@ worker.postMessage(offscreenCanvas, [offscreenCanvas]);</code></pre>

<dt><dfn enum-value for="CanvasDirection"><code data-x="dom-context-2d-direction-inherit">inherit</code></dfn>

<dd><p>Default to the directionality of the <code>canvas</code> element or <code>Document</code>
as appropriate.</p></dd>
<dd><p>Use the following process to determine which direction to treat input to the <span>text preparation algorithm</span></p>

<ol>
<li><p>If <var>object</var>'s <span>font style source object</span> is a <code>canvas</code>
element:</p>

<ol>
<li><p>If <span data-x="attr-dir">dir</span> attribute of the element is
<code data-x="attr-dir-auto">auto</code> then use the element's <span>computed value</span> of
<span>'direction'</span> as the direction.</p></li>

<li><p>Otherwise, use the value of the <span data-x="attr-dir">dir</span> attribute of the element
as the direction.</p></li>
</ol>

<li>
<p>Otherwise, <var>object</var>'s <span>font style source object</span> is an
<code>OffscreenCanvas</code> object:</p>

<ol>
<li><p>Let <var>global</var> be <var>object</var>'s <span>relevant global
object</span>.</p></li>

<li><p>If <var>global</var> is a <code>Window</code> object:</p>
<ol>
<li><p>Let <var>Document</var> be the <var>global</var>'s
<span data-x="concept-document-window">associated <code>Document</code></span>.</p></li>

<li><p>If the value of the <span data-x="attr-dir">dir attribute</span> from
<var>Document</var> is <code data-x="attr-dir-auto">auto</code> then use the
<var>Document</var>'s <span>computed value</span> of <span>'direction'</span>
as the direction.</p></li>

<li><p>Otherwise, use the value of the <span data-x="attr-dir">dir attribute</span> from
<var>Document</var> as the direction.</p></li>
</ol>
</li>

<li><p>Otherwise, treat input to the <span>text preparation algorithm</span> as left-to-right text.</p></li>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With this being clarified here, the step 4. in the text preparation algo should be updated to use it directly (currently this algo wouldn't be called, if I'm reading correctly).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. As above.

</ol>
</li>
</ol>
</dd>
</dl>

<p>The <code data-x="dom-context-2d-fontKerning">fontKerning</code> attribute's allowed keywords
Expand Down Expand Up @@ -146515,6 +146613,7 @@ INSERT INTERFACES HERE
Ştefan Vargyas,
Stefan Weiss,
Steffen Meschkat,
Stephen Chenney,
Stephen Ma,
Stephen Stewart,
Stephen White,
Expand Down