Package gtk

Application support
Interface builder
Windows
Layout Containers
Display Widgets
Buttons and Toggles
Numeric and Text Data Entry
Multiline Text Editor
Tree, List and Icon Grid Widgets
Combo Box
Menus
Toolbar
Popover
Selectors (Color, File and Font)
Ornaments
Scrolling
Printing
Shortcuts Overview
Miscellaneous
Interfaces
Abstract Base Classes
Cross-process Embedding
Recently Used Documents
Choosing from installed applications
Gestures and event handling
GTK Core Reference
Theming in GTK
Deprecated
Symbols not implemented or exported

Application support

Interface builder

Windows

Layout Containers

Display Widgets

Buttons and Toggles

Numeric and Text Data Entry

Multiline Text Editor

Conceptual Overview

GTK has a powerful framework for multiline text editing. The primary objects involved in the process are the gtk-text-buffer object, which represents the text being edited, and the gtk-text-view widget, a widget which can display a gtk-text-buffer object. Each text buffer can be displayed by any number of views.

One of the important things to remember about text in GTK is that it is in the UTF-8 encoding. This means that one character can be encoded as multiple bytes. Character counts are usually referred to as offsets, while byte counts are called indexes. If you confuse these two, things will work fine with ASCII, but as soon as your text buffer contains multibyte characters, bad things will happen.

Text in a text buffer can be marked with tags. A tag is an attribute that can be applied to some range of text. For example, a tag might be called "bold" and make the text inside the tag bold. However, the tag concept is more general than that. Tags do not have to affect appearance. They can instead affect the behavior of mouse and key presses, "lock" a range of text so the user cannot edit it, or countless other things. A tag is represented by a gtk-text-tag object. One gtk-text-tag object can be applied to any number of text ranges in any number of text buffers.

Each tag is stored in a gtk-text-tag-table object. A tag table defines a set of tags that can be used together. Each text buffer has one tag table associated with it. Only tags from that tag table can be used with the text buffer. A single tag table can be shared between multiple text buffers, however.

Tags can have names, which is convenient sometimes. For example, you can name your tag that makes things bold "bold"), but they can also be anonymous, which is convenient if you are creating tags on-the-fly.

Most text manipulation is accomplished with iterators, represented by a gtk-text-iter instance. An iterator represents a position between two characters in the text buffer. The gtk-text-iter structure is a structure designed to be allocated on the stack. It is guaranteed to be copiable by value and never contain any heap-allocated data. Iterators are not valid indefinitely. Whenever the text buffer is modified in a way that affects the number of characters in the text buffer, all outstanding iterators become invalid. Note that deleting 5 characters and then reinserting 5 still invalidates iterators, though you end up with the same number of characters you pass through a state with a different number.

Because of this, iterators cannot be used to preserve positions across buffer modifications. To preserve a position, the gtk-text-mark object is ideal. You can think of a mark as an invisible cursor or insertion point. It floats in the text buffer, saving a position. If the text surrounding the mark is deleted, the mark remains in the position the text once occupied. If text is inserted at the mark, the mark ends up either to the left or to the right of the new text, depending on its gravity. The standard text cursor in left-to-right languages is a mark with right gravity, because it stays to the right of inserted text.

Like tags, marks can be either named or anonymous. There are two marks built-in to the gtk-text-buffer class. These are named "insert" and "selection_bound" and refer to the insertion point and the boundary of the selection which is not the insertion point, respectively. If no text is selected, these two marks will be in the same position. You can manipulate what is selected and where the cursor appears by moving these marks around. If you want to place the cursor in response to a user action, be sure to use the function gtk-text-buffer-place-cursor, which moves both at once without causing a temporary selection. Moving one then the other temporarily selects the range in between the old and new positions.

Text buffers always contain at least one line, but may be empty, that is, buffers can contain zero characters. The last line in the text buffer never ends in a line separator (such as newline). The other lines in the text buffer always end in a line separator. Line separators count as characters when computing character counts and character offsets. Note that some Unicode line separators are represented with multiple bytes in UTF-8, and the two-character sequence "rn" is also considered a line separator.

Simple Example

A simple usage of the gtk-text-view widget might look like this:

(defun example-text-view-simple ()
  (within-main-loop
    (let* ((window (make-instance 'gtk-window
                                  :type :toplevel
                                  :title "Example Simple Text View"
                                  :default-width 350))
           (view (make-instance 'gtk-text-view))
           (buffer (gtk-text-view-buffer view)))
      (g-signal-connect window "destroy"
          (lambda (widget)
            (declare (ignore widget))
            (let ((start (gtk-text-buffer-start-iter buffer))
                  (end (gtk-text-buffer-end-iter buffer))
                  (include-hidden-chars t))
              (print (gtk-text-buffer-get-text buffer
                                               start
                                               end
                                               include-hidden-chars))
              (terpri)
              (leave-gtk-main))))
      (setf (gtk-text-buffer-text buffer) "Some text for the text view.")
      (gtk-container-add window view)
      (gtk-widget-show-all window))))    

In many cases it is also convenient to first create the buffer with the function gtk-text-buffer-new, then create a widget for that text buffer with the function gtk-text-view-new-with-buffer. Or you can change the buffer the widget displays after the widget is created with the function gtk-text-view-buffer.

Example of Changing Text Attributes

The way to affect text attributes in the gtk-text-view widget is to apply tags that change the attributes for a region of text. For text features that come from the theme - such as font and foreground color - use CSS to override their default values.

(defun example-text-view-attributes ()
  (within-main-loop
    (let* ((window (make-instance 'gtk-window
                                  :type :toplevel
                                  :title "Example Text View Attributes"
                                  :default-width 350))
           (provider (gtk-css-provider-new))
           (view (make-instance 'gtk-text-view))
           (buffer (gtk-text-view-buffer view)))
      (g-signal-connect window "destroy"
                        (lambda (widget)
                          (declare (ignore widget))
                          (leave-gtk-main)))
      (setf (gtk-text-buffer-text buffer) "Hello, this is some text.")
      ;; Change default font and color throughout the widget
      (gtk-css-provider-load-from-data provider
                                       "textview, text {
                                          color : Green;
                                          font : 20px Purisa; }")
      (gtk-style-context-add-provider (gtk-widget-style-context view)
                                      provider
                                      +gtk-style-provider-priority-application+)
      ;; Change left margin throughout the widget
      (setf (gtk-text-view-left-margin view) 30)
      ;; Use a tag to change the color for just one part of the widget
      (let ((tag (gtk-text-buffer-create-tag buffer
                                             "blue_foreground"
                                             :foreground "blue"))
            (start (gtk-text-buffer-iter-at-offset buffer 7))
            (end (gtk-text-buffer-iter-at-offset buffer 12)))
        ;; Apply the tag to a region of the text in the buffer
        (gtk-text-buffer-apply-tag buffer tag start end))
      ;; Add the view to the window and show all
      (gtk-container-add window view)
      (gtk-widget-show-all window))))    

The gtk-demo application that comes with GTK contains more example code for the gtk-text-view widget.

Tree, List and Icon Grid Widgets

Overview of gtk-tree-model, gtk-tree-view, and friends.

Overview

To create a tree or list in GTK, use the gtk-tree-model interface in conjunction with the gtk-tree-view widget. This widget is designed around a Model/View/Controller design and consists of four major parts:

• The tree view widget (gtk-tree-view).
• The view column (gtk-tree-view-column).
• The cell renderers (gtk-cell-renderer etc.).
• The model interface (gtk-tree-model).

The View is composed of the first three objects, while the last is the Model. One of the prime benefits of the MVC design is that multiple views can be created of a single model. For example, a model mapping the file system could be created for a file manager. Many views could be created to display various parts of the file system, but only one copy need be kept in memory.

The purpose of the cell renderers is to provide extensibility to the widget and to allow multiple ways of rendering the same type of data. For example, consider how to render a boolean variable. Should it render it as a string of "True" or "False", "On" or "Off", or should it be rendered as a checkbox?

Creating a model

GTK provides two simple models that can be used: the gtk-list-store and the gtk-tree-store. gtk-list-store is used to model list widgets, while the gtk-tree-store models trees. It is possible to develop a new type of model, but the existing models should be satisfactory for all but the most specialized of situations. Creating the model is quite simple:

GtkListStore *store = gtk_list_store_new (2, G_TYPE_STRING, G_TYPE_BOOLEAN);      

This creates a list store with two columns: a string column and a boolean column. Typically the 2 is never passed directly like that; usually an enum is created wherein the different columns are enumerated, followed by a token that represents the total number of columns. The next example will illustrate this, only using a tree store instead of a list store. Creating a tree store operates almost exactly the same.

enum
{
   TITLE_COLUMN,
   AUTHOR_COLUMN,
   CHECKED_COLUMN,
   N_COLUMNS
};


GtkTreeStore *store = gtk_tree_store_new (N_COLUMNS,       /* Total number of columns */
                                          G_TYPE_STRING,   /* Book title              */
                                          G_TYPE_STRING,   /* Author                  */
                                          G_TYPE_BOOLEAN); /* Is checked out?         */      

Adding data to the model is done using gtk-tree-store-set or gtk-list-store-set, depending upon which sort of model was created. To do this, a gtk-tree-iter must be acquired. The iterator points to the location where data will be added.

Once an iterator has been acquired, gtk-tree-store-set is used to apply data to the part of the model that the iterator points to. Consider the following example:

GtkTreeIter   iter;


gtk_tree_store_append (store, &iter, NULL);  /* Acquire an iterator */


gtk_tree_store_set (store, &iter,
                    TITLE_COLUMN, "The Principle of Reason",
                    AUTHOR_COLUMN, "Martin Heidegger",
                    CHECKED_COLUMN, FALSE,
                    -1);      

Notice that the last argument is -1. This is always done because this is a variable-argument function and it needs to know when to stop processing arguments. It can be used to set the data in any or all columns in a given row.

The third argument to gtk-tree-store-append is the parent iterator. It is used to add a row to a gtk-tree-store as a child of an existing row. This means that the new row will only be visible when its parent is visible and in its expanded state. Consider the following example:

GtkTreeIter iter1;  /* Parent iter */
GtkTreeIter iter2;  /* Child iter  */


gtk_tree_store_append (store, &iter1, NULL);  /* Acquire a toplevel iterator */
gtk_tree_store_set (store, &iter1,
                    TITLE_COLUMN, "The Art of Computer Programming",
                    AUTHOR_COLUMN, "Donald E. Knuth",
                    CHECKED_COLUMN, FALSE,
                    -1);


gtk_tree_store_append (store, &iter2, &iter1);  /* Acquire a child iterator */
gtk_tree_store_set (store, &iter2,
                    TITLE_COLUMN, "Volume 1: Fundamental Algorithms",
                    -1);


gtk_tree_store_append (store, &iter2, &iter1);
gtk_tree_store_set (store, &iter2,
                    TITLE_COLUMN, "Volume 2: Seminumerical Algorithms",
                    -1);


gtk_tree_store_append (store, &iter2, &iter1);
gtk_tree_store_set (store, &iter2,
                    TITLE_COLUMN, "Volume 3: Sorting and Searching",
                    -1);      

Creating the view component

While there are several different models to choose from, there is only one view widget to deal with. It works with either the list or the tree store. Setting up a gtk-tree-view is not a difficult matter. It needs a gtk-tree-model to know where to retrieve its data from.

GtkWidget *tree;


tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));


Columns and cell renderers      

Once the gtk-tree-view widget has a model, it will need to know how to display the model. It does this with columns and cell renderers.

Cell renderers are used to draw the data in the tree model in a way. There are a number of cell renderers that come with GTK 2.x, including the gtk-cell-renderer-text, gtk-cell-renderer-pixbuf and the gtk-cell-renderer-toggle. It is relatively easy to write a custom renderer.

A gtk-tree-view-column is the object that gtk-tree-view uses to organize the vertical columns in the tree view. It needs to know the name of the column to label for the user, what type of cell renderer to use, and which piece of data to retrieve from the model for a given row.

GtkCellRenderer *renderer;
GtkTreeViewColumn *column;


renderer = gtk_cell_renderer_text_new ();
column = gtk_tree_view_column_new_with_attributes ("Author",
                                                   renderer,
                                                   "text", AUTHOR_COLUMN,
                                                   NULL);
gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);      

At this point, all the steps in creating a displayable tree have been covered. The model is created, data is stored in it, a tree view is created and columns are added to it.

Selection handling

Most applications will need to not only deal with displaying data, but also receiving input events from users. To do this, simply get a reference to a selection object and connect to the "changed" signal.

/* Prototype for selection handler callback */
static void tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data);


/* Setup the selection handler */
GtkTreeSelection *select;


select = gtk_tree_view_get_selection (GTK_TREE_VIEW (tree));
gtk_tree_selection_set_mode (select, GTK_SELECTION_SINGLE);
g_signal_connect (G_OBJECT (select), "changed",
                  G_CALLBACK (tree_selection_changed_cb),
                  NULL);      

Then to retrieve data for the row selected:

static void
tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data)
{
        GtkTreeIter iter;
        GtkTreeModel *model;
        gchar *author;


        if (gtk_tree_selection_get_selected (selection, &model, &iter))
        {
                gtk_tree_model_get (model, &iter, AUTHOR_COLUMN, &author, -1);


                g_print ("You selected a book by %sn", author);


                g_free (author);
        }
}      

Simple Example

Here is a simple example of using a gtk-tree-view widget in context of the other widgets. It simply creates a simple model and view, and puts them together. Note that the model is never populated with data - that is left as an exercise for the reader. More information can be found on this in the GtkTreeModel section.

enum
{
   TITLE_COLUMN,
   AUTHOR_COLUMN,
   CHECKED_COLUMN,
   N_COLUMNS
};


void
setup_tree (void)
{
   GtkTreeStore *store;
   GtkWidget *tree;
   GtkTreeViewColumn *column;
   GtkCellRenderer *renderer;


   /* Create a model.  We are using the store model for now, though we
    * could use any other GtkTreeModel */
   store = gtk_tree_store_new (N_COLUMNS,
                               G_TYPE_STRING,
                               G_TYPE_STRING,
                               G_TYPE_BOOLEAN);


   /* custom function to fill the model with data */
   populate_tree_model (store);


   /* Create a view */
   tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));


   /* The view now holds a reference.  We can get rid of our own
    * reference */
   g_object_unref (G_OBJECT (store));


   /* Create a cell render and arbitrarily make it red for demonstration
    * purposes */
   renderer = gtk_cell_renderer_text_new ();
   g_object_set (G_OBJECT (renderer),
                 "foreground", "red",
                 NULL);


   /* Create a column, associating the "text" attribute of the
    * cell_renderer to the first column of the model */
   column = gtk_tree_view_column_new_with_attributes ("Author", renderer,
                                                      "text", AUTHOR_COLUMN,
                                                      NULL);


   /* Add the column to the view. */
   gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);


   /* Second column.. title of the book. */
   renderer = gtk_cell_renderer_text_new ();
   column = gtk_tree_view_column_new_with_attributes ("Title",
                                                      renderer,
                                                      "text", TITLE_COLUMN,
                                                      NULL);
   gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);


   /* Last column.. whether a book is checked out. */
   renderer = gtk_cell_renderer_toggle_new ();
   column = gtk_tree_view_column_new_with_attributes ("Checked out",
                                                      renderer,
                                                      "active", CHECKED_COLUMN,
                                                      NULL);
   gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);


   /* Now we can manipulate the view just like any other GTK widget */
   ...
}      

Combo Box

Menus

Toolbar

Popover

Selectors (Color, File and Font)

Ornaments

Scrolling

Printing

Shortcuts Overview

Miscellaneous

Interfaces

Abstract Base Classes

Cross-process Embedding

Recently Used Documents

Choosing from installed applications

Gestures and event handling

GTK Core Reference

Theming in GTK

Deprecated

Symbols not implemented or exported

The following symbols in the C library have been deprecated since version 3.16 or longer. These symbols are not implemented in or not exported from the Lisp library.

gtk_action_group_new
gtk_action_group_get_action
gtk_action_group_list_actions
gtk_action_group_add_action
gtk_action_group_add_action_with_accel
gtk_action_group_remove_action
gtk_action_group_add_actions
gtk_action_group_add_actions_full
gtk_action_group_add_toggle_actions
gtk_action_group_add_toggle_actions_full
gtk_action_group_add_radio_actions
gtk_action_group_add_radio_actions_full
gtk_action_group_set_translate_func
gtk_action_group_set_translation_domain
gtk_action_group_translate_string


gtk_application_add_accelerator
gtk_application_remove_accelerator


gtk_alternative_dialog_button_order


gtk_assistant_set_page_header_image
gtk_assistant_get_page_header_image
gtk_assistant_set_page_side_image
gtk_assistant_get_page_side_image


gtk_button_new_from_stock
gtk_button_pressed
gtk_button_released
gtk_button_enter
gtk_button_leave
gtk_button_set_alignment
gtk_button_get_alignment


gtk_dialog_set_alternative_button_order
gtk_dialog_set_alternative_button_order_from_array


gtk_image_get_icon_set
gtk_image_get_stock
gtk_image_new_from_icon_set
gtk_image_new_from_stock
gtk_image_set_from_icon_set
gtk_image_set_from_stock


gtk_notebook_get_tab_hborder
gtk_notebook_get_tab_vborder