<?xml version="1.0"?>
<!--
 Copyright (C) 2022 Aleix Pol Gonzalez <aleixpol@kde.org>

 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 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: Aleix Pol Gonzalez <aleixpol@kde.org>
-->

<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
  <!--
      org.freedesktop.portal.GlobalShortcut:
      @short_description: GlobalShortcut portal backend interface

      This portal lets applications create global shortcuts sessions, and
      register shortcuts to them. These shortcuts are activated regardless of
      the focused state of the application window.

      To use this portal, applications have to create a session under which its
      actions will be collected. Then shortcuts can be bound (see
      org.freedesktop.portal.GlobalShortcuts.Bind), and listed (see
      org.freedesktop.portal.GlobalShortcuts.ListShortcuts).

      All global shortcuts are bound to a session, and all sessions are bound to
      the application that created them.

      The #org.freedesktop.portal.GlobalShortcuts::Activated and
      #org.freedesktop.portal.GlobalShortcuts::Deactivated signals are emitted,
      respecitvely, whenever a shortcut is activated and deactivated.

      This documentation describes version 1 of this interface.
  -->
  <interface name="org.freedesktop.portal.GlobalShortcuts">
    <!--
        CreateSession:
        @options: Vardict with optional further information
        @handle: Object path for the #org.freedesktop.portal.Request object representing this call

        Creates a global shortcuts session.

        Supported keys in the @options vardict include:
        <variablelist>
          <varlistentry>
            <term>handle_token s</term>
            <listitem><para>
              A string that will be used as the last element of the @handle. Must be a valid
              object path element. See the #org.freedesktop.portal.Request documentation for
              more information about the @handle.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>session_handle_token s</term>
            <listitem><para>
              A string that will be used as the last element of the session handle. Must be a valid
              object path element. See the #org.freedesktop.portal.Session documentation for
              more information about the session handle.
            </para></listitem>
          </varlistentry>
        </variablelist>

        The following results get returned via the #org.freedesktop.portal.Request::Response signal:
        <variablelist>
          <varlistentry>
            <term>session_handle o</term>
            <listitem><para>
              The session handle. An object path for the
              #org.freedesktop.portal.Session object representing the created
              session.
            </para></listitem>
          </varlistentry>
        </variablelist>
    -->
    <method name="CreateSession">
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="o" name="handle" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QVariantMap"/>
    </method>

    <!--
        BindShortcuts:
        @session_handle: Object path for the #org.freedesktop.impl.portal.Session object representing the session
        @shortcuts: The list of shortcuts to bind
        @parent_window: Identifier for the application window, see <link linkend="parent_window">Common Conventions</link>
        @options: Vardict with optional further information
        @request_handle: Object path for the #org.freedesktop.portal.Request object representing this call

        Bind the shortcuts. This will typically result the portal presenting a
        dialog showing the shortcuts and allowing users to configure the shortcuts.
        An application can only attempt bind shortcuts of a session once.

        Each element of the @shortcuts array is a tuple composed of a shortcut id,
        and a vardict with the following keys:
        <variablelist>
          <varlistentry>
            <term>description s</term>
            <listitem><para>
              User-readable text describing what the shortcut does.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>preferred_trigger s</term>
            <listitem><para>
              The preferred shortcut trigger, defined as described by the "shortcuts"
              XDG specification. Optional.
            </para></listitem>
          </varlistentry>
        </variablelist>

        Supported keys in the @options vardict include:
        <variablelist>
          <varlistentry>
            <term>handle_token s</term>
            <listitem><para>
              A string that will be used as the last element of the
              @handle. Must be a valid object path element. See the
              #org.freedesktop.portal.Request documentation for more
              information about the @handle.
            </para></listitem>
          </varlistentry>
        </variablelist>

        The following results get returned via the #org.freedesktop.portal.Request::Response signal:
        <variablelist>
          <varlistentry>
            <term>shortcuts a(sa{sv})</term>
            <listitem><para>
              A list of shortcuts. The list of keys it may contain is described
              below, and is different from the @shortcuts variable of this method.
            </para></listitem>
          </varlistentry>
        </variablelist>

        Each element of the @shortcuts array returned by the
        #org.freedesktop.portal.Request::Response signal is a tuple composed of
        a shortcut id, and a vardict with the following keys:
        <variablelist>
          <varlistentry>
            <term>description s</term>
            <listitem><para>
              User-readable text describing what the shortcut does.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>trigger_description s</term>
            <listitem><para>
              User-readable text describing how to trigger the shortcut for the
              client to render.
            </para></listitem>
          </varlistentry>
        </variablelist>
    -->
    <method name="BindShortcuts">
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="a(sa{sv})" name="shortcuts" direction="in"/>
      <arg type="s" name="parent_window" direction="in"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="o" name="request_handle" direction="out"/>

      <annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QList&lt;QPair&lt;QString,QVariantMap&gt;&gt;"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In3" value="QVariantMap"/>
    </method>

    <!--
        ListShortcuts:
        @session_handle: Object path for the #org.freedesktop.impl.portal.Session object representing the session
        @options: Vardict with optional further information

        Lists all shortcuts.

        Supported keys in the @options vardict include:
        <variablelist>
          <varlistentry>
            <term>handle_token s</term>
            <listitem><para>
              A string that will be used as the last element of the
              @handle. Must be a valid object path element. See the
              #org.freedesktop.portal.Request documentation for more
              information about the @handle.
            </para></listitem>
          </varlistentry>
        </variablelist>

        The following results get returned via the #org.freedesktop.portal.Request::Response signal:
        <variablelist>
          <varlistentry>
            <term>shortcuts a(sa{sv})</term>
            <listitem><para>
              A list of shortcuts.

              See the #org.freedesktop.portal.Request::Response signal of the
              org.freedesktop.portal.GlobalShortcuts.BindShortcuts() method for
              the list of supported properties of shortcuts.
            </para></listitem>
          </varlistentry>
        </variablelist>
    -->
    <method name="ListShortcuts">
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="o" name="request_handle" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QVariantMap"/>
    </method>

    <!--
        Activated:
        @session_handle: Session that requested the shortcut
        @shortcut_id: the application-provided ID for the notification
        @timestamp: The timestamp, as seconds and microseconds since the Unix epoch.
        @options: Vardict with optional further information

        Notifies about a shortcut becoming active.
    -->
    <signal name="Activated">
      <arg type="o" name="session_handle" direction="out"/>
      <arg type="s" name="shortcut_id" direction="out"/>
      <arg type="t" name="timestamp" direction="out"/>
      <arg type="a{sv}" name="options" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out3" value="QVariantMap"/>
    </signal>

    <!--
        Deactivated:
        @session_handle: Session that requested the shortcut
        @shortcut_id: the application-provided ID for the notification
        @timestamp: The timestamp, as seconds and microseconds since the Unix epoch.
        @options: Vardict with optional further information

        Notifies that a shortcut is not active anymore.
    -->
    <signal name="Deactivated">
      <arg type="o" name="session_handle" direction="out"/>
      <arg type="s" name="shortcut_id" direction="out"/>
      <arg type="t" name="timestamp" direction="out"/>
      <arg type="a{sv}" name="options" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out3" value="QVariantMap"/>
    </signal>

    <!--
        ShortcutsChanged:
        @session_handle: Session that requested the shortcut
        @shortcuts: The different shortcuts that have been registered. See org.freedesktop.portal.GlobalShortcuts.

        Indicates that the information associated with some of the shortcuts has changed.

        See the #org.freedesktop.portal.Request::Response signal of the
        org.freedesktop.portal.GlobalShortcuts.BindShortcuts() method for the
        list of supported properties of shortcuts.
    -->
    <signal name="ShortcutsChanged">
      <arg type="o" name="session_handle" direction="out"/>
      <arg type="a(sa{sv})" name="shortcuts" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QList&lt;QPair&lt;QString,QVariantMap&gt;&gt;"/>
    </signal>

    <property name="version" type="u" access="read"/>
  </interface>
</node>
