Name

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 set_wrap_width(width)
def set_row_span_column(row_span)
def set_column_span_column(column_span)
def get_active()
def set_active(index)
def get_active_iter()
def set_active_iter(iter)
def set_model(model)
def get_model()
def append_text(text)
def insert_text(position, text)
def prepend_text(text)
def remove_text(position)
def popup()
def popdown()
Functions

    def gtk.combo_box_new_text()

Ancestry

+-- gobject.GObject
  +-- gtk.Object
    +-- gtk.Widget
      +-- gtk.Container
        +-- gtk.Bin
          +-- gtk.ComboBox (implements gtk.CellLayout)

Properties

"active"Read-WriteThe index of the item that is currently active.
"column-span-column"Read-WriteThe TreeModel column containing the column span values.
"model"Read-WriteThe TreeModel for the combo box.
"row-span-column"Read-WriteThe TreeModel column containing the row span values.
"wrap-width"Read-WriteThe number of columns to use to lay out the popup items.

Style Properties

"appears-as-list"Read-WriteIf TRUE, the combo box dropdowns should look like lists rather than menus.

Signal Prototypes

"changed" 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, gtk.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.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.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.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_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.

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

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.

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.

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.

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.

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.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.

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.

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" 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.