| <?xml version="1.0" encoding="UTF-8"?> |
| <protocol name="text"> |
| |
| <copyright> |
| Copyright © 2012 Intel Corporation |
| Copyright © 2013-2020 LG Electronics, Inc. |
| |
| Permission to use, copy, modify, distribute, and sell this |
| software and its documentation for any purpose is hereby granted |
| without fee, provided that the above copyright notice appear in |
| all copies and that both that copyright notice and this permission |
| notice appear in supporting documentation, and that the name of |
| the copyright holders not be used in advertising or publicity |
| pertaining to distribution of the software without specific, |
| written prior permission. The copyright holders make no |
| representations about the suitability of this software for any |
| purpose. It is provided "as is" without express or implied |
| warranty. |
| |
| THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS |
| SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND |
| FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY |
| SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
| WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN |
| AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, |
| ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF |
| THIS SOFTWARE. |
| </copyright> |
| |
| <interface name="text_model" version="1"> |
| <description summary="text model"> |
| A model for text input. Adds support for text input and input methods to |
| applications. A text_model object is created from a text_model_factory and |
| corresponds typically to a text entry in an application. Requests are used |
| to activate/deactivate the model and set information like surrounding and |
| selected text or the content type. The information about entered text is |
| sent to the model via the pre-edit and commit events. Using this interface |
| removes the need for applications to directly process hardware key events |
| and compose text out of them. |
| </description> |
| |
| <request name="set_surrounding_text"> |
| <description summary="sets the surrounding text"> |
| Sets the plain surrounding text around the input position. Cursor is the |
| byte index within the surrounding text. Anchor is the byte index of the |
| selection anchor within the surrounding text. If there is no selected |
| text anchor is the same as cursor. |
| </description> |
| <arg name="text" type="string"/> |
| <arg name="cursor" type="uint"/> |
| <arg name="anchor" type="uint"/> |
| </request> |
| |
| <request name="activate"> |
| <description summary="request activation"> |
| Requests the model to be activated (typically when the text entry gets |
| focus). The seat argument is a wl_seat which maintains the focus for |
| this activation. The surface argument is a wl_surface assigned to the |
| model and tracked for focus lost. The activated event is emitted on |
| successful activation. |
| </description> |
| <arg name="serial" type="uint"/> |
| <arg name="seat" type="object" interface="wl_seat"/> |
| <arg name="surface" type="object" interface="wl_surface"/> |
| </request> |
| |
| <request name="deactivate"> |
| <description summary="request deactivation"> |
| Requests the model to be deactivated (typically when the text entry |
| lost focus). The seat argument is a wl_seat which was used for |
| activation. |
| </description> |
| <arg name="seat" type="object" interface="wl_seat"/> |
| </request> |
| |
| <request name="reset"> |
| <description summary="reset"> |
| Should be called by an editor widget when the input state should |
| be reset, for example after the text was changed outside of the |
| normal input method flow. |
| </description> |
| <arg name="serial" type="uint"/> |
| </request> |
| |
| <request name="set_cursor_rectangle"> |
| <description summary="set_cursor_rectangle"> |
| Sets a rectangle for the cursor with x, y, width and height in surface |
| local coordinates. |
| |
| Not implemented. |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </request> |
| |
| <enum name="content_hint"> |
| <description summary="content hint"> |
| Content hint is a bitmask to allow to modify the behavior of the text |
| input. |
| </description> |
| <entry name="none" value="0x0" summary="no special behaviour"/> |
| <entry name="default" value="0x7" summary="auto completion, correction and capitalization"/> |
| <entry name="password" value="0xc0" summary="hidden and sensitive text"/> |
| <entry name="auto_completion" value="0x1" summary="suggest word completions"/> |
| <entry name="auto_correction" value="0x2" summary="suggest word corrections"/> |
| <entry name="auto_capitalization" value="0x4" summary="switch to uppercase letters at the start of a sentence"/> |
| <entry name="lowercase" value="0x8" summary="prefer lowercase letters"/> |
| <entry name="uppercase" value="0x10" summary="prefer uppercase letters"/> |
| <entry name="titlecase" value="0x20" summary="prefer casing for titles and headings (can be language dependend)"/> |
| <entry name="hidden_text" value="0x40" summary="characters should be hidden"/> |
| <entry name="sensitive_data" value="0x80" summary="typed text should not be stored"/> |
| <entry name="latin" value="0x100" summary="just latin characters should be entered"/> |
| <entry name="multiline" value="0x200" summary="the text input is multiline"/> |
| </enum> |
| |
| <enum name="content_purpose"> |
| <description summary="content purpose"> |
| The content purpose allows to specify the primary purpose of a text input. |
| |
| This allows an input method to show special purpose input panels with extra |
| characters or to disallow some characters. |
| </description> |
| <entry name="normal" value="0" summary="default input, allowing all characters"/> |
| <entry name="alpha" value="1" summary="allow only alphabetic characters"/> |
| <entry name="digits" value="2" summary="allow only digits"/> |
| <entry name="number" value="3" summary="input a number (including decimal separator and sign)"/> |
| <entry name="phone" value="4" summary="input a phone number"/> |
| <entry name="url" value="5" summary="input an URL"/> |
| <entry name="email" value="6" summary="input an email address"/> |
| <entry name="name" value="7" summary="input a name of a person"/> |
| <entry name="password" value="8" summary="input a password (combine with password or sensitive_data hint)"/> |
| <entry name="date" value="9" summary="input a date"/> |
| <entry name="time" value="10" summary="input a time"/> |
| <entry name="datetime" value="11" summary="input a date and time"/> |
| <entry name="terminal" value="12" summary="input for a terminal"/> |
| </enum> |
| |
| <request name="set_content_type"> |
| <description summary="set content purpose and hint"> |
| Sets the content purpose and content hint. While the purpose is the |
| basic purpose of an input field, the hint flags allow to modify some |
| of the behavior. |
| |
| When no content type is explicitly set, a normal content purpose with |
| default hints (auto completion, auto correction, auto capitalization) |
| should be assumed. |
| </description> |
| <arg name="hint" type="uint"/> |
| <arg name="purpose" type="uint"/> |
| </request> |
| |
| <enum name="enter_key_type"> |
| <description summary="enter key type"> |
| The enter key type can be used to alter the appearance of the enter key |
| on an input panel (virtual keyboard). |
| </description> |
| <entry name="default" value="0" summary="the default Enter key"/> |
| <entry name="return" value="1" summary="show a Return button that inserts a new line"/> |
| <entry name="done" value="2" summary="show a Done button"/> |
| <entry name="go" value="3" summary="show a Go button"/> |
| <entry name="send" value="4" summary="show a Send button"/> |
| <entry name="search" value="5" summary="show a Search button"/> |
| <entry name="next" value="6" summary="show a Next button"/> |
| <entry name="previous" value="7" summary="show a Previous button"/> |
| </enum> |
| |
| <request name="invoke_action"> |
| <description summary="invoke action"> |
| Invokes a button action on a given position. |
| |
| Not implemented. |
| </description> |
| <arg name="button" type="uint"/> |
| <arg name="index" type="uint"/> |
| </request> |
| |
| <request name="commit"> |
| <description summary="commit state"> |
| Requests to apply state changes sent so far. |
| </description> |
| </request> |
| |
| <event name="commit_string"> |
| <description summary="text to commit"> |
| Notifies when text should be inserted into the editor widget. The text |
| to commit could be either just a single character after a key press |
| or the result of some composing (pre-edit). It also sets the new |
| cursor position (as byte index) relative to the inserted text. |
| |
| Any previously set composing text should be removed. |
| </description> |
| <arg name="serial" type="uint"/> |
| <arg name="text" type="string"/> |
| </event> |
| |
| <event name="preedit_string"> |
| <description summary="pre-edit text"> |
| Notifies when a new composing text (pre-edit) should be set around the |
| current cursor position. Any previously set composing text should |
| be removed. |
| |
| The commit text can be used to replace the preedit text on reset |
| (for example on unfocus). |
| </description> |
| <arg name="serial" type="uint"/> |
| <arg name="text" type="string"/> |
| <arg name="commit" type="string"/> |
| </event> |
| |
| <event name="delete_surrounding_text"> |
| <description summary="delete surrounding text"> |
| Notifies when the text around the current cursor position should be |
| deleted. Index is relative to the current cursor (as byte index). |
| Length is the length of deleted text (as bytes). |
| </description> |
| <arg name="serial" type="uint"/> |
| <arg name="index" type="int"/> |
| <arg name="length" type="uint"/> |
| </event> |
| |
| <event name="cursor_position"> |
| <description summary="set cursor to new position"> |
| Notifies when the cursor or anchor position should be modified. It |
| should take effect after the next commit_string event. |
| |
| Not implemented. |
| </description> |
| <arg name="serial" type="uint"/> |
| <arg name="index" type="int"/> |
| <arg name="anchor" type="int"/> |
| </event> |
| |
| <enum name="preedit_style"> |
| <description summary="pre-edit style"> |
| The style for a composing text text. |
| </description> |
| <entry name="default" value="1"/> |
| <entry name="active" value="2"/> |
| <entry name="inactive" value="3"/> |
| <entry name="highlight" value="4"/> |
| <entry name="underline" value="5"/> |
| <entry name="selection" value="6"/> |
| <entry name="incorrect" value="7"/> |
| </enum> |
| |
| <event name="preedit_styling"> |
| <description summary="pre-edit styling"> |
| Sets styling information on composing text. The style is applied for |
| length (in bytes) characters from index relative to the beginning of |
| the composing text (as byte index). Multiple styles can be applied |
| to a composing text. |
| |
| This event should be handled as part of a following preedit_string |
| event. |
| </description> |
| <arg name="serial" type="uint"/> |
| <arg name="index" type="uint"/> |
| <arg name="length" type="uint"/> |
| <arg name="style" type="uint"/> |
| </event> |
| |
| <event name="preedit_cursor"> |
| <description summary="pre-edit cursor"> |
| Sets the cursor position inside the composing text (as byte index) |
| relative to the start of the composing text. |
| |
| This event should be handled as part of a following preedit_string |
| event. |
| </description> |
| <arg name="serial" type="uint"/> |
| <arg name="index" type="int"/> |
| </event> |
| |
| <event name="modifiers_map"> |
| <description summary="modifiers map"> |
| Transfers an array of 0-terminated modifiers names. The position in |
| the array is the index of the modifier as used in the modifiers |
| bitmask in the keysym event. |
| </description> |
| <arg name="map" type="array"/> |
| </event> |
| |
| <event name="keysym"> |
| <description summary="keysym"> |
| Notifies when a key event was sent. Key events should not be used |
| for normal text input operations, which should be done with |
| commit_string, delete_surrounding_text, etc. The key event follows |
| the wl_keyboard key event convention. State is a XKB keysym, state a |
| wl_keyboard key_state. Modifiers are a mask for effective modifiers |
| (where the modfier indices are set by the modifiers_map event) |
| </description> |
| <arg name="serial" type="uint"/> |
| <arg name="time" type="uint"/> |
| <arg name="sym" type="uint"/> |
| <arg name="state" type="uint"/> |
| <arg name="modifiers" type="uint"/> |
| </event> |
| |
| <event name="enter"> |
| <description summary="enter event"> |
| Notifies the model when it is activated on a given surface. Typically in |
| response to an activate request. |
| </description> |
| <arg name="surface" type="object" interface="wl_surface"/> |
| </event> |
| |
| <event name="leave"> |
| <description summary="leave event"> |
| Notifies the model when it is deactivated. Either in response to a |
| deactivate request or when the assigned surface lost focus or was |
| destroyed. |
| </description> |
| </event> |
| |
| <event name="input_panel_state"> |
| <description summary="state of the input panel"> |
| Notifies when the visibility state of the input panel changed. The state |
| is either 0 (hidden) or 1 (shown). |
| </description> |
| <arg name="state" type="uint"/> |
| </event> |
| |
| <request name="show_input_panel"> |
| <description summary="show input panels"> |
| Requests input panels (virtual keyboard) to show. |
| </description> |
| </request> |
| |
| <request name="hide_input_panel"> |
| <description summary="hide input panels"> |
| Requests input panels (virtual keyboard) to hide. |
| </description> |
| </request> |
| |
| <event name="input_panel_rect"> |
| <description summary="rect of the input panel"> |
| Notifies when the geometry of the input panel changes in surface local |
| coordinates. |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="uint"/> |
| <arg name="height" type="uint"/> |
| </event> |
| |
| <request name="set_max_text_length"> |
| <description summary="set max length of input field"> |
| Sets the maximum length of an input field. |
| </description> |
| <arg name="length" type="uint"/> |
| </request> |
| |
| <request name="set_platform_data"> |
| <description summary="set platform specific data"> |
| Sets the platform specific data (text). |
| </description> |
| <arg name="text" type="string"/> |
| </request> |
| |
| <request name="set_enter_key_type"> |
| <description summary="set type of enter key"> |
| Sets the type of the enter key on an input panel (virtual keyboard). |
| </description> |
| <arg name="enter_key_type" type="uint"/> |
| </request> |
| |
| <request name="set_input_panel_rect"> |
| <description summary="set rect of the input panel"> |
| Requests the geometry of the input panel to change. The geometry should |
| be in surface local coordinates. |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="uint"/> |
| <arg name="height" type="uint"/> |
| </request> |
| |
| <request name="reset_input_panel_rect"> |
| <description summary="reset rect of the input panel"> |
| Resets the geometry of the input panel requested. |
| </description> |
| </request> |
| |
| </interface> |
| |
| <interface name="text_model_factory" version="1"> |
| <description summary="text model factory"> |
| A factory for text models. This object is a singleton global. |
| </description> |
| |
| <request name="create_text_model"> |
| <description summary="create text model"> |
| Creates a new text model object. |
| </description> |
| <arg name="id" type="new_id" interface="text_model"/> |
| </request> |
| |
| </interface> |
| |
| </protocol> |