| 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> |