:right-sidebar: True

ComboBoxText
===================================================================

.. currentmodule:: gi.repository.Gtk





.. deprecated:: 4.10

   Use :obj:`~gi.repository.Gtk.DropDown` with a :obj:`~gi.repository.Gtk.StringList`
   instead



.. class:: ComboBoxText(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.ComboBox`, :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`



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 ``GtkComboBoxText`` is a simple variant of ``GtkComboBox`` for text-only
use cases.


.. image:: https://docs.gtk.org/gtk4/combo-box-text.png


``GtkComboBoxText`` hides the model-view complexity of ``GtkComboBox``.

To create a ``GtkComboBoxText``, use :obj:`~gi.repository.Gtk.ComboBoxText.new` or
:obj:`~gi.repository.Gtk.ComboBoxText.new_with_entry`.

You can add items to a ``GtkComboBoxText`` with
:obj:`~gi.repository.Gtk.ComboBoxText.append_text`,
:obj:`~gi.repository.Gtk.ComboBoxText.insert_text` or
:obj:`~gi.repository.Gtk.ComboBoxText.prepend_text` and remove options with
:obj:`~gi.repository.Gtk.ComboBoxText.remove`.

If the ``GtkComboBoxText`` contains an entry (via the
:obj:`~gi.repository.Gtk.ComboBox.props.has_entry` property), its contents can be retrieved
using :obj:`~gi.repository.Gtk.ComboBoxText.get_active_text`.

You should not call :obj:`~gi.repository.Gtk.ComboBox.set_model` or attempt to pack more
cells into this combo box via its :obj:`~gi.repository.Gtk.CellLayout` interface.

GtkComboBoxText as GtkBuildable
-------------------------------

The ``GtkComboBoxText`` implementation of the ``GtkBuildable`` interface supports
adding items directly using the ``<items>`` element and specifying ``<item>``
elements for each item. Each ``<item>`` element can specify the “id”
corresponding to the appended text and also supports the regular
translation attributes “translatable”, “context” and “comments”.

Here is a UI definition fragment specifying ``GtkComboBoxText`` items:

.. code-block::
   :dedent:

   <object class="GtkComboBoxText">
     <items>
       <item translatable="yes" id="factory">Factory</item>
       <item translatable="yes" id="home">Home</item>
       <item translatable="yes" id="subway">Subway</item>
     </items>
   </object>


CSS nodes
---------


.. code-block::
   :dedent:

   combobox
   ╰── box.linked
       ├── entry.combo
       ├── button.combo
       ╰── window.popup


``GtkComboBoxText`` has a single CSS node with name combobox. It adds
the style class .combo to the main CSS nodes of its entry and button
children, and the .linked class to the node of its internal box.



Constructors
------------

.. rst-class:: interim-class

.. class:: ComboBoxText
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.Widget

      Creates a new ``GtkComboBoxText``.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`







   .. classmethod:: new_with_entry() -> ~gi.repository.Gtk.Widget

      Creates a new ``GtkComboBoxText`` with an entry.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`











Methods
-------

.. rst-class:: interim-class

.. class:: ComboBoxText
   :no-index:


   .. method:: append(id: str | None, text: str) -> None

      Appends ``text`` to the list of strings stored in ``combo_box``.

      If ``id`` is non-:const:`None` then it is used as the ID of the row.

      This is the same as calling :obj:`~gi.repository.Gtk.ComboBoxText.insert`
      with a position of -1.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`




      :param id: a string ID for this value


      :param text: A string





   .. method:: append_text(text: str) -> None

      Appends ``text`` to the list of strings stored in ``combo_box``.

      This is the same as calling :obj:`~gi.repository.Gtk.ComboBoxText.insert_text`
      with a position of -1.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`




      :param text: A string





   .. method:: get_active_text() -> str | None

      Returns the currently active string in ``combo_box``.

      If no row is currently selected, :const:`None` is returned.
      If ``combo_box`` contains an entry, this function will
      return its contents (which will not necessarily
      be an item from the list).






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`







   .. method:: insert(position: int, id: str | None, text: str) -> None

      Inserts ``text`` at ``position`` in the list of strings stored in ``combo_box``.

      If ``id`` is non-:const:`None` then it is used as the ID of the row.
      See :obj:`~gi.repository.Gtk.ComboBox.props.id_column`.

      If ``position`` is negative then ``text`` is appended.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`




      :param position: An index to insert ``text``


      :param id: a string ID for this value


      :param text: A string to display





   .. method:: insert_text(position: int, text: str) -> None

      Inserts ``text`` at ``position`` in the list of strings stored in ``combo_box``.

      If ``position`` is negative then ``text`` is appended.

      This is the same as calling :obj:`~gi.repository.Gtk.ComboBoxText.insert`
      with a :const:`None` ID string.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`




      :param position: An index to insert ``text``


      :param text: A string





   .. method:: prepend(id: str | None, text: str) -> None

      Prepends ``text`` to the list of strings stored in ``combo_box``.

      If ``id`` is non-:const:`None` then it is used as the ID of the row.

      This is the same as calling :obj:`~gi.repository.Gtk.ComboBoxText.insert`
      with a position of 0.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`




      :param id: a string ID for this value


      :param text: a string





   .. method:: prepend_text(text: str) -> None

      Prepends ``text`` to the list of strings stored in ``combo_box``.

      This is the same as calling :obj:`~gi.repository.Gtk.ComboBoxText.insert_text`
      with a position of 0.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`




      :param text: A string





   .. method:: remove(position: int) -> None

      Removes the string at ``position`` from ``combo_box``.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`




      :param position: Index of the item to remove





   .. method:: remove_all() -> None

      Removes all the text entries from the combo box.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gtk.DropDown`