Appendix D. List Widget

Table of Contents
Signals
Functions
Example
List Item Widget
Signals
Functions
Example

NOTE: The List widget has been superseded by the CList widget. It is detailed here just for completeness.

The List widget is designed to act as a vertical container for widgets that should be of the type ListItem.

A List widget has its own window to receive events and its own background color which is usually white. As it is directly derived from a Container it can be treated as such by using the GTK_CONTAINER(List) macro, see the Container widget for more on this. One should already be familiar with the usage of a GList and its related functions g_list_*() to be able to use the List widget to it full extent.

There is one field inside the structure definition of the List widget that will be of greater interest to us, this is:

struct _GtkList
{
  ...
  GList *selection;
  guint selection_mode;
  ...
}; 

The selection field of a List points to a linked list of all items that are currently selected, or NULL if the selection is empty. So to learn about the current selection we read the GTK_LIST()->selection field, but do not modify it since the internal fields are maintained by the gtk_list_*() functions.

The selection_mode of the List determines the selection facilities of a List and therefore the contents of the GTK_LIST()->selection field. The selection_mode may be one of the following:

The default is GTK_SELECTION_MULTIPLE.

Signals

void selection_changed( GtkList *list );

This signal will be invoked whenever the selection field of a List has changed. This happens when a child of thekList got selected or deselected.

void select_child( GtkList   *list,
                   GtkWidget *child);

This signal is invoked when a child of the List is about to get selected. This happens mainly on calls to gtk_list_select_item(), gtk_list_select_child(), button presses and sometimes indirectly triggered on some else occasions where children get added to or removed from the List.

void unselect_child( GtkList   *list,
                     GtkWidget *child );

This signal is invoked when a child of the List is about to get deselected. This happens mainly on calls to gtk_list_unselect_item(), gtk_list_unselect_child(), button presses and sometimes indirectly triggered on some else occasions where children get added to or removed from the List.