gio_unix/auto/

desktop_app_info.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::ffi;
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// `GDesktopAppInfo` is an implementation of [`gio::AppInfo`][crate::gio::AppInfo] based on
    /// desktop files.
    ///
    /// Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
    /// GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
    /// file or the `GioUnix-2.0` GIR namespace when using it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `filename`
    ///  The origin filename of this [`DesktopAppInfo`][crate::DesktopAppInfo]
    ///
    /// Readable | Writable | Construct Only
    ///
    /// # Implements
    ///
    /// [`trait@gio::prelude::AppInfoExt`], [`DesktopAppInfoExtManual`][trait@crate::prelude::DesktopAppInfoExtManual]
    #[doc(alias = "GDesktopAppInfo")]
    pub struct DesktopAppInfo(Object<ffi::GDesktopAppInfo, ffi::GDesktopAppInfoClass>) @implements gio::AppInfo;

    match fn {
        type_ => || ffi::g_desktop_app_info_get_type(),
    }
}

impl DesktopAppInfo {
    /// Creates a new [`DesktopAppInfo`][crate::DesktopAppInfo] based on a desktop file ID.
    ///
    /// A desktop file ID is the basename of the desktop file, including the
    /// `.desktop` extension. GIO is looking for a desktop file with this name
    /// in the `applications` subdirectories of the XDG
    /// data directories (i.e. the directories specified in the `XDG_DATA_HOME`
    /// and `XDG_DATA_DIRS` environment variables). GIO also supports the
    /// prefix-to-subdirectory mapping that is described in the
    /// [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/)
    /// (i.e. a desktop ID of `kde-foo.desktop` will match
    /// `/usr/share/applications/kde/foo.desktop`).
    /// ## `desktop_id`
    /// the desktop file ID
    ///
    /// # Returns
    ///
    /// a new [`DesktopAppInfo`][crate::DesktopAppInfo], or `NULL` if no
    ///    desktop file with that ID exists.
    #[doc(alias = "g_desktop_app_info_new")]
    pub fn new(desktop_id: &str) -> Option<DesktopAppInfo> {
        unsafe { from_glib_full(ffi::g_desktop_app_info_new(desktop_id.to_glib_none().0)) }
    }

    /// Creates a new [`DesktopAppInfo`][crate::DesktopAppInfo].
    /// ## `filename`
    /// the path of a desktop file, in the GLib
    ///      filename encoding
    ///
    /// # Returns
    ///
    /// a new [`DesktopAppInfo`][crate::DesktopAppInfo] or `NULL` on error.
    #[doc(alias = "g_desktop_app_info_new_from_filename")]
    #[doc(alias = "new_from_filename")]
    pub fn from_filename(filename: impl AsRef<std::path::Path>) -> Option<DesktopAppInfo> {
        unsafe {
            from_glib_full(ffi::g_desktop_app_info_new_from_filename(
                filename.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Creates a new [`DesktopAppInfo`][crate::DesktopAppInfo].
    /// ## `key_file`
    /// an opened [type@GLib.KeyFile]
    ///
    /// # Returns
    ///
    /// a new [`DesktopAppInfo`][crate::DesktopAppInfo] or `NULL` on error.
    #[doc(alias = "g_desktop_app_info_new_from_keyfile")]
    #[doc(alias = "new_from_keyfile")]
    pub fn from_keyfile(key_file: &glib::KeyFile) -> Option<DesktopAppInfo> {
        unsafe {
            from_glib_full(ffi::g_desktop_app_info_new_from_keyfile(
                key_file.to_glib_none().0,
            ))
        }
    }

    /// Gets the user-visible display name of the
    /// [‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html)
    /// specified by @action_name.
    ///
    /// This corresponds to the `Name` key within the keyfile group for the
    /// action.
    /// ## `action_name`
    /// the name of the action as from
    ///   [`list_actions()`][Self::list_actions()]
    ///
    /// # Returns
    ///
    /// the locale-specific action name
    #[doc(alias = "g_desktop_app_info_get_action_name")]
    #[doc(alias = "get_action_name")]
    pub fn action_name(&self, action_name: &str) -> glib::GString {
        unsafe {
            from_glib_full(ffi::g_desktop_app_info_get_action_name(
                self.to_glib_none().0,
                action_name.to_glib_none().0,
            ))
        }
    }

    /// Looks up a boolean value in the keyfile backing @self.
    ///
    /// The @key is looked up in the `Desktop Entry` group.
    /// ## `key`
    /// the key to look up
    ///
    /// # Returns
    ///
    /// the boolean value, or `FALSE` if the key is not found
    #[doc(alias = "g_desktop_app_info_get_boolean")]
    #[doc(alias = "get_boolean")]
    pub fn boolean(&self, key: &str) -> bool {
        unsafe {
            from_glib(ffi::g_desktop_app_info_get_boolean(
                self.to_glib_none().0,
                key.to_glib_none().0,
            ))
        }
    }

    /// Gets the categories from the desktop file.
    ///
    /// # Returns
    ///
    /// The unparsed
    ///   [`Categories` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-categories)
    ///   from the desktop file;
    ///   i.e. no attempt is made to split it by `;` or validate it.
    #[doc(alias = "g_desktop_app_info_get_categories")]
    #[doc(alias = "get_categories")]
    pub fn categories(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::g_desktop_app_info_get_categories(
                self.to_glib_none().0,
            ))
        }
    }

    /// When @self was created from a known filename, return it.
    ///
    /// In some situations such as a [`DesktopAppInfo`][crate::DesktopAppInfo] returned
    /// from [`from_keyfile()`][Self::from_keyfile()], this function
    /// will return `NULL`.
    ///
    /// # Returns
    ///
    /// The full path to the file for @self,
    ///   or `NULL` if not known.
    #[doc(alias = "g_desktop_app_info_get_filename")]
    #[doc(alias = "get_filename")]
    pub fn filename(&self) -> Option<std::path::PathBuf> {
        unsafe { from_glib_none(ffi::g_desktop_app_info_get_filename(self.to_glib_none().0)) }
    }

    /// Gets the generic name from the desktop file.
    ///
    /// # Returns
    ///
    /// The value of the
    ///   [`GenericName` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-genericname)
    #[doc(alias = "g_desktop_app_info_get_generic_name")]
    #[doc(alias = "get_generic_name")]
    pub fn generic_name(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::g_desktop_app_info_get_generic_name(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the implemented intents from the desktop file.
    ///
    /// As per the specification, this is the list of intents that are
    /// explicitly listed in the [`Implements` key](https://specifications.freedesktop.org/desktop-entry/latest/recognized-keys.html) of the `Desktop Entry` group.
    ///
    /// # Returns
    ///
    /// a
    /// list of strings, always non-`NULL`
    #[cfg(feature = "v2_92")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_92")))]
    #[doc(alias = "g_desktop_app_info_get_intents")]
    #[doc(alias = "get_intents")]
    pub fn intents(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::g_desktop_app_info_get_intents(
                self.to_glib_none().0,
            ))
        }
    }

    /// A desktop file is hidden if the
    /// [`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden)
    /// in it is set to `True`.
    ///
    /// # Returns
    ///
    /// `TRUE` if hidden, `FALSE` otherwise.
    #[doc(alias = "g_desktop_app_info_get_is_hidden")]
    #[doc(alias = "get_is_hidden")]
    pub fn is_hidden(&self) -> bool {
        unsafe { from_glib(ffi::g_desktop_app_info_get_is_hidden(self.to_glib_none().0)) }
    }

    /// Gets the keywords from the desktop file.
    ///
    /// # Returns
    ///
    /// The value of the
    ///   [`Keywords` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-keywords)
    #[doc(alias = "g_desktop_app_info_get_keywords")]
    #[doc(alias = "get_keywords")]
    pub fn keywords(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::g_desktop_app_info_get_keywords(
                self.to_glib_none().0,
            ))
        }
    }

    /// Looks up a localized string value in the keyfile backing @self
    /// translated to the current locale.
    ///
    /// The @key is looked up in the `Desktop Entry` group.
    /// ## `key`
    /// the key to look up
    ///
    /// # Returns
    ///
    /// a newly allocated string, or `NULL` if the key is not
    ///   found
    #[doc(alias = "g_desktop_app_info_get_locale_string")]
    #[doc(alias = "get_locale_string")]
    pub fn locale_string(&self, key: &str) -> Option<glib::GString> {
        unsafe {
            from_glib_full(ffi::g_desktop_app_info_get_locale_string(
                self.to_glib_none().0,
                key.to_glib_none().0,
            ))
        }
    }

    /// Gets the value of the
    /// [`NoDisplay` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay)
    ///  which helps determine if the application info should be shown in menus. See
    /// `G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY` and [`AppInfoExtManual::should_show()`][crate::gio::prelude::AppInfoExtManual::should_show()].
    ///
    /// # Returns
    ///
    /// The value of the `NoDisplay` key
    #[doc(alias = "g_desktop_app_info_get_nodisplay")]
    #[doc(alias = "get_nodisplay")]
    pub fn is_nodisplay(&self) -> bool {
        unsafe { from_glib(ffi::g_desktop_app_info_get_nodisplay(self.to_glib_none().0)) }
    }

    /// Checks if the application info should be shown in menus that list available
    /// applications for a specific name of the desktop, based on the
    /// [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin)
    /// and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin)
    /// keys.
    ///
    /// @desktop_env should typically be given as `NULL`, in which case the
    /// `XDG_CURRENT_DESKTOP` environment variable is consulted.  If you want
    /// to override the default mechanism then you may specify @desktop_env,
    /// but this is not recommended.
    ///
    /// Note that [`AppInfoExtManual::should_show()`][crate::gio::prelude::AppInfoExtManual::should_show()] for @self will include this check
    /// (with `NULL` for @desktop_env) as well as additional checks.
    /// ## `desktop_env`
    /// a string specifying a desktop name
    ///
    /// # Returns
    ///
    /// `TRUE` if the @self should be shown in @desktop_env according to the
    /// `OnlyShowIn` and `NotShowIn` keys, `FALSE` otherwise.
    #[doc(alias = "g_desktop_app_info_get_show_in")]
    #[doc(alias = "get_show_in")]
    pub fn shows_in(&self, desktop_env: Option<&str>) -> bool {
        unsafe {
            from_glib(ffi::g_desktop_app_info_get_show_in(
                self.to_glib_none().0,
                desktop_env.to_glib_none().0,
            ))
        }
    }

    /// Retrieves the `StartupWMClass` field from @self. This represents the
    /// `WM_CLASS` property of the main window of the application, if launched
    /// through @self.
    ///
    /// # Returns
    ///
    /// the startup WM class, or `NULL` if none
    ///   is set in the desktop file.
    #[doc(alias = "g_desktop_app_info_get_startup_wm_class")]
    #[doc(alias = "get_startup_wm_class")]
    pub fn startup_wm_class(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::g_desktop_app_info_get_startup_wm_class(
                self.to_glib_none().0,
            ))
        }
    }

    /// Looks up a string value in the keyfile backing @self.
    ///
    /// The @key is looked up in the `Desktop Entry` group.
    /// ## `key`
    /// the key to look up
    ///
    /// # Returns
    ///
    /// a newly allocated string, or `NULL` if the key is not
    ///   found
    #[doc(alias = "g_desktop_app_info_get_string")]
    #[doc(alias = "get_string")]
    pub fn string(&self, key: &str) -> Option<glib::GString> {
        unsafe {
            from_glib_full(ffi::g_desktop_app_info_get_string(
                self.to_glib_none().0,
                key.to_glib_none().0,
            ))
        }
    }

    /// Looks up a string list value in the keyfile backing @self.
    ///
    /// The @key is looked up in the `Desktop Entry` group.
    /// ## `key`
    /// the key to look up
    ///
    /// # Returns
    ///
    ///
    ///   a `NULL`-terminated string array or `NULL` if the specified
    ///   key cannot be found. The array should be freed with `strfreev()`.
    #[cfg(feature = "v2_60")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_60")))]
    #[doc(alias = "g_desktop_app_info_get_string_list")]
    #[doc(alias = "get_string_list")]
    pub fn string_list(&self, key: &str) -> Vec<glib::GString> {
        unsafe {
            let mut length = std::mem::MaybeUninit::uninit();
            let ret = FromGlibContainer::from_glib_full_num(
                ffi::g_desktop_app_info_get_string_list(
                    self.to_glib_none().0,
                    key.to_glib_none().0,
                    length.as_mut_ptr(),
                ),
                length.assume_init() as _,
            );
            ret
        }
    }

    /// Returns whether @intent is implemented by the application.
    ///
    /// As per specification, an intent implemented by the application is listed in
    /// the [`Implements` key](https://specifications.freedesktop.org/desktop-entry/latest/recognized-keys.html) of the `Desktop Entry` group.
    /// ## `intent`
    /// the intent to look up
    ///
    /// # Returns
    ///
    /// true if the @intent is implemented by the application
    #[cfg(feature = "v2_92")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_92")))]
    #[doc(alias = "g_desktop_app_info_has_intent")]
    pub fn has_intent(&self, intent: &str) -> bool {
        unsafe {
            from_glib(ffi::g_desktop_app_info_has_intent(
                self.to_glib_none().0,
                intent.to_glib_none().0,
            ))
        }
    }

    /// Returns whether @key exists in the `Desktop Entry` group
    /// of the keyfile backing @self.
    /// ## `key`
    /// the key to look up
    ///
    /// # Returns
    ///
    /// `TRUE` if the @key exists
    #[doc(alias = "g_desktop_app_info_has_key")]
    pub fn has_key(&self, key: &str) -> bool {
        unsafe {
            from_glib(ffi::g_desktop_app_info_has_key(
                self.to_glib_none().0,
                key.to_glib_none().0,
            ))
        }
    }

    /// Activates the named application action.
    ///
    /// You may only call this function on action names that were
    /// returned from [`list_actions()`][Self::list_actions()].
    ///
    /// Note that if the main entry of the desktop file indicates that the
    /// application supports startup notification, and @launch_context is
    /// non-`NULL`, then startup notification will be used when activating the
    /// action (and as such, invocation of the action on the receiving side
    /// must signal the end of startup notification when it is completed).
    /// This is the expected behaviour of applications declaring additional
    /// actions, as per the
    /// [desktop file specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html).
    ///
    /// As with [`AppInfoExtManual::launch()`][crate::gio::prelude::AppInfoExtManual::launch()] there is no way to detect failures that
    /// occur while using this function.
    /// ## `action_name`
    /// the name of the action as from
    ///   [`list_actions()`][Self::list_actions()]
    /// ## `launch_context`
    /// a [`gio::AppLaunchContext`][crate::gio::AppLaunchContext]
    #[doc(alias = "g_desktop_app_info_launch_action")]
    pub fn launch_action(
        &self,
        action_name: &str,
        launch_context: Option<&impl IsA<gio::AppLaunchContext>>,
    ) {
        unsafe {
            ffi::g_desktop_app_info_launch_action(
                self.to_glib_none().0,
                action_name.to_glib_none().0,
                launch_context.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    //#[doc(alias = "g_desktop_app_info_launch_uris_as_manager")]
    //pub fn launch_uris_as_manager(&self, uris: &[&str], launch_context: Option<&impl IsA<gio::AppLaunchContext>>, spawn_flags: glib::SpawnFlags, user_setup: Option<Box_<dyn FnOnce() + 'static>>, pid_callback: /*Unimplemented*/FnMut(&DesktopAppInfo, /*Ignored*/glib::Pid), pid_callback_data: /*Unimplemented*/Option<Basic: Pointer>) -> Result<(), glib::Error> {
    //    unsafe { TODO: call ffi:g_desktop_app_info_launch_uris_as_manager() }
    //}

    /// Returns the list of
    /// [‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html)
    /// supported on the desktop file, as per the desktop file specification.
    ///
    /// As per the specification, this is the list of actions that are
    /// explicitly listed in the `Actions` key of the `Desktop Entry` group.
    ///
    /// # Returns
    ///
    /// a
    ///   list of strings, always non-`NULL`
    #[doc(alias = "g_desktop_app_info_list_actions")]
    pub fn list_actions(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::g_desktop_app_info_list_actions(
                self.to_glib_none().0,
            ))
        }
    }

    /// Sets the application as the default handler for an intent interface, or for
    /// a scope of the intent interface.
    ///
    /// If @scope is provided, the default handler for that scope of the intent
    /// interface will be set. Additionally, the application will be added to the
    /// list of the default handlers for the intent interface.
    ///
    /// If @scope is not provided, the default handler for the intent interface will
    /// be set to the application.
    /// ## `interface`
    /// the intent interface to set the app as default for
    /// ## `scope`
    /// an optional scope
    ///
    /// # Returns
    ///
    /// true on success; false otherwise
    #[cfg(feature = "v2_92")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_92")))]
    #[doc(alias = "g_desktop_app_info_set_as_default_for_intent")]
    pub fn set_as_default_for_intent(
        &self,
        interface: &str,
        scope: Option<&str>,
    ) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_desktop_app_info_set_as_default_for_intent(
                self.to_glib_none().0,
                interface.to_glib_none().0,
                scope.to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Gets the default [`gio::AppInfo`][crate::gio::AppInfo] that implements @interface and, if @scope
    /// is not `NULL`, also supports @scope.
    ///
    /// An application implements an interface if that interface is listed in
    /// the `Implements` line of the desktop file, as per the
    /// [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry/latest/interfaces.html).
    ///
    /// An application implements a scope of an interface, if the scope is listed in
    /// the [`Supports` line](https://specifications.freedesktop.org/intent-apps/latest/#scopes)
    /// of the section of the desktop file named after @interface. Scopes are specific
    /// to each @interface and are defined in the specification which defines that intent
    /// interface. A URI handler intent might have `https`, `http` and `ftp` as scopes,
    /// for example.
    ///
    /// Application priority can be adjusted via
    /// [`intentapps.list` files](https://specifications.freedesktop.org/intent-apps/latest/#file).
    /// ## `interface`
    /// the intent interface to find an app for
    /// ## `scope`
    /// an optional scope
    ///
    /// # Returns
    ///
    /// app info for the given @intent and @scope,
    ///   or `NULL` if not found.
    #[cfg(feature = "v2_92")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_92")))]
    #[doc(alias = "g_desktop_app_info_get_default_for_intent")]
    #[doc(alias = "get_default_for_intent")]
    pub fn default_for_intent(interface: &str, scope: Option<&str>) -> Option<gio::AppInfo> {
        unsafe {
            from_glib_full(ffi::g_desktop_app_info_get_default_for_intent(
                interface.to_glib_none().0,
                scope.to_glib_none().0,
            ))
        }
    }

    /// Gets all [`gio::AppInfo`][crate::gio::AppInfo]s that implement @interface and, if @scope is not
    /// `NULL`, also supports @scope.
    ///
    /// Applications earlier in the list have higher priority.
    ///
    /// An application implements an interface if that interface is listed in
    /// the `Implements` line of the desktop file, as per the
    /// [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry/latest/interfaces.html).
    ///
    /// An application implements a scope of an interface, if the scope is listed in
    /// the [`Supports` line](https://specifications.freedesktop.org/intent-apps/latest/#scopes)
    /// of the section of the desktop file named after @interface. Scopes are specific
    /// to each @interface and are defined in the specification which defines that intent
    /// interface. A URI handler intent might have `https`, `http` and `ftp` as scopes,
    /// for example.
    ///
    /// Application priority can be adjusted via
    /// [`intentapps.list` files](https://specifications.freedesktop.org/intent-apps/latest/#file).
    ///
    /// The list is guaranteed to be `NULL` terminated. The `NULL` terminator is not
    /// counted in @out_n_results.
    /// ## `interface`
    /// the intent interface to find an app for
    /// ## `scope`
    /// an optional scope
    ///
    /// # Returns
    ///
    /// an array of
    /// app infos for the given @intent and @scope, or `NULL` if none are found.
    #[cfg(feature = "v2_92")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_92")))]
    #[doc(alias = "g_desktop_app_info_get_for_intent")]
    #[doc(alias = "get_for_intent")]
    pub fn for_intent(interface: &str, scope: Option<&str>) -> Vec<gio::AppInfo> {
        unsafe {
            let mut out_n_results = std::mem::MaybeUninit::uninit();
            let ret = FromGlibContainer::from_glib_full_num(
                ffi::g_desktop_app_info_get_for_intent(
                    interface.to_glib_none().0,
                    scope.to_glib_none().0,
                    out_n_results.as_mut_ptr(),
                ),
                out_n_results.assume_init() as _,
            );
            ret
        }
    }

    /// Gets all applications that implement @interface.
    ///
    /// An application implements an interface if that interface is listed in
    /// the `Implements` line of the desktop file of the application.
    /// ## `interface`
    /// the name of the interface
    ///
    /// # Returns
    ///
    /// a list of
    ///   [`DesktopAppInfo`][crate::DesktopAppInfo] objects.
    #[doc(alias = "g_desktop_app_info_get_implementations")]
    #[doc(alias = "get_implementations")]
    pub fn implementations(interface: &str) -> Vec<DesktopAppInfo> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::g_desktop_app_info_get_implementations(
                interface.to_glib_none().0,
            ))
        }
    }
}