The Combo widget is another fairly simple widget that is really just a collection of other widgets. From the user's point of view, the widget consists of a text entry box and a pull down menu from which the user can select one of a set of predefined entries. Alternatively, the user can type a different option directly into the text box.

The Combo has two principal parts that you really care about: an entry and a list. These are accessed using the attributes:

  combo.entry

  combo.list

First off, to create a Combo, use:

  combo = gtk.Combo()

Now, if you want to set the string in the entry section of the combo, this is done by manipulating the entry widget directly:

  combo.entry.set_text(text)

To set the values in the popdown list, one uses the method:

  combo.set_popdown_strings(strings)

Before you can do this, you have to assemble a list of the strings that you want.

Here's a typical code segment for creating a set of options:

  slist = [ "String 1", "String 2", "String 3", "String 4" ]

  combo.set_popdown_strings(slist)

At this point you have set up a working Combo. There are a few aspects of its behavior that you can change. These are accomplished with the methods:

  combo.set_use_arrows(val)

  combo.set_use_arrows_always(val)

  combo.set_case_sensitive(val)

The set_use_arrows() method lets the user change the value in the entry using the up/down arrow keys when val is set to TRUE. This doesn't bring up the list, but rather replaces the current text in the entry with the next list entry (up or down, as your key choice indicates). It does this by searching in the list for the item corresponding to the current value in the entry and selecting the previous/next item accordingly. Usually in an entry the arrow keys are used to change focus (you can do that anyway using Tab). Note that when the current item is the last of the list and you press arrow-down it changes the focus (the same applies with the first item and arrow-up).

If the current value in the entry is not in the list, then the set_use_arrows() method is disabled.

The set_use_arrows_always() method, when val is TRUE, similarly allows the use of the up/down arrow keys to cycle through the choices in the dropdown list, except that it wraps around the values in the list, completely disabling the use of the up and down arrow keys for changing focus.

The set_case_sensitive() method toggles whether or not GTK+ searches for entries in a case sensitive manner. This is used when the Combo widget is asked to find a value from the list using the current entry in the text box. This completion can be performed in either a case sensitive or insensitive manner, depending upon the setting of this method. The Combo widget can also simply complete the current entry if the user presses the key combination MOD-1-Tab. MOD-1 is often mapped to the Alt key, by the xmodmap utility. Note, however that some window managers also use this key combination, which will override its use within GTK.

Now that we have a combo, tailored to look and act how we want it, all that remains is being able to get data from the combo. This is relatively straightforward. The majority of the time, all you are going to care about getting data from is the entry. The entry is accessed simply as combo.entry. The two principal things that you are going to want to do with it are attach to the "activate" signal, which indicates that the user has pressed the Return or Enter key, and read the text. The first is accomplished using something like:

  combo.entry.connect("activate", my_callback, my_data)

Getting the text at any arbitrary time is accomplished by simply using the entry method:

  string = combo.entry.get_text()

That's about all there is to it. There is a method:

  combo.disable_activate()

that will disable the activate signal on the entry widget in the combo. Personally, I can't think of why you'd want to use it, but it does exist.