Gtk.ComboBox

Gtk.ComboBox — A widget used to choose from a list of items

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.Container
                ╰── Gtk.Bin
                    ╰── Gtk.ComboBox
                        ├── Gtk.AppChooserButton
                        ╰── Gtk.ComboBoxText

See also:

Gtk.ComboBoxText, Gtk.TreeModel, Gtk.CellRenderer

Functions:

Signals:

  • “changed” (widget, user_data)
  • “format-entry-text” (combo, path, user_data)
  • “move-active” (widget, scroll_type, user_data)
  • “popdown” (button, user_data)

Description:

A Gtk.ComboBox is a widget that allows the user to choose from a list of valid choices. The Gtk.ComboBox displays the selected choice. When activated, the Gtk.ComboBox displays a popup which allows the user to make a new choice. The style in which the selected value is displayed, and the style of the popup is determined by the current theme. It may be similar to a Windows-style combo box.

The Gtk.ComboBox uses the model-view pattern; the list of valid choices is specified in the form of a tree model, and the display of the choices can be adapted to the data in the model by using cell renderers, as you would in a tree view. This is possible since Gtk.ComboBox implements the Gtk.CellLayout interface. The tree model holding the valid choices is not restricted to a flat list, it can be a real tree, and the popup will reflect the tree structure.

To allow the user to enter values not in the model, the has-entry property allows the Gtk.ComboBox to contain a GtkEntry. This entry can be accessed by calling Gtk.Bin::get_child() on the combo box.

For a simple list of textual choices, the model-view API of Gtk.ComboBox can be a bit overwhelming. In this case, Gtk.ComboBoxText offers a simple alternative. Both GtkComboBox and Gtk.ComboBoxText can contain an entry.

Function Details:

new()

new () -> Gtk.Widget

Creates a new empty Gtk.ComboBox.

  • Returns: A new Gtk.ComboBox.

  • Since: 2.4

new_with_entry()

new_with_entry () -> Gtk.Widget

Creates a new empty Gtk.ComboBox with an entry.

  • Returns: A new Gtk.ComboBox.

  • Since: 2.24

new_with_model()

new_with_model (model:Gtk.TreeModel) -> Gtk.Widget

Creates a new Gtk.ComboBox with the model initialized to model.

  • Returns: A new Gtk.ComboBox.

  • Since: 2.4

new_with_model_and_entry()

new_with_model_and_entry (model:Gtk.TreeModel) -> Gtk.Widget

Creates a new empty Gtk.ComboBox with an entryand with the model initialized to model.

  • Returns: A new Gtk.ComboBox

  • Since: 2.24

new_with_area()

new_with_area (area:Gtk.CellArea) -> Gtk.Widget

Creates a new empty Gtk.ComboBox using area to layout cells.

  • Returns: A new Gtk.ComboBox.

new_with_area_and_entry()

new_with_area_and_entry (area:Gtk.CellArea) -> Gtk.Widget

Creates a new empty Gtk.ComboBox with an entry. The new combo box will use area to layout cells.

  • Returns: A new Gtk.ComboBox.

get_wrap_width()

get_wrap_width (self) -> int

Returns the wrap width which is used to determine the number of columnsfor the popup menu. If the wrap width is larger than 1, the combo boxis in table mode.

  • Returns: the wrap width.

  • Since: 2.6

set_wrap_width()

set_wrap_width (self, width:int)

Sets the wrap width of combo_box to be width. The wrap width is basicallythe preferred number of columns when you want the popup to be layed outin a table.

  • Since: 2.4

get_row_span_column()

get_row_span_column (self) -> int

Returns the column with row span information for combo_box.

  • Returns: the row span column.

  • Since: 2.6

set_row_span_column()

set_row_span_column (self, row_span:int)

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

  • Since: 2.4

get_column_span_column()

get_column_span_column (self) -> int

Returns the column with column span information for combo_box.

  • Returns: the column span column.

  • Since: 2.6

set_column_span_column()

set_column_span_column (self, column_span:int)

Sets the column with column span information for combo_box to becolumn_span. The column span column contains integers which indicatehow many columns an item should span.

  • Since: 2.4

get_active()

get_active (self) -> int

Returns the index of the currently active item, or -1 if there’s noactive item. If the model is a non-flat treemodel, and the active itemis not an immediate child of the root of the tree, this function returns`Gtk.TreePath:get_indices (path)[0], wherepathis theGtk.TreePath` of the active item.

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

  • Since: 2.4

set_active()

set_active (self, index_:int)

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

  • Since: 2.4

set_active_iter()

set_active_iter (self, iter:Gtk.TreeIter=None)

Sets the current active item to be the one referenced by iter, orunsets the active item if iter is None.

  • Since: 2.4

get_id_column()

get_id_column (self) -> int

Returns the column which combo_box is using to get string IDsfor values from.

  • Returns: A column in the data source model of combo_box.

  • Since: 3.0

set_id_column()

set_id_column (self, id_column:int)

Sets the model column which combo_box should use to get string IDsfor values from. The column id_column in the model of combo_boxmust be of type G_TYPE_STRING.

  • Since: 3.0

get_active_id()

get_active_id (self) -> str or None

Returns the ID of the active row of combo_box. This value is takenfrom the active row and the column specified by the “id-column”property of combo_box (see Gtk.ComboBox:set_id_column()). The returned value is an interned string which means that you cancompare the pointer by value to other interned strings and that youmust not free it. If the “id-column” property of combo_box is not set, or ifno row is active, or if the active row has a None ID value, then Noneis returned.

  • Returns: the ID of the active row, or None.

  • Since: 3.0

set_active_id()

set_active_id (self, active_id:str=None) -> bool

Changes the active row of combo_box to the one that has an ID equal toactive_id, or unsets the active row if active_id is None. Rows havinga None ID string cannot be made active by this function. If the “id-column” property of combo_box is unset or if norow has the given ID then the function does nothing and returns FALSE.

  • Returns: True if a row with a matching ID was found. If a None``active_idwas given to unset the active row, the functionalways returns True.

  • Since: 3.0

get_model()

get_model (self) -> Gtk.TreeModel

Returns the Gtk.TreeModel which is acting as data source for combo_box.

  • Returns: A Gtk.TreeModel which was passedduring construction.

  • Since: 2.4

set_model()

set_model (self, model:Gtk.TreeModel=None)

Sets the model used by combo_box to be model. Will unset a previously setmodel (if applicable). If model is None, then it will unset the model. Note that this function does not clear the cell renderers, you have tocall `Gtk.CellLayout:clear()` yourself if you need to set up differentcell renderers for the new model.

  • Since: 2.4

popup_for_device()

popup_for_device (self, device:Gdk.Device)

Pops up the menu or dropdown list of combo_box, the popup windowwill be grabbed so only device and its associated pointer/keyboardare the only GdkDevices able to send events to it.

  • Since: 3.0
popup (self)

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.

  • Since: 2.4

popdown()

popdown (self)

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.

  • Since: 2.4

get_popup_accessible()

get_popup_accessible (self) -> Atk.Object

Gets the accessible object corresponding to the combo box’s popup. This function is mostly intended for use by accessibility technologies;applications should have little use for it.

  • Returns: the accessible object correspondingto the combo box’s popup.

  • Since: 2.6

set_row_separator_func()

set_row_separator_func (self, func:Gtk.TreeViewRowSeparatorFunc, data=None)

Sets the row separator function, which is used to determinewhether a row should be drawn as a separator. If the row separatorfunction is None, no separators are drawn. This is the default value.

  • Since: 2.6

set_add_tearoffs()

set_add_tearoffs (self, add_tearoffs:bool)

Gtk.ComboBox:set_add_tearoffs has been deprecated since version 3.10 and should not be used in newly-written code. Sets whether the popup menu should have a tearoffmenu item.

  • Since: 2.6

get_add_tearoffs()

get_add_tearoffs (self) -> bool

Gtk.ComboBox:get_add_tearoffs has been deprecated since version 3.10 and should not be used in newly-written code. Gets the current value of the :add-tearoffs property.

  • Returns: the current value of the :add-tearoffs property.

set_title()

set_title (self, title:str)

Gtk.ComboBox:set_title has been deprecated since version 3.10 and should not be used in newly-written code. Sets the menu’s title in tearoff mode.

  • Since: 2.10

get_title()

get_title (self) -> str

Gtk.ComboBox:get_title has been deprecated since version 3.10 and should not be used in newly-written code. Gets the current title of the menu in tearoff mode. SeeGtk.ComboBox:set_add_tearoffs().

  • Returns: the menu’s title in tearoff mode. This is an internal copy of thestring which must not be freed.

  • Since: 2.10

set_focus_on_click()

set_focus_on_click (self, focus_on_click:bool)

Sets whether the combo box will grab focus when it is clicked withthe mouse. Making mouse clicks not grab focus is useful in placeslike toolbars where you don’t want the keyboard focus removed fromthe main area of the application.

  • Since: 2.6

get_focus_on_click()

get_focus_on_click (self) -> bool

Returns whether the combo box grabs focus when it is clickedwith the mouse. See Gtk.ComboBox:set_focus_on_click().

  • Returns: True if the combo box grabs focus when it isclicked with the mouse.

  • Since: 2.6

set_button_sensitivity()

set_button_sensitivity (self, sensitivity:Gtk.SensitivityType)

Sets whether the dropdown button of the combo box should bealways sensitive (GTK_SENSITIVITY_ON), never sensitive (GTK_SENSITIVITY_OFF)or only if there is at least one item to display (GTK_SENSITIVITY_AUTO).

  • Since: 2.14

get_button_sensitivity()

get_button_sensitivity (self) -> Gtk.SensitivityType

Returns whether the combo box sets the dropdown buttonsensitive or not when there are no items in the model.

  • Returns: GTK_SENSITIVITY_ON if the dropdown buttonis sensitive when the model is empty, GTK_SENSITIVITY_OFFif the button is always insensitive orGTK_SENSITIVITY_AUTO if it is only sensitive as long asthe model has one item to be selected.

  • Since: 2.14

get_has_entry()

get_has_entry (self) -> bool

Returns whether the combo box has an entry.

  • Returns: whether there is an entry in combo_box.

  • Since: 2.24

set_entry_text_column()

set_entry_text_column (self, text_column:int)

Sets the model column which combo_box should use to get strings fromto be text_column. The column text_column in the model of combo_boxmust be of type G_TYPE_STRING. This is only relevant if combo_box has been created with“has-entry” as True.

  • Since: 2.24

get_entry_text_column()

get_entry_text_column (self) -> int

Returns the column which combo_box is using to get the stringsfrom to display in the internal entry.

  • Returns: A column in the data source model of combo_box.

  • Since: 2.24

set_popup_fixed_width()

set_popup_fixed_width (self, fixed:bool)

Specifies whether the popup’s width should be a fixed widthmatching the allocated width of the combo box.

  • Since: 3.0

get_popup_fixed_width()

get_popup_fixed_width (self) -> bool

Gets whether the popup uses a fixed width matchingthe allocated width of the combo box.

  • Returns: True if the popup uses a fixed width

  • Since: 3.0

Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk

class ComboBox(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self)
        self.set_title("ComboBox")
        self.set_default_size(150, -1)
        self.connect("destroy", Gtk.main_quit)

        liststore = Gtk.ListStore(str)

        for item in ["Debian", "Fedora", "Tiny Core", "Linux Mint", "Mageia"]:
            liststore.append([item])

        combobox = Gtk.ComboBox()
        combobox.set_model(liststore)
        combobox.set_active(0)
        combobox.connect("changed", self.on_combobox_changed)
        self.add(combobox)

        cellrenderertext = Gtk.CellRendererText()
        combobox.pack_start(cellrenderertext, True)
        combobox.add_attribute(cellrenderertext, "text", 0)

    def on_combobox_changed(self, combobox):
        treeiter = combobox.get_active_iter()
        model = combobox.get_model()

        print("ComboBox selected item: %s" % (model[treeiter][0]))

window = ComboBox()
window.show_all()

Gtk.main()

results matching ""

    No results matching ""