## GtkComboBox

GtkComboBox — a widget used to choose from a list of items.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkComboBox;
    GtkWidget*  gtk_combo_box_new               (void);
    GtkWidget*  gtk_combo_box_new_with_model    (GtkTreeModel *model);
    void        gtk_combo_box_set_wrap_width    (GtkComboBox *combo_box,
                                                 gint width);
    void        gtk_combo_box_set_row_span_column
                                                (GtkComboBox *combo_box,
                                                 gint row_span);
    void        gtk_combo_box_set_column_span_column
                                                (GtkComboBox *combo_box,
                                                 gint column_span);
    gint        gtk_combo_box_get_active        (GtkComboBox *combo_box);
    void        gtk_combo_box_set_active        (GtkComboBox *combo_box,
                                                 gint index_);
    gboolean    gtk_combo_box_get_active_iter   (GtkComboBox *combo_box,
                                                 GtkTreeIter *iter);
    void        gtk_combo_box_set_active_iter   (GtkComboBox *combo_box,
                                                 GtkTreeIter *iter);
    GtkTreeModel* gtk_combo_box_get_model       (GtkComboBox *combo_box);
    void        gtk_combo_box_set_model         (GtkComboBox *combo_box,
                                                 GtkTreeModel *model);
    GtkWidget*  gtk_combo_box_new_text          (void);
    void        gtk_combo_box_append_text       (GtkComboBox *combo_box,
                                                 const gchar *text);
    void        gtk_combo_box_insert_text       (GtkComboBox *combo_box,
                                                 gint position,
                                                 const gchar *text);
    void        gtk_combo_box_prepend_text      (GtkComboBox *combo_box,
                                                 const gchar *text);
    void        gtk_combo_box_remove_text       (GtkComboBox *combo_box,
                                                 gint position);
    void        gtk_combo_box_popup             (GtkComboBox *combo_box);
    void        gtk_combo_box_popdown           (GtkComboBox *combo_box);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkComboBox
                                     +----GtkComboBoxEntry

## Implemented Interfaces

GtkComboBox implements AtkImplementorIface and GtkCellLayout.

## Properties

      "active"               gint                  : Read / Write
      "column-span-column"   gint                  : Read / Write
      "model"                GtkTreeModel          : Read / Write
      "row-span-column"      gint                  : Read / Write
      "wrap-width"           gint                  : Read / Write

## Style Properties

      "appears-as-list"      gboolean              : Read

## Signal Prototypes

    "changed"   void        user_function      (GtkComboBox *combobox,
                                                gpointer user_data);

## Description

## Details

### struct GtkComboBox

    struct GtkComboBox;

### gtk_combo_box_new ()

    GtkWidget*  gtk_combo_box_new               (void);

Creates a new empty GtkComboBox.

Returns : | A new GtkComboBox.

Since 2.4

### gtk_combo_box_new_with_model ()

    GtkWidget*  gtk_combo_box_new_with_model    (GtkTreeModel *model);

Creates a new GtkComboBox with the model initialized to `model`.

`model` : | A GtkTreeModel.
Returns : | A new GtkComboBox.

Since 2.4

### gtk_combo_box_set_wrap_width ()

    void        gtk_combo_box_set_wrap_width    (GtkComboBox *combo_box,
                                                 gint width);

Sets the wrap width of `combo_box` to be `width`. The wrap width is basically the preferred number of columns when you want to the popup to be layed out in a table.

`combo_box` : | A GtkComboBox.
`width` : | Preferred number of columns.

Since 2.4

### gtk_combo_box_set_row_span_column ()

    void        gtk_combo_box_set_row_span_column
                                                (GtkComboBox *combo_box,
                                                 gint row_span);

Sets the column with row span information for `combo_box` to be `row_span`. The row span column contains integers which indicate how many rows an item should span.

`combo_box` : | A GtkComboBox.
`row_span` : | A column in the model passed during construction.

Since 2.4

### gtk_combo_box_set_column_span_column ()

    void        gtk_combo_box_set_column_span_column
                                                (GtkComboBox *combo_box,
                                                 gint column_span);

Sets the column with column span information for `combo_box` to be `column_span`. The column span column contains integers which indicate how many columns an item should span.

`combo_box` : | A GtkComboBox.
`column_span` : | A column in the model passed during construction.

Since 2.4

### gtk_combo_box_get_active ()

    gint        gtk_combo_box_get_active        (GtkComboBox *combo_box);

Returns the index of the currently active item, or -1 if there's no active item.

`combo_box` : | A GtkComboBox.
Returns : | An integer which is the index of the currently active item, or -1 if there's no active item.

Since 2.4

### gtk_combo_box_set_active ()

    void        gtk_combo_box_set_active        (GtkComboBox *combo_box,
                                                 gint index_);

Sets the active item of `combo_box` to be the item at `index`.

`combo_box` : | A GtkComboBox.
`index_` : | An index in the model passed during construction, or -1 to have no active item.

Since 2.4

### gtk_combo_box_get_active_iter ()

    gboolean    gtk_combo_box_get_active_iter   (GtkComboBox *combo_box,
                                                 GtkTreeIter *iter);

Sets `iter` to point to the current active item, if it exists.

`combo_box` : | A GtkComboBox
`iter` : | The uninitialized GtkTreeIter.
Returns : | `TRUE`, if `iter` was set

Since 2.4

### gtk_combo_box_set_active_iter ()

    void        gtk_combo_box_set_active_iter   (GtkComboBox *combo_box,
                                                 GtkTreeIter *iter);

Sets the current active item to be the one referenced by `iter`. `iter` must correspond to a path of depth one.

`combo_box` : | A GtkComboBox
`iter` : | The GtkTreeIter.

Since 2.4

### gtk_combo_box_get_model ()

    GtkTreeModel* gtk_combo_box_get_model       (GtkComboBox *combo_box);

Returns the GtkTreeModel which is acting as data source for `combo_box`.

`combo_box` : | A GtkComboBox.
Returns : | A GtkTreeModel which was passed during construction.

Since 2.4

### gtk_combo_box_set_model ()

    void        gtk_combo_box_set_model         (GtkComboBox *combo_box,
                                                 GtkTreeModel *model);

Sets the model used by `combo_box` to be `model`. Will unset a previously set model (if applicable). If `model` is `NULL`, then it will unset the model.

Note that this function does not clear the cell renderers, you have to call `gtk_combo_box_cell_layout_clear()` yourself if you need to set up different cell renderers for the new model.

`combo_box` : | A GtkComboBox.
`model` : | A GtkTreeModel.

Since 2.4

### gtk_combo_box_new_text ()

    GtkWidget*  gtk_combo_box_new_text          (void);

Convenience function which constructs a new text combo box, which is a GtkComboBox just displaying strings. If you use this function to create a text combo box, you should only manipulate its data source with the following convenience functions: `gtk_combo_box_append_text()`, `gtk_combo_box_insert_text()`, `gtk_combo_box_prepend_text()` and `gtk_combo_box_remove_text()`.

Returns : | A new text combo box.

Since 2.4

### gtk_combo_box_append_text ()

    void        gtk_combo_box_append_text       (GtkComboBox *combo_box,
                                                 const gchar *text);

Appends `string` to the list of strings stored in `combo_box`. Note that you can only use this function with combo boxes constructed with `gtk_combo_box_new_text()`.

`combo_box` : | A GtkComboBox constructed using `gtk_combo_box_new_text()`.
`text` : | A string.

Since 2.4

### gtk_combo_box_insert_text ()

    void        gtk_combo_box_insert_text       (GtkComboBox *combo_box,
                                                 gint position,
                                                 const gchar *text);

Inserts `string` at `position` in the list of strings stored in `combo_box`. Note that you can only use this function with combo boxes constructed with `gtk_combo_box_new_text()`.

`combo_box` : | A GtkComboBox constructed using `gtk_combo_box_new_text()`.
`position` : | An index to insert `text`.
`text` : | A string.

Since 2.4

### gtk_combo_box_prepend_text ()

    void        gtk_combo_box_prepend_text      (GtkComboBox *combo_box,
                                                 const gchar *text);

Prepends `string` to the list of strings stored in `combo_box`. Note that you can only use this function with combo boxes constructed with `gtk_combo_box_new_text()`.

`combo_box` : | A GtkComboBox constructed with `gtk_combo_box_new_text()`.
`text` : | A string.

Since 2.4

### gtk_combo_box_remove_text ()

    void        gtk_combo_box_remove_text       (GtkComboBox *combo_box,
                                                 gint position);

Removes the string at `position` from `combo_box`. Note that you can only use this function with combo boxes constructed with `gtk_combo_box_new_text()`.

`combo_box` : | A GtkComboBox constructed with `gtk_combo_box_new_text()`.
`position` : | Index of the item to remove.

Since 2.4

### gtk_combo_box_popup ()

    void        gtk_combo_box_popup             (GtkComboBox *combo_box);

Pops up the menu or dropdown list of `combo_box`.

This function is mostly intended for use by accessibility technologies; applications should have little use for it.

`combo_box` : | a GtkComboBox

Since 2.4

### gtk_combo_box_popdown ()

    void        gtk_combo_box_popdown           (GtkComboBox *combo_box);

Hides the menu or dropdown list of `combo_box`.

This function is mostly intended for use by accessibility technologies; applications should have little use for it.

`combo_box` : | a GtkComboBox

Since 2.4

## Properties

### The "`active`" property

      "active"               gint                  : Read / Write

The item which is currently active.

Allowed values: >= -1

Default value: -1

### The "`column-span-column`" property

      "column-span-column"   gint                  : Read / Write

TreeModel column containing the column span values.

Allowed values: >= 0

Default value: 0

### The "`model`" property

      "model"                GtkTreeModel          : Read / Write

The model for the combo box.

### The "`row-span-column`" property

      "row-span-column"      gint                  : Read / Write

TreeModel column containing the row span values.

Allowed values: >= 0

Default value: 0

### The "`wrap-width`" property

      "wrap-width"           gint                  : Read / Write

Wrap width for layouting the items in a grid.

Allowed values: >= 0

Default value: 0

## Style Properties

### The "`appears-as-list`" style property

      "appears-as-list"      gboolean              : Read

Whether combobox dropdowns should look like lists rather than menus.

Default value: FALSE

## Signals

### The "changed" signal

    void        user_function                  (GtkComboBox *combobox,
                                                gpointer user_data);

`combobox` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.