gio/auto/
app_launch_context.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, File};
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    /// Integrating the launch with the launching application. This is used to
16    /// handle for instance startup notification and launching the new application
17    /// on the same screen as the launching window.
18    ///
19    /// ## Signals
20    ///
21    ///
22    /// #### `launch-failed`
23    ///  The [`launch-failed`][struct@crate::AppLaunchContext#launch-failed] signal is emitted when a
24    /// [`AppInfo`][crate::AppInfo] launch fails. The startup notification id is provided,
25    /// so that the launcher can cancel the startup notification.
26    ///
27    /// Because a launch operation may involve spawning multiple instances of the
28    /// target application, you should expect this signal to be emitted multiple
29    /// times, one for each spawned instance.
30    ///
31    ///
32    ///
33    ///
34    /// #### `launch-started`
35    ///  The [`launch-started`][struct@crate::AppLaunchContext#launch-started] signal is emitted when a
36    /// [`AppInfo`][crate::AppInfo] is about to be launched. If non-null the
37    /// @platform_data is an GVariant dictionary mapping strings to variants
38    /// (ie `a{sv}`), which contains additional, platform-specific data about this
39    /// launch. On UNIX, at least the `startup-notification-id` keys will be
40    /// present.
41    ///
42    /// The value of the `startup-notification-id` key (type `s`) is a startup
43    /// notification ID corresponding to the format from the [startup-notification
44    /// specification](https://specifications.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt).
45    /// It allows tracking the progress of the launchee through startup.
46    ///
47    /// It is guaranteed that this signal is followed by either a
48    /// [`launched`][struct@crate::AppLaunchContext#launched] or
49    /// [`launch-failed`][struct@crate::AppLaunchContext#launch-failed] signal.
50    ///
51    /// Because a launch operation may involve spawning multiple instances of the
52    /// target application, you should expect this signal to be emitted multiple
53    /// times, one for each spawned instance.
54    ///
55    ///
56    ///
57    ///
58    /// #### `launched`
59    ///  The [`launched`][struct@crate::AppLaunchContext#launched] signal is emitted when a
60    /// [`AppInfo`][crate::AppInfo] is successfully launched.
61    ///
62    /// Because a launch operation may involve spawning multiple instances of the
63    /// target application, you should expect this signal to be emitted multiple
64    /// times, one time for each spawned instance.
65    ///
66    /// The @platform_data is an GVariant dictionary mapping
67    /// strings to variants (ie `a{sv}`), which contains additional,
68    /// platform-specific data about this launch. On UNIX, at least the
69    /// `pid` and `startup-notification-id` keys will be present.
70    ///
71    /// Since 2.72 the `pid` may be 0 if the process id wasn’t known (for
72    /// example if the process was launched via D-Bus). The `pid` may not be
73    /// set at all in subsequent releases.
74    ///
75    /// On Windows, `pid` is guaranteed to be valid only for the duration of the
76    /// [`launched`][struct@crate::AppLaunchContext#launched] signal emission; after the signal
77    /// is emitted, GLib will call `spawn_close_pid()`. If you need to
78    /// keep the `alias::GLib.Pid` after the signal has been emitted, then you can
79    /// duplicate `pid` using `DuplicateHandle()`.
80    ///
81    ///
82    ///
83    /// # Implements
84    ///
85    /// [`AppLaunchContextExt`][trait@crate::prelude::AppLaunchContextExt], [`trait@glib::ObjectExt`]
86    #[doc(alias = "GAppLaunchContext")]
87    pub struct AppLaunchContext(Object<ffi::GAppLaunchContext, ffi::GAppLaunchContextClass>);
88
89    match fn {
90        type_ => || ffi::g_app_launch_context_get_type(),
91    }
92}
93
94impl AppLaunchContext {
95    pub const NONE: Option<&'static AppLaunchContext> = None;
96
97    /// Creates a new application launch context. This is not normally used,
98    /// instead you instantiate a subclass of this, such as
99    /// [`GdkAppLaunchContext`](https://docs.gtk.org/gdk4/class.AppLaunchContext.html).
100    ///
101    /// # Returns
102    ///
103    /// a launch context.
104    #[doc(alias = "g_app_launch_context_new")]
105    pub fn new() -> AppLaunchContext {
106        unsafe { from_glib_full(ffi::g_app_launch_context_new()) }
107    }
108}
109
110impl Default for AppLaunchContext {
111    fn default() -> Self {
112        Self::new()
113    }
114}
115
116mod sealed {
117    pub trait Sealed {}
118    impl<T: super::IsA<super::AppLaunchContext>> Sealed for T {}
119}
120
121/// Trait containing all [`struct@AppLaunchContext`] methods.
122///
123/// # Implementors
124///
125/// [`AppLaunchContext`][struct@crate::AppLaunchContext]
126pub trait AppLaunchContextExt: IsA<AppLaunchContext> + sealed::Sealed + 'static {
127    /// Gets the display string for the @self. This is used to ensure new
128    /// applications are started on the same display as the launching
129    /// application, by setting the `DISPLAY` environment variable.
130    /// ## `info`
131    /// the app info
132    /// ## `files`
133    /// a list of [`File`][crate::File] objects
134    ///
135    /// # Returns
136    ///
137    /// a display string for the display.
138    #[doc(alias = "g_app_launch_context_get_display")]
139    #[doc(alias = "get_display")]
140    fn display(&self, info: &impl IsA<AppInfo>, files: &[File]) -> Option<glib::GString> {
141        unsafe {
142            from_glib_full(ffi::g_app_launch_context_get_display(
143                self.as_ref().to_glib_none().0,
144                info.as_ref().to_glib_none().0,
145                files.to_glib_none().0,
146            ))
147        }
148    }
149
150    /// Gets the complete environment variable list to be passed to
151    /// the child process when @self is used to launch an application.
152    /// This is a `NULL`-terminated array of strings, where each string has
153    /// the form `KEY=VALUE`.
154    ///
155    /// # Returns
156    ///
157    ///
158    ///   the child’s environment
159    #[doc(alias = "g_app_launch_context_get_environment")]
160    #[doc(alias = "get_environment")]
161    fn environment(&self) -> Vec<std::ffi::OsString> {
162        unsafe {
163            FromGlibPtrContainer::from_glib_full(ffi::g_app_launch_context_get_environment(
164                self.as_ref().to_glib_none().0,
165            ))
166        }
167    }
168
169    /// Initiates startup notification for the application and returns the
170    /// `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation,
171    /// if supported.
172    ///
173    /// The returned token may be referred to equivalently as an ‘activation token’
174    /// (using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology).
175    /// The two [are interoperable](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst).
176    ///
177    /// Activation tokens are defined in the [XDG Activation Protocol](https://wayland.app/protocols/xdg-activation-v1),
178    /// and startup notification IDs are defined in the
179    /// [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).
180    ///
181    /// Support for the XDG Activation Protocol was added in GLib 2.76.
182    /// Since GLib 2.82 @info and @files can be `NULL`. If that’s not supported by the backend,
183    /// the returned token will be `NULL`.
184    /// ## `info`
185    /// the app info
186    /// ## `files`
187    /// a list of [`File`][crate::File] objects
188    ///
189    /// # Returns
190    ///
191    /// a startup notification ID for the application, or `NULL` if
192    ///   not supported.
193    #[doc(alias = "g_app_launch_context_get_startup_notify_id")]
194    #[doc(alias = "get_startup_notify_id")]
195    fn startup_notify_id(
196        &self,
197        info: Option<&impl IsA<AppInfo>>,
198        files: &[File],
199    ) -> Option<glib::GString> {
200        unsafe {
201            from_glib_full(ffi::g_app_launch_context_get_startup_notify_id(
202                self.as_ref().to_glib_none().0,
203                info.map(|p| p.as_ref()).to_glib_none().0,
204                files.to_glib_none().0,
205            ))
206        }
207    }
208
209    /// Called when an application has failed to launch, so that it can cancel
210    /// the application startup notification started in
211    /// [`startup_notify_id()`][Self::startup_notify_id()].
212    /// ## `startup_notify_id`
213    /// the startup notification id that was returned by
214    ///   [`startup_notify_id()`][Self::startup_notify_id()].
215    #[doc(alias = "g_app_launch_context_launch_failed")]
216    fn launch_failed(&self, startup_notify_id: &str) {
217        unsafe {
218            ffi::g_app_launch_context_launch_failed(
219                self.as_ref().to_glib_none().0,
220                startup_notify_id.to_glib_none().0,
221            );
222        }
223    }
224
225    /// Arranges for @variable to be set to @value in the child’s environment when
226    /// @self is used to launch an application.
227    /// ## `variable`
228    /// the environment variable to set
229    /// ## `value`
230    /// the value for to set the variable to.
231    #[doc(alias = "g_app_launch_context_setenv")]
232    fn setenv(&self, variable: impl AsRef<std::ffi::OsStr>, value: impl AsRef<std::ffi::OsStr>) {
233        unsafe {
234            ffi::g_app_launch_context_setenv(
235                self.as_ref().to_glib_none().0,
236                variable.as_ref().to_glib_none().0,
237                value.as_ref().to_glib_none().0,
238            );
239        }
240    }
241
242    /// Arranges for @variable to be unset in the child’s environment when @self
243    /// is used to launch an application.
244    /// ## `variable`
245    /// the environment variable to remove
246    #[doc(alias = "g_app_launch_context_unsetenv")]
247    fn unsetenv(&self, variable: impl AsRef<std::ffi::OsStr>) {
248        unsafe {
249            ffi::g_app_launch_context_unsetenv(
250                self.as_ref().to_glib_none().0,
251                variable.as_ref().to_glib_none().0,
252            );
253        }
254    }
255
256    /// The [`launch-failed`][struct@crate::AppLaunchContext#launch-failed] signal is emitted when a
257    /// [`AppInfo`][crate::AppInfo] launch fails. The startup notification id is provided,
258    /// so that the launcher can cancel the startup notification.
259    ///
260    /// Because a launch operation may involve spawning multiple instances of the
261    /// target application, you should expect this signal to be emitted multiple
262    /// times, one for each spawned instance.
263    /// ## `startup_notify_id`
264    /// the startup notification id for the failed launch
265    #[doc(alias = "launch-failed")]
266    fn connect_launch_failed<F: Fn(&Self, &str) + 'static>(&self, f: F) -> SignalHandlerId {
267        unsafe extern "C" fn launch_failed_trampoline<
268            P: IsA<AppLaunchContext>,
269            F: Fn(&P, &str) + 'static,
270        >(
271            this: *mut ffi::GAppLaunchContext,
272            startup_notify_id: *mut std::ffi::c_char,
273            f: glib::ffi::gpointer,
274        ) {
275            let f: &F = &*(f as *const F);
276            f(
277                AppLaunchContext::from_glib_borrow(this).unsafe_cast_ref(),
278                &glib::GString::from_glib_borrow(startup_notify_id),
279            )
280        }
281        unsafe {
282            let f: Box_<F> = Box_::new(f);
283            connect_raw(
284                self.as_ptr() as *mut _,
285                b"launch-failed\0".as_ptr() as *const _,
286                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
287                    launch_failed_trampoline::<Self, F> as *const (),
288                )),
289                Box_::into_raw(f),
290            )
291        }
292    }
293
294    /// The [`launch-started`][struct@crate::AppLaunchContext#launch-started] signal is emitted when a
295    /// [`AppInfo`][crate::AppInfo] is about to be launched. If non-null the
296    /// @platform_data is an GVariant dictionary mapping strings to variants
297    /// (ie `a{sv}`), which contains additional, platform-specific data about this
298    /// launch. On UNIX, at least the `startup-notification-id` keys will be
299    /// present.
300    ///
301    /// The value of the `startup-notification-id` key (type `s`) is a startup
302    /// notification ID corresponding to the format from the [startup-notification
303    /// specification](https://specifications.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt).
304    /// It allows tracking the progress of the launchee through startup.
305    ///
306    /// It is guaranteed that this signal is followed by either a
307    /// [`launched`][struct@crate::AppLaunchContext#launched] or
308    /// [`launch-failed`][struct@crate::AppLaunchContext#launch-failed] signal.
309    ///
310    /// Because a launch operation may involve spawning multiple instances of the
311    /// target application, you should expect this signal to be emitted multiple
312    /// times, one for each spawned instance.
313    /// ## `info`
314    /// the [`AppInfo`][crate::AppInfo] that is about to be launched
315    /// ## `platform_data`
316    /// additional platform-specific data for this launch
317    #[cfg(feature = "v2_72")]
318    #[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
319    #[doc(alias = "launch-started")]
320    fn connect_launch_started<F: Fn(&Self, &AppInfo, Option<&glib::Variant>) + 'static>(
321        &self,
322        f: F,
323    ) -> SignalHandlerId {
324        unsafe extern "C" fn launch_started_trampoline<
325            P: IsA<AppLaunchContext>,
326            F: Fn(&P, &AppInfo, Option<&glib::Variant>) + 'static,
327        >(
328            this: *mut ffi::GAppLaunchContext,
329            info: *mut ffi::GAppInfo,
330            platform_data: *mut glib::ffi::GVariant,
331            f: glib::ffi::gpointer,
332        ) {
333            let f: &F = &*(f as *const F);
334            f(
335                AppLaunchContext::from_glib_borrow(this).unsafe_cast_ref(),
336                &from_glib_borrow(info),
337                Option::<glib::Variant>::from_glib_borrow(platform_data)
338                    .as_ref()
339                    .as_ref(),
340            )
341        }
342        unsafe {
343            let f: Box_<F> = Box_::new(f);
344            connect_raw(
345                self.as_ptr() as *mut _,
346                b"launch-started\0".as_ptr() as *const _,
347                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
348                    launch_started_trampoline::<Self, F> as *const (),
349                )),
350                Box_::into_raw(f),
351            )
352        }
353    }
354
355    /// The [`launched`][struct@crate::AppLaunchContext#launched] signal is emitted when a
356    /// [`AppInfo`][crate::AppInfo] is successfully launched.
357    ///
358    /// Because a launch operation may involve spawning multiple instances of the
359    /// target application, you should expect this signal to be emitted multiple
360    /// times, one time for each spawned instance.
361    ///
362    /// The @platform_data is an GVariant dictionary mapping
363    /// strings to variants (ie `a{sv}`), which contains additional,
364    /// platform-specific data about this launch. On UNIX, at least the
365    /// `pid` and `startup-notification-id` keys will be present.
366    ///
367    /// Since 2.72 the `pid` may be 0 if the process id wasn’t known (for
368    /// example if the process was launched via D-Bus). The `pid` may not be
369    /// set at all in subsequent releases.
370    ///
371    /// On Windows, `pid` is guaranteed to be valid only for the duration of the
372    /// [`launched`][struct@crate::AppLaunchContext#launched] signal emission; after the signal
373    /// is emitted, GLib will call `spawn_close_pid()`. If you need to
374    /// keep the `alias::GLib.Pid` after the signal has been emitted, then you can
375    /// duplicate `pid` using `DuplicateHandle()`.
376    /// ## `info`
377    /// the [`AppInfo`][crate::AppInfo] that was just launched
378    /// ## `platform_data`
379    /// additional platform-specific data for this launch
380    #[doc(alias = "launched")]
381    fn connect_launched<F: Fn(&Self, &AppInfo, &glib::Variant) + 'static>(
382        &self,
383        f: F,
384    ) -> SignalHandlerId {
385        unsafe extern "C" fn launched_trampoline<
386            P: IsA<AppLaunchContext>,
387            F: Fn(&P, &AppInfo, &glib::Variant) + 'static,
388        >(
389            this: *mut ffi::GAppLaunchContext,
390            info: *mut ffi::GAppInfo,
391            platform_data: *mut glib::ffi::GVariant,
392            f: glib::ffi::gpointer,
393        ) {
394            let f: &F = &*(f as *const F);
395            f(
396                AppLaunchContext::from_glib_borrow(this).unsafe_cast_ref(),
397                &from_glib_borrow(info),
398                &from_glib_borrow(platform_data),
399            )
400        }
401        unsafe {
402            let f: Box_<F> = Box_::new(f);
403            connect_raw(
404                self.as_ptr() as *mut _,
405                b"launched\0".as_ptr() as *const _,
406                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
407                    launched_trampoline::<Self, F> as *const (),
408                )),
409                Box_::into_raw(f),
410            )
411        }
412    }
413}
414
415impl<O: IsA<AppLaunchContext>> AppLaunchContextExt for O {}