:right-sidebar: True ComboBox =================================================================== .. currentmodule:: gi.repository.Gtk .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` instead .. class:: ComboBox(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.Gtk.ComboBoxText` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.CellEditable`, :class:`~gi.repository.Gtk.CellLayout`, :class:`~gi.repository.Gtk.ConstraintTarget` A ``GtkComboBox`` is a widget that allows the user to choose from a list of valid choices. .. image:: https://docs.gtk.org/gtk4/combo-box.png The ``GtkComboBox`` displays the selected choice; when activated, the ``GtkComboBox`` displays a popup which allows the user to make a new choice. The ``GtkComboBox`` 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 ``GtkComboBox`` implements the :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.ComboBox.props.has_entry` property allows the ``GtkComboBox`` to contain a :obj:`~gi.repository.Gtk.Entry`. This entry can be accessed by calling :obj:`~gi.repository.Gtk.ComboBox.get_child` on the combo box. For a simple list of textual choices, the model-view API of ``GtkComboBox`` can be a bit overwhelming. In this case, :obj:`~gi.repository.Gtk.ComboBoxText` offers a simple alternative. Both ``GtkComboBox`` and ``GtkComboBoxText`` can contain an entry. CSS nodes --------- .. code-block:: :dedent: combobox ├── box.linked │ ╰── button.combo │ ╰── box │ ├── cellview │ ╰── arrow ╰── window.popup A normal combobox contains a box with the .linked class, a button with the .combo class and inside those buttons, there are a cellview and an arrow. .. code-block:: :dedent: combobox ├── box.linked │ ├── entry.combo │ ╰── button.combo │ ╰── box │ ╰── arrow ╰── window.popup A ``GtkComboBox`` with an entry has a single CSS node with name combobox. It contains a box with the .linked class. That box contains an entry and a button, both with the .combo class added. The button also contains another node with name arrow. Accessibility ------------- ``GtkComboBox`` uses the :const:`~gi.repository.Gtk.AccessibleRole.COMBO_BOX` role. Constructors ------------ .. rst-class:: interim-class .. class:: ComboBox :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new empty ``GtkComboBox``. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. classmethod:: new_with_entry() -> ~gi.repository.Gtk.Widget Creates a new empty ``GtkComboBox`` with an entry. In order to use a combo box with entry, you need to tell it which column of the model contains the text for the entry by calling :obj:`~gi.repository.Gtk.ComboBox.set_entry_text_column`. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. classmethod:: new_with_model(model: ~gi.repository.Gtk.TreeModel) -> ~gi.repository.Gtk.Widget Creates a new ``GtkComboBox`` with a model. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param model: a ``GtkTreeModel`` .. classmethod:: new_with_model_and_entry(model: ~gi.repository.Gtk.TreeModel) -> ~gi.repository.Gtk.Widget Creates a new empty ``GtkComboBox`` with an entry and a model. See also :obj:`~gi.repository.Gtk.ComboBox.new_with_entry`. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param model: A ``GtkTreeModel`` Methods ------- .. rst-class:: interim-class .. class:: ComboBox :no-index: .. method:: get_active() -> int Returns the index of the currently 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 function returns `gtk_tree_path_get_indices (path)[0]`, where ``path`` is the :obj:`~gi.repository.Gtk.TreePath` of the active item. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: get_active_id() -> str | None Returns the ID of the active row of ``combo_box``. This value is taken from the active row and the column specified by the :obj:`~gi.repository.Gtk.ComboBox.props.id_column` property of ``combo_box`` (see :obj:`~gi.repository.Gtk.ComboBox.set_id_column`). The returned value is an interned string which means that you can compare the pointer by value to other interned strings and that you must not free it. If the :obj:`~gi.repository.Gtk.ComboBox.props.id_column` property of ``combo_box`` is not set, or if no row is active, or if the active row has a :const:`None` ID value, then :const:`None` is returned. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: get_active_iter() -> tuple[bool, ~gi.repository.Gtk.TreeIter] Sets ``iter`` to point to the currently active item. If no item is active, ``iter`` is left unchanged. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: get_button_sensitivity() -> ~gi.repository.Gtk.SensitivityType Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: get_child() -> ~gi.repository.Gtk.Widget | None Gets the child widget of ``combo_box``. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: get_entry_text_column() -> int Returns the column which ``combo_box`` is using to get the strings from to display in the internal entry. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: get_has_entry() -> bool Returns whether the combo box has an entry. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: get_id_column() -> int Returns the column which ``combo_box`` is using to get string IDs for values from. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: get_model() -> ~gi.repository.Gtk.TreeModel | None Returns the ``GtkTreeModel`` of ``combo_box``. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: get_popup_fixed_width() -> bool Gets whether the popup uses a fixed width. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: popdown() -> None 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. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: popup() -> None 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. Before calling this, ``combo_box`` must be mapped, or nothing will happen. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` .. method:: popup_for_device(device: ~gi.repository.Gdk.Device) -> None Pops up the menu of ``combo_box``. Note that currently this does not do anything with the device, as it was previously only used for list-mode combo boxes, and those were removed in GTK 4. However, it is retained in case similar functionality is added back later. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param device: a ``GdkDevice`` .. method:: set_active(index_: int) -> None Sets the active item of ``combo_box`` to be the item at ``index``. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param index_: An index in the model passed during construction, or -1 to have no active item .. method:: set_active_id(active_id: str | None = None) -> bool Changes the active row of ``combo_box`` to the one that has an ID equal to ``active_id``. If ``active_id`` is :const:`None`, the active row is unset. Rows having a :const:`None` ID string cannot be made active by this function. If the :obj:`~gi.repository.Gtk.ComboBox.props.id_column` property of ``combo_box`` is unset or if no row has the given ID then the function does nothing and returns :const:`False`. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param active_id: the ID of the row to select .. method:: set_active_iter(iter: ~gi.repository.Gtk.TreeIter | None = None) -> None Sets the current active item to be the one referenced by ``iter``. If ``iter`` is :const:`None`, the active item is unset. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param iter: The ``GtkTreeIter`` .. method:: set_button_sensitivity(sensitivity: ~gi.repository.Gtk.SensitivityType) -> None Sets whether the dropdown button of the combo box should update its sensitivity depending on the model contents. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param sensitivity: specify the sensitivity of the dropdown button .. method:: set_child(child: ~gi.repository.Gtk.Widget | None = None) -> None Sets the child widget of ``combo_box``. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param child: the child widget .. method:: set_entry_text_column(text_column: int) -> None Sets the model column which ``combo_box`` should use to get strings from to be ``text_column``. For this column no separate :obj:`~gi.repository.Gtk.CellRenderer` is needed. The column ``text_column`` in the model of ``combo_box`` must be of type :obj:`str`. This is only relevant if ``combo_box`` has been created with :obj:`~gi.repository.Gtk.ComboBox.props.has_entry` as :const:`True`. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param text_column: A column in ``model`` to get the strings from for the internal entry .. method:: set_id_column(id_column: int) -> None Sets the model column which ``combo_box`` should use to get string IDs for values from. The column ``id_column`` in the model of ``combo_box`` must be of type :obj:`str`. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param id_column: A column in ``model`` to get string IDs for values from .. method:: set_model(model: ~gi.repository.Gtk.TreeModel | None = None) -> None Sets the model used by ``combo_box`` to be ``model``. Will unset a previously set model (if applicable). If model is :const:`None`, then it will unset the model. Note that this function does not clear the cell renderers, you have to call :obj:`~gi.repository.Gtk.CellLayout.clear` yourself if you need to set up different cell renderers for the new model. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param model: A ``GtkTreeModel`` .. method:: set_popup_fixed_width(fixed: bool) -> None Specifies whether the popup’s width should be a fixed width. If ``fixed`` is :const:`True`, the popup's width is set to match the allocated width of the combo box. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param fixed: whether to use a fixed popup width .. method:: set_row_separator_func(func: ~typing.Callable[[...], bool] | None = None, *data: ~typing.Any) -> None Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is :const:`None`, no separators are drawn. This is the default value. .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.DropDown` :param func: a ``GtkTreeViewRowSeparatorFunc`` :param data: user data to pass to ``func`` Properties ---------- .. rst-class:: interim-class .. class:: ComboBox :no-index: .. attribute:: props.active :type: int The item which 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 `gtk_tree_path_get_indices (path)[0]`, where ``path`` is the :obj:`~gi.repository.Gtk.TreePath` of the active item. .. attribute:: props.active_id :type: str The value of the ID column of the active row. .. attribute:: props.button_sensitivity :type: ~gi.repository.Gtk.SensitivityType Whether the dropdown button is sensitive when the model is empty. .. attribute:: props.child :type: ~gi.repository.Gtk.Widget The child widget. .. attribute:: props.entry_text_column :type: int The model column to associate with strings from the entry. This is property only relevant if the combo was created with :obj:`~gi.repository.Gtk.ComboBox.props.has_entry` is :const:`True`. .. attribute:: props.has_entry :type: bool Whether the combo box has an entry. .. attribute:: props.has_frame :type: bool The ``has-frame`` property controls whether a frame is drawn around the entry. .. attribute:: props.id_column :type: int The model column that provides string IDs for the values in the model, if != -1. .. attribute:: props.model :type: ~gi.repository.Gtk.TreeModel The model from which the combo box takes its values. .. attribute:: props.popup_fixed_width :type: bool Whether the popup's width should be a fixed width matching the allocated width of the combo box. .. attribute:: props.popup_shown :type: bool Whether the combo boxes dropdown is popped up. Note that this property is mainly useful, because it allows you to connect to notify::popup-shown. Signals ------- .. rst-class:: interim-class .. class:: ComboBox.signals :no-index: .. method:: activate() -> None Emitted to when the combo box is activated. The ``::activate`` signal on ``GtkComboBox`` is an action signal and emitting it causes the combo box to pop up its dropdown. .. versionadded:: 4.6 .. method:: changed() -> None Emitted when the active item is changed. The can be due to the user selecting a different item from the list, or due to a call to :obj:`~gi.repository.Gtk.ComboBox.set_active_iter`. It will also be emitted while typing into the entry of a combo box with an entry. .. method:: format_entry_text(path: str) -> str Emitted to allow changing how the text in a combo box's entry is displayed. See :obj:`~gi.repository.Gtk.ComboBox.props.has_entry`. Connect a signal handler which returns an allocated string representing ``path``. That string will then be used to set the text in the combo box's entry. The default signal handler uses the text from the :obj:`~gi.repository.Gtk.ComboBox.props.entry_text_column` model column. Here's an example signal handler which fetches data from the model and displays it in the entry. .. code-block:: :dedent: static char * format_entry_text_callback (GtkComboBox *combo, const char *path, gpointer user_data) { GtkTreeIter iter; GtkTreeModel model; double value; model = gtk_combo_box_get_model (combo); gtk_tree_model_get_iter_from_string (model, &iter, path); gtk_tree_model_get (model, &iter, THE_DOUBLE_VALUE_COLUMN, &value, -1); return g_strdup_printf ("``%g``", value); } :param path: the :obj:`~gi.repository.Gtk.TreePath` string from the combo box's current model to format text for .. method:: move_active(scroll_type: ~gi.repository.Gtk.ScrollType) -> None Emitted to move the active selection. This is an `keybinding signal `_. :param scroll_type: a ``GtkScrollType`` .. method:: popdown() -> bool Emitted to popdown the combo box list. This is an `keybinding signal `_. The default bindings for this signal are Alt+Up and Escape. .. method:: popup() -> None Emitted to popup the combo box list. This is an `keybinding signal `_. The default binding for this signal is Alt+Down. Virtual Methods --------------- .. rst-class:: interim-class .. class:: ComboBox :no-index: .. method:: do_activate() -> None .. method:: do_changed() -> None Signal is emitted when the active item is changed. .. method:: do_format_entry_text(path: str) -> str Signal which allows you to change how the text displayed in a combo box’s entry is displayed. :param path: Fields ------ .. rst-class:: interim-class .. class:: ComboBox :no-index: .. attribute:: parent_instance