Chapter 13. TextView Widget

Table of Contents

13.1. TextView Overview
13.2. TextViews
13.3. Text Buffers
13.3.1. TextBuffer Status Information
13.3.2. Creating TextIters
13.3.3. Text Insertion, Retrieval and Deletion
13.3.4. TextMarks
13.3.5. Creating and Applying TextTags
13.3.6. Inserting Images and Widgets
13.4. Text Iters
13.4.1. TextIter Attributes
13.4.2. Text Attributes at a TextIter
13.4.3. Copying a TextIter
13.4.4. Retrieving Text and Objects
13.4.5. Checking Conditions at a TextIter
13.4.6. Checking Location in Text
13.4.7. Moving Through Text
13.4.8. Moving to a Specific Location
13.4.9. Searching in Text
13.5. Text Marks
13.6. Text Tags and Tag Tables
13.6.1. Text Tags
13.6.2. Text Tag Tables
13.7. A TextView Example

13.1. TextView Overview

TextView widgets and their associated objects (TextBuffers, TextMarks, TextIters, TextTags and TextTagTables) provide a powerful framework for multiline text editing.

A TextBuffer (see Section 13.3, “Text Buffers”) contains the text which is displayed by one or more TextView widgets.

Within GTK+ 2.0, text is encoded in UTF-8 which means that one character may be encoded as multiple bytes. Within a TextBuffer it is necessary to differentiate between the character counts (called offsets) and the byte counts (called indexes).

TextIters provide a volatile representation of the position in a TextBuffer between two characters. TextIters are valid until the number of characters in the TextBuffer changes; i.e. any time characters are inserted or deleted from a TextBuffer all TextIters will become invalid. TextIters are the primary way to specify locations in a TextBuffer for manipulating text.

TextMarks are provided to allow preservation of TextBuffer positions across buffer modifications. A mark is like a TextIter (see Section 13.4, “Text Iters”) in that it represents a position between two characters in a TextBuffer) but if the text surrounding the mark is deleted the mark remains where the deleted text once was. Likewise, if text is inserted at the mark the mark ends up either to the left or right of the inserted text depending on the gravity of the mark - right gravity leaves the mark to the right of the inserted text while left gravity leaves it to the left. TextMarks (see Section 13.5, “Text Marks”) may be named or anonymous if not given a name. Each TextBuffer has two predefined named TextMarks (see Section 13.5, “Text Marks”) called insert and selection_bound. These refer to the insertion point and the boundary of the selection (the selection is between the insert and the selection_bound marks).

TextTags (see Section 13.6.1, “Text Tags”) are objects that specify a set of attributes that can be applied to a range of text in a TextBuffer. Each TextBuffer has a TextTagTable (see Section 13.6.2, “Text Tag Tables”) which contains the tags that are available in that buffer. TextTagTables can be shared between TextBuffers to provide commonality. TextTags are generally used to change the appearance of a range of text but can also be used to prevent a range of text from being edited.