src/protocol/ext-input-trigger-action-v1.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="ext_input_trigger_action_v1">
  <copyright>
    Copyright 2025 Canonical Limited

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.
  </copyright>

  <description summary="Registration for global input actions">
    This protocol allows for a Wayland clients to subscribe to input trigger
    actions for "begin" and "end" notifications.

    ext_input_trigger_action_v1 and the associated ext_input_trigger_registration_v1
    are based on the following discussion document:
    https://docs.google.com/document/d/1Hj3BXkmW1quIEWqmN7xeJY29nSPfXP2bmoZvpOsEeJQ/
  </description>

  <interface name="ext_input_trigger_action_manager_v1" version="1">
    <description summary="used to register interest in input actions">
      This interface allows a Wayland client to register interest in
      input trigger actions.
    </description>

    <enum name="error">
      <entry name="invalid_token" value="1"
        summary="token was not issued by the compositor or has been invalidated"/>
    </enum>

    <request name="destroy" type="destructor">
      <description summary="destroy input trigger activation manager object">
        This informs the compositor that the input trigger activation manager
        object will no longer be used. Existing objects created through this
        interface remain valid.
      </description>
    </request>

    <request name="get_input_trigger_action">
      <description summary="register interest in input trigger action">
        This request creates an input trigger action object.

        The token should be one issued by the compositor. If the token was not
        issued by the compositor, or is no longer valid, the compositor must
        raise an invalid_token protocol error.

        If the token has been issued by the compositor, is still valid, but is
        no longer available, then an ext_input_trigger_action_v1.unavailable
        event should be sent immediately.
      </description>
      <arg name="token" type="string" summary="the exported action token"/>
      <arg name="id" type="new_id" interface="ext_input_trigger_action_v1"/>
    </request>
  </interface>

  <interface name="ext_input_trigger_action_v1" version="1">
    <description summary="receives notifications of input trigger actions">
      The compositor sends notification of the triggering of the associated
      action: begin and end will always be sent in pairs, with begin always
      preceding end.
    </description>

    <event name="begin">
      <description summary="begin the input action">
        One of the input triggers associated with the action has occurred.

        The app may begin the activity it associates with the action.

        For keyboard triggers, this will be sent when all keys in the
        corresponding trigger has been pressed.

        The time argument is a timestamp with millisecond granularity, with an
        undefined base. clients must not assume any relation to wall-clock
        time; timestamps are only valid for comparison/deltas.

        The activation token argument is a short-lived opaque token that may be
        used with `xdg_activation_v1` to request to focus another surface.
      </description>
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
      <arg name="activation_token" type="string" summary="an xdg_activation token"/>
    </event>

    <event name="end">
      <description summary="end the input action">
        The input trigger that led to the "begin" event has stopped.

        The app may end (or begin!) the activity it associates with the action.

        For keyboard triggers, this will be sent when any key in the
        corresponding trigger has been released.

        The time argument is a timestamp with millisecond granularity, with an
        undefined base. clients must not assume any relation to wall-clock
        time; timestamps are only valid for comparison/deltas.

        The activation token argument is a short-lived opaque token that may be
        used with `xdg_activation_v1` to request to focus another surface.
      </description>
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
      <arg name="activation_token" type="string" summary="an xdg_activation token"/>
    </event>

    <event name="unavailable">
      <description summary="the input action is (or has become) unavailable">
        Sent if the token is or becomes unavailable.

        This means the object is of no further use and should be destroyed.
      </description>
    </event>

    <request name="destroy" type="destructor">
      <description summary="destroy the input trigger activation">
        This informs the compositor that the input trigger activation will no
        longer be used.
      </description>
    </request>
  </interface>
</protocol>