:right-sidebar: True

StringList
===================================================================

.. currentmodule:: gi.repository.Gtk





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


Superclasses: :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gio.ListModel`, :class:`~gi.repository.Gtk.Buildable`



``GtkStringList`` is a list model that wraps an array of strings.

The objects in the model are of type :obj:`~gi.repository.Gtk.StringObject` and have
a "string" property that can be used inside expressions.

``GtkStringList`` is well-suited for any place where you would
typically use a ``char*[]``, but need a list model.

GtkStringList as GtkBuildable
-----------------------------

The ``GtkStringList`` implementation of the ``GtkBuildable`` interface
supports adding items directly using the ``<items>`` element and
specifying ``<item>`` elements for each item. Each ``<item>`` element
supports the regular translation attributes “translatable”,
“context” and “comments”.

Here is a UI definition fragment specifying a ``GtkStringList``


.. code-block::
   :dedent:

   <object class="GtkStringList">
     <items>
       <item translatable="yes">Factory</item>
       <item translatable="yes">Home</item>
       <item translatable="yes">Subway</item>
     </items>
   </object>




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

.. rst-class:: interim-class

.. class:: StringList
   :no-index:


   .. classmethod:: new(strings: ~typing.Sequence[str] | None = None) -> ~gi.repository.Gtk.StringList

      Creates a new ``GtkStringList`` with the given ``strings``.







      :param strings: The strings to put in the model









Methods
-------

.. rst-class:: interim-class

.. class:: StringList
   :no-index:


   .. method:: append(string: str) -> None

      Appends ``string`` to ``self``.

      The ``string`` will be copied. See
      :obj:`~gi.repository.Gtk.StringList.take` for a way to avoid that.







      :param string: the string to insert





   .. method:: get_string(position: int) -> str | None

      Gets the string that is at ``position`` in ``self``.

      If ``self`` does not contain ``position`` items, :const:`None` is returned.

      This function returns the const char *. To get the
      object wrapping it, use :func:`~gi.repository.Gio.Gio.ListModel.get_item`.







      :param position: the position to get the string for





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

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

      ``position`` must be smaller than the current
      length of the list.







      :param position: the position of the string that is to be removed





   .. method:: splice(position: int, n_removals: int, additions: ~typing.Sequence[str] | None = None) -> None

      Changes ``self`` by removing ``n_removals`` strings and adding ``additions``
      to it.

      This function is more efficient than :obj:`~gi.repository.Gtk.StringList.append`
      and :obj:`~gi.repository.Gtk.StringList.remove`, because it only emits the
      ::items-changed signal once for the change.

      This function copies the strings in ``additions``.

      The parameters ``position`` and ``n_removals`` must be correct (ie:
      ``position`` + ``n_removals`` must be less than or equal to the length
      of the list at the time this function is called).







      :param position: the position at which to make the change


      :param n_removals: the number of strings to remove


      :param additions: The strings to add





   .. method:: take(string: str) -> None

      Adds ``string`` to self at the end, and takes
      ownership of it.

      This variant of :obj:`~gi.repository.Gtk.StringList.append`
      is convenient for formatting strings:


      .. code-block::
         :dedent:

         gtk_string_list_take (self, g_strdup_print ("``%d`` dollars", lots));








      :param string: the string to insert









Properties
----------

.. rst-class:: interim-class

.. class:: StringList
   :no-index:
   

   .. attribute:: props.item_type
      :type: type

      The type of items. See :obj:`~gi.repository.Gio.ListModel.get_item_type`.



      .. versionadded:: 4.14





   .. attribute:: props.n_items
      :type: int

      The number of items. See :obj:`~gi.repository.Gio.ListModel.get_n_items`.



      .. versionadded:: 4.14





   .. attribute:: props.strings
      :type: ~typing.Sequence[str]

      


      .. versionadded:: 4.10