<?xml version="1.0"?>
<!--
 Copyright (C) 2022 Red Hat, Inc.

 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/>.
-->

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

      The Input Capture portal allows clients to capture input from local
      devices. This portal is mostly a 1:1 mapping of the
      :ref:`org.freedesktop.portal.InputCapture` portal, see that portal's
      documentation for details on methods, signals and arguments.

      This documentation describes version 2 of this interface.
  -->
  <interface name="org.freedesktop.impl.portal.InputCapture">
    <!--
        CreateSession:
        @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
        @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session being created
        @app_id: App id of the application
        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
        @options: Vardict with optional further information
        @response: Numeric response
        @results: Vardict with the results of the call

        This method was deprecated in version 2 of this interface and will not
        be called by the frontend if the implementation indicates support for
        version 2. See CreateSession2 instead.

        Create an input capture session.

        Supported keys in the @options vardict include:

        * ``capabilities`` (``u``)

          Bitmask of requested capabilities, see the
          SupportedCapabilities property. This value is required.

        The following results get returned in the @results vardict:

        * ``session_id`` (``s``)

          The session id. A string representing the created input capture session.

        * ``capabilities`` (``u``)

          The capabilities available to this session. This is always a
          subset of the requested capabilities.
    -->
    <method name="CreateSession">
      <arg type="o" name="handle" direction="in"/>
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="s" name="app_id" direction="in"/>
      <arg type="s" name="parent_window" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In4" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="u" name="response" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="results" direction="out"/>
    </method>

    <!--
        CreateSession2:
        @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session being created
        @app_id: App id of the application
        @options: Vardict with optional further information
        @results: Vardict with the results of the call

        Create an input capture session. In contrast with CreateSession, the
        created session is not in the started state.

        There are currently no supported keys in the @options vardict.

        There are currently no supported keys in the @results vardict.

        This method was added in version 2 of this interface.
    -->
    <method name="CreateSession2">
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="s" name="app_id" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In2" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QVariantMap"/>
      <arg type="a{sv}" name="results" direction="out"/>
    </method>

    <!--
        Start:
        @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
        @session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
        @app_id: App id of the application
        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
        @options: Vardict with optional further information
        @response: Numeric response
        @results: Vardict with the results of the call

        Start the input capture session. This will typically result in the portal
        presenting a dialog letting the user decide whether they want to allow the
        input of the session to be captured, and what capabilities to support.

        This method may only be called once on a session previously created with CreateSession2.
        Sessions created by the deprecated CreateSession are immediately started.

        Supported keys in the @options vardict include:

        * ``capabilities`` (``u``)

          Bitmask of requested capabilities, see the SupportedCapabilities property.
          This value is required and must not be zero.

        * ``restore_data`` (``(suv)``)

          The data to restore from a previous session.

          If the stored session cannot be restored, this value is ignored
          and the user will be prompted normally. This may happen when, for
          example, the session contains capabilities that are not available
          anymore, or when the stored permissions are withdrawn.

          The restore data is composed of the vendor name (e.g. "GNOME" or
          "KDE"), the version of the implementation-specific private data,
          and the implementation-specific private data itself.

          This option was added in version 2 of this interface.

        * ``persist_mode`` (``u``)

          How this session should persist. Default is 0. Accepted values are:

          - ``0``: Do not persist (default)
          - ``1``: Permissions persist as long as the application is running
          - ``2``: Permissions persist until explicitly revoked

          If the permission for the session to persist is granted, ``restore_data``
          will be returned in the @results vardict of the
          :ref:`org.freedesktop.impl.portal.InputCapture.Start` method.

          This option was added in version 2 of this interface.

        The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:

        * ``capabilities`` (``u``)

          The capabilities available to this session. This is always a
          subset of the requested capabilities.
          See the SupportedCapabilities property for details. Note that
          while a capability may be available to a session, there is no
          guarantee a device with that capability is currently available
          or if one does become available that it will trigger input capture.

          It is best to view this set as a negative confirmation - a
          capability that was requested but is missing is an indication that
          this application may not capture events of that capability.

        * ``clipboard_enabled`` (``b``)

          A boolean for whether the clipboard was enabled ('true') or not ('false').
          See the :ref:`org.freedesktop.portal.Clipboard` documentation for more
          information.

        * ``restore_data`` (``(suv)``)

          The data for this session to store in the XDG Portal, for a session
          with a ``persist_mode``  other than zero. If this session
          is restored in the future, this data is used as the ``restore_data``
          argument in the @options vardict.

          This option was added in version 2 of this interface.

        This method was added in version 2 of this interface.
    -->
    <method name="Start">
      <arg type="o" name="handle" direction="in"/>
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="s" name="app_id" direction="in"/>
      <arg type="s" name="parent_window" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In4" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="u" name="response" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="results" direction="out"/>
    </method>

    <!--
        GetZones:
        @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
        @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
        @app_id: App id of the application
        @options: Vardict with optional further information
        @response: Numeric response
        @results: Vardict with the results of the call

        Return the current zones for this session.

        The following results get returned in the @results vardict:

        * ``zones`` (``a(uuii)``)

          An array of zones with width, height, x-offset, y-offset.

        * ``zone_set`` (``u``)

          The zone_set ID required in
          org.freedesktop.impl.portal.InputCapture.SetPointerBarriers().
    -->
    <method name="GetZones">
      <arg type="o" name="handle" direction="in"/>
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="s" name="app_id" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In3" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="u" name="response" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="results" direction="out"/>
    </method>

    <!--
        SetPointerBarriers:
        @handle: Object path for the :ref:`org.freedesktop.impl.portal.Request` object representing this call
        @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
        @app_id: App id of the application
        @options: Vardict with optional further information
        @barriers: An array of vardicts, each specifying one barrier
        @zone_set: A unique ID referring to the zone set
        @response: Numeric response
        @results: Vardict with the results of the call

        Set up zero or more pointer barriers.

        Supported keys in the @barriers vardicts include:

        * ``barrier_id`` (``u``)

          The non-zero id of this barrier. This id is used in the
          #org.freedesktop.portal.impl.InputCapture::Activated signal to inform
          which barrier triggered input capture.

        * ``position`` (``(iiii)``)

          The x1/y1 x2/y2 position of the pointer barrier. A horizontal
          pointer barrier must have y1 == y2, a vertical pointer barrier
          must have x1 == x2. Diagonal pointer barriers are not supported.

        The following results get returned in the @results vardict:

        * ``failed_barriers`` (``au``)

          An array of barrier_ids of pointer barriers that have been denied. The
          id matches the barrier_id of the entries in the @barriers argument.
    -->
    <method name="SetPointerBarriers">
      <arg type="o" name="handle" direction="in"/>
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="s" name="app_id" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In3" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In4" value="QList&lt;QVariantMap&gt;"/>
      <arg type="aa{sv}" name="barriers" direction="in"/>
      <arg type="u" name="zone_set" direction="in"/>
      <arg type="u" name="response" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="results" direction="out"/>
    </method>

    <!--
        Enable:
        @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
        @app_id: App id of the application
        @options: Vardict with optional further information

        Enable input capturing.
    -->
    <method name="Enable">
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="s" name="app_id" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In2" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="u" name="response" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="results" direction="out"/>
    </method>

    <!--
        Disable:
        @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
        @app_id: App id of the application
        @options: Vardict with optional further information

        Disable input capturing.
    -->
    <method name="Disable">
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="s" name="app_id" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In2" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="u" name="response" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="results" direction="out"/>
    </method>

    <!--
        Release:
        @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
        @app_id: App id of the application
        @options: Vardict with optional further information

        Release ongoing input capturing.

        Supported keys in the @options vardict include:

        * ``activation_id`` (``u``)

          The same activation_id number as in the
          #org.freedesktop.impl.portal.InputCapture::Activated signal.

        * ``cursor_position`` (``(dd)``)

          The suggested cursor position within the Zones available in
          this session.

          This is a suggestion to the compositor to place the cursor in
          the correct position to allow for fluent movement between virtual
          screens. The compositor is not required to honor this suggestion.
    -->
    <method name="Release">
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="s" name="app_id" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In2" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="u" name="response" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="results" direction="out"/>
    </method>

    <!--
        ConnectToEIS:
        @session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
        @app_id: App id of the application
        @options: Vardict with optional further information
        @fd: A file descriptor to an EIS implementation that can be passed to a passive libei context

        Set up the connection to an EIS implementation. Once input capturing starts,
        input events are sent via the EI protocol between the compositor and the application.
        This call must be invoked before :ref:`org.freedesktop.portal.InputCapture.Enable`.

        A session only needs to set this up once, the EIS implementation is not affected by
        calls to Disable() and :ref:`org.freedesktop.portal.InputCapture.Enable` -
        the same context can be re-used until the session is closed.
    -->
    <method name="ConnectToEIS">
      <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
      <arg type="o" name="session_handle" direction="in"/>
      <arg type="s" name="app_id" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In2" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="h" name="fd" direction="out"/>
    </method>
    <!--
        Disabled:
        @session_handle: Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session
        @options: Vardict with optional further information

        The Disabled signal is emitted when the application will no longer
        receive captured input. If input capturing is currently ongoing, the
        #org.freedesktop.impl.portal.InputCapture::Deactivated signal is emitted
        before this signal.
    -->
    <signal name="Disabled">
      <arg type="o" name="session_handle" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="out"/>
    </signal>

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

        The Activated signal is emitted when input capture starts and input events
        are about to be sent to the application.

        This signal is only emitted after a prior call
        to org.freedesktop.impl.portal.InputCapture.Enable().

        Supported keys in the @options vardict include:

        * ``activation_id`` (``u``)

          A number that can be used to synchronize with the
          transport-layer. This number has no intrinsic meaning but
          is guaranteed to increase by an unspecified amount on each call.

          In particular: if the compositor sends an activation_id of N as
          part of this request it will also set the sequence in EIS'
          start_emulating event the same value N on the EIS connection
          before the first event from a device is sent.
          This allows an application to have a synchronization point and
          attribute an event sequence to the portal interaction.

          Applications must be able to handle the activation_id number wrapping
          around. Implementations of this portal must to increase the
          activation_id number by an sensible amount to allow for wrapping
          detection.

        * ``cursor_position`` (``(dd)``)

          The current cursor position. Note that this position may be
          outside the Zones available to this session - this indicates
          movement larger than a single pixel.

          For example, a fast movement against a barrier on the right edge
          of a screen may logically put the cursor dozens of pixels into
          the (non-existing) screen on the other side of the barrier.
          It is the application's responsibility to adjust the cursor
          position as necessary.

        * ``barrier_id`` (``u``)

          The barrier id of the barrier that triggered. If the value is
          nonzero, it matches the barrier id as specified in
          org.freedesktop.impl.portal.InputCapture.SetPointerBarriers().

          If the id is zero, the pointer barrier could be determined.
          If the id is missing, the input capture was not triggered by a
          pointer barrier.

          Where more than one pointer barrier are triggered by the same
          movement it is up to the compositor to choose one barrier (or use
          a barrier id of zero).
    -->
    <signal name="Activated">
      <arg type="o" name="session_handle" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="out"/>
    </signal>

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

        The Deactivated signal is emitted when input capture stopped and input events
        are no longer sent to the application. To prevent future input
        capture, an application must call :ref:`org.freedesktop.portal.InputCapture.Disable`.

        Supported keys in the @options vardict include:

        * ``activation_id`` (``u``)

          The same activation_id as in the corresponding
          #org.freedesktop.impl.portal.InputCapture::Activated signal.

        * ``cursor_position`` (``(dd)``)

          The current cursor position. Note that this position may be
          outside the Zones available to this session - this indicates
          movement larger than a single pixel.

          For example, a fast movement against a barrier on the right edge
          of a screen may logically put the cursor dozens of pixels into
          the (non-existing) screen on the other side of the barrier.
          It is the application's responsibility to adjust the cursor
          position as necessary.
    -->
    <signal name="Deactivated">
      <arg type="o" name="session_handle" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="out"/>
    </signal>

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

        The ZonesChanged signal is emitted when one or more of the zones
        available **to this session** change. An application should immediately call
        :ref:`org.freedesktop.portal.InputCapture.GetZones` to update its state of the zones.
    -->
    <signal name="ZonesChanged">
      <arg type="o" name="session_handle" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="out"/>
    </signal>

    <!--
        SupportedCapabilities:

        A bitmask of supported capabilities. This list is constant, it is not the list of
        capabilities currently available but rather which capabilities are
        implemented by the portal.

        Applications must ignore unknown capabilities.

        Currently defined types are:

        - ``1``: KEYBOARD
        - ``2``: POINTER
        - ``4``: TOUCHSCREEN
    -->
    <property name="SupportedCapabilities" type="u" access="read"/>
    <property name="version" type="u" access="read"/>
  </interface>
</node>
