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

Extend Canvas TextMetrics for editing and text styling #11000

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

Extend Canvas TextMetrics for editing and text styling #11000

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
20e36f8
Initial commit: TextMetrics additions
AndresRPerez12 Feb 3, 2025
370fb3c
Group similar calls together, fix typos, and use infra maps
AndresRPerez12 Feb 7, 2025
1f94348
Clarify index inclusion for ranges
AndresRPerez12 Feb 10, 2025
1b9e735
Add strokeTextCluster()
AndresRPerez12 Feb 10, 2025
9cab38c
Make TextCluster an opaque object
AndresRPerez12 Feb 12, 2025
85c06f1
Fix indentantion around getTextClusters
AndresRPerez12 Feb 12, 2025
b6a2c7a
Add description for new methods in intro section
AndresRPerez12 Feb 14, 2025
6e08c93
Clarify cluster definition
AndresRPerez12 Feb 18, 2025
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
209 changes: 209 additions & 0 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4530,6 +4530,15 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
</ul>
</dd>

<dt>Unicode</dt>
<dd>
<p>The following terms are defined in <cite>Unicode</cite>: <ref>UNICODE</ref></p>

<ul class="brief">
<li><dfn data-x-href="https://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries">grapheme cluster</dfn></li>
</ul>
</dd>

<dt>Web App Manifest</dt>

<dd>
Expand Down Expand Up @@ -65506,6 +65515,7 @@ interface mixin <dfn interface>CanvasText</dfn> {
undefined <span data-x="dom-context-2d-fillText">fillText</span>(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
undefined <span data-x="dom-context-2d-strokeText">strokeText</span>(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
<span>TextMetrics</span> <span data-x="dom-context-2d-measureText">measureText</span>(DOMString text);
undefined <span data-x="dom-context-2d-fillTextCluster">fillTextCluster</span>(<span>TextCluster</span> textCluster, double x, double y, optional <span>TextClusterOptions</span> options);
};

interface mixin <dfn interface>CanvasDrawImage</dfn> {
Expand Down Expand Up @@ -65604,6 +65614,28 @@ interface <dfn interface>TextMetrics</dfn> {
readonly attribute double <span data-x="dom-textmetrics-hangingBaseline">hangingBaseline</span>;
readonly attribute double <span data-x="dom-textmetrics-alphabeticBaseline">alphabeticBaseline</span>;
readonly attribute double <span data-x="dom-textmetrics-ideographicBaseline">ideographicBaseline</span>;

sequence&lt;DOMRectReadOnly> <span data-x="dom-textmetrics-getSelectionRects">getSelectionRects</span>(unsigned long start, unsigned long end);
DOMRectReadOnly <span data-x="dom-textmetrics-getActualBoundingBox">getActualBoundingBox</span>(unsigned long start, unsigned long end);
unsigned long <span data-x="dom-textmetrics-getIndexFromOffset">getIndexFromOffset</span>(double offset);
sequence&lt;<span>TextCluster</span>> <span data-x="dom-textmetrics-getTextClusters">getTextClusters</span>(unsigned long start, unsigned long end, optional <span>TextClusterOptions</span> options);
};

[Exposed=(Window,Worker)]
interface <dfn interface>TextCluster</dfn> {
readonly attribute double <span data-x="dom-TextCluster-x">x</span>;
readonly attribute double <span data-x="dom-TextCluster-y">y</span>;
readonly attribute unsigned long <span data-x="dom-TextCluster-begin">begin</span>;
readonly attribute unsigned long <span data-x="dom-TextCluster-end">end</span>;
readonly attribute <span>CanvasTextAlign</span> <span data-x="dom-TextCluster-align">align</span>;
readonly attribute <span>CanvasTextBaseline</span> <span data-x="dom-TextCluster-baseline">baseline</span>;
};

dictionary <dfn dictionary>TextClusterOptions</dfn> {
<span>CanvasTextAlign</span> align;
<span>CanvasTextBaseline</span> baseline;
double x;
double y;
};

dictionary <dfn dictionary>ImageDataSettings</dfn> {
Expand Down Expand Up @@ -69143,6 +69175,12 @@ try {
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-ideographicBaseline">ideographicBaseline</span></code></dt>

<dd><p>Returns the measurement described below.</p></dd>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-getSelectionRects">getSelectionRects</span>(<var>start</var>, <var>end</var>)</code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-getActualBoundingBox">getActualBoundingBox</span>(<var>start</var>, <var>end</var>)</code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-getIndexFromOffset">getIndexFromOffset</span>(<var>offset</var>)</code></dt>
<dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-getTextClusters">getTextClusters</span>(<var>start</var>, <var>end</var> [, <var>options</var> ])</code></dt>

<dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-fillTextCluster">fillTextCluster</span>(<var>textCluster</var>, <var>x</var>, <var>y</var> [, <var>options</var> ])</code></dt>
</dl>

<div w-nodev>
Expand Down Expand Up @@ -69327,6 +69365,116 @@ try {
positive numbers indicating that the given baseline is below the <span>ideographic-under
baseline</span>. (Zero if the given baseline is the <span>ideographic-under
baseline</span>.)</p></dd>

<dt><dfn method for="TextMetrics"><code data-x="dom-textmetrics-getSelectionRects">getSelectionRects(<var>start</var>, <var>end</var>)</code></dfn> method</dt>

<dd><p>Returns the set of rectangles that the UA would render as selection to select
a particular character range, in <span data-x="'px'">CSS pixels</span>. The positions are returned
relative to the alignment point given by the <code
data-x="dom-context-2d-textAlign">textAlign</code> and <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attributes.</p></dd>

<dt><dfn method for="TextMetrics"><code data-x="dom-textmetrics-getActualBoundingBox">getActualBoundingBox(<var>start</var>, <var>end</var>)</code></dfn> method</dt>

<dd>
<p>Returns the rectangle equivalent to the box described by <code
data-x="dom-textmetrics-actualBoundingBoxLeft">actualBoundingBoxLeft</code>, <code
data-x="dom-textmetrics-actualBoundingBoxRight">actualBoundingBoxRight</code>, <code
data-x="dom-textmetrics-actualBoundingBoxAscent">actualBoundingBoxAscent</code>, <code
data-x="dom-textmetrics-actualBoundingBoxDescent">actualBoundingBoxDescent</code>, for the given
range. The positions are returned relative to the alignment point given by the <code
data-x="dom-context-2d-textAlign">textAlign</code> and <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attributes.</p>

<p class="note">The bounding box can be (and usually is) different from the selection
rectangles, which are based on the advance of the text. A font that is particularly slanted or
with accents that go beyond the flow of text will have a different paint bounding box.</p>
</dd>

<dt><dfn method for="TextMetrics"><code data-x="dom-textmetrics-getIndexFromOffset">getIndexFromOffset(<var>offset</var>)</code></dfn> method</dt>

<dd><p>Returns the string index for the character at the given offset distance from the start
position of the text run, relative to the alignment point given by the <code
data-x="dom-context-2d-textAlign">textAlign</code> attribute, with offset always increasing left
to right (negative offsets are valid). Values to the left or right of the text bounds will return
0 or the length of the text, depending on the writing direction.</p></dd>

<dt><dfn method for="TextMetrics"><code data-x="dom-textmetrics-getTextClusters">getTextClusters(<var>start</var>, <var>end</var>, <var>options</var>)</code></dfn> method</dt>

<dd>
<p>Splits the given range of the text into <span data-x="grapheme cluster">grapheme clusters</span>, and returns the positional data
for each cluster, as a list of new <code>TextCluster</code> objects, with members behaving as
described in the following list: <ref>UNICODE</ref></p>

<dl>
<dt><dfn attribute for="TextCluster"><code data-x="dom-TextCluster-x">x</code></dfn> attribute</dt>

<dd>
<p>The x coordinate of the cluster, on a coordinate space using <span
data-x="'px'">CSS pixels</span>, with its origin at the anchor point defined by the <code
data-x="dom-context-2d-textAlign">textAlign</code> attribute (at the time <code
data-x="dom-context-2d-measureText">measureText()</code> was called) in relation to the text
as a whole.</p>

<p>The x position specified for each cluster corresponds to the aligment point given by the
<code data-x="dom-TextCluster-align">align</code> attribute of the cluster (e.g. if
this attribute is set to "<code data-x="">left</code>", the calculated position corresponds
to the <code data-x="dom-context-2d-textAlign-left">left</code> of each cluster). The
selection criteria for this alignment point is explained in the section for this attribute
of the cluster.</p>
</dd>

<dt><dfn attribute for="TextCluster"><code data-x="dom-TextCluster-y">y</code></dfn> attribute</dt>

<dd>
<p>The y coordinate of the cluster, on a coordinate space using <span
data-x="'px'">CSS pixels</span>, with its origin at the anchor point defined by the <code
data-x="dom-context-2d-textBaseline">textBaseline</code> attribute (at the time <code
data-x="dom-context-2d-measureText">measureText()</code> was called) in relation to the text
as a whole.</p>

<p>The y position specified for each cluster corresponds to the aligment point given by the
<code data-x="dom-TextCluster-baseline">baseline</code> attribute of the cluster (e.g. if
this attribute is set to "<code data-x="">top</code>", the calculated position corresponds
to the <code data-x="dom-context-2d-textBaseline-top">top</code> of each cluster). The
selection criteria for this alignment point is explained in the section for this attribute
of the cluster.</p>
</dd>

<dt><dfn attribute for="TextCluster"><code data-x="dom-TextCluster-begin">begin</code></dfn> attribute</dt>

<dd><p>The starting index for the range of <span data-x="code point">code points</span> that are
rendered as this cluster.</p></dd>

<dt><dfn attribute for="TextCluster"><code data-x="dom-TextCluster-end">end</code></dfn> attribute</dt>

<dd><p>The ending index for the range of <span data-x="code point">code points</span> that are
Copy link
Contributor

Choose a reason for hiding this comment

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

Is this the index one past the end? Range APIs seem to behave that way but I'm not sure how conventional it is.

Copy link
Author

Choose a reason for hiding this comment

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

Yes, it is one past the end. I hadn't realized I didn't clarify it in the spec. I'll add it explicitly as I don't know how conventional it is either.

rendered as this cluster.</p></dd>

<dt><dfn attribute for="TextCluster"><code data-x="dom-TextCluster-align">align</code></dfn> attribute</dt>

<dd><p>The align for the specific point returned for the cluster. If a
<code>TextClusterOptions</code> options dictionary is passed, and it has a value for
<code data-x="">options.align</code>, this will be the assigned value. Otherwise, it will be
set as the <code data-x="dom-context-2d-textAlign">textAlign</code> attribute. Note that this
doesn't change the origin of the coordinate system, just which point is specified for each
cluster.</p></dd>

<dt><dfn attribute for="TextCluster"><code data-x="dom-TextCluster-baseline">baseline</code></dfn> attribute</dt>

<dd><p>The baseline for the specific point returned for the cluster. If a
<code>TextClusterOptions</code> options dictionary is passed, and it has a value for
<code data-x="">options.baseline</code>, this will be the assigned value. Otherwise, it will
be set as the <code data-x="dom-context-2d-textBaseline">textBaseline</code> attribute. Note
that this doesn't change the origin of the coordinate system, just which point is specified
for each cluster.</p></dd>
</dl>

<p class="note">The user agent might internally store in the <code>TextCluster</code> object the
complete text, as well as all the <code>CanvasTextDrawingStyles</code> at the time that <code
data-x="dom-context-2d-measureText">measureText()</code> was called, as they will be needed to
correctly render the clusters as they were measured.</p>
Copy link
Contributor

Choose a reason for hiding this comment

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

Is it a requirement that the drawing command uses the same parameters as the measurement? If so I would say that directly here, because right now it seems suggestive but not prescribed.

Copy link
Author

Choose a reason for hiding this comment

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

Yes, that is specified in the section for fillTextCluster(). The idea when I first wrote it was to just mention the behavior expected, even if the implementation would most likely be to store the parameters in the cluster (as is implemented right now in Chrome).

But, following a suggestion by @Kaiido in another comment, I changed the phrasing of that requirement by using TextCluster as an opaque object that stores those parameters in cluster when they are created. Hopefully this is more clear. Let me know what you think!

</dd>
</dl>

<p class="note">Glyphs rendered using <code data-x="dom-context-2d-fillText">fillText()</code> and
Expand All @@ -69339,7 +69487,67 @@ try {
documents, rendered using CSS, straight to the canvas. This would be provided in preference to a
dedicated way of doing multiline layout.</p>

<p>The <dfn method for="CanvasText"><code
data-x="dom-context-2d-fillTextCluster">fillTextCluster(<var>textCluster</var>, <var>x</var>,
<var>y</var>, <var>options</var>)</code></dfn> method renders a <code>TextCluster</code> object.
The cluster is rendered where it would be if the whole text that was passed to <code
data-x="dom-context-2d-measureText">measureText()</code> to obtain the cluster was rendered at
Copy link
Member

@Kaiido Kaiido Feb 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Disclaimer: I'm not an editor, so take this with a grain of salt.

I feel this would be a lot clearer if the TextMetrics interface had an internal value to store the original text for each instance and reuse it where needed, instead of this tedious "the text that was passed to measureText() to obtain the cluster".

See for instance how CanvasPattern objects have a transformation matrix that isn't exposed:

Patterns have a transformation matrix, which controls how the pattern is used when it is painted. Initially, a pattern's transformation matrix must be the identity matrix.

It might even be needed to have a clear relationship established between the TextCluster and the TextMetrics from where it's been created, so that you can do something like the cluster's textmetrics's text, or, given that when the TextCluster is created text is available, and TextMetrics may not need it otherwise, you could maybe store it directly along the TextCluster (still in an internal value).

Copy link
Author

Choose a reason for hiding this comment

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

I hadn't noticed that objects like CanvasPattern were defined in this way as opaque. I like that concept and I feel it applies well to this use case. Thank you so much for the suggestion!

I have updated it to reflect this. For now I went with the second approach you mentioned (storing the text and the CanvasTextDrawingStyles directly in the cluster as internal values). Hopefully this provides more clarity. Let me know what you think!

position (<var>x</var>,<var>y</var>), unless the positioning is modified with the options
argument. Specifically, when the methods are invoked, the user agent must run these steps:</p>

<ol>
<li><p>If any of the arguments are infinite or NaN, then return.</p></li>

<li><p>Run the <span>text preparation algorithm</span>, passing it the <var>text</var>
originally passed to <code data-x="dom-context-2d-measureText">measureText()</code> to obtain
the cluster, and an object with the <code>CanvasTextDrawingStyles</code> values as they were
when the cluster was measured, with the exception of <code
Copy link
Member

Choose a reason for hiding this comment

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

This object should probably be created explicitly sooner, in the getTextClusters() method. However I'm not sure how this should be done since we want the computed values at that time.

Copy link
Author

Choose a reason for hiding this comment

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

With the use of the internal values of the opaque object, hopefully the relationship is clearer now. Passing the exact object from the cluster won't always be possible due to the possibility of passing align and baseline to to fillTextCluster() when rendering, but most of the values now come from the internally stored value.

data-x="dom-context-2d-textAlign">textAlign</code> and <code
data-x="dom-context-2d-textBaseline">textBaseline</code>, which are taken from the <code
data-x="dom-TextCluster-align">align</code> and <code
data-x="dom-TextCluster-baseline">baseline</code> attributes of <var>cluster</var>. Let
<var>glyphs</var> be the result.</p></li>

<li><p>Filter <var>glyphs</var> to include only glyphs that contain <span
data-x="code point">code points</span> within the range <code
data-x="dom-TextCluster-begin">cluster.begin</code> to <code
data-x="dom-TextCluster-end">cluster.end</code>.</p></li>

<li><p>Move all the shapes in <var>glyphs</var> to the right by <var>x</var>
<span data-x="'px'">CSS pixels</span> and down by <var>y</var> <span data-x="'px'">CSS
pixels</span>.</p></li>

<li>
<p>If a <code>TextClusterOptions</code> options dictionary is passed and it has an <code
data-x="">options.x</code> value, move all the shapes in <var>glyphs</var> to the right by
<code data-x="">options.x-cluster.x</code>.</p>

<p>If a <code>TextClusterOptions</code> options dictionary is passed and it has an <code
data-x="">options.y</code> value, move all the shapes in <var>glyphs</var> down by <code
data-x="">options.y-cluster.y</code>.</p>
</li>

<li>
<p>Paint the shapes given in <var>glyphs</var>, as transformed by the <span
data-x="dom-context-2d-transformation">current transformation matrix</span>, with each <span
data-x="'px'">CSS pixel</span> in the coordinate space of <var>glyphs</var> mapped to one
coordinate space unit.</p>

<p><span>this</span>'s <span
data-x="concept-CanvasFillStrokeStyles-fill-style">fill style</span> must be applied to the
shapes and <span>this</span>'s <span
data-x="concept-CanvasFillStrokeStyles-stroke-style">stroke style</span> must be ignored.

<p>These shapes are painted without affecting the current path, and are subject to <span
data-x="shadows">shadow effects</span>, <span data-x="concept-canvas-global-alpha">global
alpha</span>, the <span>clipping region</span>, and the <span>current compositing and blending
operator</span>.</p>
</li>
</ol>

<p class="note">By setting <code data-x="">options.x</code> and <code data-x="">options.y</code>
to 0, the cluster will be rendered exactly at the position (<var>x</var>,<var>y</var>) passed to
<code data-x="dom-context-2d-fillTextCluster">fillTextCluster()</code>.</p>

<h6>Drawing paths to the canvas</h6>

Expand Down Expand Up @@ -146080,6 +146288,7 @@ INSERT INTERFACES HERE
Andreas Kling,
Andrei Popescu,
Andres Gomez,
Andrés Ricardo Pérez Rojas,
Andres Rios,
Andreu Botella,
Andrew Barfield,
Expand Down