Warning, /libraries/plasma-wayland-protocols/src/protocols/text-input-unstable-v2.xml is written in an unsupported language. File is not indexed.
0001 <?xml version="1.0" encoding="UTF-8"?> 0002 0003 <protocol name="text_input_unstable_v2"> 0004 <copyright> 0005 SPDX-FileCopyrightText: 2012, 2013 Intel Corporation 0006 SPDX-FileCopyrightText: 2015, 2016 Jan Arne Petersen 0007 0008 SPDX-License-Identifier: MIT-CMU 0009 </copyright> 0010 0011 <interface name="zwp_text_input_v2" version="1"> 0012 <description summary="text input"> 0013 The zwp_text_input_v2 interface represents text input and input methods 0014 associated with a seat. It provides enter/leave events to follow the 0015 text input focus for a seat. 0016 0017 Requests are used to enable/disable the text-input object and set 0018 state information like surrounding and selected text or the content type. 0019 The information about the entered text is sent to the text-input object 0020 via the pre-edit and commit events. Using this interface removes the need 0021 for applications to directly process hardware key events and compose text 0022 out of them. 0023 0024 Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices 0025 have to always point to the first byte of an UTF-8 encoded code point. 0026 Lengths are not allowed to contain just a part of an UTF-8 encoded code 0027 point. 0028 0029 State is sent by the state requests (set_surrounding_text, 0030 set_content_type, set_cursor_rectangle and set_preferred_language) and 0031 an update_state request. After an enter or an input_method_change event 0032 all state information is invalidated and needs to be resent from the 0033 client. A reset or entering a new widget on client side also 0034 invalidates all current state information. 0035 </description> 0036 0037 <request name="destroy" type="destructor"> 0038 <description summary="Destroy the wp_text_input"> 0039 Destroy the wp_text_input object. Also disables all surfaces enabled 0040 through this wp_text_input object 0041 </description> 0042 </request> 0043 0044 <request name="enable"> 0045 <description summary="enable text input for surface"> 0046 Enable text input in a surface (usually when a text entry inside of it 0047 has focus). 0048 0049 This can be called before or after a surface gets text (or keyboard) 0050 focus via the enter event. Text input to a surface is only active 0051 when it has the current text (or keyboard) focus and is enabled. 0052 </description> 0053 <arg name="surface" type="object" interface="wl_surface"/> 0054 </request> 0055 0056 <request name="disable"> 0057 <description summary="disable text input for surface"> 0058 Disable text input in a surface (typically when there is no focus on any 0059 text entry inside the surface). 0060 </description> 0061 <arg name="surface" type="object" interface="wl_surface"/> 0062 </request> 0063 0064 <request name="show_input_panel"> 0065 <description summary="show input panels"> 0066 Requests input panels (virtual keyboard) to show. 0067 0068 This should be used for example to show a virtual keyboard again 0069 (with a tap) after it was closed by pressing on a close button on the 0070 keyboard. 0071 </description> 0072 </request> 0073 0074 <request name="hide_input_panel"> 0075 <description summary="hide input panels"> 0076 Requests input panels (virtual keyboard) to hide. 0077 </description> 0078 </request> 0079 0080 <request name="set_surrounding_text"> 0081 <description summary="sets the surrounding text"> 0082 Sets the plain surrounding text around the input position. Text is 0083 UTF-8 encoded. Cursor is the byte offset within the surrounding text. 0084 Anchor is the byte offset of the selection anchor within the 0085 surrounding text. If there is no selected text, anchor is the same as 0086 cursor. 0087 0088 Make sure to always send some text before and after the cursor 0089 except when the cursor is at the beginning or end of text. 0090 0091 When there was a configure_surrounding_text event take the 0092 before_cursor and after_cursor arguments into account for picking how 0093 much surrounding text to send. 0094 0095 There is a maximum length of wayland messages so text can not be 0096 longer than 4000 bytes. 0097 </description> 0098 <arg name="text" type="string"/> 0099 <arg name="cursor" type="int"/> 0100 <arg name="anchor" type="int"/> 0101 </request> 0102 0103 <enum name="content_hint" bitfield="true"> 0104 <description summary="content hint"> 0105 Content hint is a bitmask to allow to modify the behavior of the text 0106 input. 0107 </description> 0108 <entry name="none" value="0x0" summary="no special behaviour"/> 0109 <entry name="auto_completion" value="0x1" summary="suggest word completions"/> 0110 <entry name="auto_correction" value="0x2" summary="suggest word corrections"/> 0111 <entry name="auto_capitalization" value="0x4" summary="switch to uppercase letters at the start of a sentence"/> 0112 <entry name="lowercase" value="0x8" summary="prefer lowercase letters"/> 0113 <entry name="uppercase" value="0x10" summary="prefer uppercase letters"/> 0114 <entry name="titlecase" value="0x20" summary="prefer casing for titles and headings (can be language dependent)"/> 0115 <entry name="hidden_text" value="0x40" summary="characters should be hidden"/> 0116 <entry name="sensitive_data" value="0x80" summary="typed text should not be stored"/> 0117 <entry name="latin" value="0x100" summary="just latin characters should be entered"/> 0118 <entry name="multiline" value="0x200" summary="the text input is multiline"/> 0119 </enum> 0120 0121 <enum name="content_purpose"> 0122 <description summary="content purpose"> 0123 The content purpose allows to specify the primary purpose of a text 0124 input. 0125 0126 This allows an input method to show special purpose input panels with 0127 extra characters or to disallow some characters. 0128 </description> 0129 <entry name="normal" value="0" summary="default input, allowing all characters"/> 0130 <entry name="alpha" value="1" summary="allow only alphabetic characters"/> 0131 <entry name="digits" value="2" summary="allow only digits"/> 0132 <entry name="number" value="3" summary="input a number (including decimal separator and sign)"/> 0133 <entry name="phone" value="4" summary="input a phone number"/> 0134 <entry name="url" value="5" summary="input an URL"/> 0135 <entry name="email" value="6" summary="input an email address"/> 0136 <entry name="name" value="7" summary="input a name of a person"/> 0137 <entry name="password" value="8" summary="input a password (combine with password or sensitive_data hint)"/> 0138 <entry name="date" value="9" summary="input a date"/> 0139 <entry name="time" value="10" summary="input a time"/> 0140 <entry name="datetime" value="11" summary="input a date and time"/> 0141 <entry name="terminal" value="12" summary="input for a terminal"/> 0142 </enum> 0143 0144 <request name="set_content_type"> 0145 <description summary="set content purpose and hint"> 0146 Sets the content purpose and content hint. While the purpose is the 0147 basic purpose of an input field, the hint flags allow to modify some 0148 of the behavior. 0149 0150 When no content type is explicitly set, a normal content purpose with 0151 none hint should be assumed. 0152 </description> 0153 <arg name="hint" type="uint" enum="content_hint"/> 0154 <arg name="purpose" type="uint" enum="content_purpose"/> 0155 </request> 0156 0157 <request name="set_cursor_rectangle"> 0158 <description summary="set cursor position"> 0159 Sets the cursor outline as a x, y, width, height rectangle in surface 0160 local coordinates. 0161 0162 Allows the compositor to put a window with word suggestions near the 0163 cursor. 0164 </description> 0165 <arg name="x" type="int"/> 0166 <arg name="y" type="int"/> 0167 <arg name="width" type="int"/> 0168 <arg name="height" type="int"/> 0169 </request> 0170 0171 <request name="set_preferred_language"> 0172 <description summary="sets preferred language"> 0173 Sets a specific language. This allows for example a virtual keyboard to 0174 show a language specific layout. The "language" argument is a RFC-3066 0175 format language tag. 0176 0177 It could be used for example in a word processor to indicate language of 0178 currently edited document or in an instant message application which 0179 tracks languages of contacts. 0180 </description> 0181 <arg name="language" type="string"/> 0182 </request> 0183 0184 <enum name="update_state"> 0185 <description summary="update_state flags"> 0186 Defines the reason for sending an updated state. 0187 </description> 0188 <entry name="change" value="0" summary="updated state because it changed"/> 0189 <entry name="full" value="1" summary="full state after enter or input_method_changed event"/> 0190 <entry name="reset" value="2" summary="full state after reset"/> 0191 <entry name="enter" value="3" summary="full state after switching focus to a different widget on client side"/> 0192 </enum> 0193 0194 <request name="update_state"> 0195 <description summary="update state"> 0196 Allows to atomically send state updates from client. 0197 0198 This request should follow after a batch of state updating requests 0199 like set_surrounding_text, set_content_type, set_cursor_rectangle and 0200 set_preferred_language. 0201 0202 The flags field indicates why an updated state is sent to the input 0203 method. 0204 0205 Reset should be used by an editor widget after the text was changed 0206 outside of the normal input method flow. 0207 0208 For "change" it is enough to send the changed state, else the full 0209 state should be send. 0210 0211 Serial should be set to the serial from the last enter or 0212 input_method_changed event. 0213 0214 To make sure to not receive outdated input method events after a 0215 reset or switching to a new widget wl_display_sync() should be used 0216 after update_state in these cases. 0217 </description> 0218 <arg name="serial" type="uint" summary="serial of the enter or input_method_changed event"/> 0219 <arg name="reason" type="uint" enum="update_state"/> 0220 </request> 0221 0222 <event name="enter"> 0223 <description summary="enter event"> 0224 Notification that this seat's text-input focus is on a certain surface. 0225 0226 When the seat has the keyboard capability the text-input focus follows 0227 the keyboard focus. 0228 </description> 0229 <arg name="serial" type="uint" summary="serial to be used by update_state"/> 0230 <arg name="surface" type="object" interface="wl_surface"/> 0231 </event> 0232 0233 <event name="leave"> 0234 <description summary="leave event"> 0235 Notification that this seat's text-input focus is no longer on 0236 a certain surface. 0237 0238 The leave notification is sent before the enter notification 0239 for the new focus. 0240 0241 When the seat has the keyboard capability the text-input focus follows 0242 the keyboard focus. 0243 </description> 0244 <arg name="serial" type="uint"/> 0245 <arg name="surface" type="object" interface="wl_surface"/> 0246 </event> 0247 0248 <enum name="input_panel_visibility"> 0249 <entry name="hidden" value="0" 0250 summary="the input panel (virtual keyboard) is hidden"/> 0251 <entry name="visible" value="1" 0252 summary="the input panel (virtual keyboard) is visible"/> 0253 </enum> 0254 0255 <event name="input_panel_state"> 0256 <description summary="state of the input panel"> 0257 Notification that the visibility of the input panel (virtual keyboard) 0258 changed. 0259 0260 The rectangle x, y, width, height defines the area overlapped by the 0261 input panel (virtual keyboard) on the surface having the text 0262 focus in surface local coordinates. 0263 0264 That can be used to make sure widgets are visible and not covered by 0265 a virtual keyboard. 0266 </description> 0267 <arg name="state" type="uint" enum="input_panel_visibility"/> 0268 <arg name="x" type="int"/> 0269 <arg name="y" type="int"/> 0270 <arg name="width" type="int"/> 0271 <arg name="height" type="int"/> 0272 </event> 0273 0274 <event name="preedit_string"> 0275 <description summary="pre-edit"> 0276 Notify when a new composing text (pre-edit) should be set around the 0277 current cursor position. Any previously set composing text should 0278 be removed. 0279 0280 The commit text can be used to replace the composing text in some cases 0281 (for example when losing focus). 0282 0283 The text input should also handle all preedit_style and preedit_cursor 0284 events occurring directly before preedit_string. 0285 </description> 0286 <arg name="text" type="string"/> 0287 <arg name="commit" type="string"/> 0288 </event> 0289 0290 <enum name="preedit_style"> 0291 <entry name="default" value="0" summary="default style for composing text"/> 0292 <entry name="none" value="1" summary="composing text should be shown the same as non-composing text"/> 0293 <entry name="active" value="2" summary="composing text might be bold"/> 0294 <entry name="inactive" value="3" summary="composing text might be cursive"/> 0295 <entry name="highlight" value="4" summary="composing text might have a different background color"/> 0296 <entry name="underline" value="5" summary="composing text might be underlined"/> 0297 <entry name="selection" value="6" summary="composing text should be shown the same as selected text"/> 0298 <entry name="incorrect" value="7" summary="composing text might be underlined with a red wavy line"/> 0299 </enum> 0300 0301 <event name="preedit_styling"> 0302 <description summary="pre-edit styling"> 0303 Sets styling information on composing text. The style is applied for 0304 length bytes from index relative to the beginning of the composing 0305 text (as byte offset). Multiple styles can be applied to a composing 0306 text by sending multiple preedit_styling events. 0307 0308 This event is handled as part of a following preedit_string event. 0309 </description> 0310 <arg name="index" type="uint"/> 0311 <arg name="length" type="uint"/> 0312 <arg name="style" type="uint" enum="preedit_style"/> 0313 </event> 0314 0315 <event name="preedit_cursor"> 0316 <description summary="pre-edit cursor"> 0317 Sets the cursor position inside the composing text (as byte 0318 offset) relative to the start of the composing text. When index is a 0319 negative number no cursor is shown. 0320 0321 When no preedit_cursor event is sent the cursor will be at the end of 0322 the composing text by default. 0323 0324 This event is handled as part of a following preedit_string event. 0325 </description> 0326 <arg name="index" type="int"/> 0327 </event> 0328 0329 <event name="commit_string"> 0330 <description summary="commit"> 0331 Notify when text should be inserted into the editor widget. The text to 0332 commit could be either just a single character after a key press or the 0333 result of some composing (pre-edit). It could be also an empty text 0334 when some text should be removed (see delete_surrounding_text) or when 0335 the input cursor should be moved (see cursor_position). 0336 0337 Any previously set composing text should be removed. 0338 </description> 0339 <arg name="text" type="string"/> 0340 </event> 0341 0342 <event name="cursor_position"> 0343 <description summary="set cursor to new position"> 0344 Notify when the cursor or anchor position should be modified. 0345 0346 This event should be handled as part of a following commit_string 0347 event. 0348 0349 The text between anchor and index should be selected. 0350 </description> 0351 <arg name="index" type="int" summary="position of cursor"/> 0352 <arg name="anchor" type="int" summary="position of selection anchor"/> 0353 </event> 0354 0355 <event name="delete_surrounding_text"> 0356 <description summary="delete surrounding text"> 0357 Notify when the text around the current cursor position should be 0358 deleted. BeforeLength and afterLength is the length (in bytes) of text 0359 before and after the current cursor position (excluding the selection) 0360 to delete. 0361 0362 This event should be handled as part of a following commit_string 0363 or preedit_string event. 0364 </description> 0365 <arg name="before_length" type="uint" summary="length of text before current cursor position"/> 0366 <arg name="after_length" type="uint" summary="length of text after current cursor position"/> 0367 </event> 0368 0369 <event name="modifiers_map"> 0370 <description summary="modifiers map"> 0371 Transfer an array of 0-terminated modifiers names. The position in 0372 the array is the index of the modifier as used in the modifiers 0373 bitmask in the keysym event. 0374 </description> 0375 <arg name="map" type="array"/> 0376 </event> 0377 0378 <event name="keysym"> 0379 <description summary="keysym"> 0380 Notify when a key event was sent. Key events should not be used 0381 for normal text input operations, which should be done with 0382 commit_string, delete_surrounding_text, etc. The key event follows 0383 the wl_keyboard key event convention. Sym is a XKB keysym, state a 0384 wl_keyboard key_state. Modifiers are a mask for effective modifiers 0385 (where the modifier indices are set by the modifiers_map event) 0386 </description> 0387 <arg name="time" type="uint"/> 0388 <arg name="sym" type="uint"/> 0389 <arg name="state" type="uint"/> 0390 <arg name="modifiers" type="uint"/> 0391 </event> 0392 0393 <event name="language"> 0394 <description summary="language"> 0395 Sets the language of the input text. The "language" argument is a RFC-3066 0396 format language tag. 0397 </description> 0398 <arg name="language" type="string"/> 0399 </event> 0400 0401 <enum name="text_direction"> 0402 <entry name="auto" value="0" summary="automatic text direction based on text and language"/> 0403 <entry name="ltr" value="1" summary="left-to-right"/> 0404 <entry name="rtl" value="2" summary="right-to-left"/> 0405 </enum> 0406 0407 <event name="text_direction"> 0408 <description summary="text direction"> 0409 Sets the text direction of input text. 0410 0411 It is mainly needed for showing input cursor on correct side of the 0412 editor when there is no input yet done and making sure neutral 0413 direction text is laid out properly. 0414 </description> 0415 <arg name="direction" type="uint" enum="text_direction"/> 0416 </event> 0417 0418 <event name="configure_surrounding_text"> 0419 <description summary="configure amount of surrounding text to be sent"> 0420 Configure what amount of surrounding text is expected by the 0421 input method. The surrounding text will be sent in the 0422 set_surrounding_text request on the following state information updates. 0423 </description> 0424 <arg name="before_cursor" type="int"/> 0425 <arg name="after_cursor" type="int"/> 0426 </event> 0427 0428 <event name="input_method_changed"> 0429 <description summary="Notifies about a changed input method"> 0430 The input method changed on compositor side, which invalidates all 0431 current state information. New state information should be sent from 0432 the client via state requests (set_surrounding_text, 0433 set_content_hint, ...) and update_state. 0434 </description> 0435 <arg name="serial" type="uint" summary="serial to be used by update_state"/> 0436 <arg name="flags" type="uint" summary="currently unused"/> 0437 </event> 0438 </interface> 0439 0440 <interface name="zwp_text_input_manager_v2" version="1"> 0441 <description summary="text input manager"> 0442 A factory for text-input objects. This object is a global singleton. 0443 </description> 0444 0445 <request name="destroy" type="destructor"> 0446 <description summary="Destroy the wp_text_input_manager"> 0447 Destroy the wp_text_input_manager object. 0448 </description> 0449 </request> 0450 0451 <request name="get_text_input"> 0452 <description summary="create a new text input object"> 0453 Creates a new text-input object for a given seat. 0454 </description> 0455 <arg name="id" type="new_id" interface="zwp_text_input_v2"/> 0456 <arg name="seat" type="object" interface="wl_seat"/> 0457 </request> 0458 </interface> 0459 </protocol>