Text Buffers

Each text view displays the contents of a class called Gtk.TextBuffer. Text buffers store the current state of the content within a text view. They hold text, images, child widgets, text tags, and all other information necessary for rendering the document.

A single text buffer is capable of being displayed by multiple text views, but each text view has only one associated buffer. Most programmers do not take advantage of this feature, but it becomes important when you learn how to embed child widgets into a text buffer in a later section.

As with all text widgets in GTK+, text is stored as UTF-8 strings. UTF-8 is a type of character encoding that uses from 1 byte to 4 bytes for every character. To differentiate the number of bytes that a character takes up, “0” always precedes a character that is 1 byte, “110” precedes 2-byte characters, “1110” comes before 3-byte sequences, and so on. UTF-8 characters that span multiple bytes have “10” in the two most significant bits of the rest of the bytes.

By doing this, the basic 128 ASCII characters are still supported, because an additional 7 bits are available in a single-byte character after the initial “0”. UTF-8 also provides support for characters in many other languages. This method also avoids small byte sequences occurring within larger byte sequences.

When handling text buffers, you need to know two terms: offset and index. The word “offset” refers to one character. UTF-8 characters may span one or more bytes within the buffer, so a character offset in a Gtk.TextBuffer may not be a single byte long.

Most new Gtk.TextView widgets are created with Gtk.TextView.new(). By using this function, an empty buffer is created for you. This default buffer can be replaced later with set_buffer() or retrieved with get_buffer().

If you want to set the initial buffer to one that you have already created, you can create the text view with Gtk.TextView.new_with_buffer(). In most cases, it is easier to simply use the default text buffer.

If the text string is NULL-terminated, you can use –1 as the length of the string. This function silently fails if a null character is found before the specified length of text.

The current contents of the buffer are completely replaced by the new text string. In the “Text Iterators and Marks” section, you are introduced to functions that allow you to insert text into a buffer without overwriting the current content that are more suitable for inserting large amounts of text.

Recall from the previous section that there are five widgets that have native scrolling abilities, including the Gtk.TextView widget. Because text views already have the facilities to manage adjustments, container.add() should always add them to scrolled windows.

Text View Properties

Gtk.TextView was created to be a very versatile widget. Because of this, many properties are provided for the widget. In this section, you learn about a number of these widget properties.

One feature that makes the text view widget extremely useful is that you are able to apply changes to the whole or only an individual part of the widget. Text tags change the properties of a segment of text. Customizing only a part of the document is covered in a later section of this chapter.

The best way to explain what each of Gtk.TextView’s properties does is to show you a screenshot of the result, which can be viewed in Figure 8-3. You should compile the application on your own machine and try changing the values used in Listing 8-3 to get a feel for what they do as well.

It is possible to change the font and colors of individual parts of the text view content, but as shown in Listing 8-3 it is still possible to use the functions from past chapters to change the content of the whole widget. This is useful when editing documents that have a consistent style, such as text files.

At times, you may want to prevent the user from editing the document. The editable property can be changed for the entire text view with set_editable(). It is worth noting that with text tags, you can override set_editable() for certain sections of the document, so it is not always an end-all solution.

Contrast this with set_sensitive(), which prevents the user from interacting with the widget at all. If a text view is set as not editable, the user is still able to perform operations on the text that do not require the text buffer to be edited, such as selecting text. Setting a text view as insensitive prevents the user from performing any of these actions.

When you disable editing within a document, it is also useful to stop the cursor from being visible with set_cursor_visible(). By default, both of these properties are set to True, so both need to be changed to keep them in sync.

By default, there is no extra spacing placed between lines, but Listing 8-3 shows you how to add spacing above a line, below a line, and between wrapped lines. These functions add extra space between lines, so you can assume that there is already enough spacing between lines. In most cases, you should not use this feature, because spacing may not look correct to the user.

Justification is another important property of text views, especially when dealing with rich text documents. There are four default justification values: Gtk.Justification.LEFT, Gtk.Justification.RIGHT, Gtk.Justification.CENTER, and Gtk.Justification.FILL.

The last properties set by Listing 8-3 were the left and right margins. By default, there is no extra margin space added to either the left or right side, but you can add a certain number of pixels to the left with set_left_margin() or to the right with set_right_margin().

Pango Tab Arrays

Tabs added to a text view are set to a default width, but there are times when you want to change that. For example, in a source code editor, one user may want to indent two spaces while another may want to indent five spaces. GTK+ provides the Pango.TabArray object, which defines a new tab size.

The Pango.Layout object represents a whole paragraph of text. Normally, Pango uses it internally for laying out text within a widget. However, it can be employed by this example to calculate the width of the tab string.

You should always create the tab array with only one element, because there is only one tab type supported at this time. If True is not specified for the second parameter, tabs are stored as Pango units; 1 pixel is equal to 1,024 Pango units.

Editing the Text Buffer

GTK+ provides a wide array of functions for retrieving text iterators as well as manipulating text buffers. In this section, you see a few of the most important of these methods in use in Listing 8-4, and then you are introduced to many more. Figure 8-4 displays an application that inserts and retrieves the text with a Gtk.TextBuffer.

An important property of iterators is that the same iterator can be used repeatedly, because iterators become invalidated every time you edit a text buffer. In this way, you can continue to reuse the same Gtk.TextIter object instead of creating a huge number of variables.

Retrieving Text Iterators and Marks

As stated before, there are quite a number of functions available for retrieving text iterators and text marks, many of which is used throughout this chapter.

Once you have retrieved a mark, you can translate it into a text iterator with textbuffer.get_iter_at_mark(), so that it can manipulate the buffer.

The other function presented by Listing 8-4 for retrieving text iterators is buffer.get_selection_bounds(), which returns the iterators located at the insert and selection_bound marks. You can set one or both of the text iterator parameters to None, which prevent the value from returning, although it would make more sense to use the functions for the specific mark if you only need one or the other.

It is also possible to retrieve only the beginning or end iterator for the text buffer independently of the other with buffer.get_start_iter() or buffer.get_end_iter().

GTK+ also provides buffer.get_iter_at_line_index(), which chooses a position of an individual byte on the specified line. You should be extremely careful when using this function, because the index must always point to the beginning of a UTF-8 character. Remember that characters in UTF-8 may not be only a single byte!

If you want to retrieve the iterator at an offset from the first character of a specific line, buffer.get_iter_at_line_offset()does the trick.

Changing Text Buffer Contents

You have already learned how to reset the contents of a whole text buffer, but it is also useful to edit only a portion of a document. There are a number of functions provided for this purpose. Listing 8-4 shows you how to insert text into a buffer.

When this function is called, the text buffer emits the insert-text signal, and the text iterator is invalidated. However, the text iterator is then reinitialized to the end of the inserted text.

This function emits the "delete-range" signal, and both iterators are invalidated. However, the start and end iterators are both reinitialized to the start location of the deleted text.

Cutting, Copying, and Pasting Text

Figure 8-5 shows a text view with an entry field and buttons that can access the clipboard functions via the text view object.

Three clipboard options are cut, copy, and paste, which are standard to almost all text editors. They are built into every Gtk.TextView widget. However, there are times that you want to implement your own versions of these functions to include in an application menu or toolbar.

Gtk.Clipboard is a central class where data can be transferred easily between applications. To retrieve a clipboard that has already been created, you should use clipboard.get(). GTK+ 3.x only supplies a single default clipboard. GTK+ 2.x provided named clipboards but that functionality is no longer supported.

It is feasible to directly interact with the Gtk.Clipboard object that you have created, adding and removing data from it. However, when performing simple tasks including copying and retrieving text strings for a Gtk.TextView widget, it makes more sense to use Gtk.TextBuffer’s built-in methods.

If any of the content that is going to be pasted does not have the editable flag set, then it is set automatically to default_editable. In most cases, you want to set this parameter to True, because it allows the pasted content to be edited. You should also note that the paste operation is asynchronous.

Searching the Text Buffer

In most applications that use the Gtk.TextView widget, you need to search through a text buffer in one or more instances. GTK+ provides two functions for finding text in a buffer: forward_search() and backward_search().

The following example shows you how to use the first of these functions to search for a text string in a Gtk.TextBuffer; a screenshot of the example is shown in Figure 8-6. The example begins when the user clicks the Find button.

Next, we test if the search string matches the string from the buffer. If a match was found then we increment our match counter and move the start Gtk.TextIter past the string we found in the buffer. If a match was not found then increment the start Gtk.TextIter by one character. Lastly, we test upper search bound Gtk.TextIter is equal to the end of the buffer and break out of our endless loop if the two are equal.

After we break out of the loop, we report the search results to the user.

Scrolling Text Buffers

The second parameter of buffer.create_mark() allows you to specify a text string as a name for the mark. This name can reference the mark later without the actual mark object. The mark is created at the location of the specified text iterator. The last parameter creates a mark with left gravity if set to True.

You begin by placing a margin, which reduces the scrollable area. The margin must be specified as a floating-point number, which reduces the area by that factor. In most cases, you want to use 0.0 as the margin so the area is not reduced at all.

If you specify False for the use_align parameter, the function scrolls the minimal distance to get the mark onscreen; otherwise, the function uses the two alignment parameters as guides, which allows you to specify horizontal and vertical alignment of the mark within the visible area.

An alignment of 0.0 refers to the left or top of the visible area, 1.0 refers to the right or bottom and 0.5 refers to the center. The function scrolls as far as possible, but it may not be able to scroll the mark to the specified position. For example, it is impossible to scroll the last line in a buffer to the top if the buffer is larger than one character tall.

There is another function, textview.scroll_to_iter(), which behaves in the same manner as textview.scroll_to_mark(). The only difference is that it receives a Gtk.TextIter instead of a Gtk.TextMark for the location, although in most cases, you should use text marks.

Exercise 1: Text Editor

Use the Gtk.TextView widget to create a simple text editor. You should have the ability to perform multiple text editing functions, including creating a new document, opening a file, saving a file, searching the document, cutting text, copying text, and pasting text.

When creating a new document, you should make sure that the user actually wants to continue, because all changes are lost. When the Save button is pressed, it should always ask where to save the file. Once you have finished this exercise, a solution is shown in Appendix D.

This is the first instance of the Text Editor application that you are working on throughout this book. In the last few chapters of this book, you learn new elements that help you create a fully featured text editor.

The application is expanded in Chapter 10, where you add a menu and a toolbar. In Chapter 13, you add printing support and the ability to remember past open files and searches.

A solution to this exercise is in Appendix D. Much of the functionality of the text editor solution has been implemented by other examples in this chapter. Therefore, most of the solution should look familiar to you. It is a bare minimum solution, and I encourage you to expand on the basic requirements of the exercise for more practice.