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 {}