Text Styling

Text styling allows applications to draw text in different fonts, colors, sizes, and so on. Each styling attributes can apply to all of the text being drawn, or just a portion of it.

Using PBTextAttribute

The tagged union PBTextAttribute stores a single text attribute. Its type field should be set to the type of the attribute.

There are many attribute types. The most common include PBTextAttribute_SIZE, PBTextAttribute_NUMERALS, PBTextAttribute_FONT_FAMILY, PBTextAttribute_WEIGHT and PBTextAttribute_COLOR.

There are also special attribute types which can refer to predefined text style. These will be discussed later in this document.

Once the attribute type has been set, one must then set the data fields for that specific attribute. For example, if type is set to PBTextAttribute_SIZE, then the field f32 should be set to the size of the text in points as a floating point number.

Using PBPositionedTextAttribute and PBRangedTextAttribute

To specify text where different characters are individually styled, API functions often accept either an array of PBPositionedTextAttribute structures or an array of PBRangedTextAttribute structures.

PBPositionedTextAttribute contains two fields: the attribute field, a PBTextAttribute; and the start field, an int32_t. The start field gives an offset in bytes from the beginning of the text to which the array of attributes are to be applied. Each attribute will be applied starting from its start offset and will stop applying once the next attribute of the same type is reached.

For example, consider the following array of positioned text attributes, applied to a string of length 20 bytes.

start = 0; attribute.type = PBTextAttribute_COLOR; attribute.color = <red>
start = 0; attribute.type = PBTextAttribute_WEIGHT; attribute.f32 = 400
start = 5; attribute.type = PBTextAttribute_WEIGHT; attribute.f32 = 700
start = 10; attribute.type = PBTextAttribute_COLOR; attribute.color = <blue>
start = 15; attribute.type = PBTextAttribute_WEIGHT; attribute.f32 = 400

This produces the following result.

Bytes 0 to 4 will be red and not bold.
Bytes 5 to 9 will be red and bold.
Bytes 10 to 14 will be blue and bold.
Bytes 15 to 19 will be blue and not bold.

A diagrammatic duplication of the above information.

PBRangedTextAttribute contains three fields: the attribute, a start offset and an end offset. Each attribute will be applied from its start offset and stop applying at its end offset. The start offset is inclusive; the end offset is exclusive. If multiple attributes of the same type are active at a given character, then whichever attribute started later takes priority.

For example, consider the following array of ranged text attributes, applied to a string of length 20 bytes.

start = 0; end = 20; attribute.type = PBTextAttribute_COLOR; attribute.color = <red>
start = 0; end = 20; attribute.type = PBTextAttribute_WEIGHT; attribute.f32 = 400
start = 5; end = 15; attribute.type = PBTextAttribute_WEIGHT; attribute.f32 = 700
start = 10; end = 18; attribute.type = PBTextAttribute_COLOR; attribute.color = <blue>

This produces the following result.

Bytes 0 to 4 will be red and not bold.
Bytes 5 to 9 will be red and bold.
Bytes 10 to 14 will be blue and bold.
Bytes 15 to 17 will be blue and not bold.
Bytes 18 to 19 will be red and not bold.

A diagrammatic duplication of the above information.

PBTextStyle

A text style, stored in a PBTextStyle object, contains an array of text attributes. One can be created with PBTextStyleCreate, passing the attribute array.

Several preset styles are available, and can be opened with PBTextStyleOpenByName. The PBNamedTextStyle enumeration gives a list of the preset styles.

Once created, one can obtain some basic information about that text style with functions like PBTextStyleGetLineHeight. But more importantly, the text style can be used as part of an array of text attributes. Indeed, there is a text attribute type that takes a text style: PBTextAttribute_STYLE.

For convenience, there is also the text attribute type PBTextAttribute_NAMED_STYLE which lets one directly use a preset text style. This avoids the need to open and release the text style.

A text style can also contain a set of text block properties, PBTextBlockProperties, such as the spacing to place before and after a block using that text style. The block properties are with the complex text documents created by PBTextDocumentBuilder.

The most common system preset text styles are:

PBNamedTextStyle_CONTROL_DEFAULT -- the text style used by most user interface elements, like buttons and checkboxes.
PBNamedTextStyle_CONTROL_SMALL -- a smaller variant of the defualt control style.
PBNamedTextStyle_MONOSPACED -- a monospaced text style with a size and weight similar to the default control style.

PBTextDocument

A text document encapsulates a string of text as well as a set of attributes applied to the text. One can be created with PBTextDocumentCreateWithPositionedAttributes or PBTextDocumentCreateWithRangedAttributes. See the discussion above for the difference between positioned attributes and ranged attributes.

The above type of text document is called a text node. There are also complex text documents can contain other text documents. This is necessary for displaying typographical features that cannot be contained within a single paragraph of text. For example, bulleted lists and code blocks. Such text documents can be created using the PBTextDocumentBuilder APIs, or the PBTextDocumentCreateWithMarkdown function, which uses a Markdown parser to build up a complex text document.

PBTextDocumentBuilder

The text document builder APIs are not finalized and as such are not yet described here.

PBTextRoleID

TODO

Guide