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

gtk/auto/
recent_manager.rs
