1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="ext_action_binder_v1">
<copyright>
Copyright © 2015-2017 Quentin “Sardem FF7” Glidic
Copyright © 2023-2024 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>
<description summary="binds actions">
This protocol allows clients to register "actions" as a set of triggers
and metadata, and get notified when those actions are triggered by the user.
Warning! The protocol described in this file is currently in the testing
phase. Backward compatible changes may be added together with the
corresponding interface version bump. Backward incompatible changes can
only be done by creating a new major version of the extension.
</description>
<interface name="ext_action_binder_v1" version="1">
<description summary="action binder">
This interface is designed to allow any application to bind an action.
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">
Creates a binding.
After setting the metadata on all bindings created, the client must
call ext_action_binder_v1.commit for the binding to take effect.
</description>
<arg name="binding" type="new_id" interface="ext_action_binding_v1" summary="the new binding" />
</request>
<request name="commit">
<description summary="commits all created bindings">
Commits 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">
<description summary="a binding for an action">
This interface defines an individual binding, allowing the client to register metadata about
the action and receive triggered events.
</description>
<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">
Sets 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.
A name must be set before attempting to commit a binding.
Attempting to send this request twice or after the binding was bound raises an already set error.
</description>
<arg name="name_space" type="string" summary="the action namespace" />
<arg name="name" type="string" summary="the action name" />
</request>
<request name="set_description">
<description summary="set 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 or after the binding was bound 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="set the application ID">
This setting is optional.
The app ID identifies the general class of applications to which
the binding belongs. The compositor can use this to select which
client will receive an event.
Attempting to send this request twice or after the binding was bound 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 or after the binding was bound 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
on being set to that specific trigger.
The client does not know which trigger was actually set, but when a binding is
bound, it receives 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 or after the binding was bound 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 object 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>
|
