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}