
@c %start of fragment

@node GtkCombo
@chapter GtkCombo
A text entry field with a dropdown list

@section Overview
The @code{<gtk-combo>} widget consists of a single-line text entry field and a
drop-down list. The drop-down list is displayed when the user clicks on a small
arrow button to the right of the entry field.

The drop-down list is a @code{<gtk-list>} widget and can be accessed using the
member of the @code{<gtk-combo>}. List elements can contain arbitrary widgets,
but if an element is not a plain label, then you must use the
@code{gtk-list-set-item-string} function. This sets the string which will be
placed in the text entry field when the item is selected.

By default, the user can step through the items in the list using the arrow
(cursor) keys, though this behaviour can be turned off with
@code{gtk-combo-set-use-arrows}.

As of GTK+ 2.4, @code{<gtk-combo>} has been deprecated in favor of
@code{<gtk-combo-box>}.

@example 

  GtkWidget *combo;
  GList *items = NULL;

  items = g_list_append (items, "First Item");
  items = g_list_append (items, "Second Item");
  items = g_list_append (items, "Third Item");
  items = g_list_append (items, "Fourth Item");
  items = g_list_append (items, "Fifth Item");

  combo = gtk_combo_new ();
  gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
@end example

@example 

  GtkWidget *combo, *item, *hbox, *arrow, *label;

  combo = gtk_combo_new ();

  item = gtk_list_item_new ();
  gtk_widget_show (item);

  /* You can put almost anything into the GtkListItem widget. Here we will use
     a horizontal box with an arrow and a label in it. */
  hbox = gtk_hbox_new (FALSE, 3);
  gtk_container_add (GTK_CONTAINER (item), hbox);
  gtk_widget_show (hbox);

  arrow = gtk_arrow_new (GTK_ARROW_RIGHT, GTK_SHADOW_OUT);
  gtk_widget_show (arrow);
  gtk_box_pack_start (GTK_BOX (hbox), arrow, FALSE, FALSE, 0);

  label = gtk_label_new ("First Item");
  gtk_widget_show (label);
  gtk_box_pack_start (GTK_BOX (hbox), label, FALSE, FALSE, 0);

  /* You must set the string to display in the entry field when the item is
     selected. */
  gtk_combo_set_item_string (GTK_COMBO (combo), GTK_ITEM (item), "1st Item");

  /* Now we simply add the item to the combo's list. */
  gtk_container_add (GTK_CONTAINER (GTK_COMBO (combo)->list), item);
@end example

@section Usage
@include defuns-gtkcombo.xml.texi

@c %end of fragment
