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.
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.
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.
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:
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:
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.
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.
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:
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.
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
The text widget has a number of pre-installed keyboard shortcuts for
common editing, motion and selection functions. These are accessed
using Control and Alt key combinations.
In addition to these, holding down the Control key whilst using cursor
key movement will move the cursor by words rather than
characters. Holding down Shift whilst using cursor movement will
extend the selection.