XML 1.0 document, Unicode text, UTF-8 text
1
<?xml version="1.0" encoding="UTF-8"?>
2
<protocol name="input_method_unstable_v2">
3
<copyright>
5
Copyright © 2008-2011 Kristian Høgsberg
6
Copyright © 2010-2011 Intel Corporation
7
Copyright © 2012-2013 Collabora, Ltd.
8
Copyright © 2012, 2013 Intel Corporation
9
Copyright © 2015, 2016 Jan Arne Petersen
10
Copyright © 2017, 2018 Red Hat, Inc.
11
Copyright © 2018 Purism SPC
12
Permission is hereby granted, free of charge, to any person obtaining a
14
copy of this software and associated documentation files (the "Software"),
15
to deal in the Software without restriction, including without limitation
16
the rights to use, copy, modify, merge, publish, distribute, sublicense,
17
and/or sell copies of the Software, and to permit persons to whom the
18
Software is furnished to do so, subject to the following conditions:
19
The above copyright notice and this permission notice (including the next
21
paragraph) shall be included in all copies or substantial portions of the
22
Software.
23
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
27
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
29
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
30
DEALINGS IN THE SOFTWARE.
31
</copyright>
32
<description summary="Protocol for creating input methods">
34
This protocol allows applications to act as input methods for compositors.
35
An input method context is used to manage the state of the input method.
37
Text strings are UTF-8 encoded, their indices and lengths are in bytes.
39
This document adheres to the RFC 2119 when using words like "must",
41
"should", "may", etc.
42
Warning! The protocol described in this file is experimental and
44
backward incompatible changes may be made. Backward compatible changes
45
may be added together with the corresponding interface version bump.
46
Backward incompatible changes are done by bumping the version number in
47
the protocol and interface names and resetting the interface version.
48
Once the protocol is to be declared stable, the 'z' prefix and the
49
version number in the protocol and interface names are removed and the
50
interface version number is reset.
51
</description>
52
<interface name="zwp_input_method_v2" version="1">
54
<description summary="input method">
55
An input method object allows for clients to compose text.
56
The objects connects the client to a text input in an application, and
58
lets the client to serve as an input method for a seat.
59
The zwp_input_method_v2 object can occupy two distinct states: active and
61
inactive. In the active state, the object is associated to and
62
communicates with a text input. In the inactive state, there is no
63
associated text input, and the only communication is with the compositor.
64
Initially, the input method is in the inactive state.
65
Requests issued in the inactive state must be accepted by the compositor.
67
Because of the serial mechanism, and the state reset on activate event,
68
they will not have any effect on the state of the next text input.
69
There must be no more than one input method object per seat.
71
</description>
72
<event name="activate">
74
<description summary="input method has been requested">
75
Notification that a text input focused on this seat requested the input
76
method to be activated.
77
This event serves the purpose of providing the compositor with an
79
active input method.
80
This event resets all state associated with previous enable, disable,
82
surrounding_text, text_change_cause, and content_type events, as well
83
as the state associated with set_preedit_string, commit_string, and
84
delete_surrounding_text requests. In addition, it marks the
85
zwp_input_method_v2 object as active, and makes any existing
86
zwp_input_popup_surface_v2 objects visible.
87
The surrounding_text, and content_type events must follow before the
89
next done event if the text input supports the respective
90
functionality.
91
State set with this event is double-buffered. It will get applied on
93
the next zwp_input_method_v2.done event, and stay valid until changed.
94
</description>
95
</event>
96
<event name="deactivate">
98
<description summary="deactivate event">
99
Notification that no focused text input currently needs an active
100
input method on this seat.
101
This event marks the zwp_input_method_v2 object as inactive. The
103
compositor must make all existing zwp_input_popup_surface_v2 objects
104
invisible until the next activate event.
105
State set with this event is double-buffered. It will get applied on
107
the next zwp_input_method_v2.done event, and stay valid until changed.
108
</description>
109
</event>
110
<event name="surrounding_text">
112
<description summary="surrounding text event">
113
Updates the surrounding plain text around the cursor, excluding the
114
preedit text.
115
If any preedit text is present, it is replaced with the cursor for the
117
purpose of this event.
118
The argument text is a buffer containing the preedit string, and must
120
include the cursor position, and the complete selection. It should
121
contain additional characters before and after these. There is a
122
maximum length of wayland messages, so text can not be longer than 4000
123
bytes.
124
cursor is the byte offset of the cursor within the text buffer.
126
anchor is the byte offset of the selection anchor within the text
128
buffer. If there is no selected text, anchor must be the same as
129
cursor.
130
If this event does not arrive before the first done event, the input
132
method may assume that the text input does not support this
133
functionality and ignore following surrounding_text events.
134
Values set with this event are double-buffered. They will get applied
136
and set to initial values on the next zwp_input_method_v2.done
137
event.
138
The initial state for affected fields is empty, meaning that the text
140
input does not support sending surrounding text. If the empty values
141
get applied, subsequent attempts to change them may have no effect.
142
</description>
143
<arg name="text" type="string"/>
144
<arg name="cursor" type="uint"/>
145
<arg name="anchor" type="uint"/>
146
</event>
147
<event name="text_change_cause">
149
<description summary="indicates the cause of surrounding text change">
150
Tells the input method why the text surrounding the cursor changed.
151
Whenever the client detects an external change in text, cursor, or
153
anchor position, it must issue this request to the compositor. This
154
request is intended to give the input method a chance to update the
155
preedit text in an appropriate way, e.g. by removing it when the user
156
starts typing with a keyboard.
157
cause describes the source of the change.
159
The value set with this event is double-buffered. It will get applied
161
and set to its initial value on the next zwp_input_method_v2.done
162
event.
163
The initial value of cause is input_method.
165
</description>
166
<arg name="cause" type="uint" enum="zwp_text_input_v3.change_cause"/>
167
</event>
168
<event name="content_type">
170
<description summary="content purpose and hint">
171
Indicates the content type and hint for the current
172
zwp_input_method_v2 instance.
173
Values set with this event are double-buffered. They will get applied
175
on the next zwp_input_method_v2.done event.
176
The initial value for hint is none, and the initial value for purpose
178
is normal.
179
</description>
180
<arg name="hint" type="uint" enum="zwp_text_input_v3.content_hint"/>
181
<arg name="purpose" type="uint" enum="zwp_text_input_v3.content_purpose"/>
182
</event>
183
<event name="done">
185
<description summary="apply state">
186
Atomically applies state changes recently sent to the client.
187
The done event establishes and updates the state of the client, and
189
must be issued after any changes to apply them.
190
Text input state (content purpose, content hint, surrounding text, and
192
change cause) is conceptually double-buffered within an input method
193
context.
194
Events modify the pending state, as opposed to the current state in use
196
by the input method. A done event atomically applies all pending state,
197
replacing the current state. After done, the new pending state is as
198
documented for each related request.
199
Events must be applied in the order of arrival.
201
Neither current nor pending state are modified unless noted otherwise.
203
</description>
204
</event>
205
<request name="commit_string">
207
<description summary="commit string">
208
Send the commit string text for insertion to the application.
209
Inserts a string at current cursor position (see commit event
211
sequence). The string to commit could be either just a single character
212
after a key press or the result of some composing.
213
The argument text is a buffer containing the string to insert. There is
215
a maximum length of wayland messages, so text can not be longer than
216
4000 bytes.
217
Values set with this event are double-buffered. They must be applied
219
and reset to initial on the next zwp_text_input_v3.commit request.
220
The initial value of text is an empty string.
222
</description>
223
<arg name="text" type="string"/>
224
</request>
225
<request name="set_preedit_string">
227
<description summary="pre-edit string">
228
Send the pre-edit string text to the application text input.
229
Place a new composing text (pre-edit) at the current cursor position.
231
Any previously set composing text must be removed. Any previously
232
existing selected text must be removed. The cursor is moved to a new
233
position within the preedit string.
234
The argument text is a buffer containing the preedit string. There is
236
a maximum length of wayland messages, so text can not be longer than
237
4000 bytes.
238
The arguments cursor_begin and cursor_end are counted in bytes relative
240
to the beginning of the submitted string buffer. Cursor should be
241
hidden by the text input when both are equal to -1.
242
cursor_begin indicates the beginning of the cursor. cursor_end
244
indicates the end of the cursor. It may be equal or different than
245
cursor_begin.
246
Values set with this event are double-buffered. They must be applied on
248
the next zwp_input_method_v2.commit event.
249
The initial value of text is an empty string. The initial value of
251
cursor_begin, and cursor_end are both 0.
252
</description>
253
<arg name="text" type="string"/>
254
<arg name="cursor_begin" type="int"/>
255
<arg name="cursor_end" type="int"/>
256
</request>
257
<request name="delete_surrounding_text">
259
<description summary="delete text">
260
Remove the surrounding text.
261
before_length and after_length are the number of bytes before and after
263
the current cursor index (excluding the preedit text) to delete.
264
If any preedit text is present, it is replaced with the cursor for the
266
purpose of this event. In effect before_length is counted from the
267
beginning of preedit text, and after_length from its end (see commit
268
event sequence).
269
Values set with this event are double-buffered. They must be applied
271
and reset to initial on the next zwp_input_method_v2.commit request.
272
The initial values of both before_length and after_length are 0.
274
</description>
275
<arg name="before_length" type="uint"/>
276
<arg name="after_length" type="uint"/>
277
</request>
278
<request name="commit">
280
<description summary="apply state">
281
Apply state changes from commit_string, set_preedit_string and
282
delete_surrounding_text requests.
283
The state relating to these events is double-buffered, and each one
285
modifies the pending state. This request replaces the current state
286
with the pending state.
287
The connected text input is expected to proceed by evaluating the
289
changes in the following order:
290
1. Replace existing preedit string with the cursor.
292
2. Delete requested surrounding text.
293
3. Insert commit string with the cursor at its end.
294
4. Calculate surrounding text to send.
295
5. Insert new preedit text in cursor position.
296
6. Place cursor inside preedit text.
297
The serial number reflects the last state of the zwp_input_method_v2
299
object known to the client. The value of the serial argument must be
300
equal to the number of done events already issued by that object. When
301
the compositor receives a commit request with a serial different than
302
the number of past done events, it must proceed as normal, except it
303
should not change the current state of the zwp_input_method_v2 object.
304
</description>
305
<arg name="serial" type="uint"/>
306
</request>
307
<request name="get_input_popup_surface">
309
<description summary="create popup surface">
310
Creates a new zwp_input_popup_surface_v2 object wrapping a given
311
surface.
312
The surface gets assigned the "input_popup" role. If the surface
314
already has an assigned role, the compositor must issue a protocol
315
error.
316
</description>
317
<arg name="id" type="new_id" interface="zwp_input_popup_surface_v2"/>
318
<arg name="surface" type="object" interface="wl_surface"/>
319
</request>
320
<request name="grab_keyboard">
322
<description summary="grab hardware keyboard">
323
Allow an input method to receive hardware keyboard input and process
324
key events to generate text events (with pre-edit) over the wire. This
325
allows input methods which compose multiple key events for inputting
326
text like it is done for CJK languages.
327
The compositor should send all keyboard events on the seat to the grab
329
holder via the returned wl_keyboard object. Nevertheless, the
330
compositor may decide not to forward any particular event. The
331
compositor must not further process any event after it has been
332
forwarded to the grab holder.
333
Releasing the resulting wl_keyboard object releases the grab.
335
</description>
336
<arg name="keyboard" type="new_id"
337
interface="zwp_input_method_keyboard_grab_v2"/>
338
</request>
339
<event name="unavailable">
341
<description summary="input method unavailable">
342
The input method ceased to be available.
343
The compositor must issue this event as the only event on the object if
345
there was another input_method object associated with the same seat at
346
the time of its creation.
347
The compositor must issue this request when the object is no longer
349
useable, e.g. due to seat removal.
350
The input method context becomes inert and should be destroyed after
352
deactivation is handled. Any further requests and events except for the
353
destroy request must be ignored.
354
</description>
355
</event>
356
<request name="destroy" type="destructor">
358
<description summary="destroy the text input">
359
Destroys the zwp_text_input_v2 object and any associated child
360
objects, i.e. zwp_input_popup_surface_v2 and
361
zwp_input_method_keyboard_grab_v2.
362
</description>
363
</request>
364
</interface>
365
<interface name="zwp_input_popup_surface_v2" version="1">
367
<description summary="popup surface">
368
This interface marks a surface as a popup for interacting with an input
369
method.
370
The compositor should place it near the active text input area. It must
372
be visible if and only if the input method is in the active state.
373
The client must not destroy the underlying wl_surface while the
375
zwp_input_popup_surface_v2 object exists.
376
</description>
377
<event name="text_input_rectangle">
379
<description summary="set text input area position">
380
Notify about the position of the area of the text input expressed as a
381
rectangle in surface local coordinates.
382
This is a hint to the input method telling it the relative position of
384
the text being entered.
385
</description>
386
<arg name="x" type="int"/>
387
<arg name="y" type="int"/>
388
<arg name="width" type="int"/>
389
<arg name="height" type="int"/>
390
</event>
391
<request name="destroy" type="destructor"/>
393
</interface>
394
<interface name="zwp_input_method_keyboard_grab_v2" version="1">
396
<!-- Closely follows wl_keyboard version 6 -->
397
<description summary="keyboard grab">
398
The zwp_input_method_keyboard_grab_v2 interface represents an exclusive
399
grab of the wl_keyboard interface associated with the seat.
400
</description>
401
<event name="keymap">
403
<description summary="keyboard mapping">
404
This event provides a file descriptor to the client which can be
405
memory-mapped to provide a keyboard mapping description.
406
</description>
407
<arg name="format" type="uint" enum="wl_keyboard.keymap_format"
408
summary="keymap format"/>
409
<arg name="fd" type="fd" summary="keymap file descriptor"/>
410
<arg name="size" type="uint" summary="keymap size, in bytes"/>
411
</event>
412
<event name="key">
414
<description summary="key event">
415
A key was pressed or released.
416
The time argument is a timestamp with millisecond granularity, with an
417
undefined base.
418
</description>
419
<arg name="serial" type="uint" summary="serial number of the key event"/>
420
<arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
421
<arg name="key" type="uint" summary="key that produced the event"/>
422
<arg name="state" type="uint" enum="wl_keyboard.key_state"
423
summary="physical state of the key"/>
424
</event>
425
<event name="modifiers">
427
<description summary="modifier and group state">
428
Notifies clients that the modifier and/or group state has changed, and
429
it should update its local state.
430
</description>
431
<arg name="serial" type="uint" summary="serial number of the modifiers event"/>
432
<arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
433
<arg name="mods_latched" type="uint" summary="latched modifiers"/>
434
<arg name="mods_locked" type="uint" summary="locked modifiers"/>
435
<arg name="group" type="uint" summary="keyboard layout"/>
436
</event>
437
<request name="release" type="destructor">
439
<description summary="release the grab object"/>
440
</request>
441
<event name="repeat_info">
443
<description summary="repeat rate and delay">
444
Informs the client about the keyboard's repeat rate and delay.
445
This event is sent as soon as the zwp_input_method_keyboard_grab_v2
447
object has been created, and is guaranteed to be received by the
448
client before any key press event.
449
Negative values for either rate or delay are illegal. A rate of zero
451
will disable any repeating (regardless of the value of delay).
452
This event can be sent later on as well with a new value if necessary,
454
so clients should continue listening for the event past the creation
455
of zwp_input_method_keyboard_grab_v2.
456
</description>
457
<arg name="rate" type="int"
458
summary="the rate of repeating keys in characters per second"/>
459
<arg name="delay" type="int"
460
summary="delay in milliseconds since key down until repeating starts"/>
461
</event>
462
</interface>
463
<interface name="zwp_input_method_manager_v2" version="1">
465
<description summary="input method manager">
466
The input method manager allows the client to become the input method on
467
a chosen seat.
468
No more than one input method must be associated with any seat at any
470
given time.
471
</description>
472
<request name="get_input_method">
474
<description summary="request an input method object">
475
Request a new input zwp_input_method_v2 object associated with a given
476
seat.
477
</description>
478
<arg name="seat" type="object" interface="wl_seat"/>
479
<arg name="input_method" type="new_id" interface="zwp_input_method_v2"/>
480
</request>
481
<request name="destroy" type="destructor">
483
<description summary="destroy the input method manager">
484
Destroys the zwp_input_method_manager_v2 object.
485
The zwp_input_method_v2 objects originating from it remain valid.
487
</description>
488
</request>
489
</interface>
490
</protocol>
491