gtk.Combo
Prev | The gtk Class Reference | Next

## gtk.Combo

gtk.Combo — a text entry field with a dropdown list.

## Synopsis

    class gtk.Combo(gtk.HBox):
        gtk.Combo()
        def set_value_in_list(val, ok_if_empty)
        def set_use_arrows(val)
        def set_use_arrows_always(val)
        def set_case_sensitive(val)
        def set_item_string(item, item_value)
        def set_popdown_strings(strings)
        def disable_activate()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.Box
              +-- gtk.HBox
                +-- gtk.Combo

## gtk.Combo Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

gtk.Box Properties

"allow-empty" | Read/Write | If `True`, an empty value may be entered in this field
"case-sensitive" | Read/Write | If `True`, list item matching is case sensitive
"enable-arrow-keys" | Read/Write | If `True`, the arrow keys move through the list of items
"enable-arrows-always" | Read/Write | If `True`, the arrow keys work, even if the entry contents are not in the list
"value-in-list" | Read/Write | If `True`, entered values must already be present in the list

## gtk.Combo Style Properties

gtk.Widget Style Properties

## gtk.Combo Child Properties

gtk.Box Child Properties

## Attributes

"entry" | Read | the text entry widget
"list" | Read | the list shown in the drop-down window

## gtk.Combo Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

## Description

### Note

The `gtk.Combo` is deprecated in GTK+ 2.4 and PyGTK 2.4 in favor of the `gtk.ComboBox`.

The `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 `gtk.List` widget and can be accessed using the list attribute of the `gtk.Combo`. 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`() method. 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 behavior can be turned off with the `set_use_arrows`() method. 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 `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.

Note the list attribute references a gtk.List which is a deprecated widget so the combo widget may be changed or deprecated in the future.

## Constructor

        gtk.Combo()

Returns : | a combo object*

Creates an new `gtk.Combo` object.

## Methods

### gtk.Combo.set_value_in_list

        def set_value_in_list(val, ok_if_empty)

`val` : | If True the value entered must match one of the values in the list.
`ok_if_empty` : | If True an empty value is considered valid.

The `set_value_in_list`() method specifies whether the value entered in the text entry field must match one of the values in the list. This method sets the "value-in-list" property to the value of `val` and the "allow-empty" property to the value of `ok_if_empty`.

If `val` is True the user will not be able to perform any other action (the widget grabs the focus) until a valid value has been entered. If `ok_if_empty` is True an empty field is considered an acceptable value.

### gtk.Combo.set_use_arrows

        def set_use_arrows(val)

`val` : | If True can be used to navigate through the list items

The `set_use_arrows`() method sets the "enable-use-arrows" property to the value of `val`. If `val` is True the arrows keys can be used to navigate through the list items.

### gtk.Combo.set_use_arrows_always

        def set_use_arrows_always(val)

`val` : | If True the arrow keys will still work even if the text entry field does not match any of the list items.

The `set_use_arrows_always`() method sets the "enable-arrows-always" property to the values of `val`. If `val` is True the arrow keys will work even if the text entry field does not match any of the list items.

### gtk.Combo.set_case_sensitive

        def set_case_sensitive(val)

`val` : | If True the text in the list items is case sensitive.

The `set_case_sensitive`() method sets the "case-sensitive" property to the value of `val`. If `val` is True the text in the combo list items and the text entry field are case sensitive. The default value of "set-case-sensitive" is False.

### gtk.Combo.set_item_string

        def set_item_string(item, item_value)

`item` : | a list item
`item_value` : | a string to place in the entry field when `item` is selected

The `set_item_string`() method sets the string (from `item_value`) to place in the combo text entry field when the `item` is selected. This method is only needed if the list item is other than a simple label (e.g. a pixmap).

### gtk.Combo.set_popdown_strings

        def set_popdown_strings(strings)

`strings` : | a list of strings to populate the list

The `set_popdown_strings`() method is a convenience method that sets the strings used in the popdown list from. `strings` (a Python list or tuple object).

### gtk.Combo.disable_activate

        def disable_activate()

The `disable_activate`() method prevents the combo from showing the popup list when the entry 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.

Prev | Up | Next
gtk.ColorSelectionDialog | Home | gtk.ComboBox