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 {}