:right-sidebar: True

FileFilter
===================================================================

.. currentmodule:: gi.repository.Gtk





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


Superclasses: :class:`~gi.repository.Gtk.Filter`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Buildable`



``GtkFileFilter`` filters files by name or mime type.

``GtkFileFilter`` can be used to restrict the files being shown in a
``GtkFileChooser``. Files can be filtered based on their name (with
:obj:`~gi.repository.Gtk.FileFilter.add_pattern` or :obj:`~gi.repository.Gtk.FileFilter.add_suffix`)
or on their mime type (with :obj:`~gi.repository.Gtk.FileFilter.add_mime_type`).

Filtering by mime types handles aliasing and subclassing of mime
types; e.g. a filter for text/plain also matches a file with mime
type application/rtf, since application/rtf is a subclass of
text/plain. Note that ``GtkFileFilter`` allows wildcards for the
subtype of a mime type, so you can e.g. filter for image/\*.

Normally, file filters are used by adding them to a ``GtkFileChooser``
(see :obj:`~gi.repository.Gtk.FileChooser.add_filter`), but it is also possible to
manually use a file filter on any :obj:`~gi.repository.Gtk.FilterListModel` containing
``GFileInfo`` objects.

GtkFileFilter as GtkBuildable
-----------------------------

The ``GtkFileFilter`` implementation of the ``GtkBuildable`` interface
supports adding rules using the ``<mime-types>`` and ``<patterns>`` and
``<suffixes>`` elements and listing the rules within. Specifying a
``<mime-type>`` or ``<pattern>`` or ``<suffix>`` has the same effect as
as calling
:obj:`~gi.repository.Gtk.FileFilter.add_mime_type` or
:obj:`~gi.repository.Gtk.FileFilter.add_pattern` or
:obj:`~gi.repository.Gtk.FileFilter.add_suffix`.

An example of a UI definition fragment specifying ``GtkFileFilter``
rules:

.. code-block::
   :dedent:

   <object class="GtkFileFilter">
     <property name="name" translatable="yes">Text and Images</property>
     <mime-types>
       <mime-type>text/plain</mime-type>
       <mime-type>image/ *</mime-type>
     </mime-types>
     <patterns>
       <pattern>*.txt</pattern>
     </patterns>
     <suffixes>
       <suffix>png</suffix>
     </suffixes>
   </object>




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

.. rst-class:: interim-class

.. class:: FileFilter
   :no-index:


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

      Creates a new ``GtkFileFilter`` with no rules added to it.

      Such a filter doesn’t accept any files, so is not
      particularly useful until you add rules with
      :obj:`~gi.repository.Gtk.FileFilter.add_mime_type`,
      :obj:`~gi.repository.Gtk.FileFilter.add_pattern`,
      :obj:`~gi.repository.Gtk.FileFilter.add_suffix` or
      :obj:`~gi.repository.Gtk.FileFilter.add_pixbuf_formats`.

      To create a filter that accepts any file, use:

      .. code-block::
         :dedent:

         GtkFileFilter *filter = gtk_file_filter_new ();
         gtk_file_filter_add_pattern (filter, "*");











   .. classmethod:: new_from_gvariant(variant: ~gi.repository.GLib.Variant) -> ~gi.repository.Gtk.FileFilter

      Deserialize a file filter from a ``GVariant``.

      The variant must be in the format produced by
      :obj:`~gi.repository.Gtk.FileFilter.to_gvariant`.







      :param variant: an ``a{sv}`` ``GVariant``









Methods
-------

.. rst-class:: interim-class

.. class:: FileFilter
   :no-index:


   .. method:: add_mime_type(mime_type: str) -> None

      Adds a rule allowing a given mime type to ``filter``.







      :param mime_type: name of a MIME type





   .. method:: add_pattern(pattern: str) -> None

      Adds a rule allowing a shell style glob to a filter.

      Note that it depends on the platform whether pattern
      matching ignores case or not. On Windows, it does, on
      other platforms, it doesn't.







      :param pattern: a shell style glob





   .. method:: add_pixbuf_formats() -> None

      Adds a rule allowing image files in the formats supported
      by GdkPixbuf.

      This is equivalent to calling :obj:`~gi.repository.Gtk.FileFilter.add_mime_type`
      for all the supported mime types.










   .. method:: add_suffix(suffix: str) -> None

      Adds a suffix match rule to a filter.

      This is similar to adding a match for the pattern
      "*.``suffix``".

      In contrast to pattern matches, suffix matches
      are *always* case-insensitive.



      .. versionadded:: 4.4





      :param suffix: filename suffix to match





   .. method:: get_attributes() -> list[str]

      Gets the attributes that need to be filled in for the ``GFileInfo``
      passed to this filter.

      This function will not typically be used by applications;
      it is intended principally for use in the implementation
      of ``GtkFileChooser``.










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

      Gets the human-readable name for the filter.

      See :obj:`~gi.repository.Gtk.FileFilter.set_name`.










   .. method:: set_name(name: str | None = None) -> None

      Sets a human-readable name of the filter.

      This is the string that will be displayed in the file chooser
      if there is a selectable list of filters.







      :param name: the human-readable-name for the filter, or :const:`None`
         to remove any existing name.





   .. method:: to_gvariant() -> ~gi.repository.GLib.Variant

      Serialize a file filter to an ``a{sv}`` variant.














Properties
----------

.. rst-class:: interim-class

.. class:: FileFilter
   :no-index:
   

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

      The MIME types that this filter matches.



      .. versionadded:: 4.10





   .. attribute:: props.name
      :type: str

      The human-readable name of the filter.

      This is the string that will be displayed in the file chooser
      user interface if there is a selectable list of filters.







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

      The patterns that this filter matches.



      .. versionadded:: 4.10





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

      The suffixes that this filter matches.



      .. versionadded:: 4.10