gio/auto/
desktop_app_info.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, AppInfo, AppLaunchContext};
6use glib::{prelude::*, translate::*};
7use std::boxed::Box as Box_;
8
9glib::wrapper! {
10    /// `GDesktopAppInfo` is an implementation of [`AppInfo`][crate::AppInfo] based on
11    /// desktop files.
12    ///
13    /// Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
14    /// GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
15    /// file or the `GioUnix-2.0` GIR namespace when using it.
16    ///
17    /// ## Properties
18    ///
19    ///
20    /// #### `filename`
21    ///  The origin filename of this [`DesktopAppInfo`][crate::DesktopAppInfo]
22    ///
23    /// Readable | Writeable | Construct Only
24    ///
25    /// # Implements
26    ///
27    /// [`trait@glib::ObjectExt`], [`AppInfoExt`][trait@crate::prelude::AppInfoExt], [`DesktopAppInfoExtManual`][trait@crate::prelude::DesktopAppInfoExtManual], [`AppInfoExtManual`][trait@crate::prelude::AppInfoExtManual]
28    #[doc(alias = "GDesktopAppInfo")]
29    pub struct DesktopAppInfo(Object<ffi::GDesktopAppInfo, ffi::GDesktopAppInfoClass>) @implements AppInfo;
30
31    match fn {
32        type_ => || ffi::g_desktop_app_info_get_type(),
33    }
34}
35
36impl DesktopAppInfo {
37    /// Creates a new [`DesktopAppInfo`][crate::DesktopAppInfo] based on a desktop file ID.
38    ///
39    /// A desktop file ID is the basename of the desktop file, including the
40    /// `.desktop` extension. GIO is looking for a desktop file with this name
41    /// in the `applications` subdirectories of the XDG
42    /// data directories (i.e. the directories specified in the `XDG_DATA_HOME`
43    /// and `XDG_DATA_DIRS` environment variables). GIO also supports the
44    /// prefix-to-subdirectory mapping that is described in the
45    /// [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/)
46    /// (i.e. a desktop ID of `kde-foo.desktop` will match
47    /// `/usr/share/applications/kde/foo.desktop`).
48    /// ## `desktop_id`
49    /// the desktop file ID
50    ///
51    /// # Returns
52    ///
53    /// a new [`DesktopAppInfo`][crate::DesktopAppInfo], or `NULL` if no
54    ///    desktop file with that ID exists.
55    #[doc(alias = "g_desktop_app_info_new")]
56    pub fn new(desktop_id: &str) -> Option<DesktopAppInfo> {
57        unsafe { from_glib_full(ffi::g_desktop_app_info_new(desktop_id.to_glib_none().0)) }
58    }
59
60    /// Creates a new [`DesktopAppInfo`][crate::DesktopAppInfo].
61    /// ## `filename`
62    /// the path of a desktop file, in the GLib
63    ///      filename encoding
64    ///
65    /// # Returns
66    ///
67    /// a new [`DesktopAppInfo`][crate::DesktopAppInfo] or `NULL` on error.
68    #[doc(alias = "g_desktop_app_info_new_from_filename")]
69    #[doc(alias = "new_from_filename")]
70    pub fn from_filename(filename: impl AsRef<std::path::Path>) -> Option<DesktopAppInfo> {
71        unsafe {
72            from_glib_full(ffi::g_desktop_app_info_new_from_filename(
73                filename.as_ref().to_glib_none().0,
74            ))
75        }
76    }
77
78    /// Creates a new [`DesktopAppInfo`][crate::DesktopAppInfo].
79    /// ## `key_file`
80    /// an opened [type@GLib.KeyFile]
81    ///
82    /// # Returns
83    ///
84    /// a new [`DesktopAppInfo`][crate::DesktopAppInfo] or `NULL` on error.
85    #[doc(alias = "g_desktop_app_info_new_from_keyfile")]
86    #[doc(alias = "new_from_keyfile")]
87    pub fn from_keyfile(key_file: &glib::KeyFile) -> Option<DesktopAppInfo> {
88        unsafe {
89            from_glib_full(ffi::g_desktop_app_info_new_from_keyfile(
90                key_file.to_glib_none().0,
91            ))
92        }
93    }
94
95    /// Gets the user-visible display name of the
96    /// [‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html)
97    /// specified by @action_name.
98    ///
99    /// This corresponds to the `Name` key within the keyfile group for the
100    /// action.
101    /// ## `action_name`
102    /// the name of the action as from
103    ///   [`list_actions()`][Self::list_actions()]
104    ///
105    /// # Returns
106    ///
107    /// the locale-specific action name
108    #[doc(alias = "g_desktop_app_info_get_action_name")]
109    #[doc(alias = "get_action_name")]
110    pub fn action_name(&self, action_name: &str) -> glib::GString {
111        unsafe {
112            from_glib_full(ffi::g_desktop_app_info_get_action_name(
113                self.to_glib_none().0,
114                action_name.to_glib_none().0,
115            ))
116        }
117    }
118
119    /// Looks up a boolean value in the keyfile backing @self.
120    ///
121    /// The @key is looked up in the `Desktop Entry` group.
122    /// ## `key`
123    /// the key to look up
124    ///
125    /// # Returns
126    ///
127    /// the boolean value, or `FALSE` if the key is not found
128    #[doc(alias = "g_desktop_app_info_get_boolean")]
129    #[doc(alias = "get_boolean")]
130    pub fn boolean(&self, key: &str) -> bool {
131        unsafe {
132            from_glib(ffi::g_desktop_app_info_get_boolean(
133                self.to_glib_none().0,
134                key.to_glib_none().0,
135            ))
136        }
137    }
138
139    /// Gets the categories from the desktop file.
140    ///
141    /// # Returns
142    ///
143    /// The unparsed
144    ///   [`Categories` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-categories)
145    ///   from the desktop file;
146    ///   i.e. no attempt is made to split it by `;` or validate it.
147    #[doc(alias = "g_desktop_app_info_get_categories")]
148    #[doc(alias = "get_categories")]
149    pub fn categories(&self) -> Option<glib::GString> {
150        unsafe {
151            from_glib_none(ffi::g_desktop_app_info_get_categories(
152                self.to_glib_none().0,
153            ))
154        }
155    }
156
157    /// When @self was created from a known filename, return it.  In some
158    /// situations such as a [`DesktopAppInfo`][crate::DesktopAppInfo] returned from
159    /// [`from_keyfile()`][Self::from_keyfile()], this function will return `NULL`.
160    ///
161    /// # Returns
162    ///
163    /// The full path to the file for @self,
164    ///   or `NULL` if not known.
165    #[doc(alias = "g_desktop_app_info_get_filename")]
166    #[doc(alias = "get_filename")]
167    pub fn filename(&self) -> Option<std::path::PathBuf> {
168        unsafe { from_glib_none(ffi::g_desktop_app_info_get_filename(self.to_glib_none().0)) }
169    }
170
171    /// Gets the generic name from the desktop file.
172    ///
173    /// # Returns
174    ///
175    /// The value of the
176    ///   [`GenericName` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-genericname)
177    #[doc(alias = "g_desktop_app_info_get_generic_name")]
178    #[doc(alias = "get_generic_name")]
179    pub fn generic_name(&self) -> Option<glib::GString> {
180        unsafe {
181            from_glib_none(ffi::g_desktop_app_info_get_generic_name(
182                self.to_glib_none().0,
183            ))
184        }
185    }
186
187    /// A desktop file is hidden if the
188    /// [`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden)
189    /// in it is set to `True`.
190    ///
191    /// # Returns
192    ///
193    /// `TRUE` if hidden, `FALSE` otherwise.
194    #[doc(alias = "g_desktop_app_info_get_is_hidden")]
195    #[doc(alias = "get_is_hidden")]
196    pub fn is_hidden(&self) -> bool {
197        unsafe { from_glib(ffi::g_desktop_app_info_get_is_hidden(self.to_glib_none().0)) }
198    }
199
200    /// Gets the keywords from the desktop file.
201    ///
202    /// # Returns
203    ///
204    /// The value of the
205    ///   [`Keywords` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-keywords)
206    #[doc(alias = "g_desktop_app_info_get_keywords")]
207    #[doc(alias = "get_keywords")]
208    pub fn keywords(&self) -> Vec<glib::GString> {
209        unsafe {
210            FromGlibPtrContainer::from_glib_none(ffi::g_desktop_app_info_get_keywords(
211                self.to_glib_none().0,
212            ))
213        }
214    }
215
216    /// Looks up a localized string value in the keyfile backing @self
217    /// translated to the current locale.
218    ///
219    /// The @key is looked up in the `Desktop Entry` group.
220    /// ## `key`
221    /// the key to look up
222    ///
223    /// # Returns
224    ///
225    /// a newly allocated string, or `NULL` if the key is not
226    ///   found
227    #[doc(alias = "g_desktop_app_info_get_locale_string")]
228    #[doc(alias = "get_locale_string")]
229    pub fn locale_string(&self, key: &str) -> Option<glib::GString> {
230        unsafe {
231            from_glib_full(ffi::g_desktop_app_info_get_locale_string(
232                self.to_glib_none().0,
233                key.to_glib_none().0,
234            ))
235        }
236    }
237
238    /// Gets the value of the
239    /// [`NoDisplay` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay)
240    ///  which helps determine if the application info should be shown in menus. See
241    /// `G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY` and [`AppInfoExt::should_show()`][crate::prelude::AppInfoExt::should_show()].
242    ///
243    /// # Returns
244    ///
245    /// The value of the `NoDisplay` key
246    #[doc(alias = "g_desktop_app_info_get_nodisplay")]
247    #[doc(alias = "get_nodisplay")]
248    pub fn is_nodisplay(&self) -> bool {
249        unsafe { from_glib(ffi::g_desktop_app_info_get_nodisplay(self.to_glib_none().0)) }
250    }
251
252    /// Checks if the application info should be shown in menus that list available
253    /// applications for a specific name of the desktop, based on the
254    /// [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin)
255    /// and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin)
256    /// keys.
257    ///
258    /// @desktop_env should typically be given as `NULL`, in which case the
259    /// `XDG_CURRENT_DESKTOP` environment variable is consulted.  If you want
260    /// to override the default mechanism then you may specify @desktop_env,
261    /// but this is not recommended.
262    ///
263    /// Note that [`AppInfoExt::should_show()`][crate::prelude::AppInfoExt::should_show()] for @self will include this check
264    /// (with `NULL` for @desktop_env) as well as additional checks.
265    /// ## `desktop_env`
266    /// a string specifying a desktop name
267    ///
268    /// # Returns
269    ///
270    /// `TRUE` if the @self should be shown in @desktop_env according to the
271    /// `OnlyShowIn` and `NotShowIn` keys, `FALSE` otherwise.
272    #[doc(alias = "g_desktop_app_info_get_show_in")]
273    #[doc(alias = "get_show_in")]
274    pub fn shows_in(&self, desktop_env: Option<&str>) -> bool {
275        unsafe {
276            from_glib(ffi::g_desktop_app_info_get_show_in(
277                self.to_glib_none().0,
278                desktop_env.to_glib_none().0,
279            ))
280        }
281    }
282
283    /// Retrieves the `StartupWMClass` field from @self. This represents the
284    /// `WM_CLASS` property of the main window of the application, if launched
285    /// through @self.
286    ///
287    /// # Returns
288    ///
289    /// the startup WM class, or `NULL` if none
290    ///   is set in the desktop file.
291    #[doc(alias = "g_desktop_app_info_get_startup_wm_class")]
292    #[doc(alias = "get_startup_wm_class")]
293    pub fn startup_wm_class(&self) -> Option<glib::GString> {
294        unsafe {
295            from_glib_none(ffi::g_desktop_app_info_get_startup_wm_class(
296                self.to_glib_none().0,
297            ))
298        }
299    }
300
301    /// Looks up a string value in the keyfile backing @self.
302    ///
303    /// The @key is looked up in the `Desktop Entry` group.
304    /// ## `key`
305    /// the key to look up
306    ///
307    /// # Returns
308    ///
309    /// a newly allocated string, or `NULL` if the key is not
310    ///   found
311    #[doc(alias = "g_desktop_app_info_get_string")]
312    #[doc(alias = "get_string")]
313    pub fn string(&self, key: &str) -> Option<glib::GString> {
314        unsafe {
315            from_glib_full(ffi::g_desktop_app_info_get_string(
316                self.to_glib_none().0,
317                key.to_glib_none().0,
318            ))
319        }
320    }
321
322    /// Looks up a string list value in the keyfile backing @self.
323    ///
324    /// The @key is looked up in the `Desktop Entry` group.
325    /// ## `key`
326    /// the key to look up
327    ///
328    /// # Returns
329    ///
330    ///
331    ///   a `NULL`-terminated string array or `NULL` if the specified
332    ///   key cannot be found. The array should be freed with `strfreev()`.
333    #[cfg(feature = "v2_60")]
334    #[cfg_attr(docsrs, doc(cfg(feature = "v2_60")))]
335    #[doc(alias = "g_desktop_app_info_get_string_list")]
336    #[doc(alias = "get_string_list")]
337    pub fn string_list(&self, key: &str) -> Vec<glib::GString> {
338        unsafe {
339            let mut length = std::mem::MaybeUninit::uninit();
340            let ret = FromGlibContainer::from_glib_full_num(
341                ffi::g_desktop_app_info_get_string_list(
342                    self.to_glib_none().0,
343                    key.to_glib_none().0,
344                    length.as_mut_ptr(),
345                ),
346                length.assume_init() as _,
347            );
348            ret
349        }
350    }
351
352    /// Returns whether @key exists in the `Desktop Entry` group
353    /// of the keyfile backing @self.
354    /// ## `key`
355    /// the key to look up
356    ///
357    /// # Returns
358    ///
359    /// `TRUE` if the @key exists
360    #[doc(alias = "g_desktop_app_info_has_key")]
361    pub fn has_key(&self, key: &str) -> bool {
362        unsafe {
363            from_glib(ffi::g_desktop_app_info_has_key(
364                self.to_glib_none().0,
365                key.to_glib_none().0,
366            ))
367        }
368    }
369
370    /// Activates the named application action.
371    ///
372    /// You may only call this function on action names that were
373    /// returned from [`list_actions()`][Self::list_actions()].
374    ///
375    /// Note that if the main entry of the desktop file indicates that the
376    /// application supports startup notification, and @launch_context is
377    /// non-`NULL`, then startup notification will be used when activating the
378    /// action (and as such, invocation of the action on the receiving side
379    /// must signal the end of startup notification when it is completed).
380    /// This is the expected behaviour of applications declaring additional
381    /// actions, as per the
382    /// [desktop file specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html).
383    ///
384    /// As with [`AppInfoExt::launch()`][crate::prelude::AppInfoExt::launch()] there is no way to detect failures that
385    /// occur while using this function.
386    /// ## `action_name`
387    /// the name of the action as from
388    ///   [`list_actions()`][Self::list_actions()]
389    /// ## `launch_context`
390    /// a [`AppLaunchContext`][crate::AppLaunchContext]
391    #[doc(alias = "g_desktop_app_info_launch_action")]
392    pub fn launch_action(
393        &self,
394        action_name: &str,
395        launch_context: Option<&impl IsA<AppLaunchContext>>,
396    ) {
397        unsafe {
398            ffi::g_desktop_app_info_launch_action(
399                self.to_glib_none().0,
400                action_name.to_glib_none().0,
401                launch_context.map(|p| p.as_ref()).to_glib_none().0,
402            );
403        }
404    }
405
406    /// This function performs the equivalent of [`AppInfoExt::launch_uris()`][crate::prelude::AppInfoExt::launch_uris()],
407    /// but is intended primarily for operating system components that
408    /// launch applications.  Ordinary applications should use
409    /// [`AppInfoExt::launch_uris()`][crate::prelude::AppInfoExt::launch_uris()].
410    ///
411    /// If the application is launched via GSpawn, then @spawn_flags, @user_setup
412    /// and @user_setup_data are used for the call to `spawn_async()`.
413    /// Additionally, @pid_callback (with @pid_callback_data) will be called to
414    /// inform about the PID of the created process. See
415    /// `spawn_async_with_pipes()` for information on certain parameter
416    /// conditions that can enable an optimized [`posix_spawn()`](man:posix_spawn(3))
417    /// code path to be used.
418    ///
419    /// If application launching occurs via some other mechanism (for example, D-Bus
420    /// activation) then @spawn_flags, @user_setup, @user_setup_data,
421    /// @pid_callback and @pid_callback_data are ignored.
422    /// ## `uris`
423    /// List of URIs
424    /// ## `launch_context`
425    /// a [`AppLaunchContext`][crate::AppLaunchContext]
426    /// ## `spawn_flags`
427    /// [`glib::SpawnFlags`][crate::glib::SpawnFlags], used for each process
428    /// ## `user_setup`
429    /// a `callback::GLib::SpawnChildSetupFunc,
430    ///   used once  for each process.
431    /// ## `user_setup_data`
432    /// User data for @user_setup
433    /// ## `pid_callback`
434    /// Callback for child processes
435    /// ## `pid_callback_data`
436    /// User data for @callback
437    ///
438    /// # Returns
439    ///
440    /// `TRUE` on successful launch, `FALSE` otherwise.
441    #[doc(alias = "g_desktop_app_info_launch_uris_as_manager")]
442    pub fn launch_uris_as_manager(
443        &self,
444        uris: &[&str],
445        launch_context: Option<&impl IsA<AppLaunchContext>>,
446        spawn_flags: glib::SpawnFlags,
447        user_setup: Option<Box_<dyn FnOnce() + 'static>>,
448        pid_callback: Option<&mut dyn (FnMut(&DesktopAppInfo, glib::Pid))>,
449    ) -> Result<(), glib::Error> {
450        let user_setup_data: Box_<Option<Box_<dyn FnOnce() + 'static>>> = Box_::new(user_setup);
451        unsafe extern "C" fn user_setup_func(data: glib::ffi::gpointer) {
452            let callback = Box_::from_raw(data as *mut Option<Box_<dyn FnOnce() + 'static>>);
453            let callback = (*callback).expect("cannot get closure...");
454            callback()
455        }
456        let user_setup = if user_setup_data.is_some() {
457            Some(user_setup_func as _)
458        } else {
459            None
460        };
461        let mut pid_callback_data: Option<&mut dyn (FnMut(&DesktopAppInfo, glib::Pid))> =
462            pid_callback;
463        unsafe extern "C" fn pid_callback_func(
464            appinfo: *mut ffi::GDesktopAppInfo,
465            pid: glib::ffi::GPid,
466            user_data: glib::ffi::gpointer,
467        ) {
468            let appinfo = from_glib_borrow(appinfo);
469            let pid = from_glib(pid);
470            let callback = user_data as *mut Option<&mut dyn (FnMut(&DesktopAppInfo, glib::Pid))>;
471            if let Some(ref mut callback) = *callback {
472                callback(&appinfo, pid)
473            } else {
474                panic!("cannot get closure...")
475            }
476        }
477        let pid_callback = if pid_callback_data.is_some() {
478            Some(pid_callback_func as _)
479        } else {
480            None
481        };
482        let super_callback0: Box_<Option<Box_<dyn FnOnce() + 'static>>> = user_setup_data;
483        let super_callback1: &mut Option<&mut dyn (FnMut(&DesktopAppInfo, glib::Pid))> =
484            &mut pid_callback_data;
485        unsafe {
486            let mut error = std::ptr::null_mut();
487            let is_ok = ffi::g_desktop_app_info_launch_uris_as_manager(
488                self.to_glib_none().0,
489                uris.to_glib_none().0,
490                launch_context.map(|p| p.as_ref()).to_glib_none().0,
491                spawn_flags.into_glib(),
492                user_setup,
493                Box_::into_raw(super_callback0) as *mut _,
494                pid_callback,
495                super_callback1 as *mut _ as *mut _,
496                &mut error,
497            );
498            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
499            if error.is_null() {
500                Ok(())
501            } else {
502                Err(from_glib_full(error))
503            }
504        }
505    }
506
507    /// Returns the list of
508    /// [‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html)
509    /// supported on the desktop file, as per the desktop file specification.
510    ///
511    /// As per the specification, this is the list of actions that are
512    /// explicitly listed in the `Actions` key of the `Desktop Entry` group.
513    ///
514    /// # Returns
515    ///
516    /// a
517    ///   list of strings, always non-`NULL`
518    #[doc(alias = "g_desktop_app_info_list_actions")]
519    pub fn list_actions(&self) -> Vec<glib::GString> {
520        unsafe {
521            FromGlibPtrContainer::from_glib_none(ffi::g_desktop_app_info_list_actions(
522                self.to_glib_none().0,
523            ))
524        }
525    }
526
527    /// Gets all applications that implement @interface.
528    ///
529    /// An application implements an interface if that interface is listed in
530    /// the `Implements` line of the desktop file of the application.
531    /// ## `interface`
532    /// the name of the interface
533    ///
534    /// # Returns
535    ///
536    /// a list of
537    ///   [`DesktopAppInfo`][crate::DesktopAppInfo] objects.
538    #[doc(alias = "g_desktop_app_info_get_implementations")]
539    #[doc(alias = "get_implementations")]
540    pub fn implementations(interface: &str) -> Vec<DesktopAppInfo> {
541        unsafe {
542            FromGlibPtrContainer::from_glib_full(ffi::g_desktop_app_info_get_implementations(
543                interface.to_glib_none().0,
544            ))
545        }
546    }
547}