GTK+ 1.2 Tutorial
Prev | Chapter 15. Text Widget | Next

# Text Manipulation

The current insertion point of a Text widget can be set using

    void gtk_text_set_point( GtkText *text,
                             guint    index );

where `index` is the position to set the insertion point.

Analogous to this is the function for getting the current insertion point:

    guint gtk_text_get_point( GtkText *text );

A function that is useful in combination with the above two functions is

    guint gtk_text_get_length( GtkText *text );

which returns the current length of the Text widget. The length is the number of characters that are within the text block of the widget, including characters such as newline, which marks the end of lines.

In order to insert text at the current insertion point of a Text widget, the function gtk_text_insert is used, which also allows us to specify background and foreground colors and a font for the text.

    void gtk_text_insert( GtkText    *text,
                          GdkFont    *font,
                          GdkColor   *fore,
                          GdkColor   *back,
                          const char *chars,
                          gint        length );

Passing a value of `NULL` in as the value for the foreground color, background color or font will result in the values set within the widget style to be used. Using a value of `-1` for the length parameter will result in the whole of the text string given being inserted.

The text widget is one of the few within GTK that redraws itself dynamically, outside of the gtk_main function. This means that all changes to the contents of the text widget take effect immediately. This may be undesirable when performing multiple changes to the text widget. In order to allow us to perform multiple updates to the text widget without it continuously redrawing, we can freeze the widget, which temporarily stops it from automatically redrawing itself every time it is changed. We can then thaw the widget after our updates are complete.

The following two functions perform this freeze and thaw action:

    void gtk_text_freeze( GtkText *text );

    void gtk_text_thaw( GtkText *text );

Text is deleted from the text widget relative to the current insertion point by the following two functions. The return value is a TRUE or FALSE indicator of whether the operation was successful.

    gint gtk_text_backward_delete( GtkText *text,
                                   guint    nchars );

    gint gtk_text_forward_delete ( GtkText *text,
                                   guint    nchars );

If you want to retrieve the contents of the text widget, then the macro `GTK_TEXT_INDEX(t, index)` allows you to retrieve the character at position `index` within the text widget `t`.

To retrieve larger blocks of text, we can use the function

    gchar *gtk_editable_get_chars( GtkEditable *editable,
                                   gint         start_pos,
                                   gint         end_pos );

This is a function of the parent class of the text widget. A value of -1 as `end_pos` signifies the end of the text. The index of the text starts at 0.

The function allocates a new chunk of memory for the text block, so don't forget to free it with a call to g_free when you have finished with it.

Prev | Home | Next
Text Widget | Up | Keyboard Shortcuts