mirrors
/
weston
mirror of https://gitlab.freedesktop.org/wayland/weston.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

text: Improve protocol documentation. 

Signed-off-by: Jan Arne Petersen <jpetersen@openismus.com>
This commit is contained in:
Jan Arne Petersen 2013-04-18 16:47:38 +02:00 committed by Kristian Høgsberg
parent 70d942b4d7
commit 2f51d8a2ff
2 changed files with 106 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
protocol/input-method.xml
View File

@ -34,6 +34,8 @@
Input method contexts do not keep state after deactivation and should be
destroyed after deactivation is handled.
Text is generally UTF-8 encoded, indices and lengths are in bytes.
Serials are used to synchronize the state between the text input and
an input method. New serials are sent by the text input in the
commit_state request and are used by the input method to indicate
@ -44,29 +46,39 @@
<request name="destroy" type="destructor"/>
<request name="commit_string">
<description summary="commit string">
Send the commit string text to the applications text model and
set the cursor at index (as byte index) relative to the
beginning of inserted text.
Send the commit string text for insertion to the application.
The text to commit could be either just a single character after a key
press or the result of some composing (pre-edit). It could be also an
empty text when some text should be removed (see
delete_surrounding_text) or when the input cursor should be moved (see
cursor_position).
Any previously set composing text will be removed.
</description>
<arg name="serial" type="uint"/>
<arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="text" type="string"/>
</request>
<request name="preedit_string">
<description summary="pre-edit string">
Send the pre-edit string text to the applications text model. The commit
text can be used to replace the preedit text on reset (for example on
unfocus).
Send the pre-edit string text to the application text input.
The commit text can be used to replace the preedit text on reset (for
example on unfocus).
Also previously sent preedit_style and preedit_cursor requests are
processed bt the text_input also.
</description>
<arg name="serial" type="uint"/>
<arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="text" type="string"/>
<arg name="commit" type="string"/>
</request>
<request 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.
length in bytes from index relative to the beginning of
the composing text (as byte offset). Multiple styles can
be applied to a composing text.
This request should be sent before sending preedit_string request.
</description>
@ -76,18 +88,37 @@
</request>
<request name="preedit_cursor">
<description summary="pre-edit cursor">
Sets the cursor position inside the composing text (as byte index)
Sets the cursor position inside the composing text (as byte offset)
relative to the start of the composing text.
When index is negative no cursor should be displayed.
This request should be sent before sending preedit_string request.
</description>
<arg name="index" type="int"/>
</request>
<request name="delete_surrounding_text">
<description summary="delete text">
This request will be handled on text_input side as part of a directly
following commit_string request.
</description>
<arg name="index" type="int"/>
<arg name="length" type="uint"/>
</request>
<request name="cursor_position">
<description summary="set cursor to a new position">
Sets the cursor and anchor to a new position. Index is the new cursor
position in bytess (when >= 0 relative to the end of inserted text
else relative to beginning of inserted text). Anchor is the new anchor
position in bytes (when >= 0 relative to the end of inserted text, else
relative to beginning of inserted text). When there should be no
selected text anchor should be the same as index.
This request will be handled on text_input side as part of a directly
following commit_string request.
</description>
<arg name="index" type="int"/>
<arg name="anchor" type="int"/>
</request>
@ -101,7 +132,7 @@
delete_surrounfing_text, etc. The key event follows the wl_keyboard key
event convention. Sym is a XKB keysym, state a wl_keyboard key_state.
</description>
<arg name="serial" type="uint"/>
<arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="time" type="uint"/>
<arg name="sym" type="uint"/>
<arg name="state" type="uint"/>
@ -117,24 +148,41 @@
<arg name="keyboard" type="new_id" interface="wl_keyboard"/>
</request>
<request name="key">
<arg name="serial" type="uint"/>
<arg name="time" type="uint"/>
<arg name="key" type="uint"/>
<arg name="state" type="uint"/>
<description summary="forward key event">
Should be used when filtering key events with grab_keyboard.
When the wl_keyboard::key event is not processed by the input
method itself and should be sent to the client instead, forward it
with this request. The arguments should be the ones from the
wl_keyboard::key event.
For generating custom key events use the keysym request instead.
</description>
<arg name="serial" type="uint" summary="serial from wl_keyboard::key"/>
<arg name="time" type="uint" summary="time from wl_keyboard::key"/>
<arg name="key" type="uint" summary="key from wl_keyboard::key"/>
<arg name="state" type="uint" summary="state from wl_keyboard::key"/>
</request>
<request name="modifiers">
<arg name="serial" type="uint"/>
<arg name="mods_depressed" type="uint"/>
<arg name="mods_latched" type="uint"/>
<arg name="mods_locked" type="uint"/>
<arg name="group" type="uint"/>
<description summary="forward modifiers event">
Should be used when filtering key events with grab_keyboard.
When the wl_keyboard::modifiers event should be also send to the
client, forward it with this request. The arguments should be the ones
from the wl_keyboard::modifiers event.
</description>
<arg name="serial" type="uint" summary="serial from wl_keyboard::modifiers"/>
<arg name="mods_depressed" type="uint" summary="mods_depressed from wl_keyboard::modifiers"/>
<arg name="mods_latched" type="uint" summary="mods_latched from wl_keyboard::modifiers"/>
<arg name="mods_locked" type="uint" summary="mods_locked from wl_keyboard::modifiers"/>
<arg name="group" type="uint" summary="group from wl_keyboard::modifiers"/>
</request>
<request name="language">
<arg name="serial" type="uint"/>
<arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="language" type="string"/>
</request>
<request name="text_direction">
<arg name="serial" type="uint"/>
<arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="direction" type="uint"/>
</request>
<event name="surrounding_text">
@ -160,7 +208,7 @@
<arg name="index" type="uint"/>
</event>
<event name="commit_state">
<arg name="serial" type="uint"/>
<arg name="serial" type="uint" summary="serial of text input state"/>
</event>
<event name="preferred_language">
<arg name="language" type="string"/>

52
protocol/text.xml
View File

@ -39,6 +39,8 @@
for applications to directly process hardware key events and compose text
out of them.
Text is generally UTF-8 encoded, indices and lengths are in bytes.
Serials are used to synchronize the state between the text input and
an input method. New serials are sent by the text input in the
commit_state request and are used by the input method to indicate
@ -85,10 +87,11 @@
</request>
<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
Sets the plain surrounding text around the input position. Text is
UTF-8 encoded. Cursor is the byte offset within the
surrounding text. Anchor is the byte offset of the
selection anchor within the surrounding text. If there is no selected
text anchor then it is the same as cursor.
text anchor is the same as cursor.
</description>
<arg name="text" type="string"/>
<arg name="cursor" type="uint"/>
@ -208,7 +211,10 @@
be removed.
The commit text can be used to replace the preedit text on reset
(for example on unfocus).
(for example on unfocus).
The text input should also handle all preedit_style and preedit_cursor
events occuring directly before preedit_string.
</description>
<arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="text" type="string"/>
@ -227,12 +233,12 @@
<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.
length bytes from index relative to the beginning of the composing
text (as byte offset). Multiple styles can
be applied to a composing text by sending multiple preedit_styling
events.
This event should be handled as part of a following preedit_string
event.
This event is handled as part of a following preedit_string event.
</description>
<arg name="index" type="uint"/>
<arg name="length" type="uint"/>
@ -240,11 +246,11 @@
</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.
Sets the cursor position inside the composing text (as byte
offset) relative to the start of the composing text. When index is a
negative number no cursor is shown.
This event should be handled as part of a following preedit_string
event.
This event is handled as part of a following preedit_string event.
</description>
<arg name="index" type="int"/>
</event>
@ -252,8 +258,9 @@
<description summary="commit">
Notify 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 beginning of inserted text.
result of some composing (pre-edit). It could be also an empty text
when some text should be removed (see delete_surrounding_text) or when
the input cursor should be moved (see cursor_position).
Any previously set composing text should be removed.
</description>
@ -262,8 +269,10 @@
</event>
<event name="cursor_position">
<description summary="set cursor to new position">
Notify when the cursor or anchor position should be modified. It
should take effect after the next commit_string event.
Notify when the cursor or anchor position should be modified.
This event should be handled as part of a following commit_string
event.
</description>
<arg name="index" type="int"/>
<arg name="anchor" type="int"/>
@ -271,8 +280,13 @@
<event name="delete_surrounding_text">
<description summary="delete surrounding text">
Notify when the text around the current cursor position should be
deleted. Index is relative to the current cursor (as byte index).
deleted.
Index is relative to the current cursor (in bytes).
Length is the length of deleted text (in bytes).
This event should be handled as part of a following commit_string
event.
</description>
<arg name="index" type="int"/>
<arg name="length" type="uint"/>
@ -281,7 +295,7 @@
<description summary="keysym">
Notify 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_surrounfing_text, etc. The key event follows
commit_string, delete_surrounding_text, etc. The key event follows
the wl_keyboard key event convention. Sym is a XKB keysym, state a
wl_keyboard key_state. Modifiers are a mask for effective modifiers
(where the modifier indices are set by the modifiers_map event)