1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="input_method_unstable_v2">
3
4 <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
13 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
20 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
24 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
33 <description summary="Protocol for creating input methods">
34 This protocol allows applications to act as input methods for compositors.
35
36 An input method context is used to manage the state of the input method.
37
38 Text strings are UTF-8 encoded, their indices and lengths are in bytes.
39
40 This document adheres to the RFC 2119 when using words like "must",
41 "should", "may", etc.
42
43 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
53 <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
57 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
60 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
66 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
70 There must be no more than one input method object per seat.
71 </description>
72
73 <enum name="error">
74 <entry name="role" value="0" summary="wl_surface has another role"/>
75 </enum>
76
77 <event name="activate">
78 <description summary="input method has been requested">
79 Notification that a text input focused on this seat requested the input
80 method to be activated.
81
82 This event serves the purpose of providing the compositor with an
83 active input method.
84
85 This event resets all state associated with previous
86 surrounding_text, text_change_cause, and content_type events, as well
87 as the state associated with set_preedit_string, commit_string, and
88 delete_surrounding_text requests. In addition, it marks the
89 zwp_input_method_v2 object as active, and makes any existing
90 zwp_input_popup_surface_v2 objects visible.
91
92 The surrounding_text, and content_type events must follow before the
93 next done event if the text input supports the respective
94 functionality.
95
96 State set with this event is double-buffered. It will get applied on
97 the next zwp_input_method_v2.done event, and stay valid until changed.
98 </description>
99 </event>
100
101 <event name="deactivate">
102 <description summary="deactivate event">
103 Notification that no focused text input currently needs an active
104 input method on this seat.
105
106 This event marks the zwp_input_method_v2 object as inactive. The
107 compositor must make all existing zwp_input_popup_surface_v2 objects
108 invisible until the next activate event.
109
110 State set with this event is double-buffered. It will get applied on
111 the next zwp_input_method_v2.done event, and stay valid until changed.
112 </description>
113 </event>
114
115 <event name="surrounding_text">
116 <description summary="surrounding text event">
117 Updates the surrounding plain text around the cursor, excluding the
118 preedit text.
119
120 If any preedit text is present, it is replaced with the cursor for the
121 purpose of this event.
122
123 The argument text is a buffer containing the surrounding text, and must
124 include the cursor position, and the complete selection. It should
125 contain additional characters before and after these. There is a
126 maximum length of wayland messages, so text can not be longer than 4000
127 bytes.
128
129 cursor is the byte offset of the cursor within the text buffer.
130
131 anchor is the byte offset of the selection anchor within the text
132 buffer. If there is no selected text, anchor must be the same as
133 cursor.
134
135 If this event does not arrive before the first done event, the input
136 method may assume that the text input does not support this
137 functionality and ignore following surrounding_text events.
138
139 Values set with this event are double-buffered. They will get applied
140 and set to initial values on the next zwp_input_method_v2.done
141 event.
142
143 The initial state for affected fields is empty, meaning that the text
144 input does not support sending surrounding text. If the empty values
145 get applied, subsequent attempts to change them may have no effect.
146 </description>
147 <arg name="text" type="string"/>
148 <arg name="cursor" type="uint"/>
149 <arg name="anchor" type="uint"/>
150 </event>
151
152 <event name="text_change_cause">
153 <description summary="indicates the cause of surrounding text change">
154 Tells the input method why the text surrounding the cursor changed.
155
156 Whenever the client detects an external change in text, cursor, or
157 anchor position, it must issue this request to the compositor. This
158 request is intended to give the input method a chance to update the
159 preedit text in an appropriate way, e.g. by removing it when the user
160 starts typing with a keyboard.
161
162 cause describes the source of the change.
163
164 The value set with this event is double-buffered. It will get applied
165 and set to its initial value on the next zwp_input_method_v2.done
166 event.
167
168 The initial value of cause is input_method.
169 </description>
170 <arg name="cause" type="uint" enum="zwp_text_input_v3.change_cause"/>
171 </event>
172
173 <event name="content_type">
174 <description summary="content purpose and hint">
175 Indicates the content type and hint for the current
176 zwp_input_method_v2 instance.
177
178 Values set with this event are double-buffered. They will get applied
179 on the next zwp_input_method_v2.done event.
180
181 The initial value for hint is none, and the initial value for purpose
182 is normal.
183 </description>
184 <arg name="hint" type="uint" enum="zwp_text_input_v3.content_hint"/>
185 <arg name="purpose" type="uint" enum="zwp_text_input_v3.content_purpose"/>
186 </event>
187
188 <event name="done">
189 <description summary="apply state">
190 Atomically applies state changes recently sent to the client.
191
192 The done event establishes and updates the state of the client, and
193 must be issued after any changes to apply them.
194
195 Text input state (content purpose, content hint, surrounding text, and
196 change cause) is conceptually double-buffered within an input method
197 context.
198
199 Events modify the pending state, as opposed to the current state in use
200 by the input method. A done event atomically applies all pending state,
201 replacing the current state. After done, the new pending state is as
202 documented for each related request.
203
204 Events must be applied in the order of arrival.
205
206 Neither current nor pending state are modified unless noted otherwise.
207 </description>
208 </event>
209
210 <request name="commit_string">
211 <description summary="commit string">
212 Send the commit string text for insertion to the application.
213
214 Inserts a string at current cursor position (see commit event
215 sequence). The string to commit could be either just a single character
216 after a key press or the result of some composing.
217
218 The argument text is a buffer containing the string to insert. There is
219 a maximum length of wayland messages, so text can not be longer than
220 4000 bytes.
221
222 Values set with this event are double-buffered. They must be applied
223 and reset to initial on the next zwp_text_input_v3.commit request.
224
225 The initial value of text is an empty string.
226 </description>
227 <arg name="text" type="string"/>
228 </request>
229
230 <request name="set_preedit_string">
231 <description summary="pre-edit string">
232 Send the pre-edit string text to the application text input.
233
234 Place a new composing text (pre-edit) at the current cursor position.
235 Any previously set composing text must be removed. Any previously
236 existing selected text must be removed. The cursor is moved to a new
237 position within the preedit string.
238
239 The argument text is a buffer containing the preedit string. There is
240 a maximum length of wayland messages, so text can not be longer than
241 4000 bytes.
242
243 The arguments cursor_begin and cursor_end are counted in bytes relative
244 to the beginning of the submitted string buffer. Cursor should be
245 hidden by the text input when both are equal to -1.
246
247 cursor_begin indicates the beginning of the cursor. cursor_end
248 indicates the end of the cursor. It may be equal or different than
249 cursor_begin.
250
251 Values set with this event are double-buffered. They must be applied on
252 the next zwp_input_method_v2.commit event.
253
254 The initial value of text is an empty string. The initial value of
255 cursor_begin, and cursor_end are both 0.
256 </description>
257 <arg name="text" type="string"/>
258 <arg name="cursor_begin" type="int"/>
259 <arg name="cursor_end" type="int"/>
260 </request>
261
262 <request name="delete_surrounding_text">
263 <description summary="delete text">
264 Remove the surrounding text.
265
266 before_length and after_length are the number of bytes before and after
267 the current cursor index (excluding the preedit text) to delete.
268
269 If any preedit text is present, it is replaced with the cursor for the
270 purpose of this event. In effect before_length is counted from the
271 beginning of preedit text, and after_length from its end (see commit
272 event sequence).
273
274 Values set with this event are double-buffered. They must be applied
275 and reset to initial on the next zwp_input_method_v2.commit request.
276
277 The initial values of both before_length and after_length are 0.
278 </description>
279 <arg name="before_length" type="uint"/>
280 <arg name="after_length" type="uint"/>
281 </request>
282
283 <request name="commit">
284 <description summary="apply state">
285 Apply state changes from commit_string, set_preedit_string and
286 delete_surrounding_text requests.
287
288 The state relating to these events is double-buffered, and each one
289 modifies the pending state. This request replaces the current state
290 with the pending state.
291
292 The connected text input is expected to proceed by evaluating the
293 changes in the following order:
294
295 1. Replace existing preedit string with the cursor.
296 2. Delete requested surrounding text.
297 3. Insert commit string with the cursor at its end.
298 4. Calculate surrounding text to send.
299 5. Insert new preedit text in cursor position.
300 6. Place cursor inside preedit text.
301
302 The serial number reflects the last state of the zwp_input_method_v2
303 object known to the client. The value of the serial argument must be
304 equal to the number of done events already issued by that object. When
305 the compositor receives a commit request with a serial different than
306 the number of past done events, it must proceed as normal, except it
307 should not change the current state of the zwp_input_method_v2 object.
308 </description>
309 <arg name="serial" type="uint"/>
310 </request>
311
312 <request name="get_input_popup_surface">
313 <description summary="create popup surface">
314 Creates a new zwp_input_popup_surface_v2 object wrapping a given
315 surface.
316
317 The surface gets assigned the "input_popup" role. If the surface
318 already has an assigned role, the compositor must issue a protocol
319 error.
320 </description>
321 <arg name="id" type="new_id" interface="zwp_input_popup_surface_v2"/>
322 <arg name="surface" type="object" interface="wl_surface"/>
323 </request>
324
325 <request name="grab_keyboard">
326 <description summary="grab hardware keyboard">
327 Allow an input method to receive hardware keyboard input and process
328 key events to generate text events (with pre-edit) over the wire. This
329 allows input methods which compose multiple key events for inputting
330 text like it is done for CJK languages.
331
332 The compositor should send all keyboard events on the seat to the grab
333 holder via the returned wl_keyboard object. Nevertheless, the
334 compositor may decide not to forward any particular event. The
335 compositor must not further process any event after it has been
336 forwarded to the grab holder.
337
338 Releasing the resulting wl_keyboard object releases the grab.
339 </description>
340 <arg name="keyboard" type="new_id"
341 interface="zwp_input_method_keyboard_grab_v2"/>
342 </request>
343
344 <event name="unavailable">
345 <description summary="input method unavailable">
346 The input method ceased to be available.
347
348 The compositor must issue this event as the only event on the object if
349 there was another input_method object associated with the same seat at
350 the time of its creation.
351
352 The compositor must issue this request when the object is no longer
353 usable, e.g. due to seat removal.
354
355 The input method context becomes inert and should be destroyed after
356 deactivation is handled. Any further requests and events except for the
357 destroy request must be ignored.
358 </description>
359 </event>
360
361 <request name="destroy" type="destructor">
362 <description summary="destroy the text input">
363 Destroys the zwp_text_input_v2 object and any associated child
364 objects, i.e. zwp_input_popup_surface_v2 and
365 zwp_input_method_keyboard_grab_v2.
366 </description>
367 </request>
368 </interface>
369
370 <interface name="zwp_input_popup_surface_v2" version="1">
371 <description summary="popup surface">
372 This interface marks a surface as a popup for interacting with an input
373 method.
374
375 The compositor should place it near the active text input area. It must
376 be visible if and only if the input method is in the active state.
377
378 The client must not destroy the underlying wl_surface while the
379 zwp_input_popup_surface_v2 object exists.
380 </description>
381
382 <event name="text_input_rectangle">
383 <description summary="set text input area position">
384 Notify about the position of the area of the text input expressed as a
385 rectangle in surface local coordinates.
386
387 This is a hint to the input method telling it the relative position of
388 the text being entered.
389 </description>
390 <arg name="x" type="int"/>
391 <arg name="y" type="int"/>
392 <arg name="width" type="int"/>
393 <arg name="height" type="int"/>
394 </event>
395
396 <request name="destroy" type="destructor"/>
397 </interface>
398
399 <interface name="zwp_input_method_keyboard_grab_v2" version="1">
400 <!-- Closely follows wl_keyboard version 6 -->
401 <description summary="keyboard grab">
402 The zwp_input_method_keyboard_grab_v2 interface represents an exclusive
403 grab of the wl_keyboard interface associated with the seat.
404 </description>
405
406 <event name="keymap">
407 <description summary="keyboard mapping">
408 This event provides a file descriptor to the client which can be
409 memory-mapped to provide a keyboard mapping description.
410 </description>
411 <arg name="format" type="uint" enum="wl_keyboard.keymap_format"
412 summary="keymap format"/>
413 <arg name="fd" type="fd" summary="keymap file descriptor"/>
414 <arg name="size" type="uint" summary="keymap size, in bytes"/>
415 </event>
416
417 <event name="key">
418 <description summary="key event">
419 A key was pressed or released.
420 The time argument is a timestamp with millisecond granularity, with an
421 undefined base.
422 </description>
423 <arg name="serial" type="uint" summary="serial number of the key event"/>
424 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
425 <arg name="key" type="uint" summary="key that produced the event"/>
426 <arg name="state" type="uint" enum="wl_keyboard.key_state"
427 summary="physical state of the key"/>
428 </event>
429
430 <event name="modifiers">
431 <description summary="modifier and group state">
432 Notifies clients that the modifier and/or group state has changed, and
433 it should update its local state.
434 </description>
435 <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
436 <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
437 <arg name="mods_latched" type="uint" summary="latched modifiers"/>
438 <arg name="mods_locked" type="uint" summary="locked modifiers"/>
439 <arg name="group" type="uint" summary="keyboard layout"/>
440 </event>
441
442 <request name="release" type="destructor">
443 <description summary="release the grab object"/>
444 </request>
445
446 <event name="repeat_info">
447 <description summary="repeat rate and delay">
448 Informs the client about the keyboard's repeat rate and delay.
449
450 This event is sent as soon as the zwp_input_method_keyboard_grab_v2
451 object has been created, and is guaranteed to be received by the
452 client before any key press event.
453
454 Negative values for either rate or delay are illegal. A rate of zero
455 will disable any repeating (regardless of the value of delay).
456
457 This event can be sent later on as well with a new value if necessary,
458 so clients should continue listening for the event past the creation
459 of zwp_input_method_keyboard_grab_v2.
460 </description>
461 <arg name="rate" type="int"
462 summary="the rate of repeating keys in characters per second"/>
463 <arg name="delay" type="int"
464 summary="delay in milliseconds since key down until repeating starts"/>
465 </event>
466 </interface>
467
468 <interface name="zwp_input_method_manager_v2" version="1">
469 <description summary="input method manager">
470 The input method manager allows the client to become the input method on
471 a chosen seat.
472
473 No more than one input method must be associated with any seat at any
474 given time.
475 </description>
476
477 <request name="get_input_method">
478 <description summary="request an input method object">
479 Request a new input zwp_input_method_v2 object associated with a given
480 seat.
481 </description>
482 <arg name="seat" type="object" interface="wl_seat"/>
483 <arg name="input_method" type="new_id" interface="zwp_input_method_v2"/>
484 </request>
485
486 <request name="destroy" type="destructor">
487 <description summary="destroy the input method manager">
488 Destroys the zwp_input_method_manager_v2 object.
489
490 The zwp_input_method_v2 objects originating from it remain valid.
491 </description>
492 </request>
493 </interface>
494</protocol>