Chapter 14. TextView

# Chapter 14. TextView

The `TextView` widget can be used to display and edit large amounts of formatted text. Like the `TreeView`, it has a model/view design. In this case the `TextBuffer` is the model.

## The Buffer

`Gtk::TextBuffer` is a model containing the data for the `Gtk::TextView`, like the `Gtk::TreeModel` used by `Gtk::TreeView`. This allows two or more `Gtk::TextView`s to share the same `TextBuffer`, and allows those TextBuffers to be displayed slightly differently. Or you could maintain several `Gtk::TextBuffer`s and choose to display each one at different times in the same `Gtk::TextView` widget.

The `TextView` creates its own default `TextBuffer`, which you can access via the `get_buffer()` method.

Reference

### Iterators

A `Gtk::TextBuffer::iterator` and a `Gtk::TextBuffer::const_iterator` represent a position between two characters in the text buffer. Whenever the buffer is modified in a way that affects the number of characters in the buffer, all outstanding iterators become invalid. Because of this, iterators can't be used to preserve positions across buffer modifications. To preserve a position, use `Gtk::TextBuffer::Mark`.

Reference

### Tags and Formatting

#### Tags

To specify that some text in the buffer should have specific formatting, you must define a tag to hold that formatting information, and then apply that tag to the region of text. For instance, to define the tag and its properties:

    auto refTagMatch = Gtk::TextBuffer::Tag::create();
    refTagMatch->property_background() = "orange";

You can specify a name for the `Tag` when using the `create()` method, but it is not necessary.

The `Tag` class has many other properties.

Reference

#### TagTable

Each `Gtk::TextBuffer` uses a `Gtk::TextBuffer::TagTable`, which contains the `Tag`s for that buffer. 2 or more `TextBuffer`s may share the same `TagTable`. When you create `Tag`s you should add them to the `TagTable`. For instance:

    auto refTagTable = Gtk::TextBuffer::TagTable::create();
    refTagTable->add(refTagMatch);
    //Hopefully a future version of gtkmm will have a set_tag_table() method,
    //for use after creation of the buffer.
    auto refBuffer = Gtk::TextBuffer::create(refTagTable);

You can also use `get_tag_table()` to get, and maybe modify, the `TextBuffer`'s default `TagTable` instead of creating one explicitly.

Reference

#### Applying Tags

If you have created a `Tag` and added it to the `TagTable`, you may apply that tag to part of the `TextBuffer` so that some of the text is displayed with that formatting. You define the start and end of the range of text by specifying `Gtk::TextBuffer::iterator`s. For instance:

    refBuffer->apply_tag(refTagMatch, iterRangeStart, iterRangeStop);

Or you could specify the tag when first inserting the text:

    refBuffer->insert_with_tag(iter, "Some text", refTagMatch);

You can apply more than one `Tag` to the same text, by using `apply_tag()` more than once, or by using `insert_with_tags()`. The `Tag`s might specify different values for the same properties, but you can resolve these conflicts by using `Tag::set_priority()`.

### Marks

`TextBuffer` iterators are generally invalidated when the text changes, but you can use a `Gtk::TextBuffer::Mark` to remember a position in these situations. For instance,

    auto refMark = refBuffer->create_mark(iter);

You can then use the `get_iter()` method later to create an iterator for the `Mark`'s new position.

There are two built-in `Mark`s - `insert` and `selection_bound`, which you can access with `TextBuffer`'s `get_insert()` and `get_selection_bound()` methods.

Reference

### The View

As mentioned above, each `TextView` has a `TextBuffer`, and one or more `TextView`s can share the same `TextBuffer`.

Like the `TreeView`, you should probably put your `TextView` inside a `ScrolledWindow` to allow the user to see and move around the whole text area with scrollbars.

Reference

#### Default formatting

`TextView` has various methods which allow you to change the presentation of the buffer for this particular view. Some of these may be overridden by the `Gtk::TextTag`s in the buffer, if they specify the same things. For instance, `set_left_margin()`, `set_right_margin()`, `set_indent()`, etc.

#### Scrolling

`Gtk::TextView` has various `scroll_to()` methods. These allow you to ensure that a particular part of the text buffer is visible. For instance, your application's Find feature might use `Gtk::TextView::scroll_to()` to show the found text.

ComboBox with an Entry |  | Widgets and ChildAnchors