gtk4/auto/

file_filter.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT
#![allow(deprecated)]

use crate::{Buildable, Filter, ffi};
use glib::{
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// Filters files by name or mime type.
    ///
    /// [`FileFilter`][crate::FileFilter] can be used to restrict the files being shown in a
    /// file chooser. Files can be filtered based on their name (with
    /// [`add_pattern()`][Self::add_pattern()] or [`add_suffix()`][Self::add_suffix()])
    /// or on their mime type (with [`add_mime_type()`][Self::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 [`FileFilter`][crate::FileFilter] 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 file chooser
    /// (see [`FileDialog::set_filters()`][crate::FileDialog::set_filters()]), but it is also possible to
    /// manually use a file filter on any [`FilterListModel`][crate::FilterListModel] containing
    /// `GFileInfo` objects.
    ///
    /// # GtkFileFilter as GtkBuildable
    ///
    /// The [`FileFilter`][crate::FileFilter] implementation of the [`Buildable`][crate::Buildable] 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
    /// [`add_mime_type()`][Self::add_mime_type()] or
    /// [`add_pattern()`][Self::add_pattern()] or
    /// [`add_suffix()`][Self::add_suffix()].
    ///
    /// An example of a UI definition fragment specifying [`FileFilter`][crate::FileFilter]
    /// rules:
    /// ```xml
    /// <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>
    /// ```
    ///
    /// ## Properties
    ///
    ///
    /// #### `mime-types`
    ///  The MIME types that this filter matches.
    ///
    /// Writeable | Construct Only
    ///
    ///
    /// #### `name`
    ///  The human-readable name of the filter.
    ///
    /// This is the string that will be displayed in the user interface
    /// if there is a selectable list of filters.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `patterns`
    ///  The patterns that this filter matches.
    ///
    /// Writeable | Construct Only
    ///
    ///
    /// #### `suffixes`
    ///  The suffixes that this filter matches.
    ///
    /// Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`FilterExt`][trait@crate::prelude::FilterExt], [`trait@glib::ObjectExt`], [`BuildableExt`][trait@crate::prelude::BuildableExt]
    #[doc(alias = "GtkFileFilter")]
    pub struct FileFilter(Object<ffi::GtkFileFilter>) @extends Filter, @implements Buildable;

    match fn {
        type_ => || ffi::gtk_file_filter_get_type(),
    }
}

impl FileFilter {
    /// Creates a new [`FileFilter`][crate::FileFilter] with no rules added to it.
    ///
    /// Such a filter doesn’t accept any files, so is not
    /// particularly useful until you add rules with
    /// [`add_mime_type()`][Self::add_mime_type()],
    /// [`add_pattern()`][Self::add_pattern()],
    /// [`add_suffix()`][Self::add_suffix()] or
    /// [`add_pixbuf_formats()`][Self::add_pixbuf_formats()].
    ///
    /// To create a filter that accepts any file, use:
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// GtkFileFilter *filter = gtk_file_filter_new ();
    /// gtk_file_filter_add_pattern (filter, "*");
    /// ```
    ///
    /// # Returns
    ///
    /// a new [`FileFilter`][crate::FileFilter]
    #[doc(alias = "gtk_file_filter_new")]
    pub fn new() -> FileFilter {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gtk_file_filter_new()) }
    }

    /// Deserialize a file filter from a `GVariant`.
    ///
    /// The variant must be in the format produced by
    /// [`to_gvariant()`][Self::to_gvariant()].
    /// ## `variant`
    /// an `a{sv}` `GVariant`
    ///
    /// # Returns
    ///
    /// a new [`FileFilter`][crate::FileFilter] object
    #[doc(alias = "gtk_file_filter_new_from_gvariant")]
    #[doc(alias = "new_from_gvariant")]
    pub fn from_gvariant(variant: &glib::Variant) -> FileFilter {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gtk_file_filter_new_from_gvariant(
                variant.to_glib_none().0,
            ))
        }
    }

    /// Adds a rule allowing a given mime type.
    /// ## `mime_type`
    /// name of a MIME type
    #[doc(alias = "gtk_file_filter_add_mime_type")]
    pub fn add_mime_type(&self, mime_type: &str) {
        unsafe {
            ffi::gtk_file_filter_add_mime_type(self.to_glib_none().0, mime_type.to_glib_none().0);
        }
    }

    /// Adds a rule allowing a given array of mime types.
    /// It can for example be used with
    /// [Gly.Loader.get_mime_types](https://gnome.pages.gitlab.gnome.org/glycin/libglycin/type_func.Loader.get_mime_types.html).
    ///
    /// This is equivalent to calling [`add_mime_type()`][Self::add_mime_type()]
    /// for all the supported mime types.
    /// ## `mime_types`
    /// a [`None`]-terminated array of mime types
    #[cfg(feature = "v4_22")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
    #[doc(alias = "gtk_file_filter_add_mime_types")]
    pub fn add_mime_types(&self, mime_types: &[&str]) {
        unsafe {
            ffi::gtk_file_filter_add_mime_types(self.to_glib_none().0, mime_types.to_glib_none().0);
        }
    }

    /// Adds a rule allowing a shell style glob pattern.
    ///
    /// Note that it depends on the platform whether pattern
    /// matching ignores case or not. On Windows, it does, on
    /// other platforms, it doesn't.
    /// ## `pattern`
    /// a shell style glob pattern
    #[doc(alias = "gtk_file_filter_add_pattern")]
    pub fn add_pattern(&self, pattern: &str) {
        unsafe {
            ffi::gtk_file_filter_add_pattern(self.to_glib_none().0, pattern.to_glib_none().0);
        }
    }

    /// Adds a rule allowing image files in the formats supported by [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf].
    ///
    /// This is equivalent to calling [`add_mime_type()`][Self::add_mime_type()]
    /// for all the supported mime types.
    ///
    /// # Deprecated since 4.20
    ///
    /// Use the api of your image loading framework (e.g. glycin)
    ///   to enumerate supported formats
    #[cfg_attr(feature = "v4_20", deprecated = "Since 4.20")]
    #[allow(deprecated)]
    #[doc(alias = "gtk_file_filter_add_pixbuf_formats")]
    pub fn add_pixbuf_formats(&self) {
        unsafe {
            ffi::gtk_file_filter_add_pixbuf_formats(self.to_glib_none().0);
        }
    }

    /// Adds a suffix match rule to a filter.
    ///
    /// This is similar to adding a match for the pattern "*.@suffix"
    ///
    /// An exaple to filter files with the suffix ".sub":
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// gtk_file_filter_add_suffix (filter, "sub");
    /// ```
    ///
    /// Filters with multiple dots are allowed.
    ///
    /// In contrast to pattern matches, suffix matches
    /// are *always* case-insensitive.
    /// ## `suffix`
    /// filename suffix to match
    #[cfg(feature = "v4_4")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_4")))]
    #[doc(alias = "gtk_file_filter_add_suffix")]
    pub fn add_suffix(&self, suffix: &str) {
        unsafe {
            ffi::gtk_file_filter_add_suffix(self.to_glib_none().0, suffix.to_glib_none().0);
        }
    }

    /// 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 for use in file chooser implementation.
    ///
    /// # Returns
    ///
    /// the attributes
    #[doc(alias = "gtk_file_filter_get_attributes")]
    #[doc(alias = "get_attributes")]
    pub fn attributes(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::gtk_file_filter_get_attributes(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the human-readable name for the filter.
    ///
    /// See [`set_name()`][Self::set_name()].
    ///
    /// # Returns
    ///
    /// the human-readable name of the filter
    #[doc(alias = "gtk_file_filter_get_name")]
    #[doc(alias = "get_name")]
    pub fn name(&self) -> Option<glib::GString> {
        unsafe { from_glib_none(ffi::gtk_file_filter_get_name(self.to_glib_none().0)) }
    }

    /// Sets a human-readable name of the filter.
    ///
    /// This is the string that will be displayed in the user interface
    /// if there is a selectable list of filters.
    /// ## `name`
    /// the human-readable name for the filter
    #[doc(alias = "gtk_file_filter_set_name")]
    #[doc(alias = "name")]
    pub fn set_name(&self, name: Option<&str>) {
        unsafe {
            ffi::gtk_file_filter_set_name(self.to_glib_none().0, name.to_glib_none().0);
        }
    }

    /// Serialize a file filter to an `a{sv}` variant.
    ///
    /// # Returns
    ///
    /// a new, floating, `GVariant`
    #[doc(alias = "gtk_file_filter_to_gvariant")]
    pub fn to_gvariant(&self) -> glib::Variant {
        unsafe { from_glib_none(ffi::gtk_file_filter_to_gvariant(self.to_glib_none().0)) }
    }

    #[doc(alias = "name")]
    pub fn connect_name_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_name_trampoline<F: Fn(&FileFilter) + 'static>(
            this: *mut ffi::GtkFileFilter,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(&from_glib_borrow(this))
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::name".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_name_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl Default for FileFilter {
    fn default() -> Self {
        Self::new()
    }
}