Chapter 9. TextView
Prev |  | Next

## Chapter 9. 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

### 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:

    Glib::RefPtr<Gtk::TextBuffer::Tag> 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 `Tags` you should add them to the `TagTable`. For instance:

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

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 `Tags` 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,

    Glib::RefPtr<Gtk::TextBuffer::Mark> 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 `select_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` 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_iter()` to show the found text.

Prev | Up | Next
Examples | Home | Widgets and ChildAnchors