afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Close stale issues and PRs / stale (push) Successful in 13s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
313 lines
14 KiB
XML
313 lines
14 KiB
XML
<?xml version="1.0"?>
|
|
<!--
|
|
Copyright (C) 2021 Matthew Leeds
|
|
|
|
SPDX-License-Identifier: LGPL-2.1-or-later
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU Lesser General Public
|
|
License as published by the Free Software Foundation; either
|
|
version 2.1 of the License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with this library. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
Author: Matthew Leeds <mwleeds@protonmail.com>
|
|
-->
|
|
|
|
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
|
|
<!--
|
|
org.freedesktop.portal.DynamicLauncher:
|
|
@short_description: Portal for installing application launchers
|
|
|
|
The DynamicLauncher portal allows sandboxed (or unsandboxed) applications
|
|
to install launchers (.desktop files) which have an icon associated with them
|
|
and which execute a command in the application. The desktop environment
|
|
would display the launcher to the user in its menu of installed applications.
|
|
For example this can be used by a sandboxed browser to install web app
|
|
launchers. The portal also allows apps to uninstall the launchers, launch
|
|
them, and read the desktop file and icon data for them.
|
|
|
|
The standard way to install a launcher is to use the
|
|
org.freedesktop.portal.DynamicLauncher.PrepareInstall() method
|
|
which results in a dialog being presented to the user so they can confirm
|
|
they want to install the launcher. Then, the token returned by
|
|
org.freedesktop.portal.DynamicLauncher.PrepareInstall()
|
|
would be passed to the org.freedesktop.portal.DynamicLauncher.Install()
|
|
method to complete the installation.
|
|
|
|
However, in the rare circumstance that an unsandboxed process such as a
|
|
system component needs to install a launcher without user interaction, this
|
|
can be accomplished by using the org.freedesktop.portal.DynamicLauncher.RequestInstallToken()
|
|
method and passing the acquired token to org.freedesktop.portal.DynamicLauncher.Install().
|
|
|
|
This documentation describes version 1 of this interface.
|
|
-->
|
|
<interface name="org.freedesktop.portal.DynamicLauncher">
|
|
<!--
|
|
Install:
|
|
@token: Token proving authorization of the installation
|
|
@desktop_file_id: The ``.desktop`` file name to be used
|
|
@desktop_entry: The text of the Desktop Entry file to be installed, see below
|
|
@options: Vardict with optional further information
|
|
|
|
Installs a .desktop launcher and icon into appropriate directories to
|
|
allow the desktop environment to find them. Please note that this method
|
|
overwrites any existing launcher with the same id. If you want to
|
|
present the user with a confirmation dialog in that case, you can check
|
|
for it using the org.freedesktop.portal.DynamicLauncher.GetDesktopEntry()
|
|
method and clean up any state from the previous launcher if you want.
|
|
|
|
@token must be a token that was returned by a previous
|
|
org.freedesktop.portal.DynamicLauncher.PrepareInstall() or
|
|
org.freedesktop.portal.DynamicLauncher.RequestInstallToken() call.
|
|
The token can only be used once and is valid for up to five minutes.
|
|
|
|
The icon and name used for the launcher will be the ones from the previous
|
|
org.freedesktop.portal.DynamicLauncher.PrepareInstall() or
|
|
org.freedesktop.portal.DynamicLauncher.RequestInstallToken() call.
|
|
|
|
The @desktop_file_id must have ".desktop" as a suffix. Except in the
|
|
special case when the calling process has no associated app ID,
|
|
@desktop_file_id must have the app ID followed by a period as a prefix,
|
|
regardless of whether the calling process is sandboxed or unsandboxed.
|
|
|
|
The @desktop_entry should be a valid desktop entry file beginning with
|
|
``[Desktop Entry]``, except it should not include ``Name=`` or ``Icon=`` entries
|
|
(if present, these will be overwritten by the portal implementation).
|
|
The ``Exec=`` entry will be rewritten to call the sandboxed application e.g.
|
|
via "flatpak run", if the application is sandboxed.
|
|
|
|
It is recommended to include a ``TryExec=`` line with either a binary name
|
|
or an absolute path. The launcher will be deleted if the ``TryExec`` binary
|
|
cannot be found on session start.
|
|
|
|
The @options vardict currently has no supported entries.
|
|
-->
|
|
<method name="Install">
|
|
<arg type="s" name="token" direction="in"/>
|
|
<arg type="s" name="desktop_file_id" direction="in"/>
|
|
<arg type="s" name="desktop_entry" direction="in"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.In3" value="QVariantMap"/>
|
|
<arg type="a{sv}" name="options" direction="in"/>
|
|
</method>
|
|
<!--
|
|
PrepareInstall:
|
|
@parent_window: Identifier for the application window, see :doc:`window-identifiers`
|
|
@name: The default name for the launcher
|
|
@icon_v: A ``GBytesIcon`` icon as returned by ``g_icon_serialize()``. Must be a png or jpeg no larger than 512x512, or an svg
|
|
@options: Vardict with optional further information
|
|
@handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call
|
|
|
|
Presents a dialog to the user to allow them to see the icon, potentially
|
|
change the name, and confirm installation of the launcher.
|
|
|
|
Supported keys in the @options vardict:
|
|
|
|
* ``handle_token`` (``s``)
|
|
|
|
A string that will be used as the last element of the @handle. Must be a valid
|
|
object path element. See the :ref:`org.freedesktop.portal.Request` documentation for
|
|
more information about the @handle.
|
|
|
|
* ``modal`` (``b``)
|
|
|
|
Whether to make the dialog modal. Defaults to true.
|
|
|
|
* ``launcher_type`` (``u``)
|
|
|
|
The type of launcher being created. For supported values see the
|
|
#org.freedesktop.portal.DynamicLauncher:SupportedLauncherTypes property.
|
|
Defaults to "Application".
|
|
|
|
* ``target`` (``s``)
|
|
|
|
For a launcher of type "Webapp", this is the URL of the web app
|
|
being installed. This is displayed in the user-facing dialog.
|
|
For other launcher types, this is not needed.
|
|
|
|
* ``editable_name`` (``b``)
|
|
|
|
If true, the user will be able to edit the name of the launcher.
|
|
Defaults to true.
|
|
|
|
* ``editable_icon`` (``b``)
|
|
|
|
If true, the user will be able to edit the icon of the launcher,
|
|
if the implementation supports this. Defaults to false.
|
|
|
|
The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:
|
|
|
|
* ``name`` (``s``)
|
|
|
|
The name chosen by the user for the launcher.
|
|
|
|
* ``token`` (``s``)
|
|
|
|
Token that can be passed to a subsequent org.freedesktop.portal.DynamicLauncher.Install() call to
|
|
complete the installation without another dialog.
|
|
-->
|
|
<method name="PrepareInstall">
|
|
<arg type="s" name="parent_window" direction="in"/>
|
|
<arg type="s" name="name" direction="in"/>
|
|
<arg type="v" name="icon_v" direction="in"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.In3" value="QVariantMap"/>
|
|
<arg type="a{sv}" name="options" direction="in"/>
|
|
<arg type="o" name="handle" direction="out"/>
|
|
</method>
|
|
<!--
|
|
RequestInstallToken:
|
|
@name: The name that will be used in the desktop file
|
|
@icon_v: A ``GBytesIcon`` icon as returned by ``g_icon_serialize()``. Must be a png or jpeg no larger than 512x512, or an svg
|
|
@options: Vardict with optional further information
|
|
@token: the token to be used with the org.freedesktop.portal.DynamicLauncher.Install() method
|
|
|
|
This method is intended for use only by specific components that
|
|
have their application ID allowlisted in the portal backend (e.g. GNOME
|
|
Software and KDE Discover). It is otherwise not guaranteed to work.
|
|
|
|
The token returned by this method can be used to avoid the need for a
|
|
confirmation dialog; the token can be passed to the Install() method
|
|
just as if it were acquired via the PrepareInstall() method.
|
|
|
|
The @options vardict currently has no supported entries.
|
|
-->
|
|
<method name="RequestInstallToken">
|
|
<arg type="s" name="name" direction="in"/>
|
|
<arg type="v" name="icon_v" direction="in"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.In2" value="QVariantMap"/>
|
|
<arg type="a{sv}" name="options" direction="in"/>
|
|
<arg type="s" name="token" direction="out"/>
|
|
</method>
|
|
<!--
|
|
Uninstall:
|
|
@desktop_file_id: The .desktop file name
|
|
@options: Vardict with optional further information
|
|
|
|
This method deletes the desktop file and corresponding icon from the
|
|
appropriate directories to remove the launcher referred to by
|
|
@desktop_file_id.
|
|
|
|
The @desktop_file_id must have ``.desktop`` as a suffix. Except in the
|
|
special case when the calling process has no associated app ID,
|
|
@desktop_file_id must have the app ID followed by a period as a prefix,
|
|
regardless of whether the calling process is sandboxed or unsandboxed.
|
|
|
|
For example, Epiphany, which has the app ID "org.gnome.Epiphany"
|
|
in stable builds, might use a @desktop_file_id like
|
|
``org.gnome.Epiphany.WebApp_e9d0e1e4b0a10856aa3b38d9eb4375de4070d043.desktop``
|
|
In that example the desktop file would exist at the path
|
|
``~/.local/share/xdg-desktop-portal/applications/org.gnome.Epiphany.WebApp_e9d0e1e4b0a10856aa3b38d9eb4375de4070d043.desktop``
|
|
with a sym link in ``~/.local/share/applications/``.
|
|
The checksum at the end of the file name is an implementation detail in
|
|
Epiphany and not required by the portal.
|
|
|
|
This method is intended to be called by the application that created the
|
|
launcher, e.g. a web browser, so it can clean up associated data as part
|
|
of the uninstallation. Consequently, the proper way for a software center
|
|
to remove a launcher is by using the APIs provided by the application
|
|
that installed it. For example, for GNOME Software to remove web
|
|
launchers created by Epiphany, it would use the
|
|
``org.gnome.Epiphany.WebAppProvider`` D-Bus interface.
|
|
|
|
Please note that this method call will fail if the specified launcher
|
|
already does not exist.
|
|
|
|
The @options vardict currently has no supported entries.
|
|
-->
|
|
<method name="Uninstall">
|
|
<arg type="s" name="desktop_file_id" direction="in"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QVariantMap"/>
|
|
<arg type="a{sv}" name="options" direction="in"/>
|
|
</method>
|
|
<!--
|
|
GetDesktopEntry:
|
|
@desktop_file_id: The .desktop file name
|
|
@contents: the contents of the named .desktop file
|
|
|
|
This function returns the contents of a desktop file with the name
|
|
@desktop_file_id in @contents.
|
|
|
|
The @desktop_file_id must have ".desktop" as a suffix. Except in the
|
|
special case when the calling process has no associated app ID,
|
|
@desktop_file_id must have the app ID followed by a period as a prefix.
|
|
|
|
This method only works for desktop files that were created by the
|
|
dynamic launcher portal.
|
|
-->
|
|
<method name="GetDesktopEntry">
|
|
<arg type="s" name="desktop_file_id" direction="in"/>
|
|
<arg type="s" name="contents" direction="out"/>
|
|
</method>
|
|
<!--
|
|
GetIcon:
|
|
@desktop_file_id: The .desktop file name
|
|
@icon_v: the icon as a serialized #GBytesIcon
|
|
@icon_format: one of "png", "jpeg", "svg"
|
|
@icon_size: the width and height in pixels of the icon
|
|
|
|
This function returns the contents of the icon specified in the "Icon"
|
|
key of the desktop file with the name @desktop_file_id in @icon_v. The
|
|
icon #GVariant can be passed to g_icon_deserialize() to reconstruct the
|
|
#GIcon.
|
|
|
|
The @desktop_file_id must have ".desktop" as a suffix. Except in the
|
|
special case when the calling process has no associated app ID,
|
|
@desktop_file_id must have the app ID followed by a period as a prefix.
|
|
|
|
The format and size of the icon are returned in @icon_format and
|
|
@icon_size. For svg icons, @icon_size is currently always set to 4096,
|
|
but don't depend on that as it may change in the future.
|
|
|
|
This method only works for desktop files that were created by the
|
|
dynamic launcher portal.
|
|
-->
|
|
<method name="GetIcon">
|
|
<arg type="s" name="desktop_file_id" direction="in"/>
|
|
<arg type="v" name="icon_v" direction="out"/>
|
|
<arg type="s" name="icon_format" direction="out"/>
|
|
<arg type="u" name="icon_size" direction="out"/>
|
|
</method>
|
|
<!--
|
|
Launch:
|
|
@desktop_file_id: The .desktop file name
|
|
@options: Vardict with optional further information
|
|
|
|
This function launches the app specified by @desktop_file_id.
|
|
|
|
The @desktop_file_id must have ".desktop" as a suffix. Except in the
|
|
special case when the calling process has no associated app ID,
|
|
@desktop_file_id must have the app ID followed by a period as a prefix.
|
|
|
|
This method only works for desktop files that were created by the
|
|
dynamic launcher portal.
|
|
|
|
Supported keys in the @options vardict include:
|
|
|
|
* ``activation_token`` (``s``)
|
|
|
|
A token that can be used to activate the chosen application.
|
|
-->
|
|
<method name="Launch">
|
|
<arg type="s" name="desktop_file_id" direction="in"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QVariantMap"/>
|
|
<arg type="a{sv}" name="options" direction="in"/>
|
|
</method>
|
|
<!--
|
|
SupportedLauncherTypes:
|
|
|
|
A bitmask of available launcher types. Currently defined types are:
|
|
|
|
- 1: Application. A launcher that represents an application.
|
|
- 2: Webapp. A launcher that represents a web app.
|
|
-->
|
|
<property name="SupportedLauncherTypes" type="u" access="read"/>
|
|
<property name="version" type="u" access="read"/>
|
|
</interface>
|
|
</node>
|