gtk.ComboBox
Prev | The gtk Class Reference | Next

## gtk.ComboBox

gtk.ComboBox — a widget used to choose from a list of items (new in PyGTK 2.4)

## Synopsis

    class gtk.ComboBox(gtk.Bin, gtk.CellLayout):
        gtk.ComboBox(model=None)
        def get_has_entry()
        def get_entry_text_column()
        def set_entry_text_column(text_column)
        def get_wrap_width()
        def set_wrap_width(width)
        def get_row_span_column()
        def set_row_span_column(row_span)
        def get_column_span_column()
        def set_column_span_column(column_span)
        def get_button_sensitivity()
        def set_button_sensitivity(sensitivity)
        def get_active()
        def set_active(index)
        def get_active_iter()
        def set_active_iter(iter)
        def set_model(model=None)
        def get_model()
        def append_text(text)
        def insert_text(position, text)
        def prepend_text(text)
        def remove_text(position)
        def get_active_text()
        def popup()
        def popdown()
        def get_popup_accessible()
        def set_row_separator_func(func=None, data=None)
        def get_add_tearoffs()
        def set_add_tearoffs(add_tearoffs)
        def get_focus_on_click()
        def set_focus_on_click(focus_on_click)
        def get_title()
        def set_title(title)

    Functions

        def gtk.combo_box_new_text()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Bin
              +-- gtk.ComboBox

## Implemented Interfaces

`gtk.ComboBox` implements `gtk.Buildable` `atk.ImplementorIFace` `gtk.CellEditable` `gtk.CellLayout`

## gtk.ComboBox Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

"active" | Read-Write | The index of the item that is currently active.. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this property has the value of the first index of the path of the item. This property is available in GTK+ 2.4 and above.
"add-tearoffs" | Read-Write | If `True` generated menus have tearoff menu items. Note that this only affects menu style combo boxes. Default value: `False`. Available in GTK+ 2.6 and above.
"button-sensitivity" | Read-Write | Whether the dropdown button is sensitive when the model is empty. Default value: gtk.SENSITIVITY_AUTO. Available in GTK+ 2.14 and above.
"column-span-column" | Read-Write | The TreeModel column containing the column span values. This property is available in GTK+ 2.4 and above
"entry-text-column" | Read-Write | The column in the combo box's model to associate with strings from the entry if the combo was created with "has-entry" = `True`. This property is available in GTK+ 2.24 and above
"focus-on-click" | Read-Write | If `True` the combo box grabs focus when it is clicked with the mouse. Default value: `True`
"has-entry" | Read-Write-Construct Only | Whether the combo box has an entry. Default value: `False`. This property is available in GTK+ 2.24 and above
"has-frame" | Read-Write | If `True` the combo box grabs focus when it is clicked with the mouse. Default value: `True`. Available in GTK+ 2.6 and above.
"model" | Read-Write | The TreeModel for the combo box. This property is available in GTK+ 2.4 and above.
"popup-shown" | Read-Write | If `True` the dropdown menu of the combobox is popped up. Note that this property is mainly useful, because it allows you to connect to the "notify::popup-shown" signal. Available in GTK+ 2.10 and above.
"row-span-column" | Read-Write | The TreeModel column containing the row span values. This property is available in GTK+ 2.4 and above.
"tearoff-title" | Read-Write | A title that may be displayed by the window manager when the popup is torn-off. Default value: "". Available in GTK+ 2.10 and above
"wrap-width" | Read-Write | The number of columns to use to lay out the popup items. This property is available in GTK+ 2.4 and above.

## gtk.ComboBox Style Properties

gtk.Widget Style Properties

"appears-as-list" | Read-Write | If `True`, the combo box dropdowns should look like lists rather than menus.
"arrow-size" | Read-Write | Sets the minimum size of the arrow in the combo box. Note that the arrow size is coupled to the font size, so in case a larger font is used, the arrow will be larger than set by arrow size. Allowed values: >= 0. Default value: 15. Available in GTK+ 2.12 and above.
"shadow-type" | Read-Write | Which kind of shadow to draw around the combo box. Default value: gtk.SHADOW_NONE. This property is available in GTK+ 2.12 and above.

## gtk.ComboBox Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

gtk.CellEditable Signal Prototypes

"changed" | `def callback(`combobox`, `user_param1`, `...`)`
"move-active" | `def callback(`combobox`, `scroll_type`, `user_param1`, `...`)`
"popdown" | `def callback(`combobox`, `user_param1`, `...`)`
"popup" | `def callback(`combobox`, `user_param1`, `...`)`

## Description

### Note

This widget is available in GTK+ 2.4 and PyGTK 2.4 and above.

The `gtk.ComboBox` is a replacement for the `gtk.OptionMenu`. The `gtk.ComboBox` implements the `gtk.CellLayout` interface that provides a number of useful methods for managing the contents. A `gtk.ComboBox` is created with the gtk.ComboBox() constructor that is associated with the optional `gtk.TreeModel`. If no `gtk.TreeModel` is specified it can be added later with the `set_model`() method.

Alternatively, the `gtk.combo_box_new_text`() function creates a simple `gtk.ComboBox` and associated `gtk.ListStore` model. A `gtk.CellRendererText` is also created and packed in the new combo box. In this simple combo box each list item is a text string that can be selected. The convenience methods `append_text`(), `prepend_text`(), `insert_text`() and `remove_text`() can be used to manage the contents of the `gtk.ComboBox`. Using the `gtk.combo_box_new_text`() function is equivalent to:

      liststore = gtk.ListStore(gobject.TYPE_STRING)
      combobox = gtk.ComboBox(liststore)
      cell = gtk.CellRendererText()
      combobox.pack_start(cell, True)
      combobox.add_attribute(cell, 'text', 0)

## Constructor

        gtk.ComboBox(model=None)

`model` : | A valid `gtk.TreeModel`.
Returns : | A new `gtk.ComboBox`.

### Note

This constructor is available in PyGTK 2.4 and above.

Creates a new `gtk.ComboBox` associated with the optional `gtk.TreeModel` specified by `model`. If `model` is not specified the combo box will not have an associated tree model.

## Methods

### gtk.ComboBox.get_has_entry

        def get_has_entry()

Returns : | Whether there is an entry in the combo box.

### Note

This method is available in PyGTK 2.24 and above.

The `get_has_entry`() method returns whether the combo box has an entry.

### gtk.ComboBox.get_entry_text_column

        def get_entry_text_column()

Returns : | A column in the data source model of the combo box.

### Note

This method is available in PyGTK 2.24 and above.

The `get_entry_text_column`() method returns the columns which the combo box is using to get the strings from to display in the internal entry.

### gtk.ComboBox.set_entry_text_column

        def set_entry_text_column(text_column)

`text_column` : | A column in the data source model to get the strings from for the internal entry.

### Note

This method is available in PyGTK 2.24 and above.

The `set_entry_text_column`() method sets the model column which the combo box should use to get strings from to be text_column. The column text_column in the model of combo box must be of type G_TYPE_STRING.

### gtk.ComboBox.get_wrap_width

        def get_wrap_width()

Returns : | The wrap width.

### Note

This method is available in PyGTK 2.6 and above.

The `get_wrap_width`() method returns the value of the "wrap-width" property of the combo box as set by the `set_wrap_width`() method. The wrap width is basically the preferred number of columns to use to lay out the popup i.e. lays out the popup items in a table with `width` columns.

### gtk.ComboBox.set_wrap_width

        def set_wrap_width(width)

`width` : | The preferred number of columns of width.

### Note

This method is available in PyGTK 2.4 and above.

The `set_wrap_width`() method sets the wrap width (and the "wrap-width" property) of the combo box to the value specified by `width`. The wrap width is basically the preferred number of columns to use to lay out the popup i.e. lays out the popup items in a table with `width` columns.

### gtk.ComboBox.get_row_span_column

        def get_row_span_column()

Returns : | The row span column.

### Note

This method is available in PyGTK 2.6 and above.

The `get_row_span_column`() method returns the value of the "row-span-column" property. The "row-span-column" property indicates the column in the associated `gtk.TreeModel` row that contains an integer that indicates how many rows the item should span.

### gtk.ComboBox.set_row_span_column

        def set_row_span_column(row_span)

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

### Note

This method is available in PyGTK 2.4 and above.

The `set_row_span_column`() method sets the "row-span-column" property to the value specified by `row_span`. The "row-span-column" property indicates the column in the associated `gtk.TreeModel` row that contains an integer that indicates how many rows the item should span.

### gtk.ComboBox.get_column_span_column

        def get_column_span_column()

Returns : | The column span column.

### Note

This method is available in PyGTK 2.6 and above.

The `get_column_span_column`() method returns the value of the "column-span-column" property. The "column-span-column" property indicates the column in the associated `gtk.TreeModel` row that contains an integer that indicates how many columns the item should span.

### gtk.ComboBox.set_column_span_column

        def set_column_span_column(column_span)

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

### Note

This method is available in PyGTK 2.4 and above.

The `set_column_span_column`() method sets the "column-span-column" property to the value specified by `column_span`. The "column-span-column" property indicates the column in the associated `gtk.TreeModel` row that contains an integer that indicates how many columns the item should span.

### gtk.ComboBox.get_button_sensitivity

        def get_button_sensitivity()

Returns : | gtk.SENSITIVITY_ON if the dropdown button is sensitive when the model is empty, gtk.SENSITIVITY_OFF if the button is always insensitive or gtk.SENSITIVITY_AUTO if it is only sensitive as long as the model has one item to be selected.

### Note

This method is available in PyGTK 2.14 and above.

The `get_button_sensitivity`() method returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model.

### gtk.ComboBox.set_button_sensitivity

        def set_button_sensitivity(sensitivity)

`sensitivity` : | specify the sensitivity of the dropdown button.

### Note

This method is available in PyGTK 2.14 and above.

The `set_button_sensitivity`() method sets whether the dropdown button of the combo box should be always sensitive (gtk.SENSITIVITY_ON), never sensitive (gtk.SENSITIVITY_OFF) or only if there is at least one item to display (gtk.SENSITIVITY_AUTO).

### gtk.ComboBox.get_active

        def get_active()

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

### Note

This method is available in PyGTK 2.4 and above.

The `get_active`() method returns the value of the "active" property which is the index in the model of the currently active item, or -1 if there's no active item. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this method returns the first path index of the active item. For example if the path of the active item is (1, 0, 2) this method will return 1.

### gtk.ComboBox.set_active

        def set_active(index)

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

### Note

This method is available in PyGTK 2.4 and above.

The `set_active`() method sets the active item of the combo_box to the item with the model index specified by `index`. If `index` is -1 the combo box will have no active item. The "active" property is also set to the value of `index`.

### gtk.ComboBox.get_active_iter

        def get_active_iter()

Returns : | A `gtk.TreeIter` that points at the active item or `None` if there is no active item.

### Note

This method is available in PyGTK 2.4 and above.

The `get_active_iter`() method returns a `gtk.TreeIter` that points to the current active item or `None` if there is no active item.

### gtk.ComboBox.set_active_iter

        def set_active_iter(iter)

`iter` : | A valid `gtk.TreeIter` pointing at an item in the associated `gtk.TreeModel`.

### Note

This method is available in PyGTK 2.4 and above.

The `set_active_iter`() method sets the current active item to be the one referenced by `iter` in the associated `gtk.TreeModel`. `iter` must correspond to a path of depth one. The "active" property is also set by this method.

### gtk.ComboBox.set_model

        def set_model(model=None)

`model` : | A `gtk.TreeModel`.

### Note

This method is available in PyGTK 2.4 and above.

The `set_model`() method sets the model used by the combo box to the value specified by `model`. The "model" property will also be set to the value of `model`. A previously set model will be unset. If `model` is `None` or not specified, the old model will be unset.

### Note

In PyGTK 2.4.0 the model could not be `None` and did not default to `None`.

### gtk.ComboBox.get_model

        def get_model()

Returns : | A `gtk.TreeModel` or `None`.

### Note

This method is available in PyGTK 2.4 and above.

The `get_model`() method returns the value of the "model" property which contains the `gtk.TreeModel` that is acting as data source for the combo_box or `None` if no `gtk.TreeModel` is associated with the combo box.

### gtk.ComboBox.append_text

        def append_text(text)

`text` : | A string.

### Note

This method is available in PyGTK 2.4 and above.

### Warning

This method is deprecated since PyGTK 2.24 and should not be used in newly-written code. Use `gtk.ComboBoxText` instead.

The `append_text`() method appends the string specified by `text` to the list of strings stored in the combo box `gtk.ListStore`. Note that you can only use this method with combo boxes constructed with the `gtk.combo_box_new_text`() function.

### gtk.ComboBox.insert_text

        def insert_text(position, text)

`position` : | A model index where the `text` should be inserted.
`text` : | A string.

### Note

This method is available in PyGTK 2.4 and above.

### Warning

This method is deprecated since PyGTK 2.24 and should not be used in newly-written code. Use `gtk.ComboBoxText` instead.

The `insert_text`() method inserts the string specified by `text` in the combo box `gtk.ListStore` at the index specified by `position`. Note that you can only use this method with combo boxes constructed with the `gtk.combo_box_new_text`() function.

### gtk.ComboBox.prepend_text

        def prepend_text(text)

`text` : | A string.

### Note

This method is available in PyGTK 2.4 and above.

### Warning

This method is deprecated since PyGTK 2.24 and should not be used in newly-written code. Use `gtk.ComboBoxText` instead.

The `prepend_text`() method prepends the string specified by `text` to the list of strings stored in the `gtk.ListStore` associated with the combo_box. Note that you can only use this method with combo boxes constructed with the `gtk.combo_box_new_text`() function.

### gtk.ComboBox.remove_text

        def remove_text(position)

`position` : | Index of the item to remove.

### Note

This method is available in PyGTK 2.4 and above.

### Warning

This method is deprecated since PyGTK 2.24 and should not be used in newly-written code. Use `gtk.ComboBoxText` instead.

The `remove_text`() method removes the string at the index specified by `position` in the associated `gtk.ListStore`. Note that you can only use this function with combo boxes constructed with the `gtk.combo_box_new_text`() function.

### gtk.ComboBox.get_active_text

        def get_active_text()

Returns : | The currently active text.

### Note

This method is available in PyGTK 2.6 and above.

### Warning

This method is deprecated since PyGTK 2.24 and should not be used in newly-written code. Use `gtk.ComboBoxText` instead.

The `get_active_text`() method returns the currently active string or `None` if no entry is selected. Note that you can only use this function with combo boxes constructed with the `gtk.combo_box_new_text`() function.

### gtk.ComboBox.popup

        def popup()

### Note

This method is available in PyGTK 2.4 and above.

The `popup`() method pops up the menu or dropdown list of the combo box. This method is mostly intended for use by accessibility technologies; applications should have little use for it.

### gtk.ComboBox.popdown

        def popdown()

### Note

This method is available in PyGTK 2.4 and above.

The `popdown`() method hides the menu or dropdown list of the combo box. This method is mostly intended for use by accessibility technologies; applications should have little use for it.

### gtk.ComboBox.get_popup_accessible

        def get_popup_accessible()

Returns : | the accessible object corresponding to the popup.

### Note

This method is available in PyGTK 2.6 and above.

The `get_popup_accessible`() method gets the accessible object corresponding to the popup. This method is mostly intended for use by accessibility technologies; applications should have little use for it.

### gtk.ComboBox.set_row_separator_func

        def set_row_separator_func(func=None, data=None)

`func` : | a function or `None`
`data` : | user data to pass to `func`

### Note

This method is available in PyGTK 2.6 and above.

The `set_row_separator_func`() method sets the row separator function to `func`, which is used to determine if a row should be drawn as a separator. If func is `None`, no separators are drawn. This is the default value.

The signature of `func` is:

      def func(model, iter, user_data):

where `model` is the `gtk.TreeModel` used by the combo box, `iter` is a `gtk.TreeIter` pointing at a row in `model` and `user_data` is `data`. `func` returns `True` if the row is a separator. A common way to implement `func` is to have a boolean column in `model`, that indicates if the row is a separator.

### gtk.ComboBox.get_add_tearoffs

        def get_add_tearoffs()

Returns : | `True` if menus should have a tearoff menuitem.

### Note

This method is available in PyGTK 2.6 and above.

The `get_add_tearoffs`() method returns the value of the "add-tearoffs" property.

### gtk.ComboBox.set_add_tearoffs

        def set_add_tearoffs(add_tearoffs)

`add_tearoffs` : | if `True` add tearoff menu items

### Note

This method is available in PyGTK 2.6 and above.

The `set_add_tearoffs`() method sets the "add-tearoffs" property to the value of `add_tearoffs`. If `add_tearoffs` is `True`, the popup menu should have a tearoff menu item.

### gtk.ComboBox.get_focus_on_click

        def get_focus_on_click()

Returns : | `True` if the combo box grabs focus when it is clicked with the mouse.

### Note

This method is available in PyGTK 2.6 and above.

The `get_focus_on_click`() method returns the value of the "focus-on-click" property.

### gtk.ComboBox.set_focus_on_click

        def set_focus_on_click(focus_on_click)

`focus_on_click` : | if `True` the combo box grabs focus when clicked with the mouse.

### Note

This method is available in PyGTK 2.6 and above.

The `set_focus_on_click`() method sets the value of the "focus-on-click" property to the value of `focus_on_click`. If `focus_on_click` is `True` the combo box grabs focus when clicked with the mouse.

### gtk.ComboBox.get_title

        def get_title()

Returns : | the menu's title in tearoff mode..

### Note

This method is available in PyGTK 2.10 and above.

The `get_title`() method returns the value of the "tearoff-title" property that contains the current title of the menu in tearoff mode. See the `set_add_tearoffs()` method for more information.

### gtk.ComboBox.set_title

        def set_title(title)

`title` : | a title for the menu in tearoff mode.

### Note

This method is available in PyGTK 2.10 and above.

The `set_title`() method sets the "tearoff-title" property to the value of `title`. The "tearoff-title" property contains the menu's title in tearoff mode.

## Functions

### gtk.combo_box_new_text

        def gtk.combo_box_new_text()

Returns : | A new `gtk.ComboBox` for text items.

### Note

This function is available in PyGTK 2.4 and above.

### Warning

This function is deprecated since PyGTK 2.24 and should not be used in newly-written code. Use `gtk.ComboBoxText` instead.

The `gtk.combo_box_new_text`() function is a convenience function that constructs a new text combo box, which is a `gtk.ComboBox` 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 methods: `append_text`(), `insert_text`(), `prepend_text`() and `remove_text`().

## Signals

### The "changed" gtk.ComboBox Signal

        def callback(combobox, user_param1, ...)

`combobox` : | the combo box that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in PyGTK 2.4 and above.

The "changed" signal is emitted when a new item in the combo box is selected.

### The "move-active" gtk.ComboBox Signal

        def callback(combobox, scroll_type, user_param1, ...)

`combobox` : | the combo box that received the signal
`scroll_type` : | a GTK Scroll Type Constants
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in PyGTK 2.12 and above.

The "move-active" signal is a keybinding signal which gets emitted to move the active selection.

### The "popdown" gtk.ComboBox Signal

        def callback(combobox, user_param1, ...)

`combobox` : | the combo box that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in PyGTK 2.12 and above.

The "popdown" signal is a keybinding signal which gets emitted to popdown the combo box list. The default bindings for this signal are Alt+Up and Escape.

### The "popup" gtk.ComboBox Signal

        def callback(combobox, user_param1, ...)

`combobox` : | the combo box that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in PyGTK 2.12 and above.

The "popup" signal is a keybinding signal which gets emitted to popup the combo box list. The default bindings for this signal are Alt+Down.

Prev | Up | Next
gtk.Combo | Home | gtk.ComboBoxEntry