Text Widget

GTK+ 1.2 Tutorial
Prev |  | Next

# Chapter 15. Text Widget

The Text widget allows multiple lines of text to be displayed and edited. It supports both multi-colored and multi-font text, allowing them to be mixed in any way we wish. It also has a wide set of key based text editing commands, which are compatible with Emacs.

The text widget supports full cut-and-paste facilities, including the use of double- and triple-click to select a word and a whole line, respectively.

# Creating and Configuring a Text box

There is only one function for creating a new Text widget.

    GtkWidget *gtk_text_new( GtkAdjustment *hadj,
                             GtkAdjustment *vadj );

The arguments allow us to give the Text widget pointers to Adjustments that can be used to track the viewing position of the widget. Passing NULL values to either or both of these arguments will cause the gtk_text_new function to create its own.

    void gtk_text_set_adjustments( GtkText       *text,
                                   GtkAdjustment *hadj,
                                   GtkAdjustment *vadj );

The above function allows the horizontal and vertical adjustments of a text widget to be changed at any time.

The text widget will not automatically create its own scrollbars when the amount of text to be displayed is too long for the display window. We therefore have to create and add them to the display layout ourselves.

      vscrollbar = gtk_vscrollbar_new (GTK_TEXT(text)->vadj);
      gtk_box_pack_start(GTK_BOX(hbox), vscrollbar, FALSE, FALSE, 0);
      gtk_widget_show (vscrollbar);

The above code snippet creates a new vertical scrollbar, and attaches it to the vertical adjustment of the text widget, `text`. It then packs it into a box in the normal way.

Note, currently the Text widget does not support horizontal scrollbars.

There are two main ways in which a Text widget can be used: to allow the user to edit a body of text, or to allow us to display multiple lines of text to the user. In order for us to switch between these modes of operation, the text widget has the following function:

    void gtk_text_set_editable( GtkText *text,
                                gint     editable );

The `editable` argument is a TRUE or FALSE value that specifies whether the user is permitted to edit the contents of the Text widget. When the text widget is editable, it will display a cursor at the current insertion point.

You are not, however, restricted to just using the text widget in these two modes. You can toggle the editable state of the text widget at any time, and can insert text at any time.

The text widget wraps lines of text that are too long to fit onto a single line of the display window. Its default behaviour is to break words across line breaks. This can be changed using the next function:

    void gtk_text_set_word_wrap( GtkText *text,
                                 gint     word_wrap );

Using this function allows us to specify that the text widget should wrap long lines on word boundaries. The `word_wrap` argument is a TRUE or FALSE value.

Prev | Home | Next
Item Factory Example |  | Text Manipulation