// 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;
use crate::RecentFilterFlags;
use glib::translate::*;
use std::fmt;

glib::wrapper! {
    /// A [`RecentFilter`][crate::RecentFilter] can be used to restrict the files being shown
    /// in a [`RecentChooser`][crate::RecentChooser]. Files can be filtered based on their name
    /// (with [`add_pattern()`][Self::add_pattern()]), on their mime type (with
    /// [`FileFilter::add_mime_type()`][crate::FileFilter::add_mime_type()]), on the application that has
    /// registered them (with [`add_application()`][Self::add_application()]), or by
    /// a custom filter function (with `gtk_recent_filter_add_custom()`).
    ///
    /// Filtering by mime type 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 [`RecentFilter`][crate::RecentFilter] 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 [`RecentChooser`][crate::RecentChooser],
    /// see [`RecentChooserExt::add_filter()`][crate::prelude::RecentChooserExt::add_filter()], but it is also possible to
    /// manually use a filter on a file with `gtk_recent_filter_filter()`.
    ///
    /// Recently used files are supported since GTK+ 2.10.
    ///
    /// ## GtkRecentFilter as GtkBuildable
    ///
    /// The GtkRecentFilter 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>``, ``<pattern>`` or ``<application>`` has the same effect as
    /// calling [`add_mime_type()`][Self::add_mime_type()],
    /// [`add_pattern()`][Self::add_pattern()] or [`add_application()`][Self::add_application()].
    ///
    /// An example of a UI definition fragment specifying [`RecentFilter`][crate::RecentFilter]
    /// rules:
    ///
    ///
    ///
    /// **⚠️ The following code is in xml ⚠️**
    ///
    /// ```xml
    /// <object class="GtkRecentFilter">
    ///   <mime-types>
    ///     <mime-type>text/plain</mime-type>
    ///     <mime-type>image/png</mime-type>
    ///   </mime-types>
    ///   <patterns>
    ///     <pattern>*.txt</pattern>
    ///     <pattern>*.png</pattern>
    ///   </patterns>
    ///   <applications>
    ///     <application>gimp</application>
    ///     <application>gedit</application>
    ///     <application>glade</application>
    ///   </applications>
    /// </object>
    /// ```
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`], [`BuildableExt`][trait@crate::prelude::BuildableExt], [`BuildableExtManual`][trait@crate::prelude::BuildableExtManual]
    #[doc(alias = "GtkRecentFilter")]
    pub struct RecentFilter(Object<ffi::GtkRecentFilter>) @implements Buildable;

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

impl RecentFilter {
    /// Creates a new [`RecentFilter`][crate::RecentFilter] with no rules added to it.
    /// Such filter does not accept any recently used resources, so is not
    /// particularly useful until you add rules with
    /// [`add_pattern()`][Self::add_pattern()], [`add_mime_type()`][Self::add_mime_type()],
    /// [`add_application()`][Self::add_application()], [`add_age()`][Self::add_age()].
    /// To create a filter that accepts any recently used resource, use:
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    /// GtkRecentFilter *filter = gtk_recent_filter_new ();
    /// gtk_recent_filter_add_pattern (filter, "*");
    /// ```
    ///
    /// # Returns
    ///
    /// a new [`RecentFilter`][crate::RecentFilter]
    #[doc(alias = "gtk_recent_filter_new")]
    pub fn new() -> RecentFilter {
        assert_initialized_main_thread!();
        unsafe { from_glib_none(ffi::gtk_recent_filter_new()) }
    }

    /// Adds a rule that allows resources based on their age - that is, the number
    /// of days elapsed since they were last modified.
    /// ## `days`
    /// number of days
    #[doc(alias = "gtk_recent_filter_add_age")]
    pub fn add_age(&self, days: i32) {
        unsafe {
            ffi::gtk_recent_filter_add_age(self.to_glib_none().0, days);
        }
    }

    /// Adds a rule that allows resources based on the name of the application
    /// that has registered them.
    /// ## `application`
    /// an application name
    #[doc(alias = "gtk_recent_filter_add_application")]
    pub fn add_application(&self, application: &str) {
        unsafe {
            ffi::gtk_recent_filter_add_application(
                self.to_glib_none().0,
                application.to_glib_none().0,
            );
        }
    }

    //#[doc(alias = "gtk_recent_filter_add_custom")]
    //pub fn add_custom(&self, needed: RecentFilterFlags, func: /*Unimplemented*/Fn(/*Ignored*/RecentFilterInfo) -> bool, data: /*Unimplemented*/Option<Fundamental: Pointer>) {
    //    unsafe { TODO: call ffi:gtk_recent_filter_add_custom() }
    //}

    /// Adds a rule that allows resources based on the name of the group
    /// to which they belong
    /// ## `group`
    /// a group name
    #[doc(alias = "gtk_recent_filter_add_group")]
    pub fn add_group(&self, group: &str) {
        unsafe {
            ffi::gtk_recent_filter_add_group(self.to_glib_none().0, group.to_glib_none().0);
        }
    }

    /// Adds a rule that allows resources based on their registered MIME type.
    /// ## `mime_type`
    /// a MIME type
    #[doc(alias = "gtk_recent_filter_add_mime_type")]
    pub fn add_mime_type(&self, mime_type: &str) {
        unsafe {
            ffi::gtk_recent_filter_add_mime_type(self.to_glib_none().0, mime_type.to_glib_none().0);
        }
    }

    /// Adds a rule that allows resources based on a pattern matching their
    /// display name.
    /// ## `pattern`
    /// a file pattern
    #[doc(alias = "gtk_recent_filter_add_pattern")]
    pub fn add_pattern(&self, pattern: &str) {
        unsafe {
            ffi::gtk_recent_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_recent_filter_add_pixbuf_formats")]
    pub fn add_pixbuf_formats(&self) {
        unsafe {
            ffi::gtk_recent_filter_add_pixbuf_formats(self.to_glib_none().0);
        }
    }

    /// Gets the human-readable name for the filter.
    /// See [`set_name()`][Self::set_name()].
    ///
    /// # Returns
    ///
    /// the name of the filter, or [`None`]. The returned string
    ///  is owned by the filter object and should not be freed.
    #[doc(alias = "gtk_recent_filter_get_name")]
    #[doc(alias = "get_name")]
    pub fn name(&self) -> Option<glib::GString> {
        unsafe { from_glib_none(ffi::gtk_recent_filter_get_name(self.to_glib_none().0)) }
    }

    /// Gets the fields that need to be filled in for the `GtkRecentFilterInfo`
    /// passed to `gtk_recent_filter_filter()`
    ///
    /// This function will not typically be used by applications; it
    /// is intended principally for use in the implementation of
    /// [`RecentChooser`][crate::RecentChooser].
    ///
    /// # Returns
    ///
    /// bitfield of flags indicating needed fields when
    ///  calling `gtk_recent_filter_filter()`
    #[doc(alias = "gtk_recent_filter_get_needed")]
    #[doc(alias = "get_needed")]
    pub fn needed(&self) -> RecentFilterFlags {
        unsafe { from_glib(ffi::gtk_recent_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 recently used resources selector
    /// user interface if there is a selectable list of filters.
    /// ## `name`
    /// then human readable name of `self`
    #[doc(alias = "gtk_recent_filter_set_name")]
    pub fn set_name(&self, name: &str) {
        unsafe {
            ffi::gtk_recent_filter_set_name(self.to_glib_none().0, name.to_glib_none().0);
        }
    }
}

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

impl fmt::Display for RecentFilter {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("RecentFilter")
    }
}