gio/auto/

app_launch_context.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::{AppInfo, File, ffi};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// Integrating the launch with the launching application. This is used to
    /// handle for instance startup notification and launching the new application
    /// on the same screen as the launching window.
    ///
    /// ## Signals
    ///
    ///
    /// #### `launch-failed`
    ///  The [`launch-failed`][struct@crate::AppLaunchContext#launch-failed] signal is emitted when a
    /// [`AppInfo`][crate::AppInfo] launch fails. The startup notification id is provided,
    /// so that the launcher can cancel the startup notification.
    ///
    /// Because a launch operation may involve spawning multiple instances of the
    /// target application, you should expect this signal to be emitted multiple
    /// times, one for each spawned instance.
    ///
    ///
    ///
    ///
    /// #### `launch-started`
    ///  The [`launch-started`][struct@crate::AppLaunchContext#launch-started] signal is emitted when a
    /// [`AppInfo`][crate::AppInfo] is about to be launched. If non-null the
    /// @platform_data is an GVariant dictionary mapping strings to variants
    /// (ie `a{sv}`), which contains additional, platform-specific data about this
    /// launch. On UNIX, at least the `startup-notification-id` keys will be
    /// present.
    ///
    /// The value of the `startup-notification-id` key (type `s`) is a startup
    /// notification ID corresponding to the format from the [startup-notification
    /// specification](https://specifications.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt).
    /// It allows tracking the progress of the launchee through startup.
    ///
    /// It is guaranteed that this signal is followed by either a
    /// [`launched`][struct@crate::AppLaunchContext#launched] or
    /// [`launch-failed`][struct@crate::AppLaunchContext#launch-failed] signal.
    ///
    /// Because a launch operation may involve spawning multiple instances of the
    /// target application, you should expect this signal to be emitted multiple
    /// times, one for each spawned instance.
    ///
    ///
    ///
    ///
    /// #### `launched`
    ///  The [`launched`][struct@crate::AppLaunchContext#launched] signal is emitted when a
    /// [`AppInfo`][crate::AppInfo] is successfully launched.
    ///
    /// Because a launch operation may involve spawning multiple instances of the
    /// target application, you should expect this signal to be emitted multiple
    /// times, one time for each spawned instance.
    ///
    /// The @platform_data is an GVariant dictionary mapping
    /// strings to variants (ie `a{sv}`), which contains additional,
    /// platform-specific data about this launch. On UNIX, at least the
    /// `pid` and `startup-notification-id` keys will be present.
    ///
    /// Since 2.72 the `pid` may be 0 if the process id wasn’t known (for
    /// example if the process was launched via D-Bus). The `pid` may not be
    /// set at all in subsequent releases.
    ///
    /// On Windows, `pid` is guaranteed to be valid only for the duration of the
    /// [`launched`][struct@crate::AppLaunchContext#launched] signal emission; after the signal
    /// is emitted, GLib will call `spawn_close_pid()`. If you need to
    /// keep the `alias::GLib.Pid` after the signal has been emitted, then you can
    /// duplicate `pid` using `DuplicateHandle()`.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`AppLaunchContextExt`][trait@crate::prelude::AppLaunchContextExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GAppLaunchContext")]
    pub struct AppLaunchContext(Object<ffi::GAppLaunchContext, ffi::GAppLaunchContextClass>);

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

impl AppLaunchContext {
    pub const NONE: Option<&'static AppLaunchContext> = None;

    /// Creates a new application launch context. This is not normally used,
    /// instead you instantiate a subclass of this, such as
    /// [`GdkAppLaunchContext`](https://docs.gtk.org/gdk4/class.AppLaunchContext.html).
    ///
    /// # Returns
    ///
    /// a launch context.
    #[doc(alias = "g_app_launch_context_new")]
    pub fn new() -> AppLaunchContext {
        unsafe { from_glib_full(ffi::g_app_launch_context_new()) }
    }
}

impl Default for AppLaunchContext {
    fn default() -> Self {
        Self::new()
    }
}

/// Trait containing all [`struct@AppLaunchContext`] methods.
///
/// # Implementors
///
/// [`AppLaunchContext`][struct@crate::AppLaunchContext]
pub trait AppLaunchContextExt: IsA<AppLaunchContext> + 'static {
    /// Gets the display string for the @self. This is used to ensure new
    /// applications are started on the same display as the launching
    /// application, by setting the `DISPLAY` environment variable.
    /// ## `info`
    /// the app info
    /// ## `files`
    /// a list of [`File`][crate::File] objects
    ///
    /// # Returns
    ///
    /// a display string for the display.
    #[doc(alias = "g_app_launch_context_get_display")]
    #[doc(alias = "get_display")]
    fn display(&self, info: &impl IsA<AppInfo>, files: &[File]) -> Option<glib::GString> {
        unsafe {
            from_glib_full(ffi::g_app_launch_context_get_display(
                self.as_ref().to_glib_none().0,
                info.as_ref().to_glib_none().0,
                files.to_glib_none().0,
            ))
        }
    }

    /// Gets the complete environment variable list to be passed to
    /// the child process when @self is used to launch an application.
    /// This is a `NULL`-terminated array of strings, where each string has
    /// the form `KEY=VALUE`.
    ///
    /// # Returns
    ///
    ///
    ///   the child’s environment
    #[doc(alias = "g_app_launch_context_get_environment")]
    #[doc(alias = "get_environment")]
    fn environment(&self) -> Vec<std::ffi::OsString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::g_app_launch_context_get_environment(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Initiates startup notification for the application and returns the
    /// `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation,
    /// if supported.
    ///
    /// The returned token may be referred to equivalently as an ‘activation token’
    /// (using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology).
    /// The two [are interoperable](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst).
    ///
    /// Activation tokens are defined in the [XDG Activation Protocol](https://wayland.app/protocols/xdg-activation-v1),
    /// and startup notification IDs are defined in the
    /// [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).
    ///
    /// Support for the XDG Activation Protocol was added in GLib 2.76.
    /// Since GLib 2.82 @info and @files can be `NULL`. If that’s not supported by the backend,
    /// the returned token will be `NULL`.
    /// ## `info`
    /// the app info
    /// ## `files`
    /// a list of [`File`][crate::File] objects
    ///
    /// # Returns
    ///
    /// a startup notification ID for the application, or `NULL` if
    ///   not supported.
    #[doc(alias = "g_app_launch_context_get_startup_notify_id")]
    #[doc(alias = "get_startup_notify_id")]
    fn startup_notify_id(
        &self,
        info: Option<&impl IsA<AppInfo>>,
        files: &[File],
    ) -> Option<glib::GString> {
        unsafe {
            from_glib_full(ffi::g_app_launch_context_get_startup_notify_id(
                self.as_ref().to_glib_none().0,
                info.map(|p| p.as_ref()).to_glib_none().0,
                files.to_glib_none().0,
            ))
        }
    }

    /// Called when an application has failed to launch, so that it can cancel
    /// the application startup notification started in
    /// [`startup_notify_id()`][Self::startup_notify_id()].
    /// ## `startup_notify_id`
    /// the startup notification id that was returned by
    ///   [`startup_notify_id()`][Self::startup_notify_id()].
    #[doc(alias = "g_app_launch_context_launch_failed")]
    fn launch_failed(&self, startup_notify_id: &str) {
        unsafe {
            ffi::g_app_launch_context_launch_failed(
                self.as_ref().to_glib_none().0,
                startup_notify_id.to_glib_none().0,
            );
        }
    }

    /// Arranges for @variable to be set to @value in the child’s environment when
    /// @self is used to launch an application.
    /// ## `variable`
    /// the environment variable to set
    /// ## `value`
    /// the value for to set the variable to.
    #[doc(alias = "g_app_launch_context_setenv")]
    fn setenv(&self, variable: impl AsRef<std::ffi::OsStr>, value: impl AsRef<std::ffi::OsStr>) {
        unsafe {
            ffi::g_app_launch_context_setenv(
                self.as_ref().to_glib_none().0,
                variable.as_ref().to_glib_none().0,
                value.as_ref().to_glib_none().0,
            );
        }
    }

    /// Arranges for @variable to be unset in the child’s environment when @self
    /// is used to launch an application.
    /// ## `variable`
    /// the environment variable to remove
    #[doc(alias = "g_app_launch_context_unsetenv")]
    fn unsetenv(&self, variable: impl AsRef<std::ffi::OsStr>) {
        unsafe {
            ffi::g_app_launch_context_unsetenv(
                self.as_ref().to_glib_none().0,
                variable.as_ref().to_glib_none().0,
            );
        }
    }

    /// The [`launch-failed`][struct@crate::AppLaunchContext#launch-failed] signal is emitted when a
    /// [`AppInfo`][crate::AppInfo] launch fails. The startup notification id is provided,
    /// so that the launcher can cancel the startup notification.
    ///
    /// Because a launch operation may involve spawning multiple instances of the
    /// target application, you should expect this signal to be emitted multiple
    /// times, one for each spawned instance.
    /// ## `startup_notify_id`
    /// the startup notification id for the failed launch
    #[doc(alias = "launch-failed")]
    fn connect_launch_failed<F: Fn(&Self, &str) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn launch_failed_trampoline<
            P: IsA<AppLaunchContext>,
            F: Fn(&P, &str) + 'static,
        >(
            this: *mut ffi::GAppLaunchContext,
            startup_notify_id: *mut std::ffi::c_char,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    AppLaunchContext::from_glib_borrow(this).unsafe_cast_ref(),
                    &glib::GString::from_glib_borrow(startup_notify_id),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"launch-failed".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    launch_failed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The [`launch-started`][struct@crate::AppLaunchContext#launch-started] signal is emitted when a
    /// [`AppInfo`][crate::AppInfo] is about to be launched. If non-null the
    /// @platform_data is an GVariant dictionary mapping strings to variants
    /// (ie `a{sv}`), which contains additional, platform-specific data about this
    /// launch. On UNIX, at least the `startup-notification-id` keys will be
    /// present.
    ///
    /// The value of the `startup-notification-id` key (type `s`) is a startup
    /// notification ID corresponding to the format from the [startup-notification
    /// specification](https://specifications.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt).
    /// It allows tracking the progress of the launchee through startup.
    ///
    /// It is guaranteed that this signal is followed by either a
    /// [`launched`][struct@crate::AppLaunchContext#launched] or
    /// [`launch-failed`][struct@crate::AppLaunchContext#launch-failed] signal.
    ///
    /// Because a launch operation may involve spawning multiple instances of the
    /// target application, you should expect this signal to be emitted multiple
    /// times, one for each spawned instance.
    /// ## `info`
    /// the [`AppInfo`][crate::AppInfo] that is about to be launched
    /// ## `platform_data`
    /// additional platform-specific data for this launch
    #[cfg(feature = "v2_72")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
    #[doc(alias = "launch-started")]
    fn connect_launch_started<F: Fn(&Self, &AppInfo, Option<&glib::Variant>) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn launch_started_trampoline<
            P: IsA<AppLaunchContext>,
            F: Fn(&P, &AppInfo, Option<&glib::Variant>) + 'static,
        >(
            this: *mut ffi::GAppLaunchContext,
            info: *mut ffi::GAppInfo,
            platform_data: *mut glib::ffi::GVariant,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    AppLaunchContext::from_glib_borrow(this).unsafe_cast_ref(),
                    &from_glib_borrow(info),
                    Option::<glib::Variant>::from_glib_borrow(platform_data)
                        .as_ref()
                        .as_ref(),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"launch-started".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    launch_started_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// The [`launched`][struct@crate::AppLaunchContext#launched] signal is emitted when a
    /// [`AppInfo`][crate::AppInfo] is successfully launched.
    ///
    /// Because a launch operation may involve spawning multiple instances of the
    /// target application, you should expect this signal to be emitted multiple
    /// times, one time for each spawned instance.
    ///
    /// The @platform_data is an GVariant dictionary mapping
    /// strings to variants (ie `a{sv}`), which contains additional,
    /// platform-specific data about this launch. On UNIX, at least the
    /// `pid` and `startup-notification-id` keys will be present.
    ///
    /// Since 2.72 the `pid` may be 0 if the process id wasn’t known (for
    /// example if the process was launched via D-Bus). The `pid` may not be
    /// set at all in subsequent releases.
    ///
    /// On Windows, `pid` is guaranteed to be valid only for the duration of the
    /// [`launched`][struct@crate::AppLaunchContext#launched] signal emission; after the signal
    /// is emitted, GLib will call `spawn_close_pid()`. If you need to
    /// keep the `alias::GLib.Pid` after the signal has been emitted, then you can
    /// duplicate `pid` using `DuplicateHandle()`.
    /// ## `info`
    /// the [`AppInfo`][crate::AppInfo] that was just launched
    /// ## `platform_data`
    /// additional platform-specific data for this launch
    #[doc(alias = "launched")]
    fn connect_launched<F: Fn(&Self, &AppInfo, &glib::Variant) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn launched_trampoline<
            P: IsA<AppLaunchContext>,
            F: Fn(&P, &AppInfo, &glib::Variant) + 'static,
        >(
            this: *mut ffi::GAppLaunchContext,
            info: *mut ffi::GAppInfo,
            platform_data: *mut glib::ffi::GVariant,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(
                    AppLaunchContext::from_glib_borrow(this).unsafe_cast_ref(),
                    &from_glib_borrow(info),
                    &from_glib_borrow(platform_data),
                )
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"launched".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    launched_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<AppLaunchContext>> AppLaunchContextExt for O {}