gtk4/auto/

recent_manager.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, RecentData, RecentInfo};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// [`RecentManager`][crate::RecentManager] manages and looks up recently used files.
    ///
    /// Each recently used file is identified by its URI, and has meta-data
    /// associated to it, like the names and command lines of the applications
    /// that have registered it, the number of time each application has
    /// registered the same file, the mime type of the file and whether
    /// the file should be displayed only by the applications that have
    /// registered it.
    ///
    /// The recently used files list is per user.
    ///
    /// [`RecentManager`][crate::RecentManager] acts like a database of all the recently
    /// used files. You can create new [`RecentManager`][crate::RecentManager] objects, but
    /// it is more efficient to use the default manager created by GTK.
    ///
    /// Adding a new recently used file is as simple as:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// GtkRecentManager *manager;
    ///
    /// manager = gtk_recent_manager_get_default ();
    /// gtk_recent_manager_add_item (manager, file_uri);
    /// ```
    ///
    /// The [`RecentManager`][crate::RecentManager] will try to gather all the needed information
    /// from the file itself through GIO.
    ///
    /// Looking up the meta-data associated with a recently used file
    /// given its URI requires calling [`RecentManagerExt::lookup_item()`][crate::prelude::RecentManagerExt::lookup_item()]:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// GtkRecentManager *manager;
    /// GtkRecentInfo *info;
    /// GError *error = NULL;
    ///
    /// manager = gtk_recent_manager_get_default ();
    /// info = gtk_recent_manager_lookup_item (manager, file_uri, &error);
    /// if (error)
    ///   {
    ///     g_warning ("Could not find the file: %s", error->message);
    ///     g_error_free (error);
    ///   }
    /// else
    ///  {
    ///    // Use the info object
    ///    gtk_recent_info_unref (info);
    ///  }
    /// ```
    ///
    /// In order to retrieve the list of recently used files, you can use
    /// [`RecentManagerExt::items()`][crate::prelude::RecentManagerExt::items()], which returns a list of
    /// [`RecentInfo`][crate::RecentInfo].
    ///
    /// Note that the maximum age of the recently used files list is
    /// controllable through the [`gtk-recent-files-max-age`][struct@crate::Settings#gtk-recent-files-max-age]
    /// property.
    ///
    /// ## Properties
    ///
    ///
    /// #### `filename`
    ///  The full path to the file to be used to store and read the
    /// recently used resources list
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `size`
    ///  The size of the recently used resources list.
    ///
    /// Readable
    ///
    /// ## Signals
    ///
    ///
    /// #### `changed`
    ///  Emitted when the current recently used resources manager changes
    /// its contents.
    ///
    /// This can happen either by calling [`RecentManagerExt::add_item()`][crate::prelude::RecentManagerExt::add_item()]
    /// or by another application.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`RecentManagerExt`][trait@crate::prelude::RecentManagerExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GtkRecentManager")]
    pub struct RecentManager(Object<ffi::GtkRecentManager, ffi::GtkRecentManagerClass>);

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

impl RecentManager {
    pub const NONE: Option<&'static RecentManager> = None;

    /// Creates a new recent manager object.
    ///
    /// Recent manager objects are used to handle the list of recently used
    /// resources. A [`RecentManager`][crate::RecentManager] object monitors the recently used
    /// resources list, and emits the [`changed`][struct@crate::RecentManager#changed]
    /// signal each time something inside the list changes.
    ///
    /// [`RecentManager`][crate::RecentManager] objects are expensive: be sure to create them
    /// only when needed. You should use [`default()`][Self::default()]
    /// instead.
    ///
    /// # Returns
    ///
    /// A newly created [`RecentManager`][crate::RecentManager] object
    #[doc(alias = "gtk_recent_manager_new")]
    pub fn new() -> RecentManager {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gtk_recent_manager_new()) }
    }

    /// Gets a unique instance of [`RecentManager`][crate::RecentManager] that you can share
    /// in your application without caring about memory management.
    ///
    /// # Returns
    ///
    /// A unique [`RecentManager`][crate::RecentManager]. Do not ref or
    ///   unref it.
    #[doc(alias = "gtk_recent_manager_get_default")]
    #[doc(alias = "get_default")]
    #[allow(clippy::should_implement_trait)]
    pub fn default() -> RecentManager {
        assert_initialized_main_thread!();
        unsafe { from_glib_none(ffi::gtk_recent_manager_get_default()) }
    }
}

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

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::RecentManager>> Sealed for T {}
}

/// Trait containing all [`struct@RecentManager`] methods.
///
/// # Implementors
///
/// [`RecentManager`][struct@crate::RecentManager]
pub trait RecentManagerExt: IsA<RecentManager> + sealed::Sealed + 'static {
    /// Adds a new resource, pointed by @uri, into the recently used
    /// resources list, using the metadata specified inside the
    /// [`RecentData`][crate::RecentData] passed in @recent_data.
    ///
    /// The passed URI will be used to identify this resource inside the
    /// list.
    ///
    /// In order to register the new recently used resource, metadata about
    /// the resource must be passed as well as the URI; the metadata is
    /// stored in a [`RecentData`][crate::RecentData], which must contain the MIME
    /// type of the resource pointed by the URI; the name of the application
    /// that is registering the item, and a command line to be used when
    /// launching the item.
    ///
    /// Optionally, a [`RecentData`][crate::RecentData] might contain a UTF-8 string
    /// to be used when viewing the item instead of the last component of
    /// the URI; a short description of the item; whether the item should
    /// be considered private - that is, should be displayed only by the
    /// applications that have registered it.
    /// ## `uri`
    /// a valid URI
    /// ## `recent_data`
    /// metadata of the resource
    ///
    /// # Returns
    ///
    /// [`true`] if the new item was successfully added to the
    ///   recently used resources list, [`false`] otherwise
    #[doc(alias = "gtk_recent_manager_add_full")]
    fn add_full(&self, uri: &str, recent_data: &RecentData) -> bool {
        unsafe {
            from_glib(ffi::gtk_recent_manager_add_full(
                self.as_ref().to_glib_none().0,
                uri.to_glib_none().0,
                recent_data.to_glib_none().0,
            ))
        }
    }

    /// Adds a new resource, pointed by @uri, into the recently used
    /// resources list.
    ///
    /// This function automatically retrieves some of the needed
    /// metadata and setting other metadata to common default values;
    /// it then feeds the data to [`add_full()`][Self::add_full()].
    ///
    /// See [`add_full()`][Self::add_full()] if you want to explicitly
    /// define the metadata for the resource pointed by @uri.
    /// ## `uri`
    /// a valid URI
    ///
    /// # Returns
    ///
    /// [`true`] if the new item was successfully added
    ///   to the recently used resources list
    #[doc(alias = "gtk_recent_manager_add_item")]
    fn add_item(&self, uri: &str) -> bool {
        unsafe {
            from_glib(ffi::gtk_recent_manager_add_item(
                self.as_ref().to_glib_none().0,
                uri.to_glib_none().0,
            ))
        }
    }

    /// Gets the list of recently used resources.
    ///
    /// # Returns
    ///
    /// a list of
    ///   newly allocated `GtkRecentInfo objects`. Use
    ///   `Gtk::RecentInfo::unref()` on each item inside the list, and then
    ///   free the list itself using g_list_free().
    #[doc(alias = "gtk_recent_manager_get_items")]
    #[doc(alias = "get_items")]
    fn items(&self) -> Vec<RecentInfo> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::gtk_recent_manager_get_items(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Checks whether there is a recently used resource registered
    /// with @uri inside the recent manager.
    /// ## `uri`
    /// a URI
    ///
    /// # Returns
    ///
    /// [`true`] if the resource was found, [`false`] otherwise
    #[doc(alias = "gtk_recent_manager_has_item")]
    fn has_item(&self, uri: &str) -> bool {
        unsafe {
            from_glib(ffi::gtk_recent_manager_has_item(
                self.as_ref().to_glib_none().0,
                uri.to_glib_none().0,
            ))
        }
    }

    /// Searches for a URI inside the recently used resources list, and
    /// returns a [`RecentInfo`][crate::RecentInfo] containing information about the resource
    /// like its MIME type, or its display name.
    /// ## `uri`
    /// a URI
    ///
    /// # Returns
    ///
    /// a [`RecentInfo`][crate::RecentInfo] containing information
    ///   about the resource pointed by @uri, or [`None`] if the URI was
    ///   not registered in the recently used resources list. Free with
    ///   `Gtk::RecentInfo::unref()`.
    #[doc(alias = "gtk_recent_manager_lookup_item")]
    fn lookup_item(&self, uri: &str) -> Result<Option<RecentInfo>, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gtk_recent_manager_lookup_item(
                self.as_ref().to_glib_none().0,
                uri.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Changes the location of a recently used resource from @uri to @new_uri.
    ///
    /// Please note that this function will not affect the resource pointed
    /// by the URIs, but only the URI used in the recently used resources list.
    /// ## `uri`
    /// the URI of a recently used resource
    /// ## `new_uri`
    /// the new URI of the recently used resource, or
    ///    [`None`] to remove the item pointed by @uri in the list
    ///
    /// # Returns
    ///
    /// [`true`] on success
    #[doc(alias = "gtk_recent_manager_move_item")]
    fn move_item(&self, uri: &str, new_uri: Option<&str>) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::gtk_recent_manager_move_item(
                self.as_ref().to_glib_none().0,
                uri.to_glib_none().0,
                new_uri.to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Purges every item from the recently used resources list.
    ///
    /// # Returns
    ///
    /// the number of items that have been removed from the
    ///   recently used resources list
    #[doc(alias = "gtk_recent_manager_purge_items")]
    fn purge_items(&self) -> Result<i32, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret =
                ffi::gtk_recent_manager_purge_items(self.as_ref().to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(ret)
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Removes a resource pointed by @uri from the recently used resources
    /// list handled by a recent manager.
    /// ## `uri`
    /// the URI of the item you wish to remove
    ///
    /// # Returns
    ///
    /// [`true`] if the item pointed by @uri has been successfully
    ///   removed by the recently used resources list, and [`false`] otherwise
    #[doc(alias = "gtk_recent_manager_remove_item")]
    fn remove_item(&self, uri: &str) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::gtk_recent_manager_remove_item(
                self.as_ref().to_glib_none().0,
                uri.to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// The full path to the file to be used to store and read the
    /// recently used resources list
    fn filename(&self) -> Option<glib::GString> {
        ObjectExt::property(self.as_ref(), "filename")
    }

    /// The size of the recently used resources list.
    fn size(&self) -> i32 {
        ObjectExt::property(self.as_ref(), "size")
    }

    /// Emitted when the current recently used resources manager changes
    /// its contents.
    ///
    /// This can happen either by calling [`add_item()`][Self::add_item()]
    /// or by another application.
    #[doc(alias = "changed")]
    fn connect_changed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn changed_trampoline<P: IsA<RecentManager>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkRecentManager,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(RecentManager::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"changed\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    changed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "size")]
    fn connect_size_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_size_trampoline<P: IsA<RecentManager>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkRecentManager,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(RecentManager::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::size\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_size_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<RecentManager>> RecentManagerExt for O {}