Next Previous Contents

14. 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.

class GTK_TEXT
inherit
   GTK_EDITABLE
creation
   make
feature -- creation
   make ( arg_hadj : GTK_ADJUSTMENT; arg_vadj : GTK_ADJUSTMENT )

14.1 Creating and Configuring a Text box

There is only one creation procedure:

make ( arg_hadj : GTK_ADJUSTMENT; arg_vadj : GTK_ADJUSTMENT )

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

set_adjustments ( arg_hadj : GTK_ADJUSTMENT; arg_vadj : GTK_ADJUSTMENT )

The above procedure 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.make (text.vadj);
  hbox.pack_start(vscrollbar, False, False, 0);
  vscrollbar.show;

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 GTK_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 procedure:

set_editable ( editable : BOOLEAN )

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 procedure:

set_word_wrap ( word_wrap : BOOLEAN )

Using this procedure allows us to specify that the text widget should wrap long lines on word boundaries.

14.2 Text Manipulation

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

set_point ( index : INTEGER )

where index is the position to set the insertion point.

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

get_point : INTEGER

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

get_length : INTEGER

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 carriage-return, 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.

insert ( font : GDK_FONT; fore : GDK_COLOR; back : GDK_COLOR;
         chars : STRING) is

Passing a value of Void in as the value for the foreground color, background colour or font will result in the values set within the widget style to be used.

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 procedures perform this freeze and thaw action:

freeze
thaw

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.

   backward_delete ( nchars : INTEGER ) : BOOLEAN

   forward_delete ( nchars : INTEGER ) : BOOLEAN

If you want to retrieve the contents of the text widget, then the function get_char(index) allows you to retrieve the character at position index within the text widget.

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

get_chars ( start_pos : INTEGER; end_pos : INTEGER ) : STRING

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.

14.3 Keyboard Shortcuts

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.

Motion Shortcuts

Editing Shortcuts

Selection Shortcuts

14.4 A GtkText Example

-- example-start text text.e
class TEXT
inherit
   GTK_CONSTANTS
   VEGTK_MAIN
   VEGTK_CALLBACK_HANDLER
creation
   make
feature {ANY} -- Creation
   make is
   local
      window : GTK_WINDOW;
      box1, box2, hbox : GTK_BOX;
      button : GTK_BUTTON;
      checkb : GTK_CHECK_BUTTON;
      separator : GTK_HSEPARATOR;
      table : GTK_TABLE;
      vscrollbar : GTK_VSCROLLBAR;
      text : GTK_TEXT;
      cmap : GDK_COLORMAP;
      colour : GDK_COLOR;
      fixed_font : GDK_FONT;
      infile : FILE;
   do
      -- Initialise GTK
      vegtk_init;

      !!window.make (GTK_WINDOW_TOPLEVEL);
      window.set_usize (600, 500);
      window.set_policy (TRUE, TRUE, FALSE);

      signal_connect (window, "destroy",$destroy);

      window.set_title ("Text Widget Example");
      window.set_border_width (0);

      !GTK_VBOX!box1.make (False, 0);
      window.add (box1);
      box1.show;

      !GTK_VBOX!box2.make (FALSE, 10);
      box2.set_border_width (10);
      box1.pack_start (box2, TRUE, TRUE, 0);
      box2.show;

      !!table.make (2, 2, FALSE);
      table.set_row_spacing (0, 2);
      table.set_col_spacing (0, 2);
      box2.pack_start (table, TRUE, TRUE, 0);
      table.show;

      -- Create the GtkText widget
      !!text.make (Void,Void);
      text.set_editable (TRUE);
      table.attach (text, 0, 1, 0, 1,
                    GTK_EXPAND and GTK_SHRINK and GTK_FILL,
                    GTK_EXPAND and GTK_SHRINK and GTK_FILL, 0, 0);
      text.show;

      -- Add a vertical scrollbar to the GtkText widget
      !!vscrollbar.make (text.vadj);
      table.attach (vscrollbar, 1, 2, 0, 1,
                    GTK_FILL, GTK_EXPAND and GTK_SHRINK and GTK_FILL, 0, 0);
      vscrollbar.show;

      -- Get the system colour map and allocate the colour red
      !!cmap.make_system;
      !!colour.make_with_values (65535, 0, 0);
      if not cmap.alloc_color (colour, False,True) then
         print("couldn't allocate colour%N");
      else
         -- Load a fixed font
         !!fixed_font.load ("-misc-fixed-medium-r-*-*-*-140-*-*-*-*-*-*");

         -- Realizing a widget creates a window for it,
         -- ready for us to insert some text
         text.realize;

         -- Freeze the text widget, ready for multiple updates
         text.freeze;

         -- Insert some coloured text
         text.insert (Void,text.get_style.black, Void,"Supports ");
         text.insert (Void,colour, Void, "colored ");
         text.insert (Void,text.get_style.black, Void, "text and different ");
         text.insert (fixed_font, text.get_style.black, Void, "fonts%N%N");

         -- Load the file text.c into the text window

         !!infile.make_open_read("text.e");

         if infile.is_open_read then
            from
               infile.read_line
            until
               infile.end_of_file
            loop
               text.insert(fixed_font, Void, Void, infile.last_string);
               text.insert(fixed_font, Void, Void, "%N");
               infile.read_line
            end -- loop
            infile.close
         end -- if
         -- Thaw the text widget, allowing the updates to become visible
         text.thaw;

         !GTK_HBUTTON_BOX!hbox.make;
         box2.pack_start (hbox, FALSE, FALSE, 0);
         hbox.show;

         !!checkb.make_with_label("Editable");
         hbox.pack_start (checkb, FALSE, FALSE, 0);
         signal_connect_with_data (checkb, "toggled", $text_toggle_editable,
                                   text);
         checkb.set_active(TRUE);
         checkb.show;
         !!checkb.make_with_label("Wrap Words");
         hbox.pack_start (checkb, FALSE, TRUE, 0);
         signal_connect_with_data (checkb, "toggled", $text_toggle_word_wrap,
                                   text);
         checkb.set_active (FALSE);
         checkb.show;

         !!separator.make;
         box1.pack_start (separator, FALSE, TRUE, 0);
         separator.show;

         !GTK_VBOX!box2.make (FALSE, 10);
         box2.set_border_width (10);
         box1.pack_start (box2, FALSE, TRUE, 0);
         box2.show;

         !!button.make_with_label ("close");
         signal_connect_with_data (button, "clicked", $quit_app, window);
         box2.pack_start (button, TRUE, TRUE, 0);
         button.set_flags (GTK_CAN_DEFAULT);
         button.grab_default;
         button.show;

         window.show;

         gtk_main;
      end -- if
   end
   text_toggle_editable (data : ANY; cb_data : VEGTK_CALLBACK_DATA) is
   local
      checkbutton : GTK_CHECK_BUTTON;
      text : GTK_TEXT;
   do
      checkbutton ?= cb_data.get_widget;
      text ?= data;
      text.set_editable(checkbutton.get_active);
   end

   text_toggle_word_wrap (data : ANY; cb_data : VEGTK_CALLBACK_DATA) is
   local
      checkbutton : GTK_CHECK_BUTTON;
      text : GTK_TEXT;
   do
      checkbutton ?= cb_data.get_widget;
      text ?= data;
      text.set_word_wrap(checkbutton.get_active);
   end
   destroy is
   do
      gtk_main_quit;
   end
   quit_app (data : ANY) is
   local
      window : GTK_WINDOW;
   do
      window ?= data;
      window.destroy;
   end
end -- class TEXT
-- example-end


Next Previous Contents