Text and Text Attributes Overview

Purpose

Stores editable text and the formatting attributes which are applied to it.

The API does not store the layout information needed to display the text. This is done by a separate API called Text Views.

Text content is a string of Unicode characters separated into words and paragraphs by space characters and paragraph delimiters. The text is stored in the order used to input the text. A wide range of paragraph and character formatting attributes is supported, including paragraph alignment and character font, etc.

Architectural relationships

Text and Text Attributes uses the Text Views API to format the text for display. Text Views objects contain the layout information, but not the text itself or the attributes. These are obtained via an abstract interface class.

Text and Text Attributes classes are used for implementing editable text windows. UI-level objects like editable text windows typically own an editable text object to hold the rich text and attributes, and a Text Views object to store the layout and draw the text.

Description

The API has five key concepts: global text and rich text, document position and range, setting/sensing formatting, format layering and the MLayDoc interface.

Global text and rich text

Global text is text in which formatting is applied globally, so that the same character and paragraph formatting applies throughout the document. Rich text is text with rich formatting, so that formatting can apply to any portion of the document. Paragraph styles may be applied to rich text but not to global text, and pictures may be inserted into rich text but not global text.

The interface to global text is provided by CGlobalText. The interface to rich text is provided by CRichText.

Document position and range

When editing an editable text object, many functions require a start position and a length to be specified. These values indicate the range of characters to which the function should apply. The range usually has to be valid: that is, it must not extend beyond the bounds of the document. Document position zero is before the first character in the document. If the document contains n characters, position n is after the last character. Valid document positions are therefore between zero and the length of the document, inclusive.

Setting/sensing formatting

When setting or sensing a text object's formatting, a mask and a container are specified. The container has data members which store the value for every format attribute. The mask indicates which attributes are relevant to the operation.

The paragraph and character formatting containers are provided by CParaFormat and TCharFormat respectively, and the corresponding masks are provided by TParaFormatMask and by TCharFormatMask.

Format layering

Formatting is stored in format layers. Format layers are owned by the text object. A format layer may own a pointer to another format layer. This pointer is called a based-on link. The effective formatting of a text object is the set of attributes specified in its two format layers, as well as any attributes inherited from the layers' chain of based-on links. Note that in rich text, additional formatting may be applied on top of the two owned format layers. This additional formatting is referred to as "specific formatting".

The CCharFormatLayer class represents the character format layer and the CParaFormatLayer class represents the paragraph format layer.

The MLayDoc interface

The text and its attributes are stored separately from the layout information. Text Views objects (which calculate and store the layout information) access the text and its attributes via an abstract interface class called MLayDoc. This class provides all the information needed by the text layout engine to lay out the text for display. By viewing the text object purely in terms of the MLayDoc interface, the layout engine is insulated from any editable text implementation issues.

The MLayDoc interface is implemented by classes CRichText and CGlobalText.

See also

Text Views Overview