Appendix D. List Widget

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:

• GTK_SELECTION_SINGLE - The selection is either NULL or contains a GList pointer for a single selected item.

• GTK_SELECTION_BROWSE - The selection is NULL if the list contains no widgets or insensitive ones only, otherwise it contains a GList pointer for one GList structure, and therefore exactly one list item.

• GTK_SELECTION_MULTIPLE - The selection is NULL if no list items are selected or a GList pointer for the first selected item. That in turn points to a GList structure for the second selected item and so on.

• GTK_SELECTION_EXTENDED - The selection is always NULL.

The default is GTK_SELECTION_MULTIPLE.

void selection_changed( GtkList *list );

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

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