gtk/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

use crate::{Buildable, FileFilterFlags, FileFilterInfo, ffi};
use glib::translate::*;
use std::boxed::Box as Box_;

glib::wrapper! {
    /// A GtkFileFilter can be used to restrict the files being shown in a
    /// [`FileChooser`][crate::FileChooser]. Files can be filtered based on their name (with
    /// [`add_pattern()`][Self::add_pattern()]), on their mime type (with
    /// [`add_mime_type()`][Self::add_mime_type()]), or by a custom filter function
    /// (with [`add_custom()`][Self::add_custom()]).
    ///
    /// 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, filters are used by adding them to a [`FileChooser`][crate::FileChooser],
    /// see [`FileChooserExt::add_filter()`][crate::prelude::FileChooserExt::add_filter()], but it is also possible
    /// to manually use a filter on a file with [`filter()`][Self::filter()].
    ///
    /// # GtkFileFilter as GtkBuildable
    ///
    /// The GtkFileFilter implementation of the GtkBuildable interface
    /// supports adding rules using the ``<mime-types>``, ``<patterns>`` and
    /// ``<applications>`` elements and listing the rules within. Specifying
    /// a ``<mime-type>`` or ``<pattern>`` has the same effect as as calling
    /// [`add_mime_type()`][Self::add_mime_type()] or [`add_pattern()`][Self::add_pattern()].
    ///
    /// An example of a UI definition fragment specifying GtkFileFilter
    /// rules:
    ///
    ///
    ///
    /// **⚠️ The following code is in xml ⚠️**
    ///
    /// ```xml
    /// <object class="GtkFileFilter">
    ///   <mime-types>
    ///     <mime-type>text/plain</mime-type>
    ///     <mime-type>image/ *</mime-type>
    ///   </mime-types>
    ///   <patterns>
    ///     <pattern>*.txt</pattern>
    ///     <pattern>*.png</pattern>
    ///   </patterns>
    /// </object>
    /// ```
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`], [`BuildableExt`][trait@crate::prelude::BuildableExt], [`BuildableExtManual`][trait@crate::prelude::BuildableExtManual]
    #[doc(alias = "GtkFileFilter")]
    pub struct FileFilter(Object<ffi::GtkFileFilter>) @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()],
    /// or [`add_custom()`][Self::add_custom()]. 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_none(ffi::gtk_file_filter_new()) }
    }

    /// Deserialize a file filter from an a{sv} variant in
    /// the format produced by [`to_gvariant()`][Self::to_gvariant()].
    /// ## `variant`
    /// an a{sv} [`glib::Variant`][struct@crate::glib::Variant]
    ///
    /// # 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 rule to a filter that allows files based on a custom callback
    /// function. The bitfield `needed` which is passed in provides information
    /// about what sorts of information that the filter function needs;
    /// this allows GTK+ to avoid retrieving expensive information when
    /// it isn’t needed by the filter.
    /// ## `needed`
    /// bitfield of flags indicating the information that the custom
    ///  filter function needs.
    /// ## `func`
    /// callback function; if the function returns [`true`], then
    ///  the file will be displayed.
    /// ## `notify`
    /// function to call to free `data` when it is no longer needed.
    #[doc(alias = "gtk_file_filter_add_custom")]
    pub fn add_custom<P: Fn(&FileFilterInfo) -> bool + 'static>(
        &self,
        needed: FileFilterFlags,
        func: P,
    ) {
        let func_data: Box_<P> = Box_::new(func);
        unsafe extern "C" fn func_func<P: Fn(&FileFilterInfo) -> bool + 'static>(
            filter_info: *const ffi::GtkFileFilterInfo,
            data: glib::ffi::gpointer,
        ) -> glib::ffi::gboolean {
            unsafe {
                let filter_info = from_glib_borrow(filter_info);
                let callback = &*(data as *mut P);
                (*callback)(&filter_info).into_glib()
            }
        }
        let func = Some(func_func::<P> as _);
        unsafe extern "C" fn notify_func<P: Fn(&FileFilterInfo) -> bool + 'static>(
            data: glib::ffi::gpointer,
        ) {
            unsafe {
                let _callback = Box_::from_raw(data as *mut P);
            }
        }
        let destroy_call4 = Some(notify_func::<P> as _);
        let super_callback0: Box_<P> = func_data;
        unsafe {
            ffi::gtk_file_filter_add_custom(
                self.to_glib_none().0,
                needed.into_glib(),
                func,
                Box_::into_raw(super_callback0) as *mut _,
                destroy_call4,
            );
        }
    }

    /// Adds a rule allowing a given mime type to `self`.
    /// ## `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 shell style glob to a filter.
    /// ## `pattern`
    /// a shell style glob
    #[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 GdkPixbuf.
    #[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);
        }
    }

    /// Tests whether a file should be displayed according to `self`.
    /// The [`FileFilterInfo`][crate::FileFilterInfo] `filter_info` should include
    /// the fields returned from [`needed()`][Self::needed()].
    ///
    /// This function will not typically be used by applications; it
    /// is intended principally for use in the implementation of
    /// [`FileChooser`][crate::FileChooser].
    /// ## `filter_info`
    /// a [`FileFilterInfo`][crate::FileFilterInfo] containing information
    ///  about a file.
    ///
    /// # Returns
    ///
    /// [`true`] if the file should be displayed
    #[doc(alias = "gtk_file_filter_filter")]
    pub fn filter(&self, filter_info: &FileFilterInfo) -> bool {
        unsafe {
            from_glib(ffi::gtk_file_filter_filter(
                self.to_glib_none().0,
                filter_info.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,
    ///  or [`None`]. This value is owned by GTK+ and must not
    ///  be modified or freed.
    #[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)) }
    }

    /// Gets the fields that need to be filled in for the [`FileFilterInfo`][crate::FileFilterInfo]
    /// passed to [`filter()`][Self::filter()]
    ///
    /// This function will not typically be used by applications; it
    /// is intended principally for use in the implementation of
    /// [`FileChooser`][crate::FileChooser].
    ///
    /// # Returns
    ///
    /// bitfield of flags indicating needed fields when
    ///  calling [`filter()`][Self::filter()]
    #[doc(alias = "gtk_file_filter_get_needed")]
    #[doc(alias = "get_needed")]
    pub fn needed(&self) -> FileFilterFlags {
        unsafe { from_glib(ffi::gtk_file_filter_get_needed(self.to_glib_none().0)) }
    }

    /// Sets the human-readable name of the filter; this is the string
    /// that will be displayed in the file selector user interface if
    /// there is a selectable list of filters.
    /// ## `name`
    /// the human-readable-name for the filter, or [`None`]
    ///  to remove any existing name.
    #[doc(alias = "gtk_file_filter_set_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, [`glib::Variant`][struct@crate::glib::Variant]
    #[doc(alias = "gtk_file_filter_to_gvariant")]
    pub fn to_gvariant(&self) -> Option<glib::Variant> {
        unsafe { from_glib_none(ffi::gtk_file_filter_to_gvariant(self.to_glib_none().0)) }
    }
}

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