gtk4/auto/

recent_info.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::ffi;
use glib::translate::*;

glib::wrapper! {
    /// [`RecentInfo`][crate::RecentInfo] contains the metadata associated with an item in the
    /// recently used files list.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct RecentInfo(Shared<ffi::GtkRecentInfo>);

    match fn {
        ref => |ptr| ffi::gtk_recent_info_ref(ptr),
        unref => |ptr| ffi::gtk_recent_info_unref(ptr),
        type_ => || ffi::gtk_recent_info_get_type(),
    }
}

impl RecentInfo {
    /// Creates a `GAppInfo` for the specified [`RecentInfo`][crate::RecentInfo]
    ///
    /// In case of error, @error will be set either with a
    /// `GTK_RECENT_MANAGER_ERROR` or a `G_IO_ERROR`
    /// ## `app_name`
    /// the name of the application that should
    ///   be mapped to a `GAppInfo`; if [`None`] is used then the default
    ///   application for the MIME type is used
    ///
    /// # Returns
    ///
    /// the newly created `GAppInfo`
    #[doc(alias = "gtk_recent_info_create_app_info")]
    pub fn create_app_info(
        &self,
        app_name: Option<&str>,
    ) -> Result<Option<gio::AppInfo>, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gtk_recent_info_create_app_info(
                self.to_glib_none().0,
                app_name.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Checks whether the resource pointed by @self still exists.
    /// At the moment this check is done only on resources pointing
    /// to local files.
    ///
    /// # Returns
    ///
    /// [`true`] if the resource exists
    #[doc(alias = "gtk_recent_info_exists")]
    pub fn exists(&self) -> bool {
        unsafe { from_glib(ffi::gtk_recent_info_exists(self.to_glib_none().0)) }
    }

    /// Gets the time when the resource
    /// was added to the recently used resources list.
    ///
    /// # Returns
    ///
    /// a `GDateTime` for the time
    ///    when the resource was added
    #[doc(alias = "gtk_recent_info_get_added")]
    #[doc(alias = "get_added")]
    pub fn added(&self) -> glib::DateTime {
        unsafe { from_glib_none(ffi::gtk_recent_info_get_added(self.to_glib_none().0)) }
    }

    /// Gets the number of days elapsed since the last update
    /// of the resource pointed by @self.
    ///
    /// # Returns
    ///
    /// a positive integer containing the number of days
    ///   elapsed since the time this resource was last modified
    #[doc(alias = "gtk_recent_info_get_age")]
    #[doc(alias = "get_age")]
    pub fn age(&self) -> i32 {
        unsafe { ffi::gtk_recent_info_get_age(self.to_glib_none().0) }
    }

    /// Gets the data regarding the application that has registered the resource
    /// pointed by @self.
    ///
    /// If the command line contains any escape characters defined inside the
    /// storage specification, they will be expanded.
    /// ## `app_name`
    /// the name of the application that has registered this item
    ///
    /// # Returns
    ///
    /// [`true`] if an application with @app_name has registered this
    ///   resource inside the recently used list, or [`false`] otherwise. The
    ///   @app_exec string is owned by the [`RecentInfo`][crate::RecentInfo] and should not be
    ///   modified or freed
    ///
    /// ## `app_exec`
    /// return location for the string containing
    ///    the command line
    ///
    /// ## `count`
    /// return location for the number of times this item was registered
    ///
    /// ## `stamp`
    /// return location for the time this item was last
    ///    registered for this application
    #[doc(alias = "gtk_recent_info_get_application_info")]
    #[doc(alias = "get_application_info")]
    pub fn application_info(&self, app_name: &str) -> Option<(glib::GString, u32, glib::DateTime)> {
        unsafe {
            let mut app_exec = std::ptr::null();
            let mut count = std::mem::MaybeUninit::uninit();
            let mut stamp = std::ptr::null_mut();
            let ret = from_glib(ffi::gtk_recent_info_get_application_info(
                self.to_glib_none().0,
                app_name.to_glib_none().0,
                &mut app_exec,
                count.as_mut_ptr(),
                &mut stamp,
            ));
            if ret {
                Some((
                    from_glib_none(app_exec),
                    count.assume_init(),
                    from_glib_none(stamp),
                ))
            } else {
                None
            }
        }
    }

    /// Retrieves the list of applications that have registered this resource.
    ///
    /// # Returns
    ///
    /// a newly
    ///   allocated [`None`]-terminated array of strings. Use g_strfreev() to free it.
    #[doc(alias = "gtk_recent_info_get_applications")]
    #[doc(alias = "get_applications")]
    pub fn applications(&self) -> Vec<glib::GString> {
        unsafe {
            let mut length = std::mem::MaybeUninit::uninit();
            let ret = FromGlibContainer::from_glib_full_num(
                ffi::gtk_recent_info_get_applications(self.to_glib_none().0, length.as_mut_ptr()),
                length.assume_init() as _,
            );
            ret
        }
    }

    /// Gets the (short) description of the resource.
    ///
    /// # Returns
    ///
    /// the description of the resource. The returned string
    ///   is owned by the recent manager, and should not be freed.
    #[doc(alias = "gtk_recent_info_get_description")]
    #[doc(alias = "get_description")]
    pub fn description(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gtk_recent_info_get_description(self.to_glib_none().0)) }
    }

    /// Gets the name of the resource.
    ///
    /// If none has been defined, the basename
    /// of the resource is obtained.
    ///
    /// # Returns
    ///
    /// the display name of the resource. The returned string
    ///   is owned by the recent manager, and should not be freed.
    #[doc(alias = "gtk_recent_info_get_display_name")]
    #[doc(alias = "get_display_name")]
    pub fn display_name(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gtk_recent_info_get_display_name(self.to_glib_none().0)) }
    }

    /// Retrieves the icon associated to the resource MIME type.
    ///
    /// # Returns
    ///
    /// a `GIcon` containing the icon
    #[doc(alias = "gtk_recent_info_get_gicon")]
    #[doc(alias = "get_gicon")]
    pub fn gicon(&self) -> Option<gio::Icon> {
        unsafe { from_glib_full(ffi::gtk_recent_info_get_gicon(self.to_glib_none().0)) }
    }

    /// Returns all groups registered for the recently used item @self.
    ///
    /// The array of returned group names will be [`None`] terminated, so
    /// length might optionally be [`None`].
    ///
    /// # Returns
    ///
    ///
    ///   a newly allocated [`None`] terminated array of strings.
    ///   Use g_strfreev() to free it.
    #[doc(alias = "gtk_recent_info_get_groups")]
    #[doc(alias = "get_groups")]
    pub fn groups(&self) -> Vec<glib::GString> {
        unsafe {
            let mut length = std::mem::MaybeUninit::uninit();
            let ret = FromGlibContainer::from_glib_full_num(
                ffi::gtk_recent_info_get_groups(self.to_glib_none().0, length.as_mut_ptr()),
                length.assume_init() as _,
            );
            ret
        }
    }

    /// Gets the MIME type of the resource.
    ///
    /// # Returns
    ///
    /// the MIME type of the resource. The returned string
    ///   is owned by the recent manager, and should not be freed.
    #[doc(alias = "gtk_recent_info_get_mime_type")]
    #[doc(alias = "get_mime_type")]
    pub fn mime_type(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gtk_recent_info_get_mime_type(self.to_glib_none().0)) }
    }

    /// Gets the time when the meta-data
    /// for the resource was last modified.
    ///
    /// # Returns
    ///
    /// a `GDateTime` for the time
    ///   when the resource was last modified
    #[doc(alias = "gtk_recent_info_get_modified")]
    #[doc(alias = "get_modified")]
    pub fn modified(&self) -> glib::DateTime {
        unsafe { from_glib_none(ffi::gtk_recent_info_get_modified(self.to_glib_none().0)) }
    }

    /// Gets the value of the “private” flag.
    ///
    /// Resources in the recently used list that have this flag
    /// set to [`true`] should only be displayed by the applications
    /// that have registered them.
    ///
    /// # Returns
    ///
    /// [`true`] if the private flag was found, [`false`] otherwise
    #[doc(alias = "gtk_recent_info_get_private_hint")]
    #[doc(alias = "get_private_hint")]
    pub fn is_private_hint(&self) -> bool {
        unsafe { from_glib(ffi::gtk_recent_info_get_private_hint(self.to_glib_none().0)) }
    }

    /// Computes a valid UTF-8 string that can be used as the
    /// name of the item in a menu or list.
    ///
    /// For example, calling this function on an item that refers
    /// to “file:///foo/bar.txt” will yield “bar.txt”.
    ///
    /// # Returns
    ///
    /// A newly-allocated string in UTF-8 encoding
    ///   free it with g_free()
    #[doc(alias = "gtk_recent_info_get_short_name")]
    #[doc(alias = "get_short_name")]
    pub fn short_name(&self) -> glib::GString {
        unsafe { from_glib_full(ffi::gtk_recent_info_get_short_name(self.to_glib_none().0)) }
    }

    /// Gets the URI of the resource.
    ///
    /// # Returns
    ///
    /// the URI of the resource. The returned string is
    ///   owned by the recent manager, and should not be freed.
    #[doc(alias = "gtk_recent_info_get_uri")]
    #[doc(alias = "get_uri")]
    pub fn uri(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::gtk_recent_info_get_uri(self.to_glib_none().0)) }
    }

    /// Gets a displayable version of the resource’s URI.
    ///
    /// If the resource is local, it returns a local path; if the
    /// resource is not local, it returns the UTF-8 encoded content
    /// of [`uri()`][Self::uri()].
    ///
    /// # Returns
    ///
    /// a newly allocated UTF-8 string containing the
    ///   resource’s URI or [`None`]. Use g_free() when done using it.
    #[doc(alias = "gtk_recent_info_get_uri_display")]
    #[doc(alias = "get_uri_display")]
    pub fn uri_display(&self) -> Option<glib::GString> {
        unsafe { from_glib_full(ffi::gtk_recent_info_get_uri_display(self.to_glib_none().0)) }
    }

    /// Gets the time when the meta-data
    /// for the resource was last visited.
    ///
    /// # Returns
    ///
    /// a `GDateTime` for the time
    ///    when the resource was last visited
    #[doc(alias = "gtk_recent_info_get_visited")]
    #[doc(alias = "get_visited")]
    pub fn visited(&self) -> glib::DateTime {
        unsafe { from_glib_none(ffi::gtk_recent_info_get_visited(self.to_glib_none().0)) }
    }

    /// Checks whether an application registered this resource using @app_name.
    /// ## `app_name`
    /// a string containing an application name
    ///
    /// # Returns
    ///
    /// [`true`] if an application with name @app_name was found,
    ///   [`false`] otherwise
    #[doc(alias = "gtk_recent_info_has_application")]
    pub fn has_application(&self, app_name: &str) -> bool {
        unsafe {
            from_glib(ffi::gtk_recent_info_has_application(
                self.to_glib_none().0,
                app_name.to_glib_none().0,
            ))
        }
    }

    /// Checks whether @group_name appears inside the groups
    /// registered for the recently used item @self.
    /// ## `group_name`
    /// name of a group
    ///
    /// # Returns
    ///
    /// [`true`] if the group was found
    #[doc(alias = "gtk_recent_info_has_group")]
    pub fn has_group(&self, group_name: &str) -> bool {
        unsafe {
            from_glib(ffi::gtk_recent_info_has_group(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
            ))
        }
    }

    /// Checks whether the resource is local or not by looking at the
    /// scheme of its URI.
    ///
    /// # Returns
    ///
    /// [`true`] if the resource is local
    #[doc(alias = "gtk_recent_info_is_local")]
    pub fn is_local(&self) -> bool {
        unsafe { from_glib(ffi::gtk_recent_info_is_local(self.to_glib_none().0)) }
    }

    /// Gets the name of the last application that have registered the
    /// recently used resource represented by @self.
    ///
    /// # Returns
    ///
    /// an application name. Use g_free() to free it.
    #[doc(alias = "gtk_recent_info_last_application")]
    pub fn last_application(&self) -> glib::GString {
        unsafe { from_glib_full(ffi::gtk_recent_info_last_application(self.to_glib_none().0)) }
    }

    /// Checks whether two [`RecentInfo`][crate::RecentInfo] point to the same resource.
    /// ## `info_b`
    /// a [`RecentInfo`][crate::RecentInfo]
    ///
    /// # Returns
    ///
    /// [`true`] if both [`RecentInfo`][crate::RecentInfo] point to the same
    ///   resource, [`false`] otherwise
    #[doc(alias = "gtk_recent_info_match")]
    #[doc(alias = "match")]
    pub fn match_(&self, info_b: &RecentInfo) -> bool {
        unsafe {
            from_glib(ffi::gtk_recent_info_match(
                self.to_glib_none().0,
                info_b.to_glib_none().0,
            ))
        }
    }
}