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