gtk/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::{RecentData, RecentInfo, ffi};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// [`RecentManager`][crate::RecentManager] provides a facility for adding, removing and
    /// looking 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.
    ///
    /// The [`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]-structs.
    ///
    /// A [`RecentManager`][crate::RecentManager] is the model used to populate the contents of
    /// one, or more [`RecentChooser`][crate::RecentChooser] implementations.
    ///
    /// 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.
    ///
    /// Recently used files are supported since GTK+ 2.10.
    ///
    /// ## Properties
    ///
    ///
    /// #### `filename`
    ///  The full path to the file to be used to store and read the
    /// recently used resources list
    ///
    /// Readable | Writable | 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, 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” 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()) }
    }

    // rustdoc-stripper-ignore-next
    /// Creates a new builder-pattern struct instance to construct [`RecentManager`] objects.
    ///
    /// This method returns an instance of [`RecentManagerBuilder`](crate::builders::RecentManagerBuilder) which can be used to create [`RecentManager`] objects.
    pub fn builder() -> RecentManagerBuilder {
        RecentManagerBuilder::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() -> Option<RecentManager> {
        assert_initialized_main_thread!();
        unsafe { from_glib_none(ffi::gtk_recent_manager_get_default()) }
    }
}

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

// rustdoc-stripper-ignore-next
/// A [builder-pattern] type to construct [`RecentManager`] objects.
///
/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
#[must_use = "The builder must be built to be used"]
pub struct RecentManagerBuilder {
    builder: glib::object::ObjectBuilder<'static, RecentManager>,
}

impl RecentManagerBuilder {
    fn new() -> Self {
        Self {
            builder: glib::object::Object::builder(),
        }
    }

    /// The full path to the file to be used to store and read the
    /// recently used resources list
    pub fn filename(self, filename: impl Into<glib::GString>) -> Self {
        Self {
            builder: self.builder.property("filename", filename.into()),
        }
    }

    // rustdoc-stripper-ignore-next
    /// Build the [`RecentManager`].
    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
    pub fn build(self) -> RecentManager {
        assert_initialized_main_thread!();
        self.builder.build()
    }
}

/// Trait containing all [`struct@RecentManager`] methods.
///
/// # Implementors
///
/// [`RecentManager`][struct@crate::RecentManager]
pub trait RecentManagerExt: IsA<RecentManager> + 'static {
    /// Adds a new resource, pointed by `uri`, into the recently used
    /// resources list, using the metadata specified inside the
    /// [`RecentData`][crate::RecentData]-struct 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]-struct, 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]-struct 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 [`RecentInfo`][crate::RecentInfo] objects. Use
    ///  `gtk_recent_info_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]-struct containing informations about the resource
    /// like its MIME type, or its display name.
    /// ## `uri`
    /// a URI
    ///
    /// # Returns
    ///
    /// a [`RecentInfo`][crate::RecentInfo]-struct 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_recent_info_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, 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,
        ) {
            unsafe {
                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 _,
                c"changed".as_ptr(),
                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,
        ) {
            unsafe {
                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 _,
                c"notify::size".as_ptr(),
                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 {}