Representing a text selection

• TInsertionOffset represents an insertion point.
• TTextArea represents a selection, whether it is an insertion point, a range, or multiple ranges.

Representing insertion points

• A text offset
• An EPlacement value indicating whether the character associated with the insertion point precedes (kBeforeOffset) or follows (kAfterOffset) that offset (this information is used in the implementation of functions that allow navigation through text with cursor keys or a mouse)

The Text Editing framework uses TInsertionOffset to represent the current insertion point within editable text components. Use this class to represent insertion points when you want to support placement of an insertion point within displayed text by the user's cursor key movements or mouse clicks.

Encapsulating the selection

• A TInsertionOffset
• A TTextRegion, which can contain multiple TTextRange instances

You can construct a TTextArea with a TInsertionOffset, a TTextRange, or a TTextRegion. Both the insertion offset and text region data members are guaranteed to always have valid values. When you set the TTextArea to identify an insertion point selection, the TTextRegion object contains a single text range of length zero. When you set the TTextArea to identify a selected range or multiple selected ranges, the TInsertionOffset refers to the final offset of the last range in the selection.

The system also includes an iterator, TTextAreaIterator, that you can use to retrieve ranges from a TTextArea. TTextAreaIterator provides standard iteration functions that return the first, last, next, and previous range in a TTextArea instance. You specify the TTextArea when you construct the iterator.

The Text Editing framework uses this class as a lightweight mechanism for representing text selections. TTextArea includes functions that facilitate creating selection--SelectAllText, DeselectAllText, and ExtendTextSelection. See "Text selection classes" on page 142 for more information on how TTextArea is used.