GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkCombo

## Name

GtkCombo -- a text entry field with a dropdown list.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkCombo;
    GtkWidget*  gtk_combo_new                   (void);
    void        gtk_combo_set_popdown_strings   (GtkCombo *combo,
                                                 GList *strings);
    void        gtk_combo_set_value_in_list     (GtkCombo *combo,
                                                 gboolean val,
                                                 gboolean ok_if_empty);
    void        gtk_combo_set_use_arrows        (GtkCombo *combo,
                                                 gboolean val);
    void        gtk_combo_set_use_arrows_always (GtkCombo *combo,
                                                 gboolean val);
    void        gtk_combo_set_case_sensitive    (GtkCombo *combo,
                                                 gboolean val);
    void        gtk_combo_set_item_string       (GtkCombo *combo,
                                                 GtkItem *item,
                                                 const gchar *item_value);
    void        gtk_combo_disable_activate      (GtkCombo *combo);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBox
                               +----GtkHBox
                                     +----GtkCombo

## Properties

      "enable-arrow-keys"    gboolean             : Read / Write
      "enable-arrows-always" gboolean             : Read / Write
      "case-sensitive"       gboolean             : Read / Write
      "allow-empty"          gboolean             : Read / Write
      "value-in-list"        gboolean             : Read / Write

## Description

The GtkCombo 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 GtkList widget and can be accessed using the `list` member of the GtkCombo. List elements can contain arbitrary widgets, but if an element is not a plain label, then you must use the 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 gtk_combo_set_use_arrows().

Normally the arrow keys are only active when the contents of the text entry field matches one of the items in the list. If the contents of the entry field do not match any of the list items, then pressing the arrow keys does nothing. However, by calling gtk_combo_set_use_arrows_always() you can specify that the arrow keys are always active. If the contents of the entry field does not match any of the items in the list, then pressing the up or down arrow key will set the entry field to the last or first item in the list, respectively.

Example 1. Creating a GtkCombo widget with simple text items.

      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);

Example 2. Creating a GtkCombo widget with a complex item.

      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), pixmap, 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);

## Details

### struct GtkCombo

    struct GtkCombo;

The GtkFixedChild struct contains the following fields. (These fields should be considered read-only. They should never be set by an application.)

GtkWidget *entry; | the text entry field.
GtkWidget *list; | the list shown in the drop-down window.

### gtk_combo_new ()

    GtkWidget*  gtk_combo_new                   (void);

Creates a new GtkCombo.

Returns : | a new GtkCombo.

### gtk_combo_set_popdown_strings ()

    void        gtk_combo_set_popdown_strings   (GtkCombo *combo,
                                                 GList *strings);

Convenience function to set all of the items in the popup list. (See the example above.)

`combo` : | a GtkCombo.
`strings` : | a list of strings.

### gtk_combo_set_value_in_list ()

    void        gtk_combo_set_value_in_list     (GtkCombo *combo,
                                                 gboolean val,
                                                 gboolean ok_if_empty);

Specifies whether the value entered in the text entry field must match one of the values in the list. If this is set then the user will not be able to perform any other action until a valid value has been entered.

If an empty field is acceptable, the `ok_if_empty` parameter should be `TRUE`.

`combo` : | a GtkCombo.
`val` : | `TRUE` if the value entered must match one of the values in the list.
`ok_if_empty` : | `TRUE` if an empty value is considered valid.

### gtk_combo_set_use_arrows ()

    void        gtk_combo_set_use_arrows        (GtkCombo *combo,
                                                 gboolean val);

Specifies if the arrow (cursor) keys can be used to step through the items in the list. This is on by default.

`combo` : | a GtkCombo.
`val` : | `TRUE` if the arrow keys can be used to step through the items in the list.

### gtk_combo_set_use_arrows_always ()

    void        gtk_combo_set_use_arrows_always (GtkCombo *combo,
                                                 gboolean val);

Specifies if the arrow keys will still work even if the current contents of the GtkEntry field do not match any of the list items.

`combo` : | a GtkCombo.
`val` : | `TRUE` if the arrow keys will still work even if the current contents of the GtkEntry field do not match any of the list items.

### gtk_combo_set_case_sensitive ()

    void        gtk_combo_set_case_sensitive    (GtkCombo *combo,
                                                 gboolean val);

Specifies whether the text entered into the GtkEntry field and the text in the list items is case sensitive.

This may be useful, for example, when you have called gtk_combo_set_value_in_list() to limit the values entered, but you are not worried about differences in case.

`combo` : | a GtkCombo.
`val` : | `TRUE` if the text in the list items is case sensitive.

### gtk_combo_set_item_string ()

    void        gtk_combo_set_item_string       (GtkCombo *combo,
                                                 GtkItem *item,
                                                 const gchar *item_value);

Sets the string to place in the GtkEntry field when a particular list item is selected. This is needed if the list item is not a simple label.

`combo` : | a GtkCombo.
`item` : | a GtkItem.
`item_value` : | the string to place in the GtkEntry when `item` is selected.

### gtk_combo_disable_activate ()

    void        gtk_combo_disable_activate      (GtkCombo *combo);

Stops the GtkCombo widget from showing the popup list when the GtkEntry emits the "activate" signal, i.e. when the Return key is pressed. This may be useful if, for example, you want the Return key to close a dialog instead.

`combo` : | a GtkCombo.

## Properties

"`enable-arrow-keys`" (gboolean : Read / Write)

  Whether the arrow keys move through the list of items

"`enable-arrows-always`" (gboolean : Read / Write)

  Whether the arrow keys work, even if the entry contents are not in the list

"`case-sensitive`" (gboolean : Read / Write)

  Whether list item matching is case sensitive

"`allow-empty`" (gboolean : Read / Write)

  Whether an empty value may be entered in this field

"`value-in-list`" (gboolean : Read / Write)

  Whether entered values must already be present in the list

<<< Previous Page | Home | Up | Next Page >>>
Menus, Combo Box, Toolbar | GtkItemFactory