@@ 0,0 1,190 @@
+---
+title: Newsletter, March 2023
+shorttitle: March 2023
+subtitle: Color Emoji, Text Truncation, and More
+date: "2023-03-13T12:00:00Z"
+---
+
+This month saw the merge of two notable text features: color bitmap glyph support and automatic shaper-driven text truncation. With these features, we are now able to display color emoji, and we are also able to visually indicate when text with a configured maximum number of lines has been truncated. I'd like to thank Plato Team for supporting this work financially, and Elias for reviewing the mountains of patches it generated.
+
+Additionally many folks in the community contributed features and bugfixes. Thanks everyone!
+
+## Sponsorship
+
+This month, Gio thanks the following organizations and community members for their ongoing support!
+
+Supporting the whole team:
+
+- [Plato Team](https://www.platoapp.com/) via GitHub Sponsorship of Elias and Chris.
+- [Tailscale](https://tailscale.com/) via OpenCollective.
+- [Lucas Rodrigues](https://github.com/Inkeliz/) via GitHub Sponsorship of Gioui and Elias.
+- [Denys Smirnov](https://github.com/dennwc) via OpenCollective.
+- [Larry Clapp](https://github.com/theclapp) via GitHub Sponsorship of Elias and Chris.
+
+Supporting a maintainer:
+
+- [Matilda Tech](https://github.com/matildatech) via GitHub Sponsorship of Elias.
+- [Fino Meng](https://github.com/finomeng) via GitHub Sponsorship of Elias.
+- [Chris Waldon](https://github.com/whereswaldon) via GitHub Sponsorship of Elias.
+- [Tom Ingleby](https://github.com/tingleby) via GitHub Sponsorship of Elias.
+- [Tanguy Herrmann](https://github.com/dolanor) via GitHub Sponsorship of Elias.
+- A number of anonymous community members.
+
+Sponsorship money given to Gio enables Elias and I to cover the costs of running Gio's infrastructure, to pay for some of our time spent maintaining and improving Gio, and to plan for funding significant feature work. You can support Gio by contributing on [OpenCollective](https://opencollective.com/gioui) or [GitHub Sponsors](https://github.com/sponsors/gioui).
+
+## Changes by repo
+
+Below you can find summaries and details of all changes across the official project repositories.
+
+### core gio
+
+As discussed above, core saw some major changes to the text stack. That resulted in a few breaking changes in the exported API, but
+the many applications will be unaffected.
+
+#### Shaper API Changes
+
+If you directly invoke `text.Shaper.Shape` to get the `clip.PathSpec` of text, you'll now need to also invoke `text.Shaper.Bitmaps` with the same `[]text.Glyph` to get an `op.CallOp` containing bitmap glyphs. Proper use looks something like this:
+
+```go
+// Assuming we have a slice of glyphs:
+var line []text.Glyph
+path := shaper.Shape(line)
+outline := clip.Outline{Path: path}.Op().Push(gtx.Ops)
+// set the paint material here.
+material.Add(gtx.Ops)
+paint.PaintOp{}.Add(gtx.Ops)
+outline.Pop()
+// Paint any bitmaps here. Notably, this callOp may change the
+// paint material, so it's important to always set the proper
+// paint material before painting the text above.
+if call := shaper.Bitmaps(line); call != (op.CallOp{}) {
+ call.Add(gtx.Ops)
+}
+```
+
+#### Widget API Changes
+
+If you use the `widget` API for displaying text, there are a few changes that affect you:
+
+##### Grapheme Cluster Support
+
+All interactive text widgets now expose their APIs in terms of "grapheme clusters," not runes. A "grapheme cluster" is Unicode's attempt to standardize a collection of potentially many runes that a use perceives as a single character. Supporting this is critical for displaying many non-latin languages, and also for emoji (which are often built of quite a few different runes). Applications with sophisticated editor content manipulation should start checking the final rune positions of cursors *after* programmatically moving the cursor, as the final positions will be clamped to grapheme cluster boundaries.
+
+##### Label Changes
+`widget.Label` is now *always* non-interactive. Before it had a `Selectable` field you could set to make it interactive, but this added complexity and made its `Layout` signature more complicated. Its `Layout` method now looks like this:
+
+```go
+func (l Label) Layout(gtx layout.Context, lt *text.Shaper, font text.Font, size unit.Sp, txt string, textMaterial op.CallOp) layout.Dimensions {
+```
+
+The `textMaterial` parameter is expected to set a paint material for the text. If you wanted to paint black text, you could construct the textMaterial like so:
+
+```go
+macro := op.Record(gtx.Ops)
+paint.ColorOp{Color: color.NRGBA{A:255}}.Add(gtx.Ops)
+textMaterial := macro.Stop()
+```
+
+You can, of course, also use a `paint.ImageOp` or `paint.LinearGradientOp`.
+
+##### Selectable Changes
+
+`widget.Selectable` is now used to display interactive text instead of `widget.Label`. Its `Layout` method looks similar to `widget.Label`, except that it accepts two materials, one for the text and one for the text selection rectangle.
+
+```go
+func (l *Selectable) Layout(gtx layout.Context, lt *text.Shaper, font text.Font, size unit.Sp, textMaterial, selectionMaterial op.CallOp) layout.Dimensions {
+```
+
+#### Truncator-related Changes
+
+If you display text with a maximum number of lines configured via any of
+
+- `text.Parameters.MaxLines`,
+- `widget.Label.MaxLines`,
+- or `material.LabelStyle.MaxLines`
+
+you can now also supply a `Truncator` string to display if the string wasn't able to fit within the available lines. This truncator will default to `…` if not specified, and cannot be turned off. If interactive text is truncated, selecting the truncator symbol is logically equivalent to selecting the entire truncated text, so users can copy&paste the full content from a truncated label.
+
+Using `widget.Selectable.Truncated()` it is now possible to create widgets that display truncated text, add their own hover detection, and choose a way to display the un-truncated text when hovered.
+
+I've added `gioui.org/example/textfeatures` to demonstrate color glyph rendering and custom truncator strings.
+
+#### Other Changes
+
+Additionally, Serhat Sevki Dincer contributed some great code cleanups, Dominik Honnef improved `layout.List`'s scrolling performance and `widget.Image`'s scaling behaviors, and Larry Clapp fixed a bug in font fallback that could choose the wrong face for displaying strings.
+
+#### Breaking changes by author:
+
+Chris Waldon
+
+- **`font/opentype,text,widget{,/material}`**: [API] support bitmap glyph rendering. This commit supports rendering opentype glyphs containing bitmap data instead of color data. In order to support returning the shaped bitmap glyphs from the Shaper's Shape() method, it has gained a second return parameter, an op.CallOp. Adding that CallOp immediately after or immediately before painting the returned path will display the bitmap glyphs. [6ab3ff40](https://git.sr.ht/~eliasnaur/gio/commit/6ab3ff40)
+- **`widget`**: [API] implement UAX#29 grapheme clustering in text widgets. This commit teaches the text widgets how to position their cursor according to grapheme cluster boundaries rather than rune boundaries. While this is more work, the results better match the expectations of users. A "grapheme cluster" is a user-perceived character that may be composed of arbitrarily many runes. [5c54268d](https://git.sr.ht/~eliasnaur/gio/commit/5c54268d)
+- **`widget{,/material}`**: [API] split interactive and non-interactive text widgets. This commit separates the types for interactive and non-interactive text within package widget. widget.Selectable is used for all interactive text. widget.Label is used for all non-interactive text. There is no longer a field on widget.Label to provide it with a Selectable. If you want selectable text and are not relying upon the material pacakge API, you need to create widget.Selectables instead of widget.Labels. The material package's LabelStyle API is unchanged. [9d0a53fc](https://git.sr.ht/~eliasnaur/gio/commit/9d0a53fc)
+- **`text,widget{,/material}`**: [API] move all shaping parameters into text.Parameters. This commit moves the min/max width of shaped text and the text's Locale into text.Parameters. They were previously passed as separate function parameters to the shaper, but this made little sense and added visual noise. This is a breaking change, but only if you previously invoked the shaping API directly. [7e8c1092](https://git.sr.ht/~eliasnaur/gio/commit/7e8c1092)
+
+#### Non-breaking changes by author
+
+Chris Waldon:
+
+- **`text`**: test maxlines with exported API. This commit changes _how_ the test for line wrapping is implemented to rely on the exported API rather than internal symbols. [1210bbb3](https://git.sr.ht/~eliasnaur/gio/commit/1210bbb3)
+- **`widget`**: ensure proper modifiers on key events. This commit extends the key event handling for text widgets to always check for appropriate modifier keys. Previously this wasn't necessary, as the text widgets would only ever receive key events it registered for, but now it may be the top-level key event handler and thus receive all key events that aren't handled elsewhere. [b09ef80d](https://git.sr.ht/~eliasnaur/gio/commit/b09ef80d)
+- **`layout`**: ensure Spacer obeys constraints. This commit ensures that the Spacer type doesn't break layouts by ignoring when its min constraints require it to be larger or its max constraints require it to be smaller. [d7b1c7c3](https://git.sr.ht/~eliasnaur/gio/commit/d7b1c7c3)
+- **`go.*,font/opentype,text`**: switch to latest go-text/typesetting api. This commit upgrades our go-text version to the latest one which internalizes harfbuzz and supports text truncators. This allows us to drop our dependency upon Benoit's textlayout package. [47d25c13](https://git.sr.ht/~eliasnaur/gio/commit/47d25c13)
+- **`go.*,widget`**: add initial emoji rendering benchmarks. This commit upgrades our version of eliasnaur.com/font to include a color emoji font and uses that to benchmark displaying large quantities of emoji. As expected, this is very slow when the strings change frequently, and uses silly amounts of memory. Future commits will work to improve this. [3bdbcab8](https://git.sr.ht/~eliasnaur/gio/commit/3bdbcab8)
+- **`text`**: cache bitmap glyph image operations. This commit adds caching to the process of extracting bitmap images from glyphs, ensuring that we only do so once for a given glyph so long as it isn't evicted from our LRU. [25171df6](https://git.sr.ht/~eliasnaur/gio/commit/25171df6)
+- **`widget`**: make glyphIndex reusable. This commit allows the glyph index type to be reset and reused, preventing the reallocation of numerous buffers when indexing glyphs. [36e768e7](https://git.sr.ht/~eliasnaur/gio/commit/36e768e7)
+- **`go.*,text,widget{,/material}`**: implement text truncators. This commit adds support for the idea of a text "Truncator", a string that is shown at the end of truncated text to indicate that it has been shortened because it would not fit within the requested number of lines. [959f5889](https://git.sr.ht/~eliasnaur/gio/commit/959f5889)
+- **`widget`**: expose truncation status of Selectable. This commit adds an exported method to enable widgets to detect when the text displayed by a Selectable has been truncated. This can be used to implement proper show-full-text-in-an-overlay behavior in a parent widget. I haven't attempted to implement that in core yet, as it is a complex feature involving animation and pointer interaction. [5e6e1217](https://git.sr.ht/~eliasnaur/gio/commit/5e6e1217)
+- **`widget/material`**: export LabelStyle.Shaper and document fields. We panic when someone constructs a literal LabelStyle because they cannot possibly populate the shaper field. The resulting error is cryptic, and unusual within Gio because most style types are safe to construct literally. This commit enables creating literal LabelStyles by exporting the Shaper field, and also documents the purposes of all of the fields. [5a404816](https://git.sr.ht/~eliasnaur/gio/commit/5a404816)
+
+Serhat Sevki Dincer:
+
+- **`app,gpu{,/headless,/internal/rendertest}`**: replace io/ioutil with io & os. [39b11584](https://git.sr.ht/~eliasnaur/gio/commit/39b11584)
+- **`text,widget`**: remove ineffective assignments. [35a82319](https://git.sr.ht/~eliasnaur/gio/commit/35a82319)
+- **`text`**: simplify font weights. [4a1962e5](https://git.sr.ht/~eliasnaur/gio/commit/4a1962e5)
+
+Dominik Honnef:
+
+- **`layout`**: simplify implementation of List.ScrollTo. [dc9a4a40](https://git.sr.ht/~eliasnaur/gio/commit/dc9a4a40)
+- **`layout`**: improve documentation for List.ScrollTo and List.ScrollBy. [107401cf](https://git.sr.ht/~eliasnaur/gio/commit/107401cf)
+- **`widget`**: [API] correct default scaling of images. When no scale factor is set, scale by 1.0, mapping one image pixel to one device-independent pixel. This matches the behavior of CSS and other frameworks. [51b11486](https://git.sr.ht/~eliasnaur/gio/commit/51b11486)
+
+Larry Clapp:
+
+- **`text`**: fix sorting in faceOrderer.sorted. faceOrderer.sorted tried to put the "primary" font first by tweaking the "less" function in sort.Slice, but it didn't work correctly. [fa34121f](https://git.sr.ht/~eliasnaur/gio/commit/fa34121f)
+
+### gio-x
+
+X saw a major overhaul of Windows notification support by Jack Mordaunt, a missing feature added to component surfaces by Lothar May, and a bugfix to text fields by Gordon Klaus. Thanks everyone!
+
+Chris Waldon:
+
+- **`go.*,styledtext`**: update to new text shaper API. [fdc1b67](https://git.sr.ht/~whereswaldon/gio-x/commit/fdc1b67)
+- **`go.*`**: update to latest gio. [fd712aa](https://git.sr.ht/~whereswaldon/gio-x/commit/fd712aa)
+
+Lothar May:
+
+- **`component`**: add Fill color field to SurfaceStyle. [05b40af](https://git.sr.ht/~whereswaldon/gio-x/commit/05b40af)
+
+Jack Mordaunt:
+
+- **`notify`**: [windows] use COM based toast notifications. This commit changes the toast dependency to one with a similar api but uses COM directy instead of powershell. [aad49f4](https://git.sr.ht/~whereswaldon/gio-x/commit/aad49f4)
+
+Gordon Klaus:
+
+- **`component`**: lay out TextField.Editor in a Flexed child. This positions Prefix and Suffix correctly (at the ends of the field) and stretches the editor as wide as possible so it accepts click events in a larger area. [64527da](https://git.sr.ht/~whereswaldon/gio-x/commit/64527da)
+
+### gio-example
+
+As discussed above, I added a new text features example.
+
+Chris Waldon:
+
+- **`go.*`**: update to latest gio and gio-x. [d22df62](https://git.sr.ht/~eliasnaur/gio-example/commit/d22df62)
+- **`textfeatures`**: add simple demo for color glyphs and truncation. This commit adds a simple program demonstrating how to load a color emoji font, how to configure a custom text truncator, and how the truncator behaves at various max widths. [059eaf6](https://git.sr.ht/~eliasnaur/gio-example/commit/059eaf6)
+
+## End
+
+Thanks for reading!
+
+Chris Waldon