Gio.AppLaunchContext¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`get_display` (info, files)
	`get_environment` ()
	`get_startup_notify_id` (info, files)
	`launch_failed` (startup_notify_id)
	`setenv` (variable, value)
	`unsetenv` (variable)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_get_display` (info, files)
	`do_get_startup_notify_id` (info, files)
	`do_launch_failed` (startup_notify_id)
	`do_launch_started` (info, platform_data)
	`do_launched` (info, platform_data)

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`launch-failed`	The [signal`Gio`.AppLaunchContext::launch-failed] signal is emitted when a [iface`Gio`.AppInfo] launch fails.
`launch-started`	The [signal`Gio`.AppLaunchContext::launch-started] signal is emitted when a [iface`Gio`.AppInfo] is about to be launched.
`launched`	The [signal`Gio`.AppLaunchContext::launched] signal is emitted when a [iface`Gio`.AppInfo] is successfully launched.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class Gio.AppLaunchContext(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Gio.AppLaunchContextClass

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.

classmethod new()[source]¶

Returns:: a launch context.
Return type:: Gio.AppLaunchContext

Creates a new application launch context. This is not normally used, instead you instantiate a subclass of this, such as GdkAppLaunchContext.

get_display(info, files)[source]¶

Parameters:

info (Gio.AppInfo) – the app info
files ([Gio.File]) – a list of [iface`Gio`.File] objects

Returns:

a display string for the display.

Return type:

str or None

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.

get_environment()[source]¶

Returns:: the child’s environment
Return type:: [str]

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.

New in version 2.32.

get_startup_notify_id(info, files)[source]¶

Parameters:

info (Gio.AppInfo or None) – the app info
files ([Gio.File] or None) – a list of [iface`Gio`.File] objects

Returns:

a startup notification ID for the application, or NULL if not supported.

Return type:

str or None

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.

Activation tokens are defined in the XDG Activation Protocol, and startup notification IDs are defined in the freedesktop.org Startup Notification Protocol.

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.

launch_failed(startup_notify_id)[source]¶

Parameters:: startup_notify_id (str) – the startup notification id that was returned by [method`Gio`.AppLaunchContext.get_startup_notify_id].

Called when an application has failed to launch, so that it can cancel the application startup notification started in [method`Gio`.AppLaunchContext.get_startup_notify_id].

setenv(variable, value)[source]¶

Parameters:

variable (str) – the environment variable to set
value (str) – the value for to set the variable to.

Arranges for variable to be set to value in the child’s environment when self is used to launch an application.

New in version 2.32.

unsetenv(variable)[source]¶

Parameters:: variable (str) – the environment variable to remove

Arranges for variable to be unset in the child’s environment when self is used to launch an application.

New in version 2.32.

do_get_display(info, files) virtual¶

Parameters:

info (Gio.AppInfo) – the app info
files ([Gio.File]) – a list of [iface`Gio`.File] objects

Returns:

a display string for the display.

Return type:

str or None

Gets the display string for the context. This is used to ensure new applications are started on the same display as the launching application, by setting the DISPLAY environment variable.

do_get_startup_notify_id(info, files) virtual¶

Parameters:

info (Gio.AppInfo or None) – the app info
files ([Gio.File] or None) – a list of [iface`Gio`.File] objects

Returns:

a startup notification ID for the application, or NULL if not supported.

Return type:

str or None

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.

Activation tokens are defined in the XDG Activation Protocol, and startup notification IDs are defined in the freedesktop.org Startup Notification Protocol.

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.

do_launch_failed(startup_notify_id) virtual¶

Parameters:: startup_notify_id (str) – the startup notification id that was returned by [method`Gio`.AppLaunchContext.get_startup_notify_id].

Called when an application has failed to launch, so that it can cancel the application startup notification started in [method`Gio`.AppLaunchContext.get_startup_notify_id].

do_launch_started(info, platform_data) virtual¶

Parameters:

info (Gio.AppInfo) –
platform_data (GLib.Variant) –

do_launched(info, platform_data) virtual¶

Parameters:

info (Gio.AppInfo) –
platform_data (GLib.Variant) –

Signal Details¶

Gio.AppLaunchContext.signals.launch_failed(app_launch_context, startup_notify_id)¶

Signal Name:

launch-failed

Flags:

RUN_LAST

Parameters:

app_launch_context (Gio.AppLaunchContext) – The object which received the signal
startup_notify_id (str) – the startup notification id for the failed launch

The [signal`Gio`.AppLaunchContext::launch-failed] signal is emitted when a [iface`Gio`.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.

New in version 2.36.

Gio.AppLaunchContext.signals.launch_started(app_launch_context, info, platform_data)¶

Signal Name:

launch-started

Flags:

RUN_LAST

Parameters:

app_launch_context (Gio.AppLaunchContext) – The object which received the signal
info (Gio.AppInfo) – the [iface`Gio`.AppInfo] that is about to be launched
platform_data (GLib.Variant or None) – additional platform-specific data for this launch

The [signal`Gio`.AppLaunchContext::launch-started] signal is emitted when a [iface`Gio`.AppInfo] is about to be launched. If non-null the platform_data is an GLib.Variant 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. It allows tracking the progress of the launchee through startup.

It is guaranteed that this signal is followed by either a [signal`Gio`.AppLaunchContext::launched] or [signal`Gio`.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.

New in version 2.72.

Gio.AppLaunchContext.signals.launched(app_launch_context, info, platform_data)¶

Signal Name:

launched

Flags:

RUN_LAST

Parameters:

app_launch_context (Gio.AppLaunchContext) – The object which received the signal
info (Gio.AppInfo) – the [iface`Gio`.AppInfo] that was just launched
platform_data (GLib.Variant) – additional platform-specific data for this launch

The [signal`Gio`.AppLaunchContext::launched] signal is emitted when a [iface`Gio`.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 GLib.Variant 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 [signal`Gio`.AppLaunchContext::launched] signal emission; after the signal is emitted, GLib will call [func`GLib`.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().

New in version 2.36.