3.12 Text

Like the tree and list widgets, the GTK+ text widget system is very powerful if you understand its basic concepts. The separation between model and view is very important here.

The model class for text in GTK+ is GtkTextBuffer ( GTK_TYPE_TEXT_BUFFER ). To view the model, you must create a GtkTextView ( GTK_TYPE_TEXT_VIEW ) object. You can define and build these objects in any order.

Before diving into the details of the model and view classes, you should see the source code for a sample text editing application. This program supports different text formattings.

The first part of this program defines a few global variables for the model, view, and formatting buttons . In a real application, you could enclose all of this inside a data structure:

 /* -*-coding: utf-8;-*- */ /* text.c -- demonstrate text widgets */ #include <gtk/gtk.h> GtkTextBuffer *buffer; GtkTextTag *bold, *italic, *underline; GtkCheckButton *bold_button, *italic_button, *underline_button;

This small global variable indicates the state of the selection:

 gboolean format_dirty = FALSE;

Two callback functions access format_dirty . The first is changed_selection() , below. Later, this program binds a signal handler that calls this function when the user moves the text buffer cursor or alters the selection. The idea is that the format buttons should change as the selection and cursor moves. However, verifying the format upon every event is very costly, visibly slowing down your machine. Therefore, this callback only changes a global state variable.

 /* when someone moves the cursor or selects something in the view, mark    the selection variable as "changed" so that verify_format() can change    the format buttons accordingly */ void changed_selection(GtkTextBuffer *buf,                        GtkTextIter i,                        GtkTextMark *mark,  /* function does not use parms */                        gpointer data) {   format_dirty = TRUE; }

The callback function that follows does all of the real work of maintaining the formatting button states. Later, the main program binds a timeout so that the main loop runs this function every tenth of a second.

Notice how this callback returns TRUE (both when it has no work to do and at the very end). This is necessary to make the program continue generating timeouts in the main loop. Although this book does not cover timeouts in any detail, you can see that the return value and the function to set the timeout (near the end of the program) are nearly the only things you need to know to use timeouts in your own programs (if you need to know more, consult the GLib API reference).

 /* check the selection and cursor position, set the format buttons to match */ gboolean verify_format(gpointer data) {   GtkTextIter begin, end;   gboolean bold_on, bold_off;   gboolean italic_on, italic_off;   gboolean underline_on, underline_off;   /* if the cursor position or selection has not changed, do nothing */   if (!format_dirty) {      return(TRUE);   }   gtk_text_buffer_get_selection_bounds(buffer, &begin, &end);   if (!gtk_text_iter_equal(&begin, &end))   {      GtkTextIter iter = begin;      /* assume that all formatting styles are true at start */      bold_on = bold_off = TRUE;      italic_on = italic_off = TRUE;      underline_on = underline_off = TRUE;      /* run through the selection, setting format styles as necessary */      while (!gtk_text_iter_equal(&iter, &end))      {         if (gtk_text_iter_has_tag(&iter, bold))         {            bold_off = FALSE;         } else {            bold_on = FALSE;         }         if (gtk_text_iter_has_tag(&iter, italic))         {            italic_off = FALSE;         } else {            italic_on = FALSE;         }         if (gtk_text_iter_has_tag(&iter, underline))         {            underline_off = FALSE;         } else {            underline_on = FALSE;         }         gtk_text_iter_forward_cursor_position(&iter);       }       /* set check buttons to inconsistent when the tags is both          on and off in the selection */       if (!bold_on && !bold_off)       {          g_object_set(bold_button, "inconsistent", TRUE, NULL);       } else {          g_object_set(bold_button, "inconsistent", FALSE,                                    "active", bold_on,                                    NULL);       }       if (!italic_on && !italic_off)       {          g_object_set(italic_button, "inconsistent", TRUE, NULL);       } else {          g_object_set(italic_button, "inconsistent", FALSE,                                      "active", italic_on, NULL);       }       if (!underline_on && !underline_off)       {          g_object_set(underline_button, "inconsistent", TRUE, NULL);      } else {         g_object_set(underline_button, "inconsistent", FALSE,                                        "active", underline_on,                                        NULL);      }   } else {      /* if there isn't a selection, just show the tags at the         current cursor position */      bold_on = gtk_text_iter_has_tag(&begin, bold);      italic_on = gtk_text_iter_has_tag(&begin, italic);      underline_on = gtk_text_iter_has_tag(&begin, underline);      g_object_set(bold_button, "inconsistent", FALSE,                                "active", bold_on,                                NULL);      g_object_set(italic_button, "inconsistent", FALSE,                                  "active", italic_on,                                  NULL);      g_object_set(underline_button, "inconsistent", FALSE,                                     "active", underline_on,                                     NULL);   }   /* reset state */   format_dirty = FALSE;   return(TRUE); }

The format_text() function, shown next , adds or deletes a tag for the view's current selection from the text buffer based on the tag button state.

A click on one of the formatting check buttons activates this function as ahandler.

 /* when user clicks on a format check button, change tags */ void format_text(GtkCheckButton *tag_button, gpointer formatptr) {   gchar *format = (gchar *)formatptr;   GtkTextIter begin, end;   gboolean inconsistent;   gboolean button_checked;   gtk_text_buffer_get_selection_bounds(buffer, &begin, &end);   if (!gtk_text_iter_equal(&begin, &end))   {     g_object_get(tag_button, "active", &button_checked,                              "inconsistent", &inconsistent, NULL);     if (button_checked  inconsistent)     {        gtk_text_buffer_apply_tag_by_name(buffer, format, &begin, &end);        g_object_set(tag_button, "active", TRUE,                                 "inconsistent", FALSE,                                 NULL);     } else {        gtk_text_buffer_remove_tag_by_name(buffer, format, &begin, &end);          g_object_set(tag_button, "active", FALSE,                                   "inconsistent", FALSE,                                   NULL);     }   } }

There is nothing special about the main program or its declarations:

 << standard event handlers >> int main(int argc, char **argv) {   GtkWindow *window;   GtkTextTagTable *tags;   GtkTextView *view;   GtkScrolledWindow *scroller;   GtkHButtonBox *buttons;   GtkVBox *vbox;   GtkTextChildAnchor *anchor;   GtkTextIter embed_iter;   GtkButton *text_button;   GdkPixbuf *pixbuf;   /* initialize GTK+, create main window */   gtk_init(&argc, &argv);   window = g_object_new(GTK_TYPE_WINDOW,                         "title", "Text Demo",                         "default-width", 400,                         "default-height", 500,                         NULL);   << attach standard handlers >>

Now you're ready to create the text buffer (the model). This program creates the buffer's tag object and feeds it to the buffer generator function. However, you could also tell the generator to create a new tag table by passing NULL and then get a handle on the tag table with the buffer's tag-table property. You will see more text buffer functions in Section 3.12.1.

 /* create new tag table and buffer objects */   tags = gtk_text_tag_table_new();   buffer = gtk_text_buffer_new(tags);

If you already have a text buffer on hand, you can create a text view widget and couple it to the buffer with one line. The wrap-mode property is one of many text view properties that you will see in Section 3.12.2.

 /* create new text view using buffer */   view = GTK_TEXT_VIEW(gtk_text_view_new_with_buffer(buffer));   g_object_set(view, "wrap-mode", GTK_WRAP_WORD, NULL);

A text buffer's mark-set signal indicates that the cursor position and/or selection has changed:

 /* add a handler to verify format buttons when the selection,      cursor position, or mark otherwise changes */   g_signal_connect(buffer, "mark-set", G_CALLBACK(changed_selection), NULL);

The following statements give concrete formatting directives to tags in a buffer:

 /* create tags for bold, italic, and underline */   bold = gtk_text_buffer_create_tag(buffer, "bold",                                     "weight", 500,                                     NULL);   italic = gtk_text_buffer_create_tag(buffer, "italic",                                     "style", PANGO_STYLE_ITALIC,                                     NULL);   underline = gtk_text_buffer_create_tag(buffer, "underline",                                          "underline", PANGO_UNDERLINE_SINGLE,                                          NULL);

Adding text to the buffer is easy, requiring only one function call:

 /* add some default text to the buffer */   gtk_text_buffer_set_text(buffer, "\ The text you see in this window is currently stored in a \ GtkTextBuffer object; you see it with the help of a \ GtkTextView widget.\n Feel free to type your own text anywhere in this window.\n\n\ If you click any of the buttons below, you will change the \ Widgets and images can appear in text widgets:\n", -1);

Just for fun, let's throw a button widget and an image into the text buffer:

 /* add a button to the text */   text_button = g_object_new(GTK_TYPE_BUTTON, "label", "Button", NULL);   gtk_text_buffer_get_end_iter(buffer, &embed_iter);   anchor = gtk_text_buffer_create_child_anchor(buffer, &embed_iter);   gtk_text_view_add_child_at_anchor(view, GTK_WIDGET(text_button), anchor);   /* add an image to the text */   pixbuf = gdk_pixbuf_new_from_file("apple-green.png", NULL);   gtk_text_buffer_get_end_iter(buffer, &embed_iter);   gtk_text_buffer_insert_pixbuf(buffer, &embed_iter, pixbuf);

You have already seen how to create a scrolled container widget for the view and the formatting buttons:

 /* put view into scrolling widget */   scroller = g_object_new(GTK_TYPE_SCROLLED_WINDOW, NULL);   gtk_container_add(GTK_CONTAINER(scroller), GTK_WIDGET(view));   /* create check buttons for text formatting */   bold_button = g_object_new(GTK_TYPE_CHECK_BUTTON,                              "use-stock", TRUE,                              "label", GTK_STOCK_BOLD,                              NULL);   italic_button = g_object_new(GTK_TYPE_CHECK_BUTTON,                                "use-stock", TRUE,                                "label", GTK_STOCK_ITALIC,                                NULL);   underline_button = g_object_new(GTK_TYPE_CHECK_BUTTON,                                   "use-stock", TRUE,                                   "label", GTK_STOCK_UNDERLINE,                                   NULL);

The following signal handler bindings exhibit an odd trait: The handler for these buttons does something only when there is a current selection. A click gives input focus to the button. If you want to continue typing, you must then focus back on the view. When you do this, the program resets the formatting buttons to the place where you focused.

 /* bind format_text() to these check buttons so that the      the selection's format changes when you click one */   g_signal_connect(bold_button, "clicked",                    G_CALLBACK(format_text), "bold");   g_signal_connect(italic_button, "clicked",                    G_CALLBACK(format_text), "italic");   g_signal_connect(underline_button, "clicked",                    G_CALLBACK(format_text), "underline");

Packing and showing the widgets is a matter of routine:

 /* pack the check buttons into a button box */   buttons = g_object_new(GTK_TYPE_HBUTTON_BOX, NULL);   gtk_box_pack_start_defaults(GTK_BOX(buttons), GTK_WIDGET(bold_button));   gtk_box_pack_start_defaults(GTK_BOX(buttons), GTK_WIDGET(italic_button));   gtk_box_pack_start_defaults(GTK_BOX(buttons), GTK_WIDGET(underline_button));   /* pack the text view into a scrolled container */   vbox = g_object_new(GTK_TYPE_VBOX, NULL);   /* put everything into a vbox, then into the main window*/   gtk_box_pack_start_defaults(GTK_BOX(vbox), GTK_WIDGET(scroller));   gtk_box_pack_end(GTK_BOX(vbox), GTK_WIDGET(buttons), FALSE, FALSE, 0);   gtk_container_add(GTK_CONTAINER(window), GTK_WIDGET(vbox));   /* show everything */   gtk_widget_show_all(GTK_WIDGET(window));

Just before starting the main loop, however, you need to set the periodic timeout to trigger the verify_format() callback that changes the format buttons if the selection or cursor has changed. The code below uses g_timeout_add() to run the callback every 100ms (a tenth of a second).

 /* add a timeout for the format button update */   g_timeout_add(100, verify_format, NULL);   gtk_main();   return 0; }

Figure 3.19 shows the final application. Notice that the Italic check button is on, but the Bold button has an inconsistent mark because the text selection contains text both with and without the bold tag.

Figure 3.19: Text widget.

3.12.1 Text Buffers

To be proficient with text buffers, you must know the following:

Text buffers use UTF-8 encoding, so byte counts ( indices ) and character counts ( offsets ) differ .
A text buffer contains at least one (possibly empty) line. Every line but the last ends with a line separator, counted as a character. The separator can be a Unix newline, a CR-LF sequence, or another Unicode line separator. The last line in a text buffer never ends with a line separator.
Use iterators ( GtkTextIter ) to represent a position in a text buffer. An iterator is a place between two characters . As with GtkTreeIter structures, you do not manipulate text iterators as pointers, but with special utility functions.

Warning
Any change in a text buffer invalidates its current iterators.
To mark a place in a text buffer on a semi-permanent basis, use a mark ( GtkTextMark , GTK_TYPE_TEXT_MARK ). You can think of a mark as an invisible cursor.
Tags hold formatting and other information for the text buffer. A tag holds an arbitrary description for a piece of the text; you may use the same description tag for many regions of the text at once.
Each tag belongs to a tag table ( GtkTextTagTable , GTK_TYPE_TEXT_TAG_TABLE ). A text buffer can use tags only from its associated tag table. Tags have string identifiers for easy access.

As you saw in the example in Section 3.12, you can create a text buffer with

  buffer  = gtk_text_buffer_new(  tags  )

where tags is a text tag table. You can set this parameter to NULL if you would like the buffer to create a table for you. You can access this tag table with the buffer's tag-table property.

These functions manipulate the content of a GtkTextBuffer :

void gtk_text_buffer_set_text(GtkTextBuffer * buffer , const gchar * text , gint length )

Replaces buffer 's content with the UTF-8-encoded text . The length value should be the byte length of text , or -1 if the text is a NULL - terminated string.
void gtk_text_buffer_insert(GtkTextBuffer * buffer , GtkTextIter * iter , const gchar * text , gint length )

Like the preceding function, but inserts text at iter rather than replacing buffer 's contents. This function results in an insert-text signal emission ” the default handler does the actual work of inserting the text. In addition, the handler sets iter to the location just after the new text.
gboolean gtk_text_buffer_insert_interactive(GtkTextBuffer * buffer , GtkTextIter * iter , const gchar * text , gint length , gboolean editable )

Like the preceding function, but refuses to insert text at a location marked as read-only. If editable is TRUE , this function inserts text at locations that are not explicitly marked read-only.

Note
Under most circumstances, you can determine editable by calling gtk_text_view_get_editable(view) to see the current status of the buffer's view.
void gtk_text_buffer_insert_at_cursor(GtkTextBuffer * buffer , const gchar * text , gint length )

Like gtk_text_buffer_insert() , but inserts the new text at the cursor's location.
gboolean gtk_text_buffer_insert_interactive_at_cursor(GtkTextBuffer * buffer , const gchar * text , gint length , gboolean editable )

Like gtk_text_buffer_insert_interactive_at_cursor() , but inserts at the cursor position.
void gtk_text_buffer_insert_range(GtkTextBuffer * buffer , const gchar * text , GtkTextIter * iter , const GtkTextIter * begin , GtkTextIter * end )

Copies the text between begin and end to iter in buffer . If begin and end do not belong to buffer , their buffer must share a tag table with buffer . The insert-text and apply-tag signals carry out this function's work.
gboolean gtk_text_buffer_insert_range_interactive(GtkTextBuffer * buffer , const gchar * text , GtkTextIter * iter , const GtkTextIter * begin , const GtkTextIter * end , gboolean editable )

Like the preceding function, but reflects the behavior of the other _interactive functions.
void gtk_text_buffer_delete(GtkTextBuffer * buffer , GtkTextIter * begin , GtkTextIter * end )

Deletes the text between begin and end in buffer . As was the case with insertion, a signal carries out this function's work: delete-range .
gboolean gtk_text_buffer_delete_interactive(GtkTextBuffer * buffer , GtkTextIter * begin , GtkTextIter * end , gboolean editable )

Like the preceding function, but obeys read-only ranges like the other _interactive functions.
gboolean gtk_text_buffer_delete_selection(GtkTextBuffer * buffer , gboolean interactive , gboolean editable )

Removes the selection from buffer ; that is, removes all text between the insert and selection-bound marks. If interactive is true, this function behaves like the _interactive functions described earlier, consulting editable for text marked neither as read-only nor read-write.
void gtk_text_buffer_set_modified(GtkTextBuffer * buffer , gboolean modified )

Alters the modified status of buffer . Setting modified to TRUE typically means that the buffer has changed since the last time it was saved; FALSE indicates that nothing has happened since the last save (GTK+ will set the modified status to TRUE upon the next modification).

gboolean gtk_text_buffer_get_modified(GtkTextBuffer * buffer )

Returns the modified status of buffer .

Note	The preceding two functions can help you implement a file save feature in an editor. Every time the user saves the file, your application can set the modified status to FALSE . In addition, you can use the status to create an autosave feature.

void gtk_text_buffer_begin_user_action(GtkTextBuffer * buffer )

Signals the start of a user action.
void gtk_text_buffer_end_user_action(GtkTextBuffer * buffer )

Signals the end of a user action.

The user action functions emit begin-user-action and end-user-action signals. You can nest the signals. User actions can help you establish the history for an Undo feature.

The _interactive functions from earlier call the user action functions. Therefore, if you stick to the _interactive functions, you do not need to manually call the user action functions.

These functions retrieve data from a text buffer:

gchar *gtk_text_buffer_get_text(GtkTextBuffer * buffer , const GkTextIter * begin , const GtkTextIter * end , gboolean include_hidden )

Returns the text in buffer between begin and end . If include_hidden is TRUE , the text will also contain any characters marked as hidden. Unlike the _get_slice() function, discussed next, this function does not replace embedded images and anchors with a special character. Therefore, the indices and offsets in the resulting text may not agree with those in buffer .
gchar *gtk_text_buffer_get_slice(GtkTextBuffer * buffer , const GtkTextIter * begin , const GtkTextIter * end , gboolean include_hidden )

Like the preceding function, but replaces embedded images and anchors with a special Unicode character, 0xFFFC. Indices and offsets in the slice reflect those in the original buffer .
gunichar gtk_text_iter_get_char(const GtkTextIter * iter )

Returns the character at iter ; substitutes for images and anchors as described in the preceding function. If iter is at the end of its buffer, this function returns 0 and is thus suitable for use in a loop.
gint gtk_text_buffer_get_line_count(GtkTextBuffer * buffer )

Returns the number of lines in buffer . Because a GtkTextBuffer object maintains the line count internally, this function is quite fast.
gint gtk_text_buffer_get_char_count(GtkTextBuffer * buffer )

Returns the number of characters ( not bytes) in buffer . Like the preceding function, this is an efficient function.

Iterators

GtkTextIter structures indicate locations in text buffers and therefore hold a central role in the entire GtkTextBuffer API.

Note	Functions that work with iterators want the address of a preexisting iterator structure; therefore, when you see iter in this chapter, you will probably use something like &iter as the function's argument. The example program in Section 3.12 shows how this works in practice.

You can get an iterator in several ways. All of the following functions fill in a preexisting iterator structure:

void gtk_text_buffer_iter_at_line(GtkTextBuffer * buffer , GtkTextIter * iter , gint line_number )

Sets iter to the start of line line_number in buffer .
void gtk_text_buffer_iter_at_offset(GtkTextBuffer * buffer , GtkTextIter * iter , gint offset )

Sets iter to offset characters past the start of buffer .
void gtk_text_buffer_iter_at_line_offset(GtkTextBuffer * buffer , GtkTextIter * iter , gint line_number , gint offset )

Sets iter to offset characters past the start of line line_number in buffer .
void gtk_text_buffer_iter_at_line_index(GtkTextBuffer * buffer , GtkTextIter * iter , gint line_number , gint index )

Like the preceding function, but index indicates the number of bytes into line_number .
void gtk_text_buffer_iter_get_start_iter(GtkTextBuffer * buffer , GtkTextIter * iter )

Sets iter to the start of buffer .
void gtk_text_buffer_iter_get_end_iter(GtkTextBuffer * buffer , GtkTextIter * iter )

Sets iter to the end of buffer .
void gtk_text_buffer_iter_get_bounds(GtkTextBuffer * buffer , GtkTextIter * begin , GtkTextIter * end )

Sets begin and end to the start and end of buffer , respectively.
gboolean gtk_text_buffer_iter_get_selection_bounds(GtkTextBuffer * buffer , GtkTextIter * begin , GtkTextIter * end )

If there is a current selection in buffer , sets begin and end to the start and end of the selection and returns TRUE . Otherwise, returns FALSE and sets both iterators to the cursor position. If you're interested only in knowing whether or not there is a selection, you can set both iterators to NULL .

These functions return information about iterators:

GtkTextBuffer *gtk_text_iter_get_buffer(const GtkTextIter * iter )

Returns the buffer that iter describes.
gint gtk_text_iter_get_offset(const GtkTextIter * iter )

Returns the number of characters between iter and the start of its buffer.
gint gtk_text_iter_get_line(const GtkTextIter * iter )

Returns iter 's line number. The first line in a buffer is 0.
gint gtk_text_iter_get_line_offset(const GtkTextIter * iter )

Returns the number of characters between iter and the start of its line.
gint gtk_text_iter_get_visible_line_offset(const GtkTextIter * iter )

Like the preceding function, but counts only characters not marked as hidden.
gint gtk_text_iter_get_line_index(const GtkTextIter * iter )

Returns the number of bytes between iter and the start of its line.
gint gtk_text_iter_get_visible_line_index(const GtkTextIter * iter )

Like the preceding function, but counts only bytes in characters not marked as hidden.
gint gtk_text_iter_get_chars_in_line(const GtkTextIter * iter )

Returns the number of characters in iter 's line.
gint gtk_text_iter_get_bytes_in_line(const GtkTextIter * iter )

Returns the number of bytes in iter 's line.
gboolean gtk_text_iter_starts_word(const GtkTextIter * iter )

Returns TRUE if iter lies at the start of a word. Pango determines the start of a word based on language-specific algorithms.
gboolean gtk_text_iter_ends_word(const GtkTextIter * iter )

Returns TRUE if iter sits at the end of a word.
gboolean gtk_text_iter_inside_word(const GtkTextIter * iter )

Returns TRUE if iter sits inside of a word.
gboolean gtk_text_iter_starts_line(const GtkTextIter * iter )

Returns TRUE if iter sits at the start of a line.
gboolean gtk_text_iter_ends_line(const GtkTextIter * iter )

Returns TRUE if iter sits at the end of a line.
gboolean gtk_text_iter_starts_sentence(const GtkTextIter * iter )

Returns TRUE if iter sits at the start of a sentence .
gboolean gtk_text_iter_inside_sentence(const GtkTextIter * iter )

Returns TRUE if iter sits inside of a sentence.
gboolean gtk_text_iter_ends_sentence(const GtkTextIter * iter )

Returns TRUE if iter sits at the end of a sentence.
gboolean gtk_text_iter_is_start(const GtkTextIter * iter )

Returns TRUE if iter is at the start of its buffer.
gboolean gtk_text_iter_is_end(const GtkTextIter * iter )

Returns TRUE if iter is at the end of its buffer.
gboolean gtk_text_iter_is_cursor_position(const GtkTextIter * iter )

Returns TRUE if iter sits at its buffer's current cursor position.
gboolean gtk_text_iter_can_insert(const GtkTextIter * iter , gboolean default_editable )

Returns TRUE if iter 's current position is marked as read-write. If there is no such mark, this function returns default_editable . All of the _interactive functions from a few pages back call this to decide if they can insert something into or delete something from a buffer.

You can set the absolute position of an iterator with these functions (these functions assume that the iterator is already set to a place inside the appropriate buffer):

void gtk_text_iter_set_offset(GtkTextIter * iter , gint offset )

Moves iter to offset characters past the start of its buffer. If the offset is too large, iter goes to the last position in the buffer.
void gtk_text_iter_set_line(GtkTextIter * iter , gint line_number )

Places iter at the start of line line_number . A buffer starts at line 0. If the line number is too large, this function sets iter to the start of its buffer's last line.
void gtk_text_iter_set_line_offset(GtkTextIter * iter , gint offset )

Moves iter to offset characters past the start of its current line. The offset value must be between 0 and the number of characters in the line.
void gtk_text_iter_set_visible_line_offset(GtkTextIter * iter , gint offset )

Like the preceding function, but ignores characters marked as hidden.
void gtk_text_iter_set_line_index(GtkTextIter * iter , gint index )

Like gtk_text_iter_set_line_offset() , but skips bytes, not characters.
void gtk_text_iter_set_visible_line_index(GtkTextIter * iter , gint index )

Like the preceding function, but ignores characters marked as hidden.

The functions in the extensive list that follows move an iterator to a relative position inside a buffer. All return gboolean values ” TRUE if it is possible to move the iterator as requested . If you ask one of these functions to move the iterator past the start or end of a buffer, the iterator goes as far as it can, and the function returns FALSE .

Note

A cursor position is any point in the buffer where the cursor can stand. This is not necessarily between every set of two adjacent characters, especially in languages that do not use a Latin or Greek alphabet. You can move the iterator in terms of cursor positions or characters; be sure that you pick the one that you need.

gboolean gtk_text_iter_forward_cursor_position(GtkTextIter * iter )

Moves iter one cursor position ahead.
gboolean gtk_text_iter_backward_cursor_position(GtkTextIter * iter )

Moves iter one cursor position back.
gboolean gtk_text_iter_forward_cursor_positions(GtkTextIter * iter , gint count )

Moves iter count cursor positions ahead.
gboolean gtk_text_iter_backward_cursor_positions(GtkTextIter * iter , gint count )

Moves iter count cursor positions back.
gboolean gtk_text_iter_forward_char(GtkTextIter * iter )

Moves iter one character ahead.
gboolean gtk_text_iter_backward_char(GtkTextIter * iter )

Moves iter one character back.
gboolean gtk_text_iter_forward_chars(GtkTextIter * iter , gint count )

Moves iter count characters ahead.
gboolean gtk_text_iter_backward_chars(GtkTextIter * iter , gint count )

Moves iter count characters back.
gboolean gtk_text_iter_forward_line(GtkTextIter * iter )

Moves iter to the start of the next line.
gboolean gtk_text_iter_backward_line(GtkTextIter * iter )

Moves iter to the start of the previous line.
gboolean gtk_text_iter_forward_lines(GtkTextIter * iter , gint count )

Moves iter ahead count lines, to the start of the target line.
gboolean gtk_text_iter_backward_lines(GtkTextIter * iter , gint count )

Moves iter back count lines, to the start of the target line.
gboolean gtk_text_iter_forward_word_end(GtkTextIter * iter )

Moves iter to the next end of a word.
gboolean gtk_text_iter_backward_word_start(GtkTextIter * iter )

Moves iter to the previous start of a word.
gboolean gtk_text_iter_forward_word_ends(GtkTextIter * iter , gint count )

Moves iter ahead count word ends.
gboolean gtk_text_iter_backward_word_starts(GtkTextIter * iter , gint count )

Moves iter back count word starts.
gboolean gtk_text_iter_forward_sentence_end(GtkTextIter * iter )

Moves iter to the next end of sentence.
gboolean gtk_text_iter_backward_sentence_start(GtkTextIter * iter )

Moves iter to the previous start of sentence.
gboolean gtk_text_iter_forward_sentence_ends(GtkTextIter * iter , gint count )

Moves iter ahead count sentence ends.
gboolean gtk_text_iter_backward_sentence_starts(GtkTextIter * iter , gint count )

Moves iter back count sentence starts.
gboolean gtk_text_iter_forward_to_end(GtkTextIter * iter )

Moves iter to the position after the last character in its buffer.
gboolean gtk_text_iter_forward_to_line_end(GtkTextIter * iter )

Moves iter to the end of its current line.
gboolean gtk_text_iter_forward_to_tag_toggle(GtkTextIter * iter , GtkTextTag * tag )

Moves iter to the next place in the text where tag changes. If tag is NULL , this function moves the iterator to the next tag.
gboolean gtk_text_iter_backward_to_tag_toggle(GtkTextIter * iter , GtkTextTag * tag )

Like the preceding function, but searches backward.
gboolean gtk_text_iter_forward_find_char(GtkTextIter * iter , GtkTextCharPredicate func , gpointer data , const GtkTextIter * end )

Searches forward for characters until end , running func with data on each character until func returns TRUE (see the following GtkTextCharPredicate type definition discussion); at this point, this function sets iter to the matching character's position and returns. If end is NULL , this function searches until the end of the buffer.
gboolean gtk_text_iter_backward_find_char(GtkTextIter * iter , GtkTextCharPredicate func , gpointer data , const GtkTextIter * end )

Like the preceding function, but searches backward, and end must sit before iter .

GtkTextCharPredicate 's type definition is

 typedef gboolean (* GtkTextCharPredicate) (gunichar ch, gpointer user_data);

Your predicate functions should return TRUE if ch matches the search criteria (possibly determined in part by user_data ).

Here are two more functions that search text buffers:

gboolean gtk_text_iter_forward_search(const GtkTextIter * iter , const gchar * string , GtkTextSearchFlags flags , GtkTextIter * match_start , GtkTextIter * match_end , const GtkTextIter * end )

Returns TRUE if string appears between iter and end (if end is NULL , search until the end of iter 's buffer). If match_start and match_end are not NULL , this function sets these to the bounds of the matching string in iter 's buffer.

At the moment, flags may be one of the following (later GTK+ versions may implement a bitwise-OR version):
- : The search string must match exactly.
- GTK_TEXT_SEARCH_VISIBLE_ONLY : Search only text not marked as hidden.
- GTK_TEXT_SEARCH_TEXT_ONLY : Search only the text portions of buffers that may contain images and anchors.
gboolean gtk_text_iter_backward_search(const GtkTextIter * iter , const gchar * string , GtkTextSearchFlags flags , GtkTextIter * match_start , GtkTextIter * match_end , const GtkTextIter * end )

Like the preceding function, but search backward from iter . The end value must come before iter , or you can set end to NULL to search back to the beginning of the buffer.

Marks

A mark represents a particular place in a text buffer. Unlike iterators, marks are true objects ( GtkTextMark ) and survive through any changes in the text buffer. Marks respond to changes in a text buffer by means of signals and adjust themselves if necessary. You can think of a mark as being similar to the cursor position, sitting between two characters in the buffer. In fact, the cursor is a mark ” its name is insert . Furthermore, if you select something in the view, the end of the selection is the selection_bound mark.

Warning

When you want to move the cursor around in the text buffer, don't manipulate the insert and selection-bound marks directly. The two marks won't match after the change to insert and, therefore, a selection appears briefly in the text view. To change the cursor position, use

 gtk_text_buffer_place_cursor(  buffer, iter  )

to move buffer 's cursor to GtkTextIter iter .

To create a mark object at the iterator iter in buffer , use

 GtkTextMark *  mark  ; mark = gtk_text_buffer_create_mark(  buffer, name, iter, left_gravity  );

Here, name is the new mark's name (a character string; you can specify NULL if you don't need a name), and left_gravity is a gboolean value indicating the new mark's gravity . TRUE means left gravity, meaning that the mark stays put if you insert some text into the buffer at the mark's position. However, FALSE asks for right gravity; if you insert some text at the mark in this case, the mark moves to the end of the inserted text. Most marks (including the cursor) use right gravity.

If a mark has a name, you can retrieve the mark at any time with

 gtk_text_buffer_get_mark(  buffer  ,  name  )

This function returns the desired GtkTextMark or NULL if no such mark exists.

There are two convenience functions to get the cursor and end-of-selection marks:

 gtk_text_buffer_get_insert(  buffer  ) gtk_text_buffer_get_selection_bound(  buffer  )

Warning

Don't confuse gtk_text_buffer_get_selection_bound() with gtk_text_buffer_get_selection_bounds() .

Another important function is

 gtk_text_buffer_get_iter_at_mark(  buffer  ,  iter  ,  mark  )

which sets the iterator at iter to the place in buffer corresponding to mark . You need this function whenever you want to process some text at a mark.

You cannot manipulate marks with properties. Use these access functions instead:

void gtk_text_buffer_move_mark(GtkTextBuffer * buffer , GtkTextMark * mark , const GtkTextIter * iter )

Moves mark to iter in buffer .
void gtk_text_buffer_move_mark_by_name(GtkTextBuffer * buffer , const gchar * name , const GtkTextIter * iter )

Like the preceding function, but uses the mark name string rather than the object handle.
void gtk_text_buffer_delete_mark(GtkTextBuffer * buffer , GtkTextMark * mark )

Removes mark from buffer . If there are no existing references to the mark, GTK+ frees the mark's memory.
void gtk_text_buffer_delete_mark_by_name(GtkTextBuffer * buffer , const gchar * name )

Like the preceding function, but uses the mark's name string instead of the object handle.
gboolean gtk_text_mark_get_deleted(GtkTextMark * mark )

Returns TRUE if mark still exists due to outstanding references. You may want to call this function after a call to one of the preceding two functions.
void gtk_text_mark_set_visible(GtkTextMark * mark , gboolean visible )

Makes mark visible if visible is TRUE , or invisible otherwise. GTK+ draws a visible mark as a line between two characters. Under normal circumstances, the cursor is the only visible mark in a buffer, but this feature can come in handy for debugging purposes.
gboolean gtk_text_mark_get_visible(GtkTextMark * mark )

Returns TRUE if mark is currently visible.
const gchar *gtk_text_mark_get_name(GtkTextMark * mark )

Returns the string identifier of mark , or NULL if there is none.
GtkTextBuffer *gtk_text_mark_get_buffer(GtkTextMark * mark )

Returns mark 's buffer. If you remove the mark from its buffer, this function returns NULL .
gboolean gtk_text_mark_get_left_gravity(GtkTextMark * mark )

Returns TRUE if mark has left gravity or FALSE if mark has right gravity.

Tag Tables

Tag tables are GtkTextTagTable objects. These functions manage tag tables:

GtkTextTagTable *gtk_text_tag_table_new(void)

Returns a new tag table object.
GtkTextTagTable *gtk_text_buffer_get_tag_table(GtkTextBuffer * buffer )

Returns the tag table from buffer . You can use this function to get an implicitly created tag table from a buffer.
void gtk_text_tag_table_add(GtkTextTagTable * table , GtkTextTag * tag )

Inserts tag into table . This function fails if you try to insert a tag already in table or a tag with the same name as one already in table . The new tag gets the highest priority in the table.
void gtk_text_tag_table_remove(GtkTextTagTable * table , GtkTextTag * tag )

Removes tag from table . If you have no other references to tag , GTK+ destroys the tag.
GtkTextTag *gtk_text_tag_table_lookup(GtkTextTagTable * table , const gchar * name )

Returns any tag in table with the string identifier name . If there is no such tag, this function returns NULL .
gint gtk_text_tag_table_get_size(GtkTextTagTable * table )

Returns the number of tags in table .
void gtk_text_tag_table_foreach(GtkTextTagTable * table , GtkTextTagTableForeach * func , gpointer data )

Runs func on every tag in table , passing data as the second parameter to func . The type definition for func is

 typedef void (* GtkTextTagTableForeach) (GtkTextTag *tag, gpointer data);

Images and Child Widgets

You can put a GDK Pixbuf image or an arbitrary widget inside a text buffer. With this capability, you can illuminate a text or include interactive elements. To put a GdkPixbuf object pixbuf into buffer at iter , use

 gtk_text_buffer_insert_pixbuf(  buffer  ,  iter  ,  pixbuf  )

If iter points to a place in a buffer where an image resides, you can call

 gtk_text_iter_get_pixbuf(  iter  )

to retrieve the GDK Pixbuf object. If there isn't an image at that spot, this function returns NULL .

To put a child widget into a buffer, you must put it into a child anchor container ( GtkTextChildAnchor ). To create an anchor at iter in buffer , use

 GtkTextChildAnchor *  anchor  ; anchor = gtk_text_buffer_create_child_anchor(  buffer  ,  iter  );

To pack widget into the text window at anchor , you need the GtkTextView object view that will eventually show buffer :

 gtk_text_view_add_child_at_anchor(  view  ,  widget  ,  anchor  );

Note	Always remember that the child anchors belong to the buffer, but their widgets belong to the view.

To get a child anchor at a iterator iter , use

 gtk_text_iter_get_child_anchor(  iter  )

If you want to put the position of a child anchor anchor in buffer into iter , use

 gtk_text_buffer_get_iter_at_child_anchor(  buffer, iter, anchor  )

Note	Text buffers represent images and child anchors as a special Unicode character, 0xFFFC (a crossed box with OBJ inside).

Clipboards

Clipboards are temporary storage locations for copied or deleted text. You can create your own GtkClipboard ( GTK_TYPE_CLIPBOARD ) objects, but you'll probably find yourself using the system's standard clipboard more than your own; use

 GtkClipboard *  clipboard  ; clipboard = gtk_clipboard_get(GDK_NONE);

to point clipboard at the default clipboard.

These functions perform the usual cut and and paste operations on text buffers (all have no return value):

gtk_text_buffer_copy_clipboard(GtkTextBuffer * buffer , GtkClipboard * clipboard )

Copies the current selection in buffer to clipboard .
gtk_text_buffer_cut_clipboard(GtkTextBuffer * buffer , GtkClipboard * clipboard , gboolean default_editable )

Attempts to remove the current selection from buffer and places it into clipboard . If default_editable is TRUE , this function will remove text not explicitly marked as read-write in the buffer.
gtk_text_buffer_paste_clipboard(GtkTextBuffer * buffer , GtkClipboard * clipboard , GtkTextIter * iter , gboolean default_editable )

Attempts to insert the contents of clipboard into buffer at iter (if iter is NULL , this function pastes at the current cursor position). See the preceding function for the read-only nuances of this function.

Note	Clipboard text insertion occurs asynchronously; that is, GTK+ performs the operation some-where in its main loop when all of the data is in place. Therefore, don't expect newly inserted text from this function to be immediately available after this function call.

GtkTextBuffer Signals

There are many signals that go along with GtkTextBuffer objects. Most have default handlers that do the actual work, but you can attach additional handlers if you want to add some special features:

apply-tag

void handler (GtkTextBuffer * buffer , GtkTextTag * tag , GtkTextIter * begin , GtkTextIter * end , gpointer data )

Emitted when the application wants to put tag in buffer between begin and end .
remove-tag

void handler (GtkTextBuffer * buffer , GtkTextTag * tag , GtkTextIter * begin , GtkTextIter * end , gpointer data )

Emitted when the application wants to remove all applications of tag in buffer between begin and end .
changed

void handler (GtkTextBuffer * buffer , gpointer data )

Emitted when buffer changes in some way.
modified-changed

void handler (GtkTextBuffer * buffer , gpointer data )

Emitted when the program changes the modification status of buffer with gtk_text_buffer_set_modified( buffer ) .
mark-set

void handler (GtkTextBuffer * buffer , GtkTextIter * iter , GtkTextMark * mark , gpointer data )

Emitted when the program sets mark in buffer at iter . You can attach a handler to this signal to follow cursor or selection movement, because those are the marks named insert and selection-bound .
mark-deleted

void handler (GtkTextBuffer * buffer , GtkTextMark * mark , gpointer data )

Emitted when the program removes mark from buffer .
begin-user-action

void handler (GtkTextBuffer * buffer , gpointer data )

Emitted when the program calls gtk_text_buffer_begin_user_action( buffer ) .
end-user-action

void handler (GtkTextBuffer * buffer , gpointer data )

Emitted when the program calls gtk_text_buffer_end_user_action( buffer ) .

3.12.2 Text View Widgets

A GtkTextView widget formats and displays a GtkTextBuffer object. The most straightforward way to create a text view is with

 GtkTextView *  view  ; GtkTextBuffer *  buffer  ; view = gtk_text_view_new_with_buffer(  buffer  );

(This assumes that you created the buffer object somewhere else in the program.) However, if you have multiple buffers and you need to select one, you can create the view with gtk_text_view_new() and display a buffer inside with

 gtk_text_view_set_buffer(  view  ,  buffer  )

Note	The cursor and selection in text views are marks in the buffer, not a property in the view (as was the case in tree views). Therefore, you cannot create several views with the same text buffer that display separate cursor positions and selections.

GtkTextView objects have several properties that primarily control the text representation. Note that these are display options and do not deal with the formatting of the individual characters; use text buffer tags for those features.

pixels-above-lines ( gint ): The number of pixels to pad above paragraphs.
pixels-below-lines ( gint ): The number of pixels to pad below paragraphs.
pixels-inside-wrap ( gint ): The number of pixels between lines at a line break in a paragraph.
editable ( gboolean ): If FALSE , the user may not change anything inside the view.
wrap-mode ( GtkWrapMode ): The word wrap style. Possible values are
- GTK_WRAP_NONE : No word wrapping; the widget expands to fit any long lines.
- GTK_WRAP_CHAR : Per-character wrap (good for program code).
- GTK_WRAP_WORD : Per-word wrap (good for real language).
justification ( GtkJustification ): The horizontal text alignment. Possible values are
- GTK_JUSTIFY_LEFT
- GTK_JUSTIFY_RIGHT
- GTK_JUSTIFY_CENTER
- GTK_JUSTIFY_FILL (Fill spaces between characters; this actually isn't implemented in the current version, but this may be all the better because it's ugly.)
left-margin ( gint ): The number of pixels for the left margin.
right-margin ( gint ): The number of pixels for the right margin.
indent ( gint ): The number of pixels to indent paragraphs.
cursor-visible ( gboolean ): If FALSE , the view hides the cursor.

One other interesting property is tabs ( PangoTabArray ); it controls tab stops. Consult the Pango documentation for more information.

Several functions operate on text views. Most of the interesting utilities involve scrolling to specific parts of the text.

void gtk_text_view_scroll_to_mark(GtkTextView * view , GtkTextMark * mark , gdouble within_margin , gboolean align , gdouble xalign , gdouble yalign )

Scrolls to view so that the mark position is visible. The text shows up at a minimum distance from the view border; within_margin is the percentage of the height or width to use as this distance ( within_margin may lie between 0.0 and 0.5). If align is TRUE , align the target inside the window based on xalign and yalign instead. Here, 0.0 indicates the left and top, 0.5 indicates the center, and 1.0 indicates the right or bottom.
void gtk_text_view_scroll_to_iter(GtkTextView * view , GtkTextIter * iter , gdouble within_margin , gboolean align , gdouble xalign , gdouble yalign )

Like the preceding function, but scrolls to an iterator iter instead of a mark.
void gtk_text_view_scroll_mark_onscreen(GtkTextView * view , GtkTextMark * mark )

Scrolls view so that the position of mark is visible.
gboolean gtk_text_view_move_mark_onscreen(GtkTextView * view , GtkTextMark * mark )

Moves mark in its buffer to a position currently visible through view . This function returns TRUE if it actually moves the mark.
gboolean gtk_text_view_place_cursor_onscreen(GtkTextView * view )

Moves the cursor (and its mark) to a position currently visible through view . This function returns TRUE if it actually moves the cursor.
gboolean gtk_text_view_forward_display_line(GtkTextView * view , GtkTextIter * iter )

Moves an iterator iter forward to the position one line below the current location of iter in view . This function returns TRUE if it moves the iterator to the correct place (not the end position).

This is not necessarily the current line offset into the next line in the buffer; it could be in the same text buffer line due to word wrapping.
gboolean gtk_text_view_backward_display_line(GtkTextView * view , GtkTextIter * iter )

Like the preceding function, but moves iter back one line.
gboolean gtk_text_view_move_visually(GtkTextView * view , GtkTextIter * iter , gint count )

Similar to the preceding functions, but moves iter by count lines (to move backward, use a negative number for count ).
gboolean gtk_text_view_forward_display_line_end(GtkTextView * view , GtkTextIter * iter )

Like the preceding function, but moves iter to the end of its current line in view .
gboolean gtk_text_view_backward_display_line_start(GtkTextView * view , GtkTextIter * iter )

Like the preceding function, but moves iter to the start of its current line in view .
gboolean gtk_text_view_backward_starts_display_line(GtkTextView * view , const GtkTextIter * iter )

Returns TRUE if iter is at the beginning of its current line in view .

3.12 Text

3.12 Text

3.12.1 Text Buffers

Iterators

Marks

Tags

Tag Tables

Images and Child Widgets

Clipboards

GtkTextBuffer Signals

3.12.2 Text View Widgets