.. _org.freedesktop.impl.portal.InputCapture:

========================================
 Input Capture
========================================

-----------
Description
-----------

.. _org.freedesktop.impl.portal.InputCapture Description:

Capture input portal backend interface

The Capture Input 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 1 of this interface.



.. _org.freedesktop.impl.portal.InputCapture Properties:

----------
Properties
----------

.. _org.freedesktop.impl.portal.InputCapture:SupportedCapabilities:

org.freedesktop.impl.portal.InputCapture:SupportedCapabilities
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    SupportedCapabilities readable u


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

Applications must ignore unknown capabilities.

Currently defined types are:

- ``1``: KEYBOARD
- ``2``: POINTER
- ``4``: TOUCHSCREEN




.. _org.freedesktop.impl.portal.InputCapture:version:

org.freedesktop.impl.portal.InputCapture:version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    version readable u




.. _org.freedesktop.impl.portal.InputCapture Methods:

-------
Methods
-------

.. _org.freedesktop.impl.portal.InputCapture.CreateSession:

org.freedesktop.impl.portal.InputCapture.CreateSession
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    CreateSession (
      IN handle o,
      IN session_handle o,
      IN app_id s,
      IN parent_window s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



Create a capture input 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 capture input session.

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

  The capabilities available to this session. This is always a
  subset of the requested capabilities.



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



.. _org.freedesktop.impl.portal.InputCapture.GetZones:

org.freedesktop.impl.portal.InputCapture.GetZones
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    GetZones (
      IN handle o,
      IN session_handle o,
      IN app_id s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



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`_.



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



.. _org.freedesktop.impl.portal.InputCapture.SetPointerBarriers:

org.freedesktop.impl.portal.InputCapture.SetPointerBarriers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    SetPointerBarriers (
      IN handle o,
      IN session_handle o,
      IN app_id s,
      IN options a{sv},
      IN barriers aa{sv},
      IN zone_set u,
      OUT response u,
      OUT results a{sv}
    )



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.



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



.. _org.freedesktop.impl.portal.InputCapture.Enable:

org.freedesktop.impl.portal.InputCapture.Enable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Enable (
      IN session_handle o,
      IN app_id s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



Enable input capturing.



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
  

results
  



.. _org.freedesktop.impl.portal.InputCapture.Disable:

org.freedesktop.impl.portal.InputCapture.Disable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Disable (
      IN session_handle o,
      IN app_id s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



Disable input capturing.



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
  

results
  



.. _org.freedesktop.impl.portal.InputCapture.Release:

org.freedesktop.impl.portal.InputCapture.Release
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Release (
      IN session_handle o,
      IN app_id s,
      IN options a{sv},
      OUT response u,
      OUT results a{sv}
    )



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.



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
  

results
  



.. _org.freedesktop.impl.portal.InputCapture.ConnectToEIS:

org.freedesktop.impl.portal.InputCapture.ConnectToEIS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    ConnectToEIS (
      IN session_handle o,
      IN app_id s,
      IN options a{sv},
      OUT fd h
    )



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.



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


.. _org.freedesktop.impl.portal.InputCapture Signals:

-------
Signals
-------

.. _org.freedesktop.impl.portal.InputCapture::Disabled:

org.freedesktop.impl.portal.InputCapture::Disabled
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Disabled (
      session_handle o,
      options a{sv}
    )



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.



session_handle
  Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session

options
  Vardict with optional further information



.. _org.freedesktop.impl.portal.InputCapture::Activated:

org.freedesktop.impl.portal.InputCapture::Activated
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Activated (
      session_handle o,
      options a{sv}
    )



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



session_handle
  Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session

options
  Vardict with optional further information



.. _org.freedesktop.impl.portal.InputCapture::Deactivated:

org.freedesktop.impl.portal.InputCapture::Deactivated
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Deactivated (
      session_handle o,
      options a{sv}
    )



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.



session_handle
  Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session

options
  Vardict with optional further information



.. _org.freedesktop.impl.portal.InputCapture::ZonesChanged:

org.freedesktop.impl.portal.InputCapture::ZonesChanged
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    ZonesChanged (
      session_handle o,
      options a{sv}
    )



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.



session_handle
  Object path for the :ref:`org.freedesktop.impl.portal.Session` object representing the session

options
  Vardict with optional further information


