1<?xml version="1.0" encoding="UTF-8"?>
2
3<protocol name="text_input_unstable_v3">
4 <copyright>
5 Copyright © 2012, 2013 Intel Corporation
6 Copyright © 2015, 2016 Jan Arne Petersen
7 Copyright © 2017, 2018 Red Hat, Inc.
8 Copyright © 2018 Purism SPC
9
10 Permission to use, copy, modify, distribute, and sell this
11 software and its documentation for any purpose is hereby granted
12 without fee, provided that the above copyright notice appear in
13 all copies and that both that copyright notice and this permission
14 notice appear in supporting documentation, and that the name of
15 the copyright holders not be used in advertising or publicity
16 pertaining to distribution of the software without specific,
17 written prior permission. The copyright holders make no
18 representations about the suitability of this software for any
19 purpose. It is provided "as is" without express or implied
20 warranty.
21
22 THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
23 SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
24 FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
25 SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
26 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
27 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
28 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
29 THIS SOFTWARE.
30 </copyright>
31
32 <description summary="Protocol for composing text">
33 This protocol allows compositors to act as input methods and to send text
34 to applications. A text input object is used to manage state of what are
35 typically text entry fields in the application.
36
37 This document adheres to the RFC 2119 when using words like "must",
38 "should", "may", etc.
39
40 Warning! The protocol described in this file is experimental and
41 backward incompatible changes may be made. Backward compatible changes
42 may be added together with the corresponding interface version bump.
43 Backward incompatible changes are done by bumping the version number in
44 the protocol and interface names and resetting the interface version.
45 Once the protocol is to be declared stable, the 'z' prefix and the
46 version number in the protocol and interface names are removed and the
47 interface version number is reset.
48 </description>
49
50 <interface name="zwp_text_input_v3" version="2">
51 <description summary="text input">
52 The zwp_text_input_v3 interface represents text input and input methods
53 associated with a seat. It provides enter/leave events to follow the
54 text input focus for a seat.
55
56 Requests are used to enable/disable the text-input object and set
57 state information like surrounding and selected text or the content type.
58 The information about the entered text is sent to the text-input object
59 via the preedit_string and commit_string events.
60
61 Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices
62 must not point to middle bytes inside a code point: they must either
63 point to the first byte of a code point or to the end of the buffer.
64 Lengths must be measured between two valid indices.
65
66 Focus moving throughout surfaces will result in the emission of
67 zwp_text_input_v3.enter and zwp_text_input_v3.leave events. The focused
68 surface must commit zwp_text_input_v3.enable and
69 zwp_text_input_v3.disable requests as the keyboard focus moves across
70 editable and non-editable elements of the UI. Those two requests are not
71 expected to be paired with each other, the compositor must be able to
72 handle consecutive series of the same request.
73
74 State is sent by the state requests (set_surrounding_text,
75 set_content_type and set_cursor_rectangle) and a commit request. After an
76 enter event or disable request all state information is invalidated and
77 needs to be resent by the client.
78 </description>
79
80 <request name="destroy" type="destructor">
81 <description summary="Destroy the wp_text_input">
82 Destroy the wp_text_input object. Also disables all surfaces enabled
83 through this wp_text_input object.
84 </description>
85 </request>
86
87 <request name="enable">
88 <description summary="Request text input to be enabled">
89 Requests text input on the surface previously obtained from the enter
90 event.
91
92 This request must be issued every time the focused text input changes
93 to a new one, including within the current surface. Use
94 zwp_text_input_v3.disable when there is no longer any input focus on
95 the current surface.
96
97 Clients must not enable more than one text input on the single seat
98 and should disable the current text input before enabling the new one.
99 Requests to enable a text input when another text input is enabled
100 on the same seat must be ignored by compositor.
101
102 This request resets all state associated with previous enable, disable,
103 set_surrounding_text, set_text_change_cause, set_content_type, and
104 set_cursor_rectangle requests, as well as the state associated with
105 preedit_string, commit_string, and delete_surrounding_text events.
106
107 The set_surrounding_text, set_content_type and set_cursor_rectangle
108 requests must follow if the text input supports the necessary
109 functionality.
110
111 State set with this request is double-buffered. It will get applied on
112 the next zwp_text_input_v3.commit request, and stay valid until the
113 next committed enable or disable request.
114
115 The changes must be applied by the compositor after issuing a
116 zwp_text_input_v3.commit request.
117 </description>
118 </request>
119
120 <request name="disable">
121 <description summary="Disable text input on a surface">
122 Explicitly disable text input on the current surface (typically when
123 there is no focus on any text entry inside the surface).
124
125 State set with this request is double-buffered. It will get applied on
126 the next zwp_text_input_v3.commit request.
127 </description>
128 </request>
129
130 <request name="set_surrounding_text">
131 <description summary="sets the surrounding text">
132 Sets the surrounding plain text around the input, excluding the preedit
133 text.
134
135 The client should notify the compositor of any changes in any of the
136 values carried with this request, including changes caused by handling
137 incoming text-input events as well as changes caused by other
138 mechanisms like keyboard typing.
139
140 If the client is unaware of the text around the cursor, it should not
141 issue this request, to signify lack of support to the compositor.
142
143 Text is UTF-8 encoded, and should include the cursor position, the
144 complete selection and additional characters before and after them.
145 There is a maximum length of wayland messages, so text can not be
146 longer than 4000 bytes.
147
148 Cursor is the byte offset of the cursor within text buffer.
149
150 Anchor is the byte offset of the selection anchor within text buffer.
151 If there is no selected text, anchor is the same as cursor.
152
153 If any preedit text is present, it is replaced with a cursor for the
154 purpose of this event.
155
156 Values set with this request are double-buffered. They will get applied
157 on the next zwp_text_input_v3.commit request, and stay valid until the
158 next committed enable or disable request.
159
160 The initial state for affected fields is empty, meaning that the text
161 input does not support sending surrounding text. If the empty values
162 get applied, subsequent attempts to change them may have no effect.
163 </description>
164 <arg name="text" type="string"/>
165 <arg name="cursor" type="int"/>
166 <arg name="anchor" type="int"/>
167 </request>
168
169 <enum name="change_cause">
170 <description summary="text change reason">
171 Reason for the change of surrounding text or cursor posision.
172 </description>
173 <entry name="input_method" value="0" summary="input method caused the change"/>
174 <entry name="other" value="1" summary="something else than the input method caused the change"/>
175 </enum>
176
177 <request name="set_text_change_cause">
178 <description summary="indicates the cause of surrounding text change">
179 Tells the compositor why the text surrounding the cursor changed.
180
181 Whenever the client detects an external change in text, cursor, or
182 anchor posision, it must issue this request to the compositor. This
183 request is intended to give the input method a chance to update the
184 preedit text in an appropriate way, e.g. by removing it when the user
185 starts typing with a keyboard.
186
187 cause describes the source of the change.
188
189 The value set with this request is double-buffered. It must be applied
190 and reset to initial at the next zwp_text_input_v3.commit request.
191
192 The initial value of cause is input_method.
193 </description>
194 <arg name="cause" type="uint" enum="change_cause"/>
195 </request>
196
197 <enum name="content_hint" bitfield="true">
198 <description summary="content hint">
199 Content hint is a bitmask to allow to modify the behavior of the text
200 input.
201 </description>
202 <entry name="none" value="0x0" summary="no special behavior"/>
203 <entry name="completion" value="0x1" summary="suggest word completions"/>
204 <entry name="spellcheck" value="0x2" summary="suggest word corrections"/>
205 <entry name="auto_capitalization" value="0x4" summary="switch to uppercase letters at the start of a sentence"/>
206 <entry name="lowercase" value="0x8" summary="prefer lowercase letters"/>
207 <entry name="uppercase" value="0x10" summary="prefer uppercase letters"/>
208 <entry name="titlecase" value="0x20" summary="prefer casing for titles and headings (can be language dependent)"/>
209 <entry name="hidden_text" value="0x40" summary="characters should be hidden"/>
210 <entry name="sensitive_data" value="0x80" summary="typed text should not be stored"/>
211 <entry name="latin" value="0x100" summary="just Latin characters should be entered"/>
212 <entry name="multiline" value="0x200" summary="the text input is multiline"/>
213 <entry
214 name="on_screen_input_provided" value="0x400" since="2"
215 summary="an on-screen way to fill in the input is already provided by the client"/>
216 <entry
217 name="no_emoji" value="0x800" since="2"
218 summary="prefer not offering emoji support"/>
219 <entry
220 name="preedit_shown" value="0x1000" since="2"
221 summary="the text input will display preedit text in place"/>
222 </enum>
223
224 <enum name="content_purpose">
225 <description summary="content purpose">
226 The content purpose allows to specify the primary purpose of a text
227 input.
228
229 This allows an input method to show special purpose input panels with
230 extra characters or to disallow some characters.
231 </description>
232 <entry name="normal" value="0" summary="default input, allowing all characters"/>
233 <entry name="alpha" value="1" summary="allow only alphabetic characters"/>
234 <entry name="digits" value="2" summary="allow only digits"/>
235 <entry name="number" value="3" summary="input a number (including decimal separator and sign)"/>
236 <entry name="phone" value="4" summary="input a phone number"/>
237 <entry name="url" value="5" summary="input an URL"/>
238 <entry name="email" value="6" summary="input an email address"/>
239 <entry name="name" value="7" summary="input a name of a person"/>
240 <entry name="password" value="8" summary="input a password (combine with sensitive_data hint)"/>
241 <entry name="pin" value="9" summary="input is a numeric password (combine with sensitive_data hint)"/>
242 <entry name="date" value="10" summary="input a date"/>
243 <entry name="time" value="11" summary="input a time"/>
244 <entry name="datetime" value="12" summary="input a date and time"/>
245 <entry name="terminal" value="13" summary="input for a terminal"/>
246 </enum>
247
248 <request name="set_content_type">
249 <description summary="set content purpose and hint">
250 Sets the content purpose and content hint. While the purpose is the
251 basic purpose of an input field, the hint flags allow to modify some of
252 the behavior.
253
254 Values set with this request are double-buffered. They will get applied
255 on the next zwp_text_input_v3.commit request.
256 Subsequent attempts to update them may have no effect. The values
257 remain valid until the next committed enable or disable request.
258
259 The initial value for hint is none, and the initial value for purpose
260 is normal.
261 </description>
262 <arg name="hint" type="uint" enum="content_hint"/>
263 <arg name="purpose" type="uint" enum="content_purpose"/>
264 </request>
265
266 <request name="set_cursor_rectangle">
267 <description summary="set cursor position">
268 Marks an area around the cursor as a x, y, width, height rectangle in
269 surface local coordinates.
270
271 Allows the compositor to put a window with word suggestions near the
272 cursor, without obstructing the text being input.
273
274 If the client is unaware of the position of edited text, it should not
275 issue this request, to signify lack of support to the compositor.
276
277 Values set with this request are double-buffered. They will get applied
278 on the next zwp_text_input_v3.commit request, and stay valid until the
279 next committed enable or disable request.
280
281 The initial values describing a cursor rectangle are empty. That means
282 the text input does not support describing the cursor area. If the
283 empty values get applied, subsequent attempts to change them may have
284 no effect.
285
286 As of version 2, the zwp_text_input_v3.commit request does not apply
287 values sent with this request. Instead, it stores them in a separate
288 "committed" area. The committed values, if still valid, get applied on
289 the next wl_surface.commit request on the surface with text-input focus.
290 Both committed and applied values get invalidated on:
291
292 - the next committed enable or disable request, or
293 - a change of the focused surface of the text-input (leave or enter events).
294
295 This double stage application allows the compositor to position
296 the input method popup in the same frame as the contents
297 of the text on the surface are updated.
298 </description>
299 <arg name="x" type="int"/>
300 <arg name="y" type="int"/>
301 <arg name="width" type="int"/>
302 <arg name="height" type="int"/>
303 </request>
304
305 <request name="commit">
306 <description summary="commit state">
307 Atomically applies state changes recently sent to the compositor.
308
309 The commit request establishes and updates the state of the client, and
310 must be issued after any changes to apply them.
311
312 Text input state (enabled status, content purpose, content hint,
313 surrounding text and change cause, cursor rectangle) is conceptually
314 double-buffered within the context of a text input, i.e. between a
315 committed enable request and the following committed enable or disable
316 request.
317
318 Protocol requests modify the pending state, as opposed to the current
319 state in use by the input method. A commit request atomically applies
320 all pending state, replacing the current state. After commit, the new
321 pending state is as documented for each related request.
322
323 Requests are applied in the order of arrival.
324
325 Neither current nor pending state are modified unless noted otherwise.
326
327 The compositor must count the number of commit requests coming from
328 each zwp_text_input_v3 object and use the count as the serial in done
329 events.
330 </description>
331 </request>
332
333 <event name="enter">
334 <description summary="enter event">
335 Notification that this seat's text-input focus is on a certain surface.
336
337 If client has created multiple text input objects, compositor must send
338 this event to all of them.
339
340 When the seat has the keyboard capability the text-input focus follows
341 the keyboard focus. This event sets the current surface for the
342 text-input object.
343 </description>
344 <arg name="surface" type="object" interface="wl_surface"/>
345 </event>
346
347 <event name="leave">
348 <description summary="leave event">
349 Notification that this seat's text-input focus is no longer on a
350 certain surface. The client should reset any preedit string previously
351 set.
352
353 The leave notification clears the current surface. It is sent before
354 the enter notification for the new focus. After leave event, compositor
355 must ignore requests from any text input instances until next enter
356 event.
357
358 When the seat has the keyboard capability the text-input focus follows
359 the keyboard focus.
360 </description>
361 <arg name="surface" type="object" interface="wl_surface"/>
362 </event>
363
364 <event name="preedit_string">
365 <description summary="pre-edit">
366 Notify when a new composing text (pre-edit) should be set at the
367 current cursor position. Any previously set composing text must be
368 removed. Any previously existing selected text must be removed.
369
370 The argument text contains the pre-edit string buffer.
371
372 The parameters cursor_begin and cursor_end are counted in bytes
373 relative to the beginning of the submitted text buffer. Cursor should
374 be hidden when both are equal to -1.
375
376 They could be represented by the client as a line if both values are
377 the same, or as a text highlight otherwise.
378
379 Values set with this event are double-buffered. They must be applied
380 and reset to initial on the next zwp_text_input_v3.done event.
381
382 The initial value of text is an empty string, and cursor_begin,
383 cursor_end and cursor_hidden are all 0.
384 </description>
385 <arg name="text" type="string" allow-null="true"/>
386 <arg name="cursor_begin" type="int"/>
387 <arg name="cursor_end" type="int"/>
388 </event>
389
390 <event name="commit_string">
391 <description summary="text commit">
392 Notify when text should be inserted into the editor widget. The text to
393 commit could be either just a single character after a key press or the
394 result of some composing (pre-edit).
395
396 Values set with this event are double-buffered. They must be applied
397 and reset to initial on the next zwp_text_input_v3.done event.
398
399 The initial value of text is an empty string.
400 </description>
401 <arg name="text" type="string" allow-null="true"/>
402 </event>
403
404 <event name="delete_surrounding_text">
405 <description summary="delete surrounding text">
406 Notify when the text around the current cursor position should be
407 deleted.
408
409 Before_length and after_length are the number of bytes before and after
410 the current cursor index (excluding the selection) to delete.
411
412 If a preedit text is present, in effect before_length is counted from
413 the beginning of it, and after_length from its end (see done event
414 sequence).
415
416 Values set with this event are double-buffered. They must be applied
417 and reset to initial on the next zwp_text_input_v3.done event.
418
419 The initial values of both before_length and after_length are 0.
420 </description>
421 <arg name="before_length" type="uint" summary="length of text before current cursor position"/>
422 <arg name="after_length" type="uint" summary="length of text after current cursor position"/>
423 </event>
424
425 <event name="done">
426 <description summary="apply changes">
427 Instruct the application to apply changes to state requested by the
428 preedit_string, commit_string delete_surrounding_text, and action
429 events.
430
431 The state relating to these events is double-buffered, and each one
432 modifies the pending state. This event replaces the current state with
433 the pending state.
434
435 The application must proceed by evaluating the changes in the following
436 order:
437
438 1. Replace existing preedit string with the cursor.
439 2. Delete requested surrounding text.
440 3. Insert commit string with the cursor at its end.
441 4. Calculate surrounding text to send.
442 5. Insert new preedit text in cursor position.
443 6. Place cursor inside preedit text.
444 7. Perform the requested action.
445
446 The serial number reflects the last state of the zwp_text_input_v3
447 object known to the compositor. The value of the serial argument must
448 be equal to the number of commit requests already issued on that object.
449
450 When the client receives a done event with a serial different than the
451 number of past commit requests, it must proceed with evaluating and
452 applying the changes as normal, except it should not change the current
453 state of the zwp_text_input_v3 object. All pending state requests
454 (set_surrounding_text, set_content_type and set_cursor_rectangle) on
455 the zwp_text_input_v3 object should be sent and committed after
456 receiving a zwp_text_input_v3.done event with a matching serial.
457 </description>
458 <arg name="serial" type="uint"/>
459 </event>
460
461 <!-- Version 2 additions -->
462 <enum name="error" since="2">
463 <entry name="invalid_action" value="0" summary="an invalid or duplicate action was specified"/>
464 </enum>
465
466 <enum name="action" since="2">
467 <description summary="action">
468 A possible action to perform on a text input.
469
470 The submit action is intended for input entries that expect some sort of
471 activation after user interaction, e.g. the URL entry in a browser.
472 </description>
473 <entry name="none" value="0" summary="no action"/>
474 <entry name="submit" value="1" summary="the action is submitted"/>
475 </enum>
476
477 <event name="action" since="2">
478 <description summary="action performed">
479 An action was performed on this text input.
480
481 Values set with this event are double-buffered. They must be applied
482 and reset to initial on the next zwp_text_input_v3.done event.
483
484 The initial value of action is none.
485 </description>
486 <arg name="action" type="uint" enum="action" summary="action performed"/>
487 <arg name="serial" type="uint" summary="serial number of the action event"/>
488 </event>
489
490 <event name="language" since="2">
491 <description summary="notify of language selection">
492 Notify the application of language used by the input method.
493
494 This event will be sent on creation if known and for all subsequent changes.
495
496 The language should be specified as an IETF BCP 47 tag.
497 Setting an empty string will reset any known language back to the default unknown state.
498 </description>
499 <arg name="language" type="string" summary="new language set by IME"/>
500 </event>
501
502 <request name="set_available_actions" since="2">
503 <description summary="set the available actions">
504 Set the actions available for this text input.
505
506 Values set with this request are double-buffered. They will get applied
507 on the next zwp_text_input_v3.commit request.
508
509 If the available_actions array contains the none action, or contains the
510 same action multiple times, the compositor must raise the invalid_action
511 protocol error.
512
513 Initially, no actions are available.
514 </description>
515 <arg name="available_actions" type="array" summary="available actions"/>
516 </request>
517
518 <request name="show_input_panel" since="2">
519 <description summary="show input panel">
520 Requests an input panel to be shown (e.g. a on-screen keyboard).
521
522 This request only hints the desired interaction pattern from the
523 client side, and its effect may be ignored by compositors given
524 other environmental factors. Repeated calls will be ignored.
525 </description>
526 </request>
527
528 <request name="hide_input_panel" since="2">
529 <description summary="hide input panel">
530 Requests an input panel to be hidden.
531
532 This request only hints the desired interaction pattern from the
533 client side, and its effect may be ignored by compositors given
534 other environmental factors. Repeated calls will be ignored.
535 </description>
536 </request>
537
538 <enum name="preedit_hint">
539 <description summary="preedit style hint">
540 Style hints for the preedit string.
541 </description>
542 <entry name="whole" value="1" summary="simple pre-edit text style, typically underlined"/>
543 <entry name="selection" value="2"
544 summary="hint for a selected piece of text, e.g. per-character navigation and composition"/>
545 <entry name="prediction" value="3" summary="predicted text, not typed by the user"/>
546 <entry name="prefix" value="4"
547 summary="prefixed text not being currently edited, e.g. prior to a 'selection' section"/>
548 <entry name="suffix" value="5"
549 summary="suffixed text not being currently edited, e.g. after a 'selection' section"/>
550 <entry name="spelling_error" value="6" summary="spelling error"/>
551 <entry name="compose_error" value="7"
552 summary="wrong composition, e.g. user input that can not be transliterated"/>
553 </enum>
554
555 <event name="preedit_hint" since="2">
556 <description summary="pre-edit">
557 Notify of contextual hints for the pre-edit string. This
558 event is always sent together with a zwp_text_input_v3.preedit_string
559 event.
560
561 The parameters start and end are counted in bytes relative to the
562 beginning of the text buffer submitted through
563 zwp_text_input_v3.preedit_string, and represent the substring in the
564 pre-edit text affected by the hint.
565
566 Multiple events may be submitted if the preedit string has different
567 sections. The extent of hints may overlap. The parts of the preedit
568 string that are not covered by any zwp_text_input_v3.preedit_hint event,
569 the text will be considered unhinted. This is also the case if no
570 preedit_hint event is sent.
571
572 Clients should provide recognizable visuals to these hints. if they are
573 unable to comply with this requisition, it may be preferable for them
574 keep the preedit_shown content hint disabled.
575
576 Values set with this event are double-buffered. They must be applied
577 and reset on the next zwp_text_input_v3.done event.
578 </description>
579 <arg name="start" type="uint" summary="starting point of the affected substring"/>
580 <arg name="end" type="uint" summary="end point of the affected substring"/>
581 <arg name="hint" type="uint" enum="preedit_hint" summary="hint to apply"/>
582 </event>
583 </interface>
584
585 <interface name="zwp_text_input_manager_v3" version="2">
586 <description summary="text input manager">
587 A factory for text-input objects. This object is a global singleton.
588 </description>
589
590 <request name="destroy" type="destructor">
591 <description summary="Destroy the wp_text_input_manager">
592 Destroy the wp_text_input_manager object.
593 </description>
594 </request>
595
596 <request name="get_text_input">
597 <description summary="create a new text input object">
598 Creates a new text-input object for a given seat.
599 </description>
600 <arg name="id" type="new_id" interface="zwp_text_input_v3"/>
601 <arg name="seat" type="object" interface="wl_seat"/>
602 </request>
603 </interface>
604</protocol>