:right-sidebar: True AppLaunchContext =================================================================== .. currentmodule:: gi.repository.Gio .. class:: AppLaunchContext(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` :Constructors: :: AppLaunchContext(**properties) new() -> Gio.AppLaunchContext Constructors ------------ .. rst-class:: interim-class .. class:: AppLaunchContext :no-index: .. classmethod:: new() -> ~gi.repository.Gio.AppLaunchContext Creates a new application launch context. This is not normally used, instead you instantiate a subclass of this, such as ``GdkAppLaunchContext``. Methods ------- .. rst-class:: interim-class .. class:: AppLaunchContext :no-index: .. method:: get_display(info: ~gi.repository.Gio.AppInfo, files: list[~gi.repository.Gio.File]) -> str | 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. :param info: a :obj:`~gi.repository.Gio.AppInfo` :param files: a :obj:`~gi.repository.GLib.List` of :obj:`~gi.repository.Gio.File` objects .. method:: get_environment() -> list[str] Gets the complete environment variable list to be passed to the child process when ``context`` is used to launch an application. This is a :const:`None`-terminated array of strings, where each string has the form ``KEY=VALUE``. .. versionadded:: 2.32 .. method:: get_startup_notify_id(info: ~gi.repository.Gio.AppInfo, files: list[~gi.repository.Gio.File]) -> str | 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. :param info: a :obj:`~gi.repository.Gio.AppInfo` :param files: a :obj:`~gi.repository.GLib.List` of :obj:`~gi.repository.Gio.File` objects .. method:: launch_failed(startup_notify_id: str) -> None Called when an application has failed to launch, so that it can cancel the application startup notification started in :func:`~gi.repository.Gio.AppLaunchContext.get_startup_notify_id`. :param startup_notify_id: the startup notification id that was returned by :func:`~gi.repository.Gio.AppLaunchContext.get_startup_notify_id`. .. method:: setenv(variable: str, value: str) -> None Arranges for ``variable`` to be set to ``value`` in the child's environment when ``context`` is used to launch an application. .. versionadded:: 2.32 :param variable: the environment variable to set :param value: the value for to set the variable to. .. method:: unsetenv(variable: str) -> None Arranges for ``variable`` to be unset in the child's environment when ``context`` is used to launch an application. .. versionadded:: 2.32 :param variable: the environment variable to remove Signals ------- .. rst-class:: interim-class .. class:: AppLaunchContext.signals :no-index: .. method:: launch_failed(startup_notify_id: str) -> None The :obj:`~gi.repository.Gio.AppLaunchContext`::launch-failed signal is emitted when a :obj:`~gi.repository.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. .. versionadded:: 2.36 :param startup_notify_id: the startup notification id for the failed launch .. method:: launch_started(info: ~gi.repository.Gio.AppInfo, platform_data: ~gi.repository.GLib.Variant | None = None) -> None The :obj:`~gi.repository.Gio.AppLaunchContext`::launch-started signal is emitted when a :obj:`~gi.repository.Gio.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 :obj:`~gi.repository.Gio.AppLaunchContext`::launched or :obj:`~gi.repository.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. .. versionadded:: 2.72 :param info: the :obj:`~gi.repository.Gio.AppInfo` that is about to be launched :param platform_data: additional platform-specific data for this launch .. method:: launched(info: ~gi.repository.Gio.AppInfo, platform_data: ~gi.repository.GLib.Variant) -> None The :obj:`~gi.repository.Gio.AppLaunchContext`::launched signal is emitted when a :obj:`~gi.repository.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 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 :obj:`~gi.repository.Gio.AppLaunchContext`::launched signal emission; after the signal is emitted, GLib will call :func:`~gi.repository.GLib.spawn_close_pid`. If you need to keep the :obj:`~gi.repository.GLib.Pid` after the signal has been emitted, then you can duplicate ``pid`` using ``DuplicateHandle()``. .. versionadded:: 2.36 :param info: the :obj:`~gi.repository.Gio.AppInfo` that was just launched :param platform_data: additional platform-specific data for this launch Virtual Methods --------------- .. rst-class:: interim-class .. class:: AppLaunchContext :no-index: .. method:: do_get_display(info: ~gi.repository.Gio.AppInfo, files: list[~gi.repository.Gio.File]) -> str | 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. :param info: a :obj:`~gi.repository.Gio.AppInfo` :param files: a :obj:`~gi.repository.GLib.List` of :obj:`~gi.repository.Gio.File` objects .. method:: do_get_startup_notify_id(info: ~gi.repository.Gio.AppInfo, files: list[~gi.repository.Gio.File]) -> str | 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. :param info: a :obj:`~gi.repository.Gio.AppInfo` :param files: a :obj:`~gi.repository.GLib.List` of :obj:`~gi.repository.Gio.File` objects .. method:: do_launch_failed(startup_notify_id: str) -> None Called when an application has failed to launch, so that it can cancel the application startup notification started in :func:`~gi.repository.Gio.AppLaunchContext.get_startup_notify_id`. :param startup_notify_id: the startup notification id that was returned by :func:`~gi.repository.Gio.AppLaunchContext.get_startup_notify_id`. .. method:: do_launch_started(info: ~gi.repository.Gio.AppInfo, platform_data: ~gi.repository.GLib.Variant) -> None :param info: :param platform_data: .. method:: do_launched(info: ~gi.repository.Gio.AppInfo, platform_data: ~gi.repository.GLib.Variant) -> None :param info: :param platform_data: Fields ------ .. rst-class:: interim-class .. class:: AppLaunchContext :no-index: .. attribute:: parent_instance .. attribute:: priv