:right-sidebar: True

Completion
===================================================================

.. currentmodule:: gi.repository.GLib





.. deprecated:: 2.26

   Rarely used API


.. class:: Completion(*args, **kwargs)
   :no-contents-entry:






``GCompletion`` provides support for automatic completion of a string
using any group of target strings. It is typically used for file
name completion as is common in many UNIX shells.

A ``GCompletion`` is created using :obj:`~gi.repository.GLib.Completion.new`\. Target items are
added and removed with :obj:`~gi.repository.GLib.Completion.add_items`\,
:obj:`~gi.repository.GLib.Completion.remove_items` and
:obj:`~gi.repository.GLib.Completion.clear_items`\. A completion attempt is requested with
:obj:`~gi.repository.GLib.Completion.complete` or :obj:`~gi.repository.GLib.Completion.complete_utf8`\.
When no longer needed, the ``GCompletion`` is freed with
:obj:`~gi.repository.GLib.Completion.free`\.

Items in the completion can be simple strings (e.g. filenames), or
pointers to arbitrary data structures. If data structures are used
you must provide a :obj:`~gi.repository.GLib.CompletionFunc` in :obj:`~gi.repository.GLib.Completion.new`\,
which retrieves the item’s string from the data structure. You can change
the way in which strings are compared by setting a different
:obj:`~gi.repository.GLib.CompletionStrncmpFunc` in :obj:`~gi.repository.GLib.Completion.set_compare`\.

``GCompletion`` has been marked as deprecated, since this API is rarely
used and not very actively maintained.




Methods
-------

.. rst-class:: interim-class

.. class:: Completion
   :no-index:


   .. method:: clear_items() -> None

      Removes all items from the :obj:`~gi.repository.GLib.Completion`\. The items are not freed, so if the
      memory was dynamically allocated, it should be freed after calling this
      function.





      .. deprecated:: 2.26

         Rarely used API






   .. method:: complete_utf8(prefix: str, new_prefix: str) -> list[str]

      Attempts to complete the string ``prefix`` using the :obj:`~gi.repository.GLib.Completion` target items.
      In contrast to :func:`~gi.repository.GLib.Completion.complete`, this function returns the largest common
      prefix that is a valid UTF-8 string, omitting a possible common partial
      character.

      You should use this function instead of :func:`~gi.repository.GLib.Completion.complete` if your
      items are UTF-8 strings.


      .. versionadded:: 2.4




      .. deprecated:: 2.26

         Rarely used API



      :param prefix: the prefix string, typically used by the user, which is compared
            with each of the items

      :param new_prefix: if non-:const:`None`, returns the longest prefix which is common to all
            items that matched ``prefix``\, or :const:`None` if no items matched ``prefix``\.
            This string should be freed when no longer needed.




   .. method:: free() -> None

      Frees all memory used by the :obj:`~gi.repository.GLib.Completion`\. The items are not freed, so if
      the memory was dynamically allocated, it should be freed after calling this
      function.





      .. deprecated:: 2.26

         Rarely used API
















Fields
------

.. rst-class:: interim-class

.. class:: Completion
   :no-index:
   

   .. attribute:: cache

      The list of items which begin with ``prefix``\.






   .. attribute:: func

      Function which is called to get the string associated with a
             target item. It is :const:`None` if the target items are strings.






   .. attribute:: items

      List of target items (strings or data structures).






   .. attribute:: prefix

      The last prefix passed to :func:`~gi.repository.GLib.Completion.complete` or
               :func:`~gi.repository.GLib.Completion.complete_utf8`.






   .. attribute:: strncmp_func

      The function to use when comparing strings.  Use
                     :func:`~gi.repository.GLib.Completion.set_compare` to modify this function.