| 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 enable, disable, |
| 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 preedit string, 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> |