Model

This chapter describes how rich text content is represented in boustro. The terminology from this chapter is used throughout the book.

Document

A document in boustro is a list of lines of formatted text and embeddable content (called embeds). An immutable document is represented by a Document. While editing a document, its state is maintained by a DocumentController.

A document holds a collection of Paragraphs. Paragraphs are either a line of rich text — or an embed — which can be any custom content, for example an image or a code block.

Text

A text line represents rich text using a spanned string. Text lines can be modified with line modifiers. These modifiers wrap a line of text and can modify how they are displayed or override their style. Boustro has a modifier for bullet lists.

Spanned strings hold text, along with a list of spans that apply formatting or attach gestures to the text. The mutable version of a SpannedString is a SpannedTextEditingController — a subclass of Flutter's TextEditingController that manages formatting of its text.

Both SpannedString and SpannedTextEditingController maintain a SpanList. SpanList is an immutable list of AttributeSpan.

Attribute spans hold an attribute and a range:

• Range: range in the source text to which the attribute is applied. The boundaries of the range are indices into the source text, using Unicode (Extended) Grapheme Clusters (EGC) as the unit. EGC map to user-perceived characters. EGC indices are used to prevent indices in the middle of user-perceived characters. If you use a Range directly, you likely want to use the characters package.
• TextAttribute: The attribute can be resolved to a TextStyle (to apply formatting) and gestures (for example tap handler that opens a hyperlink) with its resolve method, which can optionally use an AttributeTheme to resolve to a style and gestures. The attribute also defines SpanExpandRules which determine how the span responds to insertions in the source text.

Embeds

An embed, in boustro, is a custom piece of content that can be embedded in rich text.

Visually, an embed can be any widget, and users can define different widgets for the editable and view-only version of the embed.

See Embeds to learn how embeds work and how to create custom embeds.

Component

A component is any implementation of TextAttribute, LineModifier or ParagraphEmbed. This concept is not used within boustro itself, but it's useful to define it for talking about customization in boustro.