From 2f51d8a2ffe59d559db0faf89485bd968838d06c Mon Sep 17 00:00:00 2001 From: Jan Arne Petersen Date: Thu, 18 Apr 2013 16:47:38 +0200 Subject: [PATCH] text: Improve protocol documentation. Signed-off-by: Jan Arne Petersen --- protocol/input-method.xml | 98 +++++++++++++++++++++++++++++---------- protocol/text.xml | 52 +++++++++++++-------- 2 files changed, 106 insertions(+), 44 deletions(-) diff --git a/protocol/input-method.xml b/protocol/input-method.xml index 4ccb08e1..41369ef0 100644 --- a/protocol/input-method.xml +++ b/protocol/input-method.xml @@ -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 @@ - 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. - + - 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. - + 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. @@ -76,18 +88,37 @@ - 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. + + + + This request will be handled on text_input side as part of a directly + following commit_string request. + + + 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. + @@ -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. - + @@ -117,24 +148,41 @@ - - - - + + 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. + + + + + - - - - - + + 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. + + + + + + - + - + @@ -160,7 +208,7 @@ - + diff --git a/protocol/text.xml b/protocol/text.xml index 508c3153..1b5284dc 100644 --- a/protocol/text.xml +++ b/protocol/text.xml @@ -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 @@ - 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. @@ -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. @@ -227,12 +233,12 @@ 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. @@ -240,11 +246,11 @@ - 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. @@ -252,8 +258,9 @@ 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. @@ -262,8 +269,10 @@ - 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. @@ -271,8 +280,13 @@ 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. @@ -281,7 +295,7 @@ 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)