aboutsummaryrefslogtreecommitdiff
path: root/protocol
diff options
context:
space:
mode:
authorAnna (navi) Figueiredo Gomes <navi@vlhl.dev>2023-10-09 22:12:46 +0100
committerAnna (navi) Figueiredo Gomes <navi@vlhl.dev>2024-03-01 01:33:13 +0100
commitd1b979d9bd858c45e9ee23a418a390e0ea4ed0cc (patch)
treea1fab7b278a704927ba28115f59697a8cebe85fa /protocol
parent2a897af7dc532a3585401ae317d586a69c1af1d3 (diff)
ext-action-binder-v1: new protocol implementation
Signed-off-by: Anna (navi) Figueiredo Gomes <navi@vlhl.dev>
Diffstat (limited to 'protocol')
-rw-r--r--protocol/ext-action-binder-v1.xml203
-rw-r--r--protocol/meson.build1
2 files changed, 204 insertions, 0 deletions
diff --git a/protocol/ext-action-binder-v1.xml b/protocol/ext-action-binder-v1.xml
new file mode 100644
index 00000000..b477c137
--- /dev/null
+++ b/protocol/ext-action-binder-v1.xml
@@ -0,0 +1,203 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="action_binder_v1">
+ <copyright>
+ Copyright © 2015-2017 Quentin “Sardem FF7” Glidic, 2023 Anna "navi" Figueiredo Gomes
+
+ Permission to use, copy, modify, distribute, and sell this
+ software and its documentation for any purpose is hereby granted
+ without fee, provided that the above copyright notice appear in
+ all copies and that both that copyright notice and this permission
+ notice appear in supporting documentation, and that the name of
+ the copyright holders not be used in advertising or publicity
+ pertaining to distribution of the software without specific,
+ written prior permission. The copyright holders make no
+ representations about the suitability of this software for any
+ purpose. It is provided "as is" without express or implied
+ warranty.
+
+ THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+ SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+ SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+ AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+ THIS SOFTWARE.
+ </copyright>
+
+ <interface name="ext_action_binder_v1" version="1">
+ <description summary="action binder">
+ This interface is designed to allow any application to bind
+ an action.
+
+ An action is an arbitrary couple of a namespace and a name describing the
+ wanted behaviour. These two strings are not meant to be user-visible.
+ Some namespaces are well-known and shared by applications while each
+ application can have its own namespaces for internal actions.
+ It is possible to have the same action in several namespaces, e.g. to
+ allow application-specific bindings in addition to global actions.
+
+ It is left to the compositor to determine which client will get events.
+ The choice can be based on policy, heuristic, user configuration, or any
+ other mechanism that may be relevant.
+ Here are some examples of dispatching choice: all applications, last
+ focused, user-defined preference order, latest fullscreened application.
+
+ This interface is exposed as global
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="unbind the actions">
+ The client no longer wants to receive events for any action.
+ </description>
+ </request>
+
+ <request name="create_binding">
+ <description summary="create a binding"/>
+ <arg name="binding" type="new_id" interface="ext_action_binding_v1" summary="the new binding" />
+ </request>
+
+ <request name="bind">
+ <description summary="binds all created bindings">
+ Binds all bindings created from this interface.
+ This request may be called again if new bindings are created,
+ already bound bindings are unaffected.
+
+ After calling bind, either the "bound" or "rejected" event is sent
+ for each binding created.
+
+ If no action has been set for any binding, the error "invalid_binding" is raised.
+ </description>
+ </request>
+
+ <enum name="error">
+ <entry name="invalid_binding" value="0" summary="the binding has no action set"/>
+ </enum>
+ </interface>
+
+ <interface name="ext_action_binding_v1" version="1">
+ <request name="destroy" type="destructor">
+ <description summary="unbind the actions">
+ The client no longer wants to receive events for this binding.
+ </description>
+ </request>
+
+ <request name="set_name">
+ <description summary="sets the namespace:name of a binding">
+ This an action.
+ Sets the namespace:name of the binding.
+
+ Attempting to send this request twice raises an already set error
+ </description>
+ <arg name="namespace" type="string" summary="the action namespace" />
+ <arg name="name" type="string" summary="the action name" />
+ </request>
+
+ <request name="set_description">
+ <description summary="sets the human-readable description of a binding">
+ This setting is optional.
+ This description may be used by the compositor to render a ui for bindings.
+
+ Attempting to send this request twice raises an already_set error
+ </description>
+ <arg name="description" type="string" summary="a human-readable description of what the binding does" />
+ </request>
+
+ <request name="set_app_id">
+ <description summary="sets an app_id for this binding">
+ This setting is optional.
+
+ Attempting to send this request twice raises an already_set error
+ </description>
+ <arg name="app_id" type="string" summary="app_id of the application requesting this bind"/>
+ </request>
+
+ <request name="set_seat">
+ <description summary="sets a target seat">
+ This setting is optional.
+
+ Attempting to send this request twice raises an already_set error
+ </description>
+ <arg name="seat" type="object" interface="wl_seat" summary="target seat"/>
+ </request>
+
+ <request name="set_trigger_hint">
+ <description summary="sets the machine-readable trigger of a binding">
+ This setting is optional.
+ The trigger is a suggestion to the compositor, and the action should not rely
+ to being set to that specific trigger.
+
+ The client does not know which trigger was actually set, but when a binding is
+ bound, it recieves from the compositor a human readable string describing the trigger,
+ if any, so it could show it in a ui.
+
+ The trigger format is split into two fields, what kind of device triggers it, and a
+ general trigger string.
+
+ as of version 1 of this protocol, the following kinds are defined:
+ "sym": trigger is a combo of XKB key names
+ "mouse": trigger is button[1-9], mapped to their x11 values, (1=left, 2=middle, 3=right,
+ 4=scroll up, 5=scroll down, 6=scroll left, 7=scroll right, 8=back, 9=forward)
+ "switch": trigger on the format switch:state, where "lid" and "tablet" are valid switches
+ "gesture": trigger on the format gesture[:fingers][:direction] with the following gestures:
+ hold: 1-5 fingers, no direction
+ swipe: 3-5 fingers, up, down, left or right
+ pinch: 2-5 fingers, all above, inward, outward, clockwise, counterclockwise
+
+ Attempting to send this request twice raises an already_set error
+ </description>
+ <arg name="kind" type="string" summary="what category of trigger it fits in"/>
+ <arg name="trigger" type="string" summary="a trigger that the client would like to trigger the action"/>
+ </request>
+
+ <event name="bound">
+ <description summary="the compositor bound the binding to an action">
+ Sent after the event was processed, and was bound to one or more of the actions set.
+ </description>
+ <arg name="trigger" type="string" summary="human-readable string describing the trigger for the action" />
+ </event>
+
+ <event name="rejected">
+ <description summary="the compositor rejected the binding">
+ Sent after the event was processed, and got rejected.
+ or at any time should the compositor want to remove the binding.
+ The compositor will send no further events after this event.
+ The client should destroy the resource at this point.
+ </description>
+ </event>
+
+ <enum name="trigger_type">
+ <description summary="type of binding triggered">
+ Depending on the user configuration, an action can be either one_shot or
+ sustained. The client must handle all the three event types and either make
+ sense of them or ignore them properly.
+
+ one_shot actions are for events that don't have a defined "end", like a laptop
+ lid closing, or a gesture. The client should not expect to recieve a released or
+ ending event for that action.
+
+ sustained actions have a start and an end. after a 'pressed' event is sent, a
+ 'released' event should eventually be sent as well.
+ </description>
+ <entry name="one_shot" value="0"
+ summary="a one shot action was triggered" />
+ <entry name="pressed" value="1"
+ summary="a sustained action was started" />
+ <entry name="released" value="2"
+ summary="a sustained action ended" />
+ </enum>
+
+ <event name="triggered">
+ <description summary="the action triggered">
+ This event is sent when actions are triggered.
+ If a binding would trigger both triggered and started events, the
+ started event must be sent first.
+ </description>
+ <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+ <arg name="type" type="uint" enum="trigger_type" summary="the type of trigger that was sent"/>
+ </event>
+ <enum name="error">
+ <entry name="already_set" value="0" summary="property was already set"/>
+ </enum>
+ </interface>
+</protocol>
diff --git a/protocol/meson.build b/protocol/meson.build
index 6a8d82b4..f411a6ff 100644
--- a/protocol/meson.build
+++ b/protocol/meson.build
@@ -52,6 +52,7 @@ protocols = {
'drm': 'drm.xml',
'input-method-unstable-v2': 'input-method-unstable-v2.xml',
'kde-server-decoration': 'server-decoration.xml',
+ 'ext-action-binder-v1': 'ext-action-binder-v1.xml',
'virtual-keyboard-unstable-v1': 'virtual-keyboard-unstable-v1.xml',
'wlr-data-control-unstable-v1': 'wlr-data-control-unstable-v1.xml',
'wlr-export-dmabuf-unstable-v1': 'wlr-export-dmabuf-unstable-v1.xml',