gtk/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]-struct contains private data only, and should
    /// be accessed using the provided API.
    ///
    /// [`RecentInfo`][crate::RecentInfo] constains all the meta-data
    /// associated with an entry 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 [`gio::AppInfo`][crate::gio::AppInfo] for the specified [`RecentInfo`][crate::RecentInfo]
    /// ## `app_name`
    /// the name of the application that should
    ///  be mapped to a [`gio::AppInfo`][crate::gio::AppInfo]; if [`None`] is used then the default
    ///  application for the MIME type is used
    ///
    /// # Returns
    ///
    /// the newly created [`gio::AppInfo`][crate::gio::AppInfo], or [`None`].
    ///  In case of error, `error` will be set either with a
    ///  `GTK_RECENT_MANAGER_ERROR` or a `G_IO_ERROR`
    #[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 timestamp (seconds from system’s Epoch) when the resource
    /// was added to the recently used resources list.
    ///
    /// # Returns
    ///
    /// the number of seconds elapsed from system’s Epoch when
    ///  the resource was added to the list, or -1 on failure.
    #[doc(alias = "gtk_recent_info_get_added")]
    #[doc(alias = "get_added")]
    pub fn added(&self) -> libc::time_t {
        unsafe { 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
    ///
    /// ## `time_`
    /// return location for the timestamp 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, libc::time_t)> {
        unsafe {
            let mut app_exec = std::ptr::null();
            let mut count = std::mem::MaybeUninit::uninit();
            let mut time_ = std::mem::MaybeUninit::uninit();
            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(),
                time_.as_mut_ptr(),
            ));
            if ret {
                Some((
                    from_glib_none(app_exec),
                    count.assume_init(),
                    time_.assume_init(),
                ))
            } 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) -> Option<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) -> Option<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 [`gio::Icon`][crate::gio::Icon] containing the icon, or [`None`].
    ///  Use `g_object_unref()` when finished using 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
        }
    }

    /// Retrieves the icon of size `size` associated to the resource MIME type.
    /// ## `size`
    /// the size of the icon in pixels
    ///
    /// # Returns
    ///
    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf] containing the icon,
    ///  or [`None`]. Use `g_object_unref()` when finished using the icon.
    #[doc(alias = "gtk_recent_info_get_icon")]
    #[doc(alias = "get_icon")]
    pub fn icon(&self, size: i32) -> Option<gdk_pixbuf::Pixbuf> {
        unsafe { from_glib_full(ffi::gtk_recent_info_get_icon(self.to_glib_none().0, size)) }
    }

    /// 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) -> Option<glib::GString> {
        unsafe { from_glib_none(ffi::gtk_recent_info_get_mime_type(self.to_glib_none().0)) }
    }

    /// Gets the timestamp (seconds from system’s Epoch) when the meta-data
    /// for the resource was last modified.
    ///
    /// # Returns
    ///
    /// the number of seconds elapsed from system’s Epoch when
    ///  the resource was last modified, or -1 on failure.
    #[doc(alias = "gtk_recent_info_get_modified")]
    #[doc(alias = "get_modified")]
    pub fn modified(&self) -> libc::time_t {
        unsafe { 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) -> Option<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) -> Option<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 timestamp (seconds from system’s Epoch) when the meta-data
    /// for the resource was last visited.
    ///
    /// # Returns
    ///
    /// the number of seconds elapsed from system’s Epoch when
    ///  the resource was last visited, or -1 on failure.
    #[doc(alias = "gtk_recent_info_get_visited")]
    #[doc(alias = "get_visited")]
    pub fn visited(&self) -> libc::time_t {
        unsafe { 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) -> Option<glib::GString> {
        unsafe { from_glib_full(ffi::gtk_recent_info_last_application(self.to_glib_none().0)) }
    }

    /// Checks whether two [`RecentInfo`][crate::RecentInfo]-struct point to the same
    /// resource.
    /// ## `info_b`
    /// a [`RecentInfo`][crate::RecentInfo]
    ///
    /// # Returns
    ///
    /// [`true`] if both [`RecentInfo`][crate::RecentInfo]-struct 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,
            ))
        }
    }
}