<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <HTML> <HEAD> <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9"> <TITLE>GTK v1.2 Tutorial: List Widget</TITLE> <LINK HREF="gtk_tut-30.html" REL=previous> <LINK HREF="gtk_tut.html#toc31" REL=contents> </HEAD> <BODY BGCOLOR="#FFFFFF"> Next <A HREF="gtk_tut-30.html">Previous</A> <A HREF="gtk_tut.html#toc31">Contents</A> <HR NOSHADE> <H2><A NAME="s31">31. List Widget</A></H2> <P>NOTE: The List widget has been superseded by the CList widget. It is detailed here just for completeness. <P>The List widget is designed to act as a vertical container for widgets that should be of the type ListItem. <P>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. <P>There is one field inside the structure definition of the List widget that will be of greater interest to us, this is: <P> <BLOCKQUOTE><CODE> <PRE> struct _GtkList { ... GList *selection; guint selection_mode; ... }; </PRE> </CODE></BLOCKQUOTE> <P>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. <P>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: <P> <UL> <LI> <CODE>GTK_SELECTION_SINGLE</CODE> - The selection is either NULL or contains a GList pointer for a single selected item. </LI> <LI> <CODE>GTK_SELECTION_BROWSE</CODE> - 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. </LI> <LI> <CODE>GTK_SELECTION_MULTIPLE</CODE> - 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. </LI> <LI> <CODE>GTK_SELECTION_EXTENDED</CODE> - The selection is always NULL.</LI> </UL> <P>The default is <CODE>GTK_SELECTION_MULTIPLE</CODE>. <P> <H2><A NAME="ss31.1">31.1 Signals</A> </H2> <P> <BLOCKQUOTE><CODE> <PRE> void selection_changed( GtkList *list ); </PRE> </CODE></BLOCKQUOTE> <P>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. <P> <BLOCKQUOTE><CODE> <PRE> void select_child( GtkList *list, GtkWidget *child); </PRE> </CODE></BLOCKQUOTE> <P>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. <P> <BLOCKQUOTE><CODE> <PRE> void unselect_child( GtkList *list, GtkWidget *child ); </PRE> </CODE></BLOCKQUOTE> <P>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. <P> <H2><A NAME="ss31.2">31.2 Functions</A> </H2> <P> <BLOCKQUOTE><CODE> <PRE> guint gtk_list_get_type( void ); </PRE> </CODE></BLOCKQUOTE> <P>Returns the "GtkList" type identifier. <P> <BLOCKQUOTE><CODE> <PRE> GtkWidget *gtk_list_new( void ); </PRE> </CODE></BLOCKQUOTE> <P>Create a new List object. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_insert_items( GtkList *list, GList *items, gint position ); </PRE> </CODE></BLOCKQUOTE> <P>Insert list items into the list, starting at <CODE>position</CODE>. <CODE>items</CODE> is a doubly linked list where each nodes data pointer is expected to point to a newly created ListItem. The GList nodes of <CODE>items</CODE> are taken over by the list. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_append_items( GtkList *list, GList *items); </PRE> </CODE></BLOCKQUOTE> <P>Insert list items just like gtk_list_insert_items() at the end of the list. The GList nodes of <CODE>items</CODE> are taken over by the list. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_prepend_items( GtkList *list, GList *items); </PRE> </CODE></BLOCKQUOTE> <P>Insert list items just like gtk_list_insert_items() at the very beginning of the list. The GList nodes of <CODE>items</CODE> are taken over by the list. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_remove_items( GtkList *list, GList *items); </PRE> </CODE></BLOCKQUOTE> <P>Remove list items from the list. <CODE>items</CODE> is a doubly linked list where each nodes data pointer is expected to point to a direct child of list. It is the callers responsibility to make a call to g_list_free(items) afterwards. Also the caller has to destroy the list items himself. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_clear_items( GtkList *list, gint start, gint end ); </PRE> </CODE></BLOCKQUOTE> <P>Remove and destroy list items from the list. A widget is affected if its current position within the list is in the range specified by <CODE>start</CODE> and <CODE>end</CODE>. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_select_item( GtkList *list, gint item ); </PRE> </CODE></BLOCKQUOTE> <P>Invoke the select_child signal for a list item specified through its current position within the list. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_unselect_item( GtkList *list, gint item); </PRE> </CODE></BLOCKQUOTE> <P>Invoke the unselect_child signal for a list item specified through its current position within the list. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_select_child( GtkList *list, GtkWidget *child); </PRE> </CODE></BLOCKQUOTE> <P>Invoke the select_child signal for the specified child. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_unselect_child( GtkList *list, GtkWidget *child); </PRE> </CODE></BLOCKQUOTE> <P>Invoke the unselect_child signal for the specified child. <P> <BLOCKQUOTE><CODE> <PRE> gint gtk_list_child_position( GtkList *list, GtkWidget *child); </PRE> </CODE></BLOCKQUOTE> <P>Return the position of <CODE>child</CODE> within the list. "-1" is returned on failure. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_set_selection_mode( GtkList *list, GtkSelectionMode mode ); </PRE> </CODE></BLOCKQUOTE> <P>Set the selection mode MODE which can be of GTK_SELECTION_SINGLE, GTK_SELECTION_BROWSE, GTK_SELECTION_MULTIPLE or GTK_SELECTION_EXTENDED. <P> <BLOCKQUOTE><CODE> <PRE> GtkList *GTK_LIST( gpointer obj ); </PRE> </CODE></BLOCKQUOTE> <P>Cast a generic pointer to "GtkList *". <P> <BLOCKQUOTE><CODE> <PRE> GtkListClass *GTK_LIST_CLASS( gpointer class); </PRE> </CODE></BLOCKQUOTE> <P>Cast a generic pointer to "GtkListClass *". <P> <BLOCKQUOTE><CODE> <PRE> gint GTK_IS_LIST( gpointer obj); </PRE> </CODE></BLOCKQUOTE> <P>Determine if a generic pointer refers to a "GtkList" object. <P> <H2><A NAME="ss31.3">31.3 Example</A> </H2> <P>Following is an example program that will print out the changes of the selection of a List, and lets you "arrest" list items into a prison by selecting them with the rightmost mouse button. <P> <BLOCKQUOTE><CODE> <PRE> /* example-start list list.c */ /* Include the GTK header files * Include stdio.h, we need that for the printf() function */ #include <gtk/gtk.h> #include <stdio.h> /* This is our data identification string to store * data in list items */ const gchar *list_item_data_key="list_item_data"; /* prototypes for signal handler that we are going to connect * to the List widget */ static void sigh_print_selection( GtkWidget *gtklist, gpointer func_data); static void sigh_button_event( GtkWidget *gtklist, GdkEventButton *event, GtkWidget *frame ); /* Main function to set up the user interface */ gint main( int argc, gchar *argv[] ) { GtkWidget *separator; GtkWidget *window; GtkWidget *vbox; GtkWidget *scrolled_window; GtkWidget *frame; GtkWidget *gtklist; GtkWidget *button; GtkWidget *list_item; GList *dlist; guint i; gchar buffer[64]; /* Initialize GTK (and subsequently GDK) */ gtk_init(&argc, &argv); /* Create a window to put all the widgets in * connect gtk_main_quit() to the "destroy" event of * the window to handle window manager close-window-events */ window=gtk_window_new(GTK_WINDOW_TOPLEVEL); gtk_window_set_title(GTK_WINDOW(window), "GtkList Example"); gtk_signal_connect(GTK_OBJECT(window), "destroy", GTK_SIGNAL_FUNC(gtk_main_quit), NULL); /* Inside the window we need a box to arrange the widgets * vertically */ vbox=gtk_vbox_new(FALSE, 5); gtk_container_set_border_width(GTK_CONTAINER(vbox), 5); gtk_container_add(GTK_CONTAINER(window), vbox); gtk_widget_show(vbox); /* This is the scrolled window to put the List widget inside */ scrolled_window=gtk_scrolled_window_new(NULL, NULL); gtk_widget_set_usize(scrolled_window, 250, 150); gtk_container_add(GTK_CONTAINER(vbox), scrolled_window); gtk_widget_show(scrolled_window); /* Create thekList widget. * Connect the sigh_print_selection() signal handler * function to the "selection_changed" signal of the List * to print out the selected items each time the selection * has changed */ gtklist=gtk_list_new(); gtk_scrolled_window_add_with_viewport( GTK_SCROLLED_WINDOW(scrolled_window), gtklist); gtk_widget_show(gtklist); gtk_signal_connect(GTK_OBJECT(gtklist), "selection_changed", GTK_SIGNAL_FUNC(sigh_print_selection), NULL); /* We create a "Prison" to put a list item in ;) */ frame=gtk_frame_new("Prison"); gtk_widget_set_usize(frame, 200, 50); gtk_container_set_border_width(GTK_CONTAINER(frame), 5); gtk_frame_set_shadow_type(GTK_FRAME(frame), GTK_SHADOW_OUT); gtk_container_add(GTK_CONTAINER(vbox), frame); gtk_widget_show(frame); /* Connect the sigh_button_event() signal handler to the List * which will handle the "arresting" of list items */ gtk_signal_connect(GTK_OBJECT(gtklist), "button_release_event", GTK_SIGNAL_FUNC(sigh_button_event), frame); /* Create a separator */ separator=gtk_hseparator_new(); gtk_container_add(GTK_CONTAINER(vbox), separator); gtk_widget_show(separator); /* Finally create a button and connect its "clicked" signal * to the destruction of the window */ button=gtk_button_new_with_label("Close"); gtk_container_add(GTK_CONTAINER(vbox), button); gtk_widget_show(button); gtk_signal_connect_object(GTK_OBJECT(button), "clicked", GTK_SIGNAL_FUNC(gtk_widget_destroy), GTK_OBJECT(window)); /* Now we create 5 list items, each having its own * label and add them to the List using gtk_container_add() * Also we query the text string from the label and * associate it with the list_item_data_key for each list item */ for (i=0; i<5; i++) { GtkWidget *label; gchar *string; sprintf(buffer, "ListItemContainer with Label #%d", i); label=gtk_label_new(buffer); list_item=gtk_list_item_new(); gtk_container_add(GTK_CONTAINER(list_item), label); gtk_widget_show(label); gtk_container_add(GTK_CONTAINER(gtklist), list_item); gtk_widget_show(list_item); gtk_label_get(GTK_LABEL(label), &string); gtk_object_set_data(GTK_OBJECT(list_item), list_item_data_key, string); } /* Here, we are creating another 5 labels, this time * we use gtk_list_item_new_with_label() for the creation * we can't query the text string from the label because * we don't have the labels pointer and therefore * we just associate the list_item_data_key of each * list item with the same text string. * For adding of the list items we put them all into a doubly * linked list (GList), and then add them by a single call to * gtk_list_append_items(). * Because we use g_list_prepend() to put the items into the * doubly linked list, their order will be descending (instead * of ascending when using g_list_append()) */ dlist=NULL; for (; i<10; i++) { sprintf(buffer, "List Item with Label %d", i); list_item=gtk_list_item_new_with_label(buffer); dlist=g_list_prepend(dlist, list_item); gtk_widget_show(list_item); gtk_object_set_data(GTK_OBJECT(list_item), list_item_data_key, "ListItem with integrated Label"); } gtk_list_append_items(GTK_LIST(gtklist), dlist); /* Finally we want to see the window, don't we? ;) */ gtk_widget_show(window); /* Fire up the main event loop of gtk */ gtk_main(); /* We get here after gtk_main_quit() has been called which * happens if the main window gets destroyed */ return(0); } /* This is the signal handler that got connected to button * press/release events of the List */ void sigh_button_event( GtkWidget *gtklist, GdkEventButton *event, GtkWidget *frame ) { /* We only do something if the third (rightmost mouse button * was released */ if (event->type==GDK_BUTTON_RELEASE && event->button==3) { GList *dlist, *free_list; GtkWidget *new_prisoner; /* Fetch the currently selected list item which * will be our next prisoner ;) */ dlist=GTK_LIST(gtklist)->selection; if (dlist) new_prisoner=GTK_WIDGET(dlist->data); else new_prisoner=NULL; /* Look for already imprisoned list items, we * will put them back into the list. * Remember to free the doubly linked list that * gtk_container_children() returns */ dlist=gtk_container_children(GTK_CONTAINER(frame)); free_list=dlist; while (dlist) { GtkWidget *list_item; list_item=dlist->data; gtk_widget_reparent(list_item, gtklist); dlist=dlist->next; } g_list_free(free_list); /* If we have a new prisoner, remove him from the * List and put him into the frame "Prison". * We need to unselect the item first. */ if (new_prisoner) { GList static_dlist; static_dlist.data=new_prisoner; static_dlist.next=NULL; static_dlist.prev=NULL; gtk_list_unselect_child(GTK_LIST(gtklist), new_prisoner); gtk_widget_reparent(new_prisoner, frame); } } } /* This is the signal handler that gets called if List * emits the "selection_changed" signal */ void sigh_print_selection( GtkWidget *gtklist, gpointer func_data ) { GList *dlist; /* Fetch the doubly linked list of selected items * of the List, remember to treat this as read-only! */ dlist=GTK_LIST(gtklist)->selection; /* If there are no selected items there is nothing more * to do than just telling the user so */ if (!dlist) { g_print("Selection cleared\n"); return; } /* Ok, we got a selection and so we print it */ g_print("The selection is a "); /* Get the list item from the doubly linked list * and then query the data associated with list_item_data_key. * We then just print it */ while (dlist) { GtkObject *list_item; gchar *item_data_string; list_item=GTK_OBJECT(dlist->data); item_data_string=gtk_object_get_data(list_item, list_item_data_key); g_print("%s ", item_data_string); dlist=dlist->next; } g_print("\n"); } /* example-end */ </PRE> </CODE></BLOCKQUOTE> <P> <H2><A NAME="ss31.4">31.4 List Item Widget</A> </H2> <P>The ListItem widget is designed to act as a container holding up to one child, providing functions for selection/deselection just like the List widget requires them for its children. <P>A ListItem has its own window to receive events and has its own background color which is usually white. <P>As it is directly derived from an Item it can be treated as such by using the GTK_ITEM(ListItem) macro, see the Item widget for more on this. Usually a ListItem just holds a label to identify, e.g., a filename within a List -- therefore the convenience function gtk_list_item_new_with_label() is provided. The same effect can be achieved by creating a Label on its own, setting its alignment to xalign=0 and yalign=0.5 with a subsequent container addition to the ListItem. <P>As one is not forced to add a GtkLabel to a GtkListItem, you could also add a GtkVBox or a GtkArrow etc. to the GtkListItem. <P> <H2><A NAME="ss31.5">31.5 Signals</A> </H2> <P>AkListItem does not create new signals on its own, but inherits the signals of a Item. <P> <H2><A NAME="ss31.6">31.6 Functions</A> </H2> <P> <BLOCKQUOTE><CODE> <PRE> guint gtk_list_item_get_type( void ); </PRE> </CODE></BLOCKQUOTE> <P>Returns the "GtkListItem" type identifier. <P> <BLOCKQUOTE><CODE> <PRE> GtkWidget *gtk_list_item_new( void ); </PRE> </CODE></BLOCKQUOTE> <P>Create a new ListItem object. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure. <P> <BLOCKQUOTE><CODE> <PRE> GtkWidget *gtk_list_item_new_with_label( gchar *label ); </PRE> </CODE></BLOCKQUOTE> <P>Create a new ListItem object, having a single GtkLabel as the sole child. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_item_select( GtkListItem *list_item ); </PRE> </CODE></BLOCKQUOTE> <P>This function is basically a wrapper around a call to gtk_item_select (GTK_ITEM (list_item)) which will emit the select signal. *Note GtkItem::, for more info. <P> <BLOCKQUOTE><CODE> <PRE> void gtk_list_item_deselect( GtkListItem *list_item ); </PRE> </CODE></BLOCKQUOTE> <P>This function is basically a wrapper around a call to gtk_item_deselect (GTK_ITEM (list_item)) which will emit the deselect signal. *Note GtkItem::, for more info. <P> <BLOCKQUOTE><CODE> <PRE> GtkListItem *GTK_LIST_ITEM( gpointer obj ); </PRE> </CODE></BLOCKQUOTE> <P>Cast a generic pointer to "GtkListItem *". <P> <BLOCKQUOTE><CODE> <PRE> GtkListItemClass *GTK_LIST_ITEM_CLASS( gpointer class ); </PRE> </CODE></BLOCKQUOTE> <P>Cast a generic pointer to GtkListItemClass*. *Note Standard Macros::, for more info. <P> <BLOCKQUOTE><CODE> <PRE> gint GTK_IS_LIST_ITEM( gpointer obj ); </PRE> </CODE></BLOCKQUOTE> <P>Determine if a generic pointer refers to a `GtkListItem' object. *Note Standard Macros::, for more info. <P> <H2><A NAME="ss31.7">31.7 Example</A> </H2> <P>Please see the List example on this, which covers the usage of a ListItem as well. <P> <P> <HR NOSHADE> Next <A HREF="gtk_tut-30.html">Previous</A> <A HREF="gtk_tut.html#toc31">Contents</A> </BODY> </HTML>