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::TextViews to share the same TextBuffer, and allows those TextBuffers to be displayed slightly differently. Or you could maintain several Gtk::TextBuffers 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.
- 12.1.1. Iterators
- 12.1.2. Tags and Formatting
- 12.1.3. Marks
- 12.1.4. The View
12.1.1. 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.
12.1.2. Tags and Formatting
- 12.1.2.1. Tags
- 12.1.2.2. TagTable
- 12.1.2.3. Applying Tags
12.1.2.1. 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.
12.1.2.2. TagTable
Each Gtk::TextBuffer uses a Gtk::TextBuffer::TagTable, which contains the Tags for that buffer. 2 or more TextBuffers may share the same TagTable. When you create Tags 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.
12.1.2.3. 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::iterators. 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().
12.1.3. 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 Marks - insert and selection_bound, which you can access with TextBuffer's get_insert() and get_selection_bound() methods.
12.1.4. The View
As mentioned above, each TextView has a TextBuffer, and one or more TextViews 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.
- 12.1.4.1. Default formatting
- 12.1.4.2. Scrolling
12.1.4.1. 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::TextTags in the buffer, if they specify the same things. For instance, set_left_margin(), set_right_margin(), set_indent(), etc.