skia2/experimental/sktext/include/SkText.md

title	linkTitle
SkText public API	SkText public API

The main idea behind SkText is to design a flexible API that allows a user from different platforms to shape, manipulate and draw text.

As text formatting works in stages, SkText presents a set of text objects that keep data from each stage. That staging approach allows a user to stop at any stage and drop all the data from the previous stages. Currently, we support the following stages:

• Parsing the text to extract all the unicode information that may be needed later: graphemes, words, hard/soft line breaks, whitespaces, bidi regions and so on. Class UnicodeText contains the initial text in utf16 format, and the mapping of unicode information to codepoints in a form of enum bit flags. It also has a method resolveFonts that creates a FontResolvedText object.

• Resolving fonts to break the text into blocks that can be shaped with one single font (selected out of a given list of fonts). Class FontResolvedText contains the results in a form of a list of text blocks with a single typeface for each. It also has a method shape that creates a ShapedText object.

• Shaping the text into a single line of glyphs according to all given formatting information (fonts, text direction, scripts, languages and so on). Class ShapedText contains the results in the form of a list of shaped blocks with all the information that comes from shaping: glyph ids, positioning, and mapping to the initial text and so on. It also has a method wrap that creates a WrappedText object.

• Wrapping the text into a list of lines (by a given width) and formatting it on the lines (left, right, center alignment or justification). Class WrappedText contains the shaped results from the previous stage only broken by lines and repositioned by lines. It also has a method prepareToDraw that creates a DrawableText object, and a method prepareToNavigate that creates a SelectableText object.

• Drawing the text into a canvas. This is more of an example of how to draw the text because it only covers a rather simple case of drawing (limited decorating supported). Based on this example a user can create a custom drawing class as complex as needed. Class DrawableText contains a list of SkTextBlob objects ready to be drawn on a canvas.

• Navigating the text by grapheme cluster (later, grapheme, glyph cluster or glyph). It has all the functionality for text editing. Class SelectableText contains all the methods for that: hit test, move position (left, right, up, down, to the beginning of the text or the line, to the end of the text or the line), select an arbitrary text (aligned to a grapheme cluster) and so on.

All the objects described above can exist independently of each other, so a user can decide which ones to keep.

Let’s consider few scenarios (flows):

1. A user only needs to get the unicode information.
   Strictly speaking, it’s not a text shaping operation but UnicodeText would allow it.
2. A user needs to draw the text.
   That requires performing the first 4 stages, but a user only needs to hold on to the DrawableText object afterwards (removing UnicodeText, ShapedText and WrappedText objects).
3. A user needs to draw and edit the text.
   That requires performing all the 5 stages. A user will have to hold on to DrawableText and SelectableText (removing the first 3 objects).
4. A user only needs to be wrapped text, implementing a custom drawing procedure.
   That requires performing the first 3 stages. A user will have to hold on to WrappedText (removing the first 2 objects).

At the moment there is no support for updating the text (which theoretically could be a less expensive operation). Any changes in the initial text will require the full set of operations.