gtk4/auto/
recent_manager.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, RecentData, RecentInfo};
6use glib::{
7    object::ObjectType as _,
8    prelude::*,
9    signal::{connect_raw, SignalHandlerId},
10    translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15    /// [`RecentManager`][crate::RecentManager] manages and looks up recently used files.
16    ///
17    /// Each recently used file is identified by its URI, and has meta-data
18    /// associated to it, like the names and command lines of the applications
19    /// that have registered it, the number of time each application has
20    /// registered the same file, the mime type of the file and whether
21    /// the file should be displayed only by the applications that have
22    /// registered it.
23    ///
24    /// The recently used files list is per user.
25    ///
26    /// [`RecentManager`][crate::RecentManager] acts like a database of all the recently
27    /// used files. You can create new [`RecentManager`][crate::RecentManager] objects, but
28    /// it is more efficient to use the default manager created by GTK.
29    ///
30    /// Adding a new recently used file is as simple as:
31    ///
32    /// **⚠️ The following code is in c ⚠️**
33    ///
34    /// ```c
35    /// GtkRecentManager *manager;
36    ///
37    /// manager = gtk_recent_manager_get_default ();
38    /// gtk_recent_manager_add_item (manager, file_uri);
39    /// ```
40    ///
41    /// The [`RecentManager`][crate::RecentManager] will try to gather all the needed information
42    /// from the file itself through GIO.
43    ///
44    /// Looking up the meta-data associated with a recently used file
45    /// given its URI requires calling [`RecentManagerExt::lookup_item()`][crate::prelude::RecentManagerExt::lookup_item()]:
46    ///
47    /// **⚠️ The following code is in c ⚠️**
48    ///
49    /// ```c
50    /// GtkRecentManager *manager;
51    /// GtkRecentInfo *info;
52    /// GError *error = NULL;
53    ///
54    /// manager = gtk_recent_manager_get_default ();
55    /// info = gtk_recent_manager_lookup_item (manager, file_uri, &error);
56    /// if (error)
57    ///   {
58    ///     g_warning ("Could not find the file: %s", error->message);
59    ///     g_error_free (error);
60    ///   }
61    /// else
62    ///  {
63    ///    // Use the info object
64    ///    gtk_recent_info_unref (info);
65    ///  }
66    /// ```
67    ///
68    /// In order to retrieve the list of recently used files, you can use
69    /// [`RecentManagerExt::items()`][crate::prelude::RecentManagerExt::items()], which returns a list of
70    /// [`RecentInfo`][crate::RecentInfo].
71    ///
72    /// Note that the maximum age of the recently used files list is
73    /// controllable through the [`gtk-recent-files-max-age`][struct@crate::Settings#gtk-recent-files-max-age]
74    /// property.
75    ///
76    /// ## Properties
77    ///
78    ///
79    /// #### `filename`
80    ///  The full path to the file to be used to store and read the
81    /// recently used resources list
82    ///
83    /// Readable | Writeable | Construct Only
84    ///
85    ///
86    /// #### `size`
87    ///  The size of the recently used resources list.
88    ///
89    /// Readable
90    ///
91    /// ## Signals
92    ///
93    ///
94    /// #### `changed`
95    ///  Emitted when the current recently used resources manager changes
96    /// its contents.
97    ///
98    /// This can happen either by calling [`RecentManagerExt::add_item()`][crate::prelude::RecentManagerExt::add_item()]
99    /// or by another application.
100    ///
101    ///
102    ///
103    /// # Implements
104    ///
105    /// [`RecentManagerExt`][trait@crate::prelude::RecentManagerExt], [`trait@glib::ObjectExt`]
106    #[doc(alias = "GtkRecentManager")]
107    pub struct RecentManager(Object<ffi::GtkRecentManager, ffi::GtkRecentManagerClass>);
108
109    match fn {
110        type_ => || ffi::gtk_recent_manager_get_type(),
111    }
112}
113
114impl RecentManager {
115    pub const NONE: Option<&'static RecentManager> = None;
116
117    /// Creates a new recent manager object.
118    ///
119    /// Recent manager objects are used to handle the list of recently used
120    /// resources. A [`RecentManager`][crate::RecentManager] object monitors the recently used
121    /// resources list, and emits the [`changed`][struct@crate::RecentManager#changed]
122    /// signal each time something inside the list changes.
123    ///
124    /// [`RecentManager`][crate::RecentManager] objects are expensive: be sure to create them
125    /// only when needed. You should use [`default()`][Self::default()]
126    /// instead.
127    ///
128    /// # Returns
129    ///
130    /// A newly created [`RecentManager`][crate::RecentManager] object
131    #[doc(alias = "gtk_recent_manager_new")]
132    pub fn new() -> RecentManager {
133        assert_initialized_main_thread!();
134        unsafe { from_glib_full(ffi::gtk_recent_manager_new()) }
135    }
136
137    /// Gets a unique instance of [`RecentManager`][crate::RecentManager] that you can share
138    /// in your application without caring about memory management.
139    ///
140    /// # Returns
141    ///
142    /// A unique [`RecentManager`][crate::RecentManager]. Do not ref or
143    ///   unref it.
144    #[doc(alias = "gtk_recent_manager_get_default")]
145    #[doc(alias = "get_default")]
146    #[allow(clippy::should_implement_trait)]
147    pub fn default() -> RecentManager {
148        assert_initialized_main_thread!();
149        unsafe { from_glib_none(ffi::gtk_recent_manager_get_default()) }
150    }
151}
152
153impl Default for RecentManager {
154    fn default() -> Self {
155        Self::new()
156    }
157}
158
159mod sealed {
160    pub trait Sealed {}
161    impl<T: super::IsA<super::RecentManager>> Sealed for T {}
162}
163
164/// Trait containing all [`struct@RecentManager`] methods.
165///
166/// # Implementors
167///
168/// [`RecentManager`][struct@crate::RecentManager]
169pub trait RecentManagerExt: IsA<RecentManager> + sealed::Sealed + 'static {
170    /// Adds a new resource, pointed by @uri, into the recently used
171    /// resources list, using the metadata specified inside the
172    /// [`RecentData`][crate::RecentData] passed in @recent_data.
173    ///
174    /// The passed URI will be used to identify this resource inside the
175    /// list.
176    ///
177    /// In order to register the new recently used resource, metadata about
178    /// the resource must be passed as well as the URI; the metadata is
179    /// stored in a [`RecentData`][crate::RecentData], which must contain the MIME
180    /// type of the resource pointed by the URI; the name of the application
181    /// that is registering the item, and a command line to be used when
182    /// launching the item.
183    ///
184    /// Optionally, a [`RecentData`][crate::RecentData] might contain a UTF-8 string
185    /// to be used when viewing the item instead of the last component of
186    /// the URI; a short description of the item; whether the item should
187    /// be considered private - that is, should be displayed only by the
188    /// applications that have registered it.
189    /// ## `uri`
190    /// a valid URI
191    /// ## `recent_data`
192    /// metadata of the resource
193    ///
194    /// # Returns
195    ///
196    /// [`true`] if the new item was successfully added to the
197    ///   recently used resources list, [`false`] otherwise
198    #[doc(alias = "gtk_recent_manager_add_full")]
199    fn add_full(&self, uri: &str, recent_data: &RecentData) -> bool {
200        unsafe {
201            from_glib(ffi::gtk_recent_manager_add_full(
202                self.as_ref().to_glib_none().0,
203                uri.to_glib_none().0,
204                recent_data.to_glib_none().0,
205            ))
206        }
207    }
208
209    /// Adds a new resource, pointed by @uri, into the recently used
210    /// resources list.
211    ///
212    /// This function automatically retrieves some of the needed
213    /// metadata and setting other metadata to common default values;
214    /// it then feeds the data to [`add_full()`][Self::add_full()].
215    ///
216    /// See [`add_full()`][Self::add_full()] if you want to explicitly
217    /// define the metadata for the resource pointed by @uri.
218    /// ## `uri`
219    /// a valid URI
220    ///
221    /// # Returns
222    ///
223    /// [`true`] if the new item was successfully added
224    ///   to the recently used resources list
225    #[doc(alias = "gtk_recent_manager_add_item")]
226    fn add_item(&self, uri: &str) -> bool {
227        unsafe {
228            from_glib(ffi::gtk_recent_manager_add_item(
229                self.as_ref().to_glib_none().0,
230                uri.to_glib_none().0,
231            ))
232        }
233    }
234
235    /// Gets the list of recently used resources.
236    ///
237    /// # Returns
238    ///
239    /// a list of
240    ///   newly allocated `GtkRecentInfo objects`. Use
241    ///   `Gtk::RecentInfo::unref()` on each item inside the list, and then
242    ///   free the list itself using g_list_free().
243    #[doc(alias = "gtk_recent_manager_get_items")]
244    #[doc(alias = "get_items")]
245    fn items(&self) -> Vec<RecentInfo> {
246        unsafe {
247            FromGlibPtrContainer::from_glib_full(ffi::gtk_recent_manager_get_items(
248                self.as_ref().to_glib_none().0,
249            ))
250        }
251    }
252
253    /// Checks whether there is a recently used resource registered
254    /// with @uri inside the recent manager.
255    /// ## `uri`
256    /// a URI
257    ///
258    /// # Returns
259    ///
260    /// [`true`] if the resource was found, [`false`] otherwise
261    #[doc(alias = "gtk_recent_manager_has_item")]
262    fn has_item(&self, uri: &str) -> bool {
263        unsafe {
264            from_glib(ffi::gtk_recent_manager_has_item(
265                self.as_ref().to_glib_none().0,
266                uri.to_glib_none().0,
267            ))
268        }
269    }
270
271    /// Searches for a URI inside the recently used resources list, and
272    /// returns a [`RecentInfo`][crate::RecentInfo] containing information about the resource
273    /// like its MIME type, or its display name.
274    /// ## `uri`
275    /// a URI
276    ///
277    /// # Returns
278    ///
279    /// a [`RecentInfo`][crate::RecentInfo] containing information
280    ///   about the resource pointed by @uri, or [`None`] if the URI was
281    ///   not registered in the recently used resources list. Free with
282    ///   `Gtk::RecentInfo::unref()`.
283    #[doc(alias = "gtk_recent_manager_lookup_item")]
284    fn lookup_item(&self, uri: &str) -> Result<Option<RecentInfo>, glib::Error> {
285        unsafe {
286            let mut error = std::ptr::null_mut();
287            let ret = ffi::gtk_recent_manager_lookup_item(
288                self.as_ref().to_glib_none().0,
289                uri.to_glib_none().0,
290                &mut error,
291            );
292            if error.is_null() {
293                Ok(from_glib_full(ret))
294            } else {
295                Err(from_glib_full(error))
296            }
297        }
298    }
299
300    /// Changes the location of a recently used resource from @uri to @new_uri.
301    ///
302    /// Please note that this function will not affect the resource pointed
303    /// by the URIs, but only the URI used in the recently used resources list.
304    /// ## `uri`
305    /// the URI of a recently used resource
306    /// ## `new_uri`
307    /// the new URI of the recently used resource, or
308    ///    [`None`] to remove the item pointed by @uri in the list
309    ///
310    /// # Returns
311    ///
312    /// [`true`] on success
313    #[doc(alias = "gtk_recent_manager_move_item")]
314    fn move_item(&self, uri: &str, new_uri: Option<&str>) -> Result<(), glib::Error> {
315        unsafe {
316            let mut error = std::ptr::null_mut();
317            let is_ok = ffi::gtk_recent_manager_move_item(
318                self.as_ref().to_glib_none().0,
319                uri.to_glib_none().0,
320                new_uri.to_glib_none().0,
321                &mut error,
322            );
323            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
324            if error.is_null() {
325                Ok(())
326            } else {
327                Err(from_glib_full(error))
328            }
329        }
330    }
331
332    /// Purges every item from the recently used resources list.
333    ///
334    /// # Returns
335    ///
336    /// the number of items that have been removed from the
337    ///   recently used resources list
338    #[doc(alias = "gtk_recent_manager_purge_items")]
339    fn purge_items(&self) -> Result<i32, glib::Error> {
340        unsafe {
341            let mut error = std::ptr::null_mut();
342            let ret =
343                ffi::gtk_recent_manager_purge_items(self.as_ref().to_glib_none().0, &mut error);
344            if error.is_null() {
345                Ok(ret)
346            } else {
347                Err(from_glib_full(error))
348            }
349        }
350    }
351
352    /// Removes a resource pointed by @uri from the recently used resources
353    /// list handled by a recent manager.
354    /// ## `uri`
355    /// the URI of the item you wish to remove
356    ///
357    /// # Returns
358    ///
359    /// [`true`] if the item pointed by @uri has been successfully
360    ///   removed by the recently used resources list, and [`false`] otherwise
361    #[doc(alias = "gtk_recent_manager_remove_item")]
362    fn remove_item(&self, uri: &str) -> Result<(), glib::Error> {
363        unsafe {
364            let mut error = std::ptr::null_mut();
365            let is_ok = ffi::gtk_recent_manager_remove_item(
366                self.as_ref().to_glib_none().0,
367                uri.to_glib_none().0,
368                &mut error,
369            );
370            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
371            if error.is_null() {
372                Ok(())
373            } else {
374                Err(from_glib_full(error))
375            }
376        }
377    }
378
379    /// The full path to the file to be used to store and read the
380    /// recently used resources list
381    fn filename(&self) -> Option<glib::GString> {
382        ObjectExt::property(self.as_ref(), "filename")
383    }
384
385    /// The size of the recently used resources list.
386    fn size(&self) -> i32 {
387        ObjectExt::property(self.as_ref(), "size")
388    }
389
390    /// Emitted when the current recently used resources manager changes
391    /// its contents.
392    ///
393    /// This can happen either by calling [`add_item()`][Self::add_item()]
394    /// or by another application.
395    #[doc(alias = "changed")]
396    fn connect_changed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
397        unsafe extern "C" fn changed_trampoline<P: IsA<RecentManager>, F: Fn(&P) + 'static>(
398            this: *mut ffi::GtkRecentManager,
399            f: glib::ffi::gpointer,
400        ) {
401            let f: &F = &*(f as *const F);
402            f(RecentManager::from_glib_borrow(this).unsafe_cast_ref())
403        }
404        unsafe {
405            let f: Box_<F> = Box_::new(f);
406            connect_raw(
407                self.as_ptr() as *mut _,
408                b"changed\0".as_ptr() as *const _,
409                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
410                    changed_trampoline::<Self, F> as *const (),
411                )),
412                Box_::into_raw(f),
413            )
414        }
415    }
416
417    #[doc(alias = "size")]
418    fn connect_size_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
419        unsafe extern "C" fn notify_size_trampoline<P: IsA<RecentManager>, F: Fn(&P) + 'static>(
420            this: *mut ffi::GtkRecentManager,
421            _param_spec: glib::ffi::gpointer,
422            f: glib::ffi::gpointer,
423        ) {
424            let f: &F = &*(f as *const F);
425            f(RecentManager::from_glib_borrow(this).unsafe_cast_ref())
426        }
427        unsafe {
428            let f: Box_<F> = Box_::new(f);
429            connect_raw(
430                self.as_ptr() as *mut _,
431                b"notify::size\0".as_ptr() as *const _,
432                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
433                    notify_size_trampoline::<Self, F> as *const (),
434                )),
435                Box_::into_raw(f),
436            )
437        }
438    }
439}
440
441impl<O: IsA<RecentManager>> RecentManagerExt for O {}