Discussion:
[PATCH wayland-protocols] text: Create second version of text input protocol
(too old to reply)
Jan Arne Petersen
2016-01-28 07:52:40 UTC
Permalink
There were some shortcomings in the first version of the protocol which
makes it not really useful in real world applications. It is not really
possible to fix them in a compatible way so introduce a new v2 of the
protocol.

Fixes some shortcomings of the first version:

* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
* Improve update state handling
* Allow state requests
---
unstable/text-input/text-input-unstable-v2.xml | 369 +++++++++++++++++++++++++
1 file changed, 369 insertions(+)
create mode 100644 unstable/text-input/text-input-unstable-v2.xml

diff --git a/unstable/text-input/text-input-unstable-v2.xml b/unstable/text-input/text-input-unstable-v2.xml
new file mode 100644
index 0000000..f757e92
--- /dev/null
+++ b/unstable/text-input/text-input-unstable-v2.xml
@@ -0,0 +1,369 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<protocol name="text_input_unstable_v2">
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+ Copyright © 2015, 2016 Jan Arne Petersen
+
+ 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="zwp_text_input_v2" version="1">
+ <description summary="text input">
+ The zwp_text_input_v2 interface repesents text input and input methods
+ associated with a seat. It provides enter/leave event to follow the
+ text input focus for a seat.
+
+ Requests are used to activate/deactivate the text-input object and set
+ state information like surrounding and selected text or the content type.
+ The information about entered text is sent to the text-input object 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.
+
+ 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
+ the known text input state in evsents like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+ </description>
+ <request name="activate">
+ <description summary="request activation">
+ Requests to activate a surface for text input (typically when a
+ text entry in it gets focus).
+
+ There can only be one active surface per client and seat. When surface is
+ null all surfaces of the client get deactivated.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
+ </request>
+ <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>
+ <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>
+ </request>
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="uint"/>
+ </request>
+ <enum name="content_hint" bitfield="true">
+ <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 dependent)"/>
+ <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" enum="content_hint"/>
+ <arg name="purpose" type="uint" enum="content_purpose"/>
+ </request>
+ <request name="set_cursor_rectangle">
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which tracks
+ languages of contacts.
+ </description>
+ <arg name="language" type="string"/>
+ </request>
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="request" value="1" summary="sent state after request"/>
+ <entry name="reset" value="2" summary="updated state after reset"/>
+ <entry name="enter" value="3" summary="updated state after switching focus to a different widget on client side"/>
+ </enum>
+ <request name="update_state">
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
+ <request name="invoke_action">
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+ <event name="leave">
+ <description summary="leave event">
+ Notify the text-input object when it lost focus. Either in response
+ to a deactivate request or when the assigned surface lost focus or was
+ destroyed.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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="input_panel_state">
+ <description summary="state of the input panel">
+ Notify when the visibility state of the input panel changed.
+ </description>
+ <arg name="state" type="uint"/>
+ </event>
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="style should be the same as in non-composing text"/>
+ <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 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint" enum="preedit_style"/>
+ </event>
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+ <event name="commit_string">
+ <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 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>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ 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"/>
+ </event>
+ <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 (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"/>
+ </event>
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
+ <event name="language">
+ <description summary="language">
+ Sets the language of the input text. The "language" argument is a RFC-3066
+ format language tag.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </event>
+ <enum name="text_direction">
+ <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
+ <entry name="ltr" value="1" summary="left-to-right"/>
+ <entry name="rtl" value="2" summary="right-to-left"/>
+ </enum>
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing input cursor on correct side of the
+ editor when there is no input yet done and making sure neutral
+ direction text is laid out properly.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint" enum="text_direction"/>
+ </event>
+ <event name="request_surrounding_text">
+ <description summary="request surrounding text from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+ <event name="request_state">
+ <description summary="request state from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_text_input_v2_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
+ <request name="get_text_input">
+ <description summary="create a new text input object">
+ Creates a new text-input object for a given seat.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_text_input_v2"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+ </interface>
+</protocol>
--
2.5.0
Giulio Camuffo
2016-01-28 09:46:04 UTC
Permalink
Post by Jan Arne Petersen
There were some shortcomings in the first version of the protocol which
makes it not really useful in real world applications. It is not really
possible to fix them in a compatible way so introduce a new v2 of the
protocol.
* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
* Improve update state handling
* Allow state requests
---
unstable/text-input/text-input-unstable-v2.xml | 369 +++++++++++++++++++++++++
1 file changed, 369 insertions(+)
create mode 100644 unstable/text-input/text-input-unstable-v2.xml
diff --git a/unstable/text-input/text-input-unstable-v2.xml b/unstable/text-input/text-input-unstable-v2.xml
new file mode 100644
index 0000000..f757e92
--- /dev/null
+++ b/unstable/text-input/text-input-unstable-v2.xml
@@ -0,0 +1,369 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<protocol name="text_input_unstable_v2">
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+ Copyright © 2015, 2016 Jan Arne Petersen
+
+ 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="zwp_text_input_v2" version="1">
+ <description summary="text input">
+ The zwp_text_input_v2 interface repesents text input and input methods
+ associated with a seat. It provides enter/leave event to follow the
+ text input focus for a seat.
+
+ Requests are used to activate/deactivate the text-input object and set
+ state information like surrounding and selected text or the content type.
+ The information about entered text is sent to the text-input object 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.
+
+ 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
+ the known text input state in evsents like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+ </description>
+ <request name="activate">
+ <description summary="request activation">
+ Requests to activate a surface for text input (typically when a
+ text entry in it gets focus).
+
+ There can only be one active surface per client and seat. When surface is
+ null all surfaces of the client get deactivated.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
+ </request>
+ <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>
+ <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>
+ </request>
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
+ </description>
+ <arg name="text" type="string"/>
The string type has a maximum allowed size, i wonder if that is a
problem. See https://bugreports.qt.io/browse/QTBUG-43789
If it's ok i think the documentation should be explicit about it,
otherwise maybe we could pass a fd instead of a string, that the
compositor would read from to get the surrounding text.


--
Giulio
Post by Jan Arne Petersen
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="uint"/>
+ </request>
+ <enum name="content_hint" bitfield="true">
+ <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 dependent)"/>
+ <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" enum="content_hint"/>
+ <arg name="purpose" type="uint" enum="content_purpose"/>
+ </request>
+ <request name="set_cursor_rectangle">
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which tracks
+ languages of contacts.
+ </description>
+ <arg name="language" type="string"/>
+ </request>
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="request" value="1" summary="sent state after request"/>
+ <entry name="reset" value="2" summary="updated state after reset"/>
+ <entry name="enter" value="3" summary="updated state after switching focus to a different widget on client side"/>
+ </enum>
+ <request name="update_state">
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
+ <request name="invoke_action">
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+ <event name="leave">
+ <description summary="leave event">
+ Notify the text-input object when it lost focus. Either in response
+ to a deactivate request or when the assigned surface lost focus or was
+ destroyed.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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="input_panel_state">
+ <description summary="state of the input panel">
+ Notify when the visibility state of the input panel changed.
+ </description>
+ <arg name="state" type="uint"/>
+ </event>
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="style should be the same as in non-composing text"/>
+ <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 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint" enum="preedit_style"/>
+ </event>
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+ <event name="commit_string">
+ <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 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>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ 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"/>
+ </event>
+ <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 (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"/>
+ </event>
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
+ <event name="language">
+ <description summary="language">
+ Sets the language of the input text. The "language" argument is a RFC-3066
+ format language tag.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </event>
+ <enum name="text_direction">
+ <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
+ <entry name="ltr" value="1" summary="left-to-right"/>
+ <entry name="rtl" value="2" summary="right-to-left"/>
+ </enum>
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing input cursor on correct side of the
+ editor when there is no input yet done and making sure neutral
+ direction text is laid out properly.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint" enum="text_direction"/>
+ </event>
+ <event name="request_surrounding_text">
+ <description summary="request surrounding text from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+ <event name="request_state">
+ <description summary="request state from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_text_input_v2_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
+ <request name="get_text_input">
+ <description summary="create a new text input object">
+ Creates a new text-input object for a given seat.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_text_input_v2"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+ </interface>
+</protocol>
--
2.5.0
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Jan Arne Petersen
2016-01-28 10:26:04 UTC
Permalink
Hi,
Post by Giulio Camuffo
Post by Jan Arne Petersen
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
+ </description>
+ <arg name="text" type="string"/>
The string type has a maximum allowed size, i wonder if that is a
problem. See https://bugreports.qt.io/browse/QTBUG-43789
If it's ok i think the documentation should be explicit about it,
otherwise maybe we could pass a fd instead of a string, that the
compositor would read from to get the surrounding text.
Yes, we should document, that one should not send too big texts with
this request. In my opinion 4076 Byte (around the cursor) should be
usually enough (also for performance reasons we do not want to send so
much text around). The limit needs to be enforced by the toolkit to
prevent bugs like the above though.

If there is rally a need for bigger surrounding texts, we can still add
another request with a fd to a later protocol version.

Regards
Jan Arne
--
Jan Arne Petersen | ***@kdab.com | Senior Software Engineer
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel: +49-30-521325470
KDAB - The Qt Experts
Jonas Ådahl
2016-01-28 10:05:45 UTC
Permalink
Post by Jan Arne Petersen
There were some shortcomings in the first version of the protocol which
makes it not really useful in real world applications. It is not really
possible to fix them in a compatible way so introduce a new v2 of the
protocol.
* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
* Improve update state handling
* Allow state requests
I haven't looked much at the actual protocol yet, but I have some
comments anyway to begin with.
Post by Jan Arne Petersen
---
unstable/text-input/text-input-unstable-v2.xml | 369 +++++++++++++++++++++++++
1 file changed, 369 insertions(+)
create mode 100644 unstable/text-input/text-input-unstable-v2.xml
diff --git a/unstable/text-input/text-input-unstable-v2.xml b/unstable/text-input/text-input-unstable-v2.xml
new file mode 100644
index 0000000..f757e92
--- /dev/null
+++ b/unstable/text-input/text-input-unstable-v2.xml
@@ -0,0 +1,369 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<protocol name="text_input_unstable_v2">
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+ Copyright © 2015, 2016 Jan Arne Petersen
+
+ 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="zwp_text_input_v2" version="1">
+ <description summary="text input">
+ The zwp_text_input_v2 interface repesents text input and input methods
+ associated with a seat. It provides enter/leave event to follow the
+ text input focus for a seat.
+
+ Requests are used to activate/deactivate the text-input object and set
+ state information like surrounding and selected text or the content type.
+ The information about entered text is sent to the text-input object 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.
+
+ 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
+ the known text input state in evsents like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+ </description>
Please add an empty line between the events, requests and enums in the
interfaces. It makes it much easer to read.

Seems to miss a <request name="destroy" type="destructor"/>
Post by Jan Arne Petersen
+ <request name="activate">
+ <description summary="request activation">
+ Requests to activate a surface for text input (typically when a
+ text entry in it gets focus).
+
+ There can only be one active surface per client and seat. When surface is
+ null all surfaces of the client get deactivated.
Why not make this a separate request and drop the allow-null? It makes
it clearer that "activate" sometimes deactivates.
Post by Jan Arne Petersen
+ </description>
+ <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
+ </request>
+ <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>
+ <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>
+ </request>
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="uint"/>
+ </request>
+ <enum name="content_hint" bitfield="true">
+ <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 dependent)"/>
+ <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" enum="content_hint"/>
+ <arg name="purpose" type="uint" enum="content_purpose"/>
+ </request>
+ <request name="set_cursor_rectangle">
Missing <description/>.
Post by Jan Arne Petersen
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which tracks
+ languages of contacts.
+ </description>
+ <arg name="language" type="string"/>
+ </request>
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="request" value="1" summary="sent state after request"/>
+ <entry name="reset" value="2" summary="updated state after reset"/>
+ <entry name="enter" value="3" summary="updated state after switching focus to a different widget on client side"/>
+ </enum>
+ <request name="update_state">
Missing <description/>
Post by Jan Arne Petersen
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
+ <request name="invoke_action">
Missing <description/>
Post by Jan Arne Petersen
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+ <event name="leave">
+ <description summary="leave event">
+ Notify the text-input object when it lost focus. Either in response
+ to a deactivate request or when the assigned surface lost focus or was
There is no "deactivate" request.
Post by Jan Arne Petersen
+ destroyed.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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="input_panel_state">
+ <description summary="state of the input panel">
+ Notify when the visibility state of the input panel changed.
+ </description>
+ <arg name="state" type="uint"/>
+ </event>
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="style should be the same as in non-composing text"/>
+ <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 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint" enum="preedit_style"/>
+ </event>
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+ <event name="commit_string">
+ <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 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>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ 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"/>
+ </event>
+ <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 (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"/>
+ </event>
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
+ <event name="language">
+ <description summary="language">
+ Sets the language of the input text. The "language" argument is a RFC-3066
+ format language tag.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </event>
+ <enum name="text_direction">
+ <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
+ <entry name="ltr" value="1" summary="left-to-right"/>
+ <entry name="rtl" value="2" summary="right-to-left"/>
+ </enum>
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing input cursor on correct side of the
+ editor when there is no input yet done and making sure neutral
+ direction text is laid out properly.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint" enum="text_direction"/>
+ </event>
+ <event name="request_surrounding_text">
+ <description summary="request surrounding text from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+ <event name="request_state">
+ <description summary="request state from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_text_input_v2_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
Missing a destroy request here too.


Jonas
Post by Jan Arne Petersen
+ <request name="get_text_input">
+ <description summary="create a new text input object">
+ Creates a new text-input object for a given seat.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_text_input_v2"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+ </interface>
+</protocol>
--
2.5.0
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Jan Arne Petersen
2016-02-02 11:40:11 UTC
Permalink
Post by Jonas Ådahl
Post by Jan Arne Petersen
There were some shortcomings in the first version of the protocol which
makes it not really useful in real world applications. It is not really
possible to fix them in a compatible way so introduce a new v2 of the
protocol.
* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
* Improve update state handling
* Allow state requests
I haven't looked much at the actual protocol yet, but I have some
comments anyway to begin with.
Post by Jan Arne Petersen
---
unstable/text-input/text-input-unstable-v2.xml | 369 +++++++++++++++++++++++++
1 file changed, 369 insertions(+)
create mode 100644 unstable/text-input/text-input-unstable-v2.xml
diff --git a/unstable/text-input/text-input-unstable-v2.xml b/unstable/text-input/text-input-unstable-v2.xml
new file mode 100644
index 0000000..f757e92
--- /dev/null
+++ b/unstable/text-input/text-input-unstable-v2.xml
@@ -0,0 +1,369 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<protocol name="text_input_unstable_v2">
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+ Copyright © 2015, 2016 Jan Arne Petersen
+
+ 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="zwp_text_input_v2" version="1">
+ <description summary="text input">
+ The zwp_text_input_v2 interface repesents text input and input methods
+ associated with a seat. It provides enter/leave event to follow the
+ text input focus for a seat.
+
+ Requests are used to activate/deactivate the text-input object and set
+ state information like surrounding and selected text or the content type.
+ The information about entered text is sent to the text-input object 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.
+
+ 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
+ the known text input state in evsents like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+ </description>
Please add an empty line between the events, requests and enums in the
interfaces. It makes it much easer to read.
Seems to miss a <request name="destroy" type="destructor"/>
Both done
Post by Jonas Ådahl
Post by Jan Arne Petersen
+ <request name="activate">
+ <description summary="request activation">
+ Requests to activate a surface for text input (typically when a
+ text entry in it gets focus).
+
+ There can only be one active surface per client and seat. When surface is
+ null all surfaces of the client get deactivated.
Why not make this a separate request and drop the allow-null? It makes
it clearer that "activate" sometimes deactivates.
There are enable and disable now.
Post by Jonas Ådahl
Post by Jan Arne Petersen
+ </description>
+ <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
+ </request>
+ <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>
+ <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>
+ </request>
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="uint"/>
+ </request>
+ <enum name="content_hint" bitfield="true">
+ <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 dependent)"/>
+ <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" enum="content_hint"/>
+ <arg name="purpose" type="uint" enum="content_purpose"/>
+ </request>
+ <request name="set_cursor_rectangle">
Missing <description/>.
Post by Jan Arne Petersen
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which tracks
+ languages of contacts.
+ </description>
+ <arg name="language" type="string"/>
+ </request>
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="request" value="1" summary="sent state after request"/>
+ <entry name="reset" value="2" summary="updated state after reset"/>
+ <entry name="enter" value="3" summary="updated state after switching focus to a different widget on client side"/>
+ </enum>
+ <request name="update_state">
Missing <description/>
Post by Jan Arne Petersen
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
+ <request name="invoke_action">
Missing <description/>
Post by Jan Arne Petersen
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+ <event name="leave">
+ <description summary="leave event">
+ Notify the text-input object when it lost focus. Either in response
+ to a deactivate request or when the assigned surface lost focus or was
There is no "deactivate" request.
Post by Jan Arne Petersen
+ destroyed.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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="input_panel_state">
+ <description summary="state of the input panel">
+ Notify when the visibility state of the input panel changed.
+ </description>
+ <arg name="state" type="uint"/>
+ </event>
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="style should be the same as in non-composing text"/>
+ <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 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint" enum="preedit_style"/>
+ </event>
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+ <event name="commit_string">
+ <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 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>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ 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"/>
+ </event>
+ <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 (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"/>
+ </event>
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
+ <event name="language">
+ <description summary="language">
+ Sets the language of the input text. The "language" argument is a RFC-3066
+ format language tag.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </event>
+ <enum name="text_direction">
+ <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
+ <entry name="ltr" value="1" summary="left-to-right"/>
+ <entry name="rtl" value="2" summary="right-to-left"/>
+ </enum>
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing input cursor on correct side of the
+ editor when there is no input yet done and making sure neutral
+ direction text is laid out properly.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint" enum="text_direction"/>
+ </event>
+ <event name="request_surrounding_text">
+ <description summary="request surrounding text from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+ <event name="request_state">
+ <description summary="request state from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_text_input_v2_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
Missing a destroy request here too.
Added all missing desriptions and destroy requests.
Post by Jonas Ådahl
Post by Jan Arne Petersen
+ <request name="get_text_input">
+ <description summary="create a new text input object">
+ Creates a new text-input object for a given seat.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_text_input_v2"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+ </interface>
+</protocol>
--
2.5.0
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
--
Jan Arne Petersen | ***@kdab.com | Senior Software Engineer
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel: +49-30-521325470
KDAB - The Qt Experts
Daiki Ueno
2016-01-28 12:05:45 UTC
Permalink
Hello,
Post by Jan Arne Petersen
* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
These sound nice.
Post by Jan Arne Petersen
* Improve update state handling
* Allow state requests
I have a few comments regarding them, inlined below.
Post by Jan Arne Petersen
+ 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
There is no commit_state request anymore.
Post by Jan Arne Petersen
+ <event name="request_surrounding_text">
+ <description summary="request surrounding text from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+ <event name="request_state">
+ <description summary="request state from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ </event>
These events have the same description. Would you mind explaining how
they are supposed to be used, maybe in combination with the
set_surrounding_text request?

Thanks,
--
Daiki Ueno
Jan Arne Petersen
2016-02-02 11:41:54 UTC
Permalink
Hi,
Post by Daiki Ueno
Hello,
Post by Jan Arne Petersen
* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
These sound nice.
Post by Jan Arne Petersen
* Improve update state handling
* Allow state requests
I have a few comments regarding them, inlined below.
Post by Jan Arne Petersen
+ 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
There is no commit_state request anymore.
Ok fixed to update_state.
Post by Daiki Ueno
Post by Jan Arne Petersen
+ <event name="request_surrounding_text">
+ <description summary="request surrounding text from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+ <event name="request_state">
+ <description summary="request state from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ </event>
These events have the same description. Would you mind explaining how
they are supposed to be used, maybe in combination with the
set_surrounding_text request?
They are called configure_surrounding_text and demand_full_state and are
better documented in PATCH v3.

Thanks
Jan Arne
--
Jan Arne Petersen | ***@kdab.com | Senior Software Engineer
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel: +49-30-521325470
KDAB - The Qt Experts
Rui Tiago Cação Matos
2016-01-28 20:16:29 UTC
Permalink
Hi,

thanks for sending this. I was actually going to start a discussion
about the existing protocol but let's go from here instead. Comments
inline:

First a question of scope: a client would only ever need to instance
one text_input object per wl_seat and then "associate" it with a
particular wl_surface through the activate request. Am I right?

Not having a destroy request isn't so bad if that's the intended scope
but I think we should still have one.
Post by Jan Arne Petersen
+ Text is generally UTF-8 encoded, indices and lengths are in bytes.
Why bytes instead of characters? It seems to me that using characters
is less error prone since an offset in bytes might end up in the
middle of an UTF-8 encoded character.
Post by Jan Arne Petersen
+ 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
+ the known text input state in evsents like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
Any particular reason for serials to be generated and controlled by
clients? For the intended use case it seems ok but it's odd when
compared with other serials in wayland.
Post by Jan Arne Petersen
+ <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>
Do we really need these requests? Isn't the fact that a text input is
currently active enough for the compositor/IM to decide on its own if
it should show an input panel?
Post by Jan Arne Petersen
+ <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>
+ </request>
Shouldn't this have a serial argument if we go with client controlled serials?

Otherwise reset could remain like this but adding specification to
what happens with serials sent in events from this point onwards.
Post by Jan Arne Petersen
+ <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.
No strong opinion, particularly since these are just hints and thus
compositors/IMs are free to ignore them (right?), but I think the
default should be "none".
Post by Jan Arne Petersen
+ <request name="set_cursor_rectangle">
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
This needs specification. Why is it a rectangle and what does it
represent exactly? Are the coordinates relative to the activated
wl_surface? What are compositors expected to do with it?
Post by Jan Arne Petersen
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="request" value="1" summary="sent state after request"/>
+ <entry name="reset" value="2" summary="updated state after reset"/>
+ <entry name="enter" value="3" summary="updated state after switching focus to a different widget on client side"/>
+ </enum>
+ <request name="update_state">
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
This seems very underspecified. Care to elaborate how it's supposed to be used?
Post by Jan Arne Petersen
+ <request name="invoke_action">
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
Underspecified.
Post by Jan Arne Petersen
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
Wayland clients aren't aware of how many hardware keyboards exist. In
fact there might be none and a compositor is still free to advertise
the keyboard capability and assign keyboard focus (e.g. a touch screen
only device). I don't think we should mention wl_keyboard at all. Just
say that each wl_seat has a text-input focus and this is the enter
event for said focus.
Post by Jan Arne Petersen
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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>
What's the purpose of this event?
Post by Jan Arne Petersen
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notify when the visibility state of the input panel changed.
+ </description>
+ <arg name="state" type="uint"/>
+ </event>
Unsure if we need this event at all. But if we do, it must at least
specify that this event will only be sent if this client currently
holds the text-input focus and the type should be be an enum.
Post by Jan Arne Petersen
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify when a new composing text (pre-edit) should be set around the
+ current cursor position. Any previously set composing text should
+ be removed.
Should that read: "Any previously set _preedit_ text should be removed" ?
Post by Jan Arne Petersen
+ The commit text can be used to replace the preedit text on reset
Can? I think this should be a "should" like below.
Post by Jan Arne Petersen
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+ <event name="commit_string">
+ <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 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.
Again, you mean s/composing/pre-edit/ right?
Post by Jan Arne Petersen
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ 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"/>
+ </event>
"anchor" needs to be specified. Does it mean that the text between
index and anchor should be selected?
Post by Jan Arne Petersen
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
Just like the modifiers_map event above, I don't think having this in
the protocol is a good idea. If the compositor/IM wants to send key
events to a client it can just use the wl_keyboard interface. Am I
missing something?
Post by Jan Arne Petersen
+ <event name="request_surrounding_text">
+ <description summary="request surrounding text from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+ <event name="request_state">
+ <description summary="request state from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ </event>
Both these events need clarification. What's flags? How should clients respond?

I think that's all for now. Thanks,
Rui
Jan Arne Petersen
2016-02-02 12:26:13 UTC
Permalink
Hi Rui,
Post by Rui Tiago Cação Matos
Hi,
thanks for sending this. I was actually going to start a discussion
about the existing protocol but let's go from here instead. Comments
First a question of scope: a client would only ever need to instance
one text_input object per wl_seat and then "associate" it with a
particular wl_surface through the activate request. Am I right?
Yes. There is one text_input object per wl_seat, which can be used to
track the text focus via enter/leave and to enable text input per
wl_suface via enable/disable (renamed in v3).

So there is only text input happening when the surface which has text
focus is also enabled.
Post by Rui Tiago Cação Matos
Not having a destroy request isn't so bad if that's the intended scope
but I think we should still have one.
Added them.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ Text is generally UTF-8 encoded, indices and lengths are in bytes.
Why bytes instead of characters? It seems to me that using characters
is less error prone since an offset in bytes might end up in the
middle of an UTF-8 encoded character.
Yes text needs also to be valid UTF-8. Bytes seemed easier to use for
different toolkits with UTF-16 strings. But yes one could also use
characters if there is a big demand for it.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ 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
+ the known text input state in evsents like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
Any particular reason for serials to be generated and controlled by
clients? For the intended use case it seems ok but it's odd when
compared with other serials in wayland.
Yes usually serials are used in Wayland on compositor side to make sure
that requests from clients are valid (setting a cursor in response to an
enter event for example).

Here we need to make sure that events from the compositor still make
sense for the client. In this case serials need to be generated on
client side.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <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>
Do we really need these requests? Isn't the fact that a text input is
currently active enough for the compositor/IM to decide on its own if
it should show an input panel?
Added some more description. Basically when the virtual keyboard is
hidden by pressing some hide button (or sliding it away or whatever)
there needs to be a way for the client to request it again.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <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>
+ </request>
Shouldn't this have a serial argument if we go with client controlled serials?
Otherwise reset could remain like this but adding specification to
what happens with serials sent in events from this point onwards.
Removed reset. It is part of update_state now.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <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.
No strong opinion, particularly since these are just hints and thus
compositors/IMs are free to ignore them (right?), but I think the
default should be "none".
Yes, they might be not relevant for all input methods. Removed the
defaults, which should be handled by toolkits (what to set when nothing
special is specified on an input widget).
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="set_cursor_rectangle">
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
This needs specification. Why is it a rectangle and what does it
represent exactly? Are the coordinates relative to the activated
wl_surface? What are compositors expected to do with it?
"Sets the cursor outline as a rectangle relative to the surface.

Allows the compositor to put a window with word suggestions near the
cursor." from patch v3
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="request" value="1" summary="sent state after request"/>
+ <entry name="reset" value="2" summary="updated state after reset"/>
+ <entry name="enter" value="3" summary="updated state after switching focus to a different widget on client side"/>
+ </enum>
+ <request name="update_state">
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
This seems very underspecified. Care to elaborate how it's supposed to be used?
See better description in v3:
"Allows to atomically send state updates from client.

This request should follow after a batch of state updating requests
like set_surrounding_text, set_content_type, set_cursor_rectangle and
set_preferred_language.

The flags field indicates why an updated state is sent to the input
method.

Reset should be used by an editor widget after the text was changed
outside of the normal input method flow.

For "change" it is enough to send the changed state, else the full
state should be send."
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="invoke_action">
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
Underspecified.
"Allows to invoke an action when tapping or clicking the currently
composed word in the text input.

This can be used by input methods to offer more word suggestions." from
patch v3
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
Wayland clients aren't aware of how many hardware keyboards exist. In
fact there might be none and a compositor is still free to advertise
the keyboard capability and assign keyboard focus (e.g. a touch screen
only device). I don't think we should mention wl_keyboard at all. Just
say that each wl_seat has a text-input focus and this is the enter
event for said focus.
Yes text focus also works without hardware keyboard and without
wl_keyboards being there. But if there is a hardware keyboard text focus
must be the same as keyboard focus (or horrible things will happen)
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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>
What's the purpose of this event?
It allows in keysym to reference modifiers via a bitfield instead of
having to send an array of strings.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notify when the visibility state of the input panel changed.
+ </description>
+ <arg name="state" type="uint"/>
+ </event>
Unsure if we need this event at all. But if we do, it must at least
specify that this event will only be sent if this client currently
holds the text-input focus and the type should be be an enum.
That is valid for nearly all events (only send to the client with
text-input focus). Added rectangle arguments to allow to move text input
fields away from underneath a virtual keyboard.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify when a new composing text (pre-edit) should be set around the
+ current cursor position. Any previously set composing text should
+ be removed.
Should that read: "Any previously set _preedit_ text should be removed" ?
Composing text == pre-edit.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ The commit text can be used to replace the preedit text on reset
Can? I think this should be a "should" like below.
It depends a bit what happened exactly to a text field on client side.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+ <event name="commit_string">
+ <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 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.
Again, you mean s/composing/pre-edit/ right?
Post by Jan Arne Petersen
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ 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"/>
+ </event>
"anchor" needs to be specified. Does it mean that the text between
index and anchor should be selected?
Yes. Added better description to v3
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
Just like the modifiers_map event above, I don't think having this in
the protocol is a good idea. If the compositor/IM wants to send key
events to a client it can just use the wl_keyboard interface. Am I
missing something?
There might be no hardware keyboard present (so no wl_keyboard
interface). This is mostly useful for synthetic key events generated by
a virtual keyboard (enter, backspace, cursor, whatever), which cannot be
send via wl_keyboard.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="request_surrounding_text">
+ <description summary="request surrounding text from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+ <event name="request_state">
+ <description summary="request state from client">
+ Request to get the surrounding text and cursor position sent from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint"/>
+ </event>
Both these events need clarification. What's flags? How should clients respond?
See better names/description in PATCH v3:

" <event name="configure_surrounding_text">
<description summary="configure amount of surrounding text to be
send from client">
Configure what amount of surrounding text is sent by the
set_surrounding_text request on the following state information
updates.
</description>
<arg name="before_cursor" type="int"/>
<arg name="after_cursor" type="int"/>
</event>

<event name="demand_full_state">
<description summary="demand the full state from client">
Ask to get full current state information sent from the client via
state requests (set_surrounding_text, set_content_hint, ...) and
update_state.
</description>
<arg name="serial" type="uint" summary="serial of the latest known
text input state"/>
<arg name="flags" type="uint" summary="currently unused"/>
</event>
"
Post by Rui Tiago Cação Matos
I think that's all for now. Thanks,
Thanks,
Jan Arne
--
Jan Arne Petersen | ***@kdab.com | Senior Software Engineer
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel: +49-30-521325470
KDAB - The Qt Experts
Jan Arne Petersen
2016-02-02 11:26:24 UTC
Permalink
There were some shortcomings in the first version of the protocol which
makes it not really useful in real world applications. It is not really
possible to fix them in a compatible way so introduce a new v2 of the
protocol.

Fixes some shortcomings of the first version:

* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
* Improve update state handling
* Allow state requests
---
unstable/text-input/text-input-unstable-v2.xml | 481 +++++++++++++++++++++++++
1 file changed, 481 insertions(+)
create mode 100644 unstable/text-input/text-input-unstable-v2.xml

diff --git a/unstable/text-input/text-input-unstable-v2.xml b/unstable/text-input/text-input-unstable-v2.xml
new file mode 100644
index 0000000..2fc5e7d
--- /dev/null
+++ b/unstable/text-input/text-input-unstable-v2.xml
@@ -0,0 +1,481 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<protocol name="text_input_unstable_v2">
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+ Copyright © 2015, 2016 Jan Arne Petersen
+
+ 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="zwp_text_input_v2" version="1">
+ <description summary="text input">
+ The zwp_text_input_v2 interface repesents text input and input methods
+ associated with a seat. It provides enter/leave event to follow the
+ text input focus for a seat.
+
+ Requests are used to enable/disable the text-input object and set
+ state information like surrounding and selected text or the content type.
+ The information about entered text is sent to the text-input object 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.
+
+ Text is 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
+ update_state request and are used by the input method to indicate
+ the known text input state in evsents like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input">
+ Destroy the wp_text_input object. Also disables all surfaces enabled
+ through this wp_text_input object
+ </description>
+ </request>
+
+ <request name="enable">
+ <description summary="enable text input for surface">
+ Enable text input in a surface (usually when a text entry inside of it
+ has focus).
+
+ This can be called before or after a surface gets text (or keyboard)
+ focus via the enter event. Text input to a surface is only active
+ when it has the current text (or keyboard) focus and is enabled.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="disable">
+ <description summary="disable text input for surface">
+ Disable text input in a surface (typically when there is no focus on any
+ text entry inside the surface).
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="show_input_panel">
+ <description summary="show input panels">
+ Requests input panels (virtual keyboard) to show.
+
+ This should be used for example to show a virtual keyboard again
+ (with a tap) after it was closed by pressing on a close button on the
+ keyboard.
+ </description>
+ </request>
+
+ <request name="hide_input_panel">
+ <description summary="hide input panels">
+ Requests input panels (virtual keyboard) to hide.
+ </description>
+ </request>
+
+ <request name="reset">
+ <description summary="reset">
+ </description>
+ </request>
+
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
+
+ Make sure to always send some text before and after the cursor
+ except when the cursor is at the beginning or end of text.
+
+ When there was a
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="int"/>
+ </request>
+
+ <enum name="content_hint" bitfield="true">
+ <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="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 dependent)"/>
+ <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" enum="content_hint"/>
+ <arg name="purpose" type="uint" enum="content_purpose"/>
+ </request>
+
+ <request name="set_cursor_rectangle">
+ <description summary="set cursor position">
+ Sets the cursor outline as a rectangle relative to the surface.
+
+ Allows the compositor to put a window with word suggestions near the
+ cursor.
+ </description>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which
+ tracks languages of contacts.
+ </description>
+ <arg name="language" type="string"/>
+ </request>
+
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="full" value="1" summary="full state after demand_full_state event"/>
+ <entry name="reset" value="2" summary="full state after reset"/>
+ <entry name="enter" value="3" summary="full state after switching focus to a different widget on client side"/>
+ </enum>
+
+ <request name="update_state">
+ <description summary="update state">
+ Allows to atomically send state updates from client.
+
+ This request should follow after a batch of state updating requests
+ like set_surrounding_text, set_content_type, set_cursor_rectangle and
+ set_preferred_language.
+
+ The flags field indicates why an updated state is sent to the input
+ method.
+
+ Reset should be used by an editor widget after the text was changed
+ outside of the normal input method flow.
+
+ For "change" it is enough to send the changed state, else the full
+ state should be send.
+ </description>
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
+
+ <request name="invoke_action">
+ <description summary="invokes an action">
+ Allows to invoke an action when tapping or clicking the currently
+ composed word in the text input.
+
+ This can be used by input methods to offer more word suggestions.
+ </description>
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
+
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="leave">
+ <description summary="leave event">
+ Notification that this seat's text-input focus is no longer on
+ a certain surface.
+
+ The leave notification is sent before the enter notification
+ for the new focus.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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>
+
+ <enum name="input_panel_visibility">
+ <entry name="hidden" value="0"
+ summary="the input panel (virtual keyboard) is hidden"/>
+ <entry name="hidden" value="1"
+ summary="the input panel (virtual keyboard) is visible"/>
+ </enum>
+
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notification that the visibility of the input panel (virtual keyboard)
+ changed.
+
+ The rectangle x, y, width, height defines the bounding rectangle on
+ the surface with text focus which is overlapped by the input panel
+ (virtual keyboard). That can be used to make widgets with text focus
+ visible.
+ </description>
+ <arg name="state" type="uint" enum="input_panel_visibility"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </event>
+
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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 composing text in some cases
+ (for example on unfocus).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="composing text should be shown the same as non-composing text"/>
+ <entry name="active" value="2" summary="composing text might be bold"/>
+ <entry name="inactive" value="3" summary="composing text might be cursive"/>
+ <entry name="highlight" value="4" summary="composing text might have a different background color"/>
+ <entry name="underline" value="5" summary="composing text might be underlined"/>
+ <entry name="selection" value="6" summary="composing text should be shown the same as selected text"/>
+ <entry name="incorrect" value="7" summary="composing text might be underlined with a red wavy line"/>
+ </enum>
+
+ <event name="preedit_styling">
+ <description summary="pre-edit styling">
+ Sets styling information on composing text. The style is applied for
+ 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint" enum="preedit_style"/>
+ </event>
+
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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.
+
+ When no preedit_cursor event is sent the cursor will be at the end of
+ the composing text by default.
+
+ This event is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+
+ <event name="commit_string">
+ <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 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>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ Notify when the cursor or anchor position should be modified.
+
+ This event should be handled as part of a following commit_string
+ event.
+
+ The text between anchor and index should be selected.
+ </description>
+ <arg name="index" type="int" summary="position of cursor"/>
+ <arg name="anchor" type="int" summary="position of selection anchor"/>
+ </event>
+
+ <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 (in bytes).
+ Length is the length of deleted text (in bytes).
+
+ This event should be handled as part of a following commit_string
+ or preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ <arg name="length" type="uint"/>
+ </event>
+
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
+
+ <event name="language">
+ <description summary="language">
+ Sets the language of the input text. The "language" argument is a RFC-3066
+ format language tag.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </event>
+
+ <enum name="text_direction">
+ <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
+ <entry name="ltr" value="1" summary="left-to-right"/>
+ <entry name="rtl" value="2" summary="right-to-left"/>
+ </enum>
+
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing input cursor on correct side of the
+ editor when there is no input yet done and making sure neutral
+ direction text is laid out properly.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint" enum="text_direction"/>
+ </event>
+
+ <event name="configure_surrounding_text">
+ <description summary="configure amount of surrounding text to be send from client">
+ Configure what amount of surrounding text is sent by the
+ set_surrounding_text request on the following state information updates.
+ </description>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+
+ <event name="demand_full_state">
+ <description summary="demand the full state from client">
+ Ask to get full current state information sent from the client via
+ state requests (set_surrounding_text, set_content_hint, ...) and
+ update_state.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint" summary="currently unused"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_text_input_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input_manager">
+ Destroy the wp_text_input_manager object.
+ </description>
+ </request>
+
+ <request name="get_text_input">
+ <description summary="create a new text input object">
+ Creates a new text-input object for a given seat.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_text_input_v2"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+ </interface>
+</protocol>
--
2.5.0
Jan Arne Petersen
2016-02-02 11:32:27 UTC
Permalink
There were some shortcomings in the first version of the protocol which
makes it not really useful in real world applications. It is not really
possible to fix them in a compatible way so introduce a new v2 of the
protocol.

Fixes some shortcomings of the first version:

* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
* Improve update state handling
* Allow state requests
---
unstable/text-input/text-input-unstable-v2.xml | 481 +++++++++++++++++++++++++
1 file changed, 481 insertions(+)
create mode 100644 unstable/text-input/text-input-unstable-v2.xml

diff --git a/unstable/text-input/text-input-unstable-v2.xml b/unstable/text-input/text-input-unstable-v2.xml
new file mode 100644
index 0000000..e7d2d50
--- /dev/null
+++ b/unstable/text-input/text-input-unstable-v2.xml
@@ -0,0 +1,481 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<protocol name="text_input_unstable_v2">
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+ Copyright © 2015, 2016 Jan Arne Petersen
+
+ 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="zwp_text_input_v2" version="1">
+ <description summary="text input">
+ The zwp_text_input_v2 interface repesents text input and input methods
+ associated with a seat. It provides enter/leave event to follow the
+ text input focus for a seat.
+
+ Requests are used to enable/disable the text-input object and set
+ state information like surrounding and selected text or the content type.
+ The information about entered text is sent to the text-input object 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.
+
+ Text is 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
+ update_state request and are used by the input method to indicate
+ the known text input state in evsents like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input">
+ Destroy the wp_text_input object. Also disables all surfaces enabled
+ through this wp_text_input object
+ </description>
+ </request>
+
+ <request name="enable">
+ <description summary="enable text input for surface">
+ Enable text input in a surface (usually when a text entry inside of it
+ has focus).
+
+ This can be called before or after a surface gets text (or keyboard)
+ focus via the enter event. Text input to a surface is only active
+ when it has the current text (or keyboard) focus and is enabled.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="disable">
+ <description summary="disable text input for surface">
+ Disable text input in a surface (typically when there is no focus on any
+ text entry inside the surface).
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="show_input_panel">
+ <description summary="show input panels">
+ Requests input panels (virtual keyboard) to show.
+
+ This should be used for example to show a virtual keyboard again
+ (with a tap) after it was closed by pressing on a close button on the
+ keyboard.
+ </description>
+ </request>
+
+ <request name="hide_input_panel">
+ <description summary="hide input panels">
+ Requests input panels (virtual keyboard) to hide.
+ </description>
+ </request>
+
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
+
+ Make sure to always send some text before and after the cursor
+ except when the cursor is at the beginning or end of text.
+
+ When there was a configure_surrounding_text event take the
+ before_cursor and after_cursor arguments into account for picking how
+ much surrounding text to send.
+
+ There is a maximum length of wayland messages so text can not be
+ longer than 4000 bytes.
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="int"/>
+ </request>
+
+ <enum name="content_hint" bitfield="true">
+ <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="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 dependent)"/>
+ <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" enum="content_hint"/>
+ <arg name="purpose" type="uint" enum="content_purpose"/>
+ </request>
+
+ <request name="set_cursor_rectangle">
+ <description summary="set cursor position">
+ Sets the cursor outline as a rectangle relative to the surface.
+
+ Allows the compositor to put a window with word suggestions near the
+ cursor.
+ </description>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which
+ tracks languages of contacts.
+ </description>
+ <arg name="language" type="string"/>
+ </request>
+
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="full" value="1" summary="full state after demand_full_state event"/>
+ <entry name="reset" value="2" summary="full state after reset"/>
+ <entry name="enter" value="3" summary="full state after switching focus to a different widget on client side"/>
+ </enum>
+
+ <request name="update_state">
+ <description summary="update state">
+ Allows to atomically send state updates from client.
+
+ This request should follow after a batch of state updating requests
+ like set_surrounding_text, set_content_type, set_cursor_rectangle and
+ set_preferred_language.
+
+ The flags field indicates why an updated state is sent to the input
+ method.
+
+ Reset should be used by an editor widget after the text was changed
+ outside of the normal input method flow.
+
+ For "change" it is enough to send the changed state, else the full
+ state should be send.
+ </description>
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
+
+ <request name="invoke_action">
+ <description summary="invokes an action">
+ Allows to invoke an action when tapping or clicking the currently
+ composed word in the text input.
+
+ This can be used by input methods to offer more word suggestions.
+ </description>
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
+
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="leave">
+ <description summary="leave event">
+ Notification that this seat's text-input focus is no longer on
+ a certain surface.
+
+ The leave notification is sent before the enter notification
+ for the new focus.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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>
+
+ <enum name="input_panel_visibility">
+ <entry name="hidden" value="0"
+ summary="the input panel (virtual keyboard) is hidden"/>
+ <entry name="hidden" value="1"
+ summary="the input panel (virtual keyboard) is visible"/>
+ </enum>
+
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notification that the visibility of the input panel (virtual keyboard)
+ changed.
+
+ The rectangle x, y, width, height defines the bounding rectangle on
+ the surface with text focus which is overlapped by the input panel
+ (virtual keyboard). That can be used to make widgets with text focus
+ visible.
+ </description>
+ <arg name="state" type="uint" enum="input_panel_visibility"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </event>
+
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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 composing text in some cases
+ (for example on unfocus).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="composing text should be shown the same as non-composing text"/>
+ <entry name="active" value="2" summary="composing text might be bold"/>
+ <entry name="inactive" value="3" summary="composing text might be cursive"/>
+ <entry name="highlight" value="4" summary="composing text might have a different background color"/>
+ <entry name="underline" value="5" summary="composing text might be underlined"/>
+ <entry name="selection" value="6" summary="composing text should be shown the same as selected text"/>
+ <entry name="incorrect" value="7" summary="composing text might be underlined with a red wavy line"/>
+ </enum>
+
+ <event name="preedit_styling">
+ <description summary="pre-edit styling">
+ Sets styling information on composing text. The style is applied for
+ 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint" enum="preedit_style"/>
+ </event>
+
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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.
+
+ When no preedit_cursor event is sent the cursor will be at the end of
+ the composing text by default.
+
+ This event is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+
+ <event name="commit_string">
+ <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 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>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ Notify when the cursor or anchor position should be modified.
+
+ This event should be handled as part of a following commit_string
+ event.
+
+ The text between anchor and index should be selected.
+ </description>
+ <arg name="index" type="int" summary="position of cursor"/>
+ <arg name="anchor" type="int" summary="position of selection anchor"/>
+ </event>
+
+ <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 (in bytes).
+ Length is the length of deleted text (in bytes).
+
+ This event should be handled as part of a following commit_string
+ or preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ <arg name="length" type="uint"/>
+ </event>
+
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
+
+ <event name="language">
+ <description summary="language">
+ Sets the language of the input text. The "language" argument is a RFC-3066
+ format language tag.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </event>
+
+ <enum name="text_direction">
+ <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
+ <entry name="ltr" value="1" summary="left-to-right"/>
+ <entry name="rtl" value="2" summary="right-to-left"/>
+ </enum>
+
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing input cursor on correct side of the
+ editor when there is no input yet done and making sure neutral
+ direction text is laid out properly.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint" enum="text_direction"/>
+ </event>
+
+ <event name="configure_surrounding_text">
+ <description summary="configure amount of surrounding text to be send from client">
+ Configure what amount of surrounding text is sent by the
+ set_surrounding_text request on the following state information updates.
+ </description>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+
+ <event name="demand_full_state">
+ <description summary="demand the full state from client">
+ Ask to get full current state information sent from the client via
+ state requests (set_surrounding_text, set_content_hint, ...) and
+ update_state.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint" summary="currently unused"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_text_input_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input_manager">
+ Destroy the wp_text_input_manager object.
+ </description>
+ </request>
+
+ <request name="get_text_input">
+ <description summary="create a new text input object">
+ Creates a new text-input object for a given seat.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_text_input_v2"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+ </interface>
+</protocol>
--
2.5.0
Silvan Jegen
2016-02-02 12:23:05 UTC
Permalink
Hi

Please find some comments and spelling corrections below.
Post by Jan Arne Petersen
There were some shortcomings in the first version of the protocol which
makes it not really useful in real world applications. It is not really
possible to fix them in a compatible way so introduce a new v2 of the
protocol.
* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
* Improve update state handling
* Allow state requests
---
unstable/text-input/text-input-unstable-v2.xml | 481 +++++++++++++++++++++++++
1 file changed, 481 insertions(+)
create mode 100644 unstable/text-input/text-input-unstable-v2.xml
diff --git a/unstable/text-input/text-input-unstable-v2.xml b/unstable/text-input/text-input-unstable-v2.xml
new file mode 100644
index 0000000..2fc5e7d
--- /dev/null
+++ b/unstable/text-input/text-input-unstable-v2.xml
@@ -0,0 +1,481 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<protocol name="text_input_unstable_v2">
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+ Copyright © 2015, 2016 Jan Arne Petersen
+
+ 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="zwp_text_input_v2" version="1">
+ <description summary="text input">
+ The zwp_text_input_v2 interface represents text input and input methods
s/repesents/represents/
Post by Jan Arne Petersen
+ associated with a seat. It provides enter/leave event to follow the
s/event/events/
Post by Jan Arne Petersen
+ text input focus for a seat.
+
+ Requests are used to enable/disable the text-input object and set
+ state information like surrounding and selected text or the content type.
+ The information about entered text is sent to the text-input object via
"about the entered text" may sound more natural.
Post by Jan Arne Petersen
+ 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.
+
+ Text is UTF-8 encoded, indices and lengths are in bytes.
This seems problematic to me when dealing with multi-byte encoded
Unicode points. The behavior should be better defined in that case.
Please see comments further below.
Post by Jan Arne Petersen
+ 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
+ update_state request and are used by the input method to indicate
+ the known text input state in evsents like preedit_string, commit_string,
s/evsents/events/
Post by Jan Arne Petersen
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input">
+ Destroy the wp_text_input object. Also disables all surfaces enabled
+ through this wp_text_input object
+ </description>
+ </request>
+
+ <request name="enable">
+ <description summary="enable text input for surface">
+ Enable text input in a surface (usually when a text entry inside of it
+ has focus).
+
+ This can be called before or after a surface gets text (or keyboard)
+ focus via the enter event. Text input to a surface is only active
+ when it has the current text (or keyboard) focus and is enabled.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="disable">
+ <description summary="disable text input for surface">
+ Disable text input in a surface (typically when there is no focus on any
+ text entry inside the surface).
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="show_input_panel">
+ <description summary="show input panels">
+ Requests input panels (virtual keyboard) to show.
+
+ This should be used for example to show a virtual keyboard again
+ (with a tap) after it was closed by pressing on a close button on the
+ keyboard.
+ </description>
+ </request>
+
+ <request name="hide_input_panel">
+ <description summary="hide input panels">
+ Requests input panels (virtual keyboard) to hide.
+ </description>
+ </request>
+
+ <request name="reset">
+ <description summary="reset">
There is a description missing. Maybe something like

"Resets the state of the input method."?
Post by Jan Arne Petersen
+ </description>
+ </request>
+
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
Adding a comma here makes the text more readable.

"text, anchor is the same as cursor."
Post by Jan Arne Petersen
+
+ Make sure to always send some text before and after the cursor
+ except when the cursor is at the beginning or end of text.
+
+ When there was a
This line should be removed (or completed... :P).
Post by Jan Arne Petersen
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="int"/>
+ </request>
+
+ <enum name="content_hint" bitfield="true">
+ <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="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 dependent)"/>
+ <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" enum="content_hint"/>
+ <arg name="purpose" type="uint" enum="content_purpose"/>
+ </request>
+
+ <request name="set_cursor_rectangle">
+ <description summary="set cursor position">
+ Sets the cursor outline as a rectangle relative to the surface.
+
+ Allows the compositor to put a window with word suggestions near the
+ cursor.
+ </description>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which
+ tracks languages of contacts.
+ </description>
+ <arg name="language" type="string"/>
+ </request>
+
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="full" value="1" summary="full state after demand_full_state event"/>
+ <entry name="reset" value="2" summary="full state after reset"/>
+ <entry name="enter" value="3" summary="full state after switching focus to a different widget on client side"/>
+ </enum>
+
+ <request name="update_state">
+ <description summary="update state">
+ Allows to atomically send state updates from client.
+
+ This request should follow after a batch of state updating requests
+ like set_surrounding_text, set_content_type, set_cursor_rectangle and
+ set_preferred_language.
+
+ The flags field indicates why an updated state is sent to the input
+ method.
+
+ Reset should be used by an editor widget after the text was changed
+ outside of the normal input method flow.
+
+ For "change" it is enough to send the changed state, else the full
+ state should be send.
+ </description>
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
+
+ <request name="invoke_action">
+ <description summary="invokes an action">
+ Allows to invoke an action when tapping or clicking the currently
+ composed word in the text input.
+
+ This can be used by input methods to offer more word suggestions.
+ </description>
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
+
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="leave">
+ <description summary="leave event">
+ Notification that this seat's text-input focus is no longer on
+ a certain surface.
+
+ The leave notification is sent before the enter notification
+ for the new focus.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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>
+
+ <enum name="input_panel_visibility">
+ <entry name="hidden" value="0"
+ summary="the input panel (virtual keyboard) is hidden"/>
+ <entry name="hidden" value="1"
The entry name should be "visible" not "hidden" I assume.
Post by Jan Arne Petersen
+ summary="the input panel (virtual keyboard) is visible"/>
+ </enum>
+
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notification that the visibility of the input panel (virtual keyboard)
+ changed.
+
+ The rectangle x, y, width, height defines the bounding rectangle on
+ the surface with text focus which is overlapped by the input panel
+ (virtual keyboard). That can be used to make widgets with text focus
+ visible.
+ </description>
+ <arg name="state" type="uint" enum="input_panel_visibility"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </event>
+
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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 composing text in some cases
+ (for example on unfocus).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="composing text should be shown the same as non-composing text"/>
+ <entry name="active" value="2" summary="composing text might be bold"/>
+ <entry name="inactive" value="3" summary="composing text might be cursive"/>
+ <entry name="highlight" value="4" summary="composing text might have a different background color"/>
+ <entry name="underline" value="5" summary="composing text might be underlined"/>
+ <entry name="selection" value="6" summary="composing text should be shown the same as selected text"/>
+ <entry name="incorrect" value="7" summary="composing text might be underlined with a red wavy line"/>
+ </enum>
+
+ <event name="preedit_styling">
+ <description summary="pre-edit styling">
+ Sets styling information on composing text. The style is applied for
+ length bytes from index relative to the beginning of the composing
Having the offset in bytes is odd here. If you have a Unicode code
point that is encoded with 3 UTF-8 bytes and the offset includes only
one of the bytes are you then supposed to apply the style on this code
point? Or do you only apply the style if more than half of the encoded
bytes of a code point are included in the offset...
Post by Jan Arne Petersen
+ text (as byte offset). Multiple styles can be applied to a composing
+ text by sending multiple preedit_styling events.
+
+ This event is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint" enum="preedit_style"/>
+ </event>
+
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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.
If we use byte offsets we should define what should happen if the offset
bytes do not include all bytes of an encoded code point.
Post by Jan Arne Petersen
+
+ When no preedit_cursor event is sent the cursor will be at the end of
+ the composing text by default.
+
+ This event is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+
+ <event name="commit_string">
+ <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 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>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ Notify when the cursor or anchor position should be modified.
+
+ This event should be handled as part of a following commit_string
+ event.
+
+ The text between anchor and index should be selected.
+ </description>
+ <arg name="index" type="int" summary="position of cursor"/>
If we have byte offsets here as well we would have to decide what to do
in regards to multi-byte encoded Unicode points.
Post by Jan Arne Petersen
+ <arg name="anchor" type="int" summary="position of selection anchor"/>
+ </event>
+
+ <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 (in bytes).
+ Length is the length of deleted text (in bytes).
See comment about multi-byte-encoded Unicode points above.
Post by Jan Arne Petersen
+
+ This event should be handled as part of a following commit_string
+ or preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ <arg name="length" type="uint"/>
+ </event>
+
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
+
+ <event name="language">
+ <description summary="language">
+ Sets the language of the input text. The "language" argument is a RFC-3066
+ format language tag.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </event>
+
+ <enum name="text_direction">
+ <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
+ <entry name="ltr" value="1" summary="left-to-right"/>
+ <entry name="rtl" value="2" summary="right-to-left"/>
+ </enum>
+
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing input cursor on correct side of the
+ editor when there is no input yet done and making sure neutral
+ direction text is laid out properly.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint" enum="text_direction"/>
+ </event>
+
+ <event name="configure_surrounding_text">
+ <description summary="configure amount of surrounding text to be send from client">
s/send/sent/


Thanks for all this work!


Cheers,

Silvan
Post by Jan Arne Petersen
+ Configure what amount of surrounding text is sent by the
+ set_surrounding_text request on the following state information updates.
+ </description>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+
+ <event name="demand_full_state">
+ <description summary="demand the full state from client">
+ Ask to get full current state information sent from the client via
+ state requests (set_surrounding_text, set_content_hint, ...) and
+ update_state.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint" summary="currently unused"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_text_input_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input_manager">
+ Destroy the wp_text_input_manager object.
+ </description>
+ </request>
+
+ <request name="get_text_input">
+ <description summary="create a new text input object">
+ Creates a new text-input object for a given seat.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_text_input_v2"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+ </interface>
+</protocol>
--
2.5.0
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Jan Arne Petersen
2016-02-02 13:41:19 UTC
Permalink
Hi Silvan,
Post by Silvan Jegen
Hi
Please find some comments and spelling corrections below.
Post by Jan Arne Petersen
There were some shortcomings in the first version of the protocol which
makes it not really useful in real world applications. It is not really
possible to fix them in a compatible way so introduce a new v2 of the
protocol.
* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
* Improve update state handling
* Allow state requests
---
unstable/text-input/text-input-unstable-v2.xml | 481 +++++++++++++++++++++++++
1 file changed, 481 insertions(+)
create mode 100644 unstable/text-input/text-input-unstable-v2.xml
diff --git a/unstable/text-input/text-input-unstable-v2.xml b/unstable/text-input/text-input-unstable-v2.xml
new file mode 100644
index 0000000..2fc5e7d
--- /dev/null
+++ b/unstable/text-input/text-input-unstable-v2.xml
@@ -0,0 +1,481 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<protocol name="text_input_unstable_v2">
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+ Copyright © 2015, 2016 Jan Arne Petersen
+
+ 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="zwp_text_input_v2" version="1">
+ <description summary="text input">
+ The zwp_text_input_v2 interface represents text input and input methods
s/repesents/represents/
fixed
Post by Silvan Jegen
Post by Jan Arne Petersen
+ associated with a seat. It provides enter/leave event to follow the
s/event/events/
fixed
Post by Silvan Jegen
Post by Jan Arne Petersen
+ text input focus for a seat.
+
+ Requests are used to enable/disable the text-input object and set
+ state information like surrounding and selected text or the content type.
+ The information about entered text is sent to the text-input object via
"about the entered text" may sound more natural.
fixed
Post by Silvan Jegen
Post by Jan Arne Petersen
+ 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.
+
+ Text is UTF-8 encoded, indices and lengths are in bytes.
This seems problematic to me when dealing with multi-byte encoded
Unicode points. The behavior should be better defined in that case.
Please see comments further below.
From v4:

"Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices
have to always point to the first byte of an UTF-8 encoded code point.
Lengths are not allowed to contain just a part of an UTF-8 encoded code
point."

The protocol is usually not used by application developers directly but
by a toolkit which has to convert from toolkit strings/indices/lengths
to the protocol string/index/length format and back. Which seems to be
quite easy with above protocol definition. We could also use Unicode
characters for index/length should not make much a difference.
Post by Silvan Jegen
Post by Jan Arne Petersen
+ 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
+ update_state request and are used by the input method to indicate
+ the known text input state in evsents like preedit_string, commit_string,
s/evsents/events/
fixed
Post by Silvan Jegen
Post by Jan Arne Petersen
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input">
+ Destroy the wp_text_input object. Also disables all surfaces enabled
+ through this wp_text_input object
+ </description>
+ </request>
+
+ <request name="enable">
+ <description summary="enable text input for surface">
+ Enable text input in a surface (usually when a text entry inside of it
+ has focus).
+
+ This can be called before or after a surface gets text (or keyboard)
+ focus via the enter event. Text input to a surface is only active
+ when it has the current text (or keyboard) focus and is enabled.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="disable">
+ <description summary="disable text input for surface">
+ Disable text input in a surface (typically when there is no focus on any
+ text entry inside the surface).
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="show_input_panel">
+ <description summary="show input panels">
+ Requests input panels (virtual keyboard) to show.
+
+ This should be used for example to show a virtual keyboard again
+ (with a tap) after it was closed by pressing on a close button on the
+ keyboard.
+ </description>
+ </request>
+
+ <request name="hide_input_panel">
+ <description summary="hide input panels">
+ Requests input panels (virtual keyboard) to hide.
+ </description>
+ </request>
+
+ <request name="reset">
+ <description summary="reset">
There is a description missing. Maybe something like
"Resets the state of the input method."?
Request got removed (instead update_state with the "reset" flag is used)
Post by Silvan Jegen
Post by Jan Arne Petersen
+ </description>
+ </request>
+
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
Adding a comma here makes the text more readable.
"text, anchor is the same as cursor."
fixed
Post by Silvan Jegen
Post by Jan Arne Petersen
+
+ Make sure to always send some text before and after the cursor
+ except when the cursor is at the beginning or end of text.
+
+ When there was a
This line should be removed (or completed... :P).
Completed missing text:

"When there was a configure_surrounding_text event take the
before_cursor and after_cursor arguments into account for picking how
much surrounding text to send.

There is a maximum length of wayland messages so text can not be
longer than 4000 bytes."
Post by Silvan Jegen
Post by Jan Arne Petersen
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="int"/>
+ </request>
+
+ <enum name="content_hint" bitfield="true">
+ <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="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 dependent)"/>
+ <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" enum="content_hint"/>
+ <arg name="purpose" type="uint" enum="content_purpose"/>
+ </request>
+
+ <request name="set_cursor_rectangle">
+ <description summary="set cursor position">
+ Sets the cursor outline as a rectangle relative to the surface.
+
+ Allows the compositor to put a window with word suggestions near the
+ cursor.
+ </description>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which
+ tracks languages of contacts.
+ </description>
+ <arg name="language" type="string"/>
+ </request>
+
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="full" value="1" summary="full state after demand_full_state event"/>
+ <entry name="reset" value="2" summary="full state after reset"/>
+ <entry name="enter" value="3" summary="full state after switching focus to a different widget on client side"/>
+ </enum>
+
+ <request name="update_state">
+ <description summary="update state">
+ Allows to atomically send state updates from client.
+
+ This request should follow after a batch of state updating requests
+ like set_surrounding_text, set_content_type, set_cursor_rectangle and
+ set_preferred_language.
+
+ The flags field indicates why an updated state is sent to the input
+ method.
+
+ Reset should be used by an editor widget after the text was changed
+ outside of the normal input method flow.
+
+ For "change" it is enough to send the changed state, else the full
+ state should be send.
+ </description>
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
+
+ <request name="invoke_action">
+ <description summary="invokes an action">
+ Allows to invoke an action when tapping or clicking the currently
+ composed word in the text input.
+
+ This can be used by input methods to offer more word suggestions.
+ </description>
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
+
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="leave">
+ <description summary="leave event">
+ Notification that this seat's text-input focus is no longer on
+ a certain surface.
+
+ The leave notification is sent before the enter notification
+ for the new focus.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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>
+
+ <enum name="input_panel_visibility">
+ <entry name="hidden" value="0"
+ summary="the input panel (virtual keyboard) is hidden"/>
+ <entry name="hidden" value="1"
The entry name should be "visible" not "hidden" I assume.
fixed
Post by Silvan Jegen
Post by Jan Arne Petersen
+ summary="the input panel (virtual keyboard) is visible"/>
+ </enum>
+
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notification that the visibility of the input panel (virtual keyboard)
+ changed.
+
+ The rectangle x, y, width, height defines the bounding rectangle on
+ the surface with text focus which is overlapped by the input panel
+ (virtual keyboard). That can be used to make widgets with text focus
+ visible.
+ </description>
+ <arg name="state" type="uint" enum="input_panel_visibility"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </event>
+
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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 composing text in some cases
+ (for example on unfocus).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="composing text should be shown the same as non-composing text"/>
+ <entry name="active" value="2" summary="composing text might be bold"/>
+ <entry name="inactive" value="3" summary="composing text might be cursive"/>
+ <entry name="highlight" value="4" summary="composing text might have a different background color"/>
+ <entry name="underline" value="5" summary="composing text might be underlined"/>
+ <entry name="selection" value="6" summary="composing text should be shown the same as selected text"/>
+ <entry name="incorrect" value="7" summary="composing text might be underlined with a red wavy line"/>
+ </enum>
+
+ <event name="preedit_styling">
+ <description summary="pre-edit styling">
+ Sets styling information on composing text. The style is applied for
+ length bytes from index relative to the beginning of the composing
Having the offset in bytes is odd here. If you have a Unicode code
point that is encoded with 3 UTF-8 bytes and the offset includes only
one of the bytes are you then supposed to apply the style on this code
point? Or do you only apply the style if more than half of the encoded
bytes of a code point are included in the offset...
see above
Post by Silvan Jegen
Post by Jan Arne Petersen
+ text (as byte offset). Multiple styles can be applied to a composing
+ text by sending multiple preedit_styling events.
+
+ This event is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint" enum="preedit_style"/>
+ </event>
+
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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.
If we use byte offsets we should define what should happen if the offset
bytes do not include all bytes of an encoded code point.
see above
Post by Silvan Jegen
Post by Jan Arne Petersen
+
+ When no preedit_cursor event is sent the cursor will be at the end of
+ the composing text by default.
+
+ This event is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+
+ <event name="commit_string">
+ <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 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>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ Notify when the cursor or anchor position should be modified.
+
+ This event should be handled as part of a following commit_string
+ event.
+
+ The text between anchor and index should be selected.
+ </description>
+ <arg name="index" type="int" summary="position of cursor"/>
If we have byte offsets here as well we would have to decide what to do
in regards to multi-byte encoded Unicode points.
Post by Jan Arne Petersen
+ <arg name="anchor" type="int" summary="position of selection anchor"/>
+ </event>
+
+ <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 (in bytes).
+ Length is the length of deleted text (in bytes).
See comment about multi-byte-encoded Unicode points above.
Post by Jan Arne Petersen
+
+ This event should be handled as part of a following commit_string
+ or preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ <arg name="length" type="uint"/>
+ </event>
+
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
+
+ <event name="language">
+ <description summary="language">
+ Sets the language of the input text. The "language" argument is a RFC-3066
+ format language tag.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </event>
+
+ <enum name="text_direction">
+ <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
+ <entry name="ltr" value="1" summary="left-to-right"/>
+ <entry name="rtl" value="2" summary="right-to-left"/>
+ </enum>
+
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing input cursor on correct side of the
+ editor when there is no input yet done and making sure neutral
+ direction text is laid out properly.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint" enum="text_direction"/>
+ </event>
+
+ <event name="configure_surrounding_text">
+ <description summary="configure amount of surrounding text to be send from client">
s/send/sent/
fixed
Post by Silvan Jegen
Thanks for all this work!
Cheers,
Silvan
Thanks,
Jan Arne
Post by Silvan Jegen
Post by Jan Arne Petersen
+ Configure what amount of surrounding text is sent by the
+ set_surrounding_text request on the following state information updates.
+ </description>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+
+ <event name="demand_full_state">
+ <description summary="demand the full state from client">
+ Ask to get full current state information sent from the client via
+ state requests (set_surrounding_text, set_content_hint, ...) and
+ update_state.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint" summary="currently unused"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_text_input_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input_manager">
+ Destroy the wp_text_input_manager object.
+ </description>
+ </request>
+
+ <request name="get_text_input">
+ <description summary="create a new text input object">
+ Creates a new text-input object for a given seat.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_text_input_v2"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+ </interface>
+</protocol>
--
2.5.0
_______________________________________________
wayland-devel mailing list
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
--
Jan Arne Petersen | ***@kdab.com | Senior Software Engineer
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel: +49-30-521325470
KDAB - The Qt Experts
Jan Arne Petersen
2016-02-02 12:58:40 UTC
Permalink
Post by Jan Arne Petersen
+ Text is generally UTF-8 encoded, indices and lengths are in bytes.
Remove the word "generally". *All* text in your api's are UTF-8.
Done
Post by Jan Arne Petersen
+ <request name="activate">
+ <description summary="request activation">
+ Requests to activate a surface for text input (typically when a
+ text entry in it gets focus).
+
+ There can only be one active surface per client and seat.
When surface is
+ null all surfaces of the client get deactivated.
+ </description>
I think clients should be allowed to send activate more than once per
surface, it is to indicate the input focus switching between widgets.
This removes the need for another api to indicate the widget is
switching. Sending null for the surface, or a different event, would
indicate that the keyboard focus is no longer on a text input widget.
We use enable/disable request now. That should be a bit easier to handle
from client side.
Post by Jan Arne Petersen
+ <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>
+ </request>
I believe this request can be replaced by redundant activate requests.
It got integrated into update_state.
Post by Jan Arne Petersen
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="uint"/>
+ </request>
The anchor could be very far away from the cursor, much farther than any
small limit on the request size. I think this means the anchor position
could be negative or larger than the text length. Sending this without
clamping would be a good idea, the input method would then have a hint
where the anchor is, and it can clamp the value itself.
If the client wants new text to replace the selected text, the text
between anchor+cursor will be deleted, and any input method decisions
would depend on the text outside the anchor..cursor range. This may be
larger than the allowed buffer size, so I think clients have to send the
text as though the selection was deleted.
A client that does not want to replace the selected text could still
send an anchor, but then I am not clear if the input method can take
advantage of knowing what characters are selected to modify the results.
So it is possible the anchor is not needed at all.
Ok I use an int for anchor now. It still make sense for an input method
to know what is in the selection even when it gets replaced by new
entered text.
Post by Jan Arne Petersen
+ <entry name="auto_completion" value="0x1" summary="suggest
word completions"/>
+ <entry name="auto_correction" value="0x2" summary="suggest
word corrections"/>
I think you might want non-zero bits to *disable* features. This allows
zero to be the default, and means that if some new correction is
invented in the future then they can default to on without you having to
modify the numerical value of default.
Toolkits need to handle default on client side now.
Post by Jan Arne Petersen
+ <entry name="hidden_text" value="0x40" summary="characters
should be hidden"/>
Can you explain this? The client still has to do something to display
dots instead of characters, right? My guess is that this is an indicator
that the input method should not show any of the surrounding text in
popup controls. For instance maybe it can suggest word completion for
your password, but the display must show stars for the already-typed
characters. Is this correct?
Hopefully how clients and the input methods show hidden characters can
be agreed by convention, rather than adding more api to communicate that.
Yes you do not want to show already typed text on a virtual keyboard in
a password field. Usually the keyboard would show nothing then, no
reason to show dots/stars on the virtual keyboard.
Post by Jan Arne Petersen
+ <entry name="latin" value="0x100" summary="just latin
characters should be entered"/>
Do you mean ASCII? It seems unlikely you mean "the subset of Unicode
that they have declared are Latin characters" since that excludes
numbers and space and includes vast numbers of characters that some
software will not handle.
I guess we can remove it. Instead clients should just use
set_preferred_language("en").
Post by Jan Arne Petersen
+ <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"/>
I think it will work a lot better if the client can indicate in
set_surrounding_text that only a certain class of character is
acceptable right now. So if it is a date of for nn/nn/nn, then it will
indicate that slash or digit is required, depending on what is to the
left of the cursor. And the meaning of "phone number" and "date" and
"time" and "url" (and "zip code" and "ssn" and "inventory part number")
are all thus moved to the client.
Toolkits do not support that (in contrast to the content hints we
implemented here).

It is also useful to have a virtual keyboard adapted for entering urls
with keys for '.' '/' or '.com' or for emails with '@'. The virtual
keyboard can also provide completion based on url/email for example.
Post by Jan Arne Petersen
+ <entry name="name" value="7" summary="input a name of a person"/>
This gets more interesting because it may change the spelling corrector.
Yes and use address book for completion.
Post by Jan Arne Petersen
+ <enum name="update_state">
+ <entry name="request" value="1" summary="sent state after request"/>
Confusing. Actually your event is called "request", not to be confused
with what Wayland calls a "request". At least change this to the name of
the event (which is "request_state"). Better yet rename the event so it
does not have the word "request" in it.
Yes changed it the event is called demand_full_state now.
Post by Jan Arne Petersen
+ <request name="invoke_action">
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
Missing documentation? I would guess this is how clients send the
keyboard events to the input method?
Added description. It is about clicking/touching within the
composing/pre-edit text.
Post by Jan Arne Petersen
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a
certain surface.
+
+ When the seat has one or more keyboards the text-input focus
follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
I don't understand how this is used. It seems like the client will get
the keyboard focus events, and then tells the input method, not the
other way around.
There might be no hardware keyboards present so we provide enter/leave
for text focus. If there is a hardware keyboard text focus is the same
as keyboard focus.

Clients just enable/disable a surface for text input, which surface has
text focus (keyboard focus) is handled by compositor.
Post by Jan Arne Petersen
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="style should be the
same as in non-composing text"/>
+ <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>
It is not clear from this if "default" is different from all the others,
or is it equal to "active"?
Added more description to v3:

default: "default style for composing text"
none: "composing text should be shown the same as non-composing text"
active: "composing text might be bold"
inactive: "composing text might be cursive"
highlight: "composing text might have a different background color"
underline: "composing text might be underlined"
selection: "composing text should be shown the same as selected text"
incorrect: "composing text might be underlined with a red wavy line"
Post by Jan Arne Petersen
+ <event name="preedit_styling">
+ <description summary="pre-edit styling">
+ Sets styling information on composing text. The style is
applied for
+ 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.
Can more than one of these be applied to the same bytes? If so, are they
allowed to intersect arbitrarily? I think it is reasonable to require
the input method to require any ranges to be entirely inside or outside
each previously-sent ranges. This makes it easier for a client to
mindlessly insert <b> and </b> tags into pango input.
It might make sense to combine some so I do not want to exclude that.
Post by Jan Arne Petersen
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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 is handled as part of a following preedit_string
event.
+ </description>
Might want to say what happens if no cursor is sent. My guess is that
the cursor is put at the end of the preedit string.
Yes exactly added that to the documentation.
Post by Jan Arne Petersen
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
Is this for keysyms that the input method did not handle? Or for fake
key strokes? Or both?
For synthetic key events (fake stroke) for unhandled real hardware key
events wl_keyboard should be used (keyboard focus is the same as text
focus).
Post by Jan Arne Petersen
This provides a method for a client to avoid using libxkbd. Though I
still do not understand the problem, there seems to be a lot of claims
here that it is not possible, because of something to do with different
keymaps.
There might be no hardware keyboard (so no wl_keyboard) and we do not
have keycodes or the whole xkb state for synthetic key events but just a
sym and modifiers.
Post by Jan Arne Petersen
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing input cursor on correct side
of the
+ editor when there is no input yet done and making sure neutral
+ direction text is laid out properly.
+ </description>
I'm not sure what the purpose of this is, but I feel like this should be
part of the preedit events. The preedit may in fact be an empty string,
and then the client will need to know what end to put the cursor on.
I do not see the need to fold it into pre-edit. Seems like more
complicate than just sending an extra event when text direction matters
Post by Jan Arne Petersen
+ <event name="request_surrounding_text">
+ <description summary="request surrounding text from client">
+ Request to get the surrounding text and cursor position sent
from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest
known text input state"/>
+ <arg name="flags" type="uint"/>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
Would prefer that there not be two events that cause the same response.
Maybe this should be an indicator of how much text the input method
wants, when the request_state is done.
Yes done it is called configure_surrounding_text now.
Post by Jan Arne Petersen
+ <event name="request_state">
+ <description summary="request state from client">
+ Request to get the surrounding text and cursor position sent
from the client.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest
known text input state"/>
+ <arg name="flags" type="uint"/>
+ </event>
+ </interface>
I do not believe this event is necessary. Clients should instead always
send the surrounding text any time it changes, except if the change was
due to a commit. This avoids a round trip.
Yes that is more for use cases like you switch the input method in while
a text field is focussed and the new input method needs the state.
(Else we would need to cache state on compositor side which I do not like)
Post by Jan Arne Petersen
Putting "request" into the event name is confusing, as "request" has a
defined meaning in Wayland api.
Renamed it to demand_full_state.

Thanks,
Jan Arne
--
Jan Arne Petersen | ***@kdab.com | Senior Software Engineer
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel: +49-30-521325470
KDAB - The Qt Experts
Bill Spitzak
2016-02-03 01:59:11 UTC
Permalink
Post by Jan Arne Petersen
Post by Jan Arne Petersen
+ Text is generally UTF-8 encoded, indices and lengths are in bytes.
Remove the word "generally". *All* text in your api's are UTF-8.
Done
Post by Jan Arne Petersen
+ <request name="activate">
+ <description summary="request activation">
+ Requests to activate a surface for text input (typically
when a
Post by Jan Arne Petersen
+ text entry in it gets focus).
+
+ There can only be one active surface per client and seat.
When surface is
+ null all surfaces of the client get deactivated.
+ </description>
I think clients should be allowed to send activate more than once per
surface, it is to indicate the input focus switching between widgets.
This removes the need for another api to indicate the widget is
switching. Sending null for the surface, or a different event, would
indicate that the keyboard focus is no longer on a text input widget.
We use enable/disable request now. That should be a bit easier to handle
from client side.
Post by Jan Arne Petersen
+ <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>
+ </request>
I believe this request can be replaced by redundant activate requests.
It got integrated into update_state.
Post by Jan Arne Petersen
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as cursor.
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="uint"/>
+ </request>
The anchor could be very far away from the cursor, much farther than any
small limit on the request size. I think this means the anchor position
could be negative or larger than the text length. Sending this without
clamping would be a good idea, the input method would then have a hint
where the anchor is, and it can clamp the value itself.
If the client wants new text to replace the selected text, the text
between anchor+cursor will be deleted, and any input method decisions
would depend on the text outside the anchor..cursor range. This may be
larger than the allowed buffer size, so I think clients have to send the
text as though the selection was deleted.
A client that does not want to replace the selected text could still
send an anchor, but then I am not clear if the input method can take
advantage of knowing what characters are selected to modify the results.
So it is possible the anchor is not needed at all.
Ok I use an int for anchor now. It still make sense for an input method
to know what is in the selection even when it gets replaced by new
entered text.
I am unclear whether it is the input method's job to decide whether
characters replace the selection, or the client's job.

My concern is this:

- The input method has rules so that if the text before the cursor is "A"
and the user types 'x', you get "Ay". If the text is any other letter such
as "C" you get "Cx".

- Assume the text before the cursor is "Annnnnnnnn" where all the 'n' are
selected, and the length of the selection exceeds the size allowed by the
surrounding text request. Therefore the input method cannot know there is
an 'A' there.

- The user types 'x'. The input method cannot be aware that there is an A
there and the result will be "Ax", not the correct "Ay".

My proposed solution is that the client decides whether input replaces the
selection or is appended to it. If it replaces the selection, the text it
sends the input method is with the selection already deleted.

Other solution is that the above situation does not happen in real input
methods.
Post by Jan Arne Petersen
Post by Jan Arne Petersen
I think you might want non-zero bits to *disable* features. This allows
zero to be the default, and means that if some new correction is
invented in the future then they can default to on without you having to
modify the numerical value of default.
Toolkits need to handle default on client side now.
I'm concerned that the value of "default" should not change. Assuming most
toolkits choose default, it should not vary depending on when the toolkit
was compiled.
Post by Jan Arne Petersen
Yes you do not want to show already typed text on a virtual keyboard in
a password field. Usually the keyboard would show nothing then, no
reason to show dots/stars on the virtual keyboard.
I would assume it is considered better to use preedit than to have a
virtual keyboard with it's own display, but I guess this is useful if
somebody insists on making the keyboard work that way.
Post by Jan Arne Petersen
+ <request name="invoke_action">
Post by Jan Arne Petersen
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
Missing documentation? I would guess this is how clients send the
keyboard events to the input method?
Added description. It is about clicking/touching within the
composing/pre-edit text.
Makes sense. I think this could also be used to invoke the spelling
corrector if the user clicks in previous incorrect text.
Post by Jan Arne Petersen
default: "default style for composing text"
none: "composing text should be shown the same as non-composing text"
active: "composing text might be bold"
inactive: "composing text might be cursive"
highlight: "composing text might have a different background color"
underline: "composing text might be underlined"
selection: "composing text should be shown the same as selected text"
incorrect: "composing text might be underlined with a red wavy line"
I think I asked the question a bit wrong. The input method may be relying
on the user being able to distinguish two different highlights, and this
assumption would fail if a client renders them the same. Are there any
pairs of these numbers the client is allowed to render the same (for
instance default and none, can they be rendered identically?).
Post by Jan Arne Petersen
Post by Jan Arne Petersen
Can more than one of these be applied to the same bytes? If so, are they
allowed to intersect arbitrarily? I think it is reasonable to require
the input method to require any ranges to be entirely inside or outside
each previously-sent ranges. This makes it easier for a client to
mindlessly insert <b> and </b> tags into pango input.
It might make sense to combine some so I do not want to exclude that.
Yes I agree combining them is required. My question is whether the input
method should be restricted to simple nesting. For instance if it wants a
region of active that intersects a region of highlight, it is not allowed
to do this:

active range = 1..5
highlight range = 3..7

Instead it must do this, so the highlight ranges do not cross previous
boundaries:

active range = 1..5
highlight range = 3..5
highlight range = 6..7

I believe if clients are allowed to assume this it will make their job
easier.
Post by Jan Arne Petersen
+ <event name="keysym">
Post by Jan Arne Petersen
+ <description summary="keysym">
+ Notify when a key event was sent. Key events should not be
used
Post by Jan Arne Petersen
+ 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. 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)
Post by Jan Arne Petersen
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
Is this for keysyms that the input method did not handle? Or for fake
key strokes? Or both?
For synthetic key events (fake stroke) for unhandled real hardware key
events wl_keyboard should be used (keyboard focus is the same as text
focus).
How does the compositor prevent wl_keyboard events it used from being sent
to the client? What if the input method wants to handle the 'x' key itself,
but send the 'xy' combination to the client? It will have to eat the x-down
event, and then send a fake one just before the y-down???

I figured the input method would get all the keyboard events and would call
this with unhandled keystrokes.

I personally feel that Wayland will need to add an api that is more like
this, rather than clients running libxkb. It would solve all these
problems, and also make it far easier on remote desktop clients on systems
where you cannot get the keystrokes except in already-cooked form, and for
utilities that insert fake keystrokes. However I have been repeatedly told
that this is "impossible", for some reason having to do with multiple
keymaps (??). If you are able to get this in, then good for you. First step
toward fixing this.

Yes that is more for use cases like you switch the input method in while
Post by Jan Arne Petersen
a text field is focussed and the new input method needs the state.
(Else we would need to cache state on compositor side which I do not like)
This seems reasonable. It is trivial for a client to send the surrounding
text an extra time.

To prevent the client from sending surround text requests that are ignored,
I guess the input method should send a configure indicating that no text is
needed, then change it just before sending this event.
Jan Arne Petersen
2016-02-02 13:02:12 UTC
Permalink
Post by Jan Arne Petersen
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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).
+
+ The text input should also handle all preedit_style and
preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest
known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="style should be the
same as in non-composing text"/>
+ <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 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 is handled as part of a following preedit_string
event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint" enum="preedit_style"/>
+ </event>
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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 is handled as part of a following preedit_string
event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+ <event name="commit_string">
+ <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 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>
+ <arg name="serial" type="uint" summary="serial of the latest
known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ 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"/>
+ </event>
+ <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 (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"/>
+ </event>
I feel there are a lot of reasons to combine the preview and commit
strings. An actual commit would be done by setting the preview and then
sending a commit event.
- The preview has to be able to delete surrounding text, so that it can
preview a merge between typed text and surrounding characters.
- Conversely, to match how most text input works in software now, you
need to preserve the "incorrect" indicator in the committed text. This
is so the word remains marked as incorrect. There also has to be a way
for the client to return to that text and tell the input method to
continue, so the spelling correction code in the input method can be
reused (not just to make the client's work easier, but for the far more
important reason of making the ui consistent!).
These remove the differences between commit and preview, so it makes
sense to merge them.
Besides allowing the user to return to a misspelled word, it may make
sense to return to a preedit. I'm not sure as I have no experience with
Asian input methods. But it does seem possible.
Sorry no toolkit supports that. While the current proposed protocol can
be implemented with current Qt, Gtk+ and EFL. Androids input method API
is also quite similar to what is proposed here.
Post by Jan Arne Petersen
- Make delete surrounding text part of preview. Client has to remember
the deleted text so it can restore it for the next preview (which may
delete less).
Delete surrounding text also works for pre-edit, i fixed the documentation.
Post by Jan Arne Petersen
- Change commit_string to just a commit event that says the previous
preview string is the final result. This allows the commit to include
highlighting.
- Possibly allow the highlight regions to be larger than the preview
text. This could allow a spelling corrector to mark existing text as
part of the incorrect word. The alternative is that the spelling
corrector would have to delete the word, and insert it again with the
incorrect highlighting.
- Add a request to return to composing without a keystroke. The cursor
must be inside a previous commit or preview string. The idea is that the
user can later click on the misspelled words and somehow get the
spelling corrector to reappear. Also maybe it would allow returning to
other partially-composed strings.
See above.

Thanks,
Jan Arne
--
Jan Arne Petersen | ***@kdab.com | Senior Software Engineer
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel: +49-30-521325470
KDAB - The Qt Experts
Bill Spitzak
2016-02-03 01:15:16 UTC
Permalink
Post by Jan Arne Petersen
Post by Jan Arne Petersen
Besides allowing the user to return to a misspelled word, it may make
sense to return to a preedit. I'm not sure as I have no experience with
Asian input methods. But it does seem possible.
Sorry no toolkit supports that. While the current proposed protocol can
be implemented with current Qt, Gtk+ and EFL. Androids input method API
is also quite similar to what is proposed here.
I'm sorry but I am familiar toolkits that allow the user to return to a
previously misspelled word and invoke the spelling corrector. My browser is
right now drawing squiqqly red lines under "toolkits" and "squiggly".

This means that the "incorrect" highlighting has to be preserved from the
preedit string. I think the easiest way to do this is to merge the commit
and preedit apis, so an input method can commit highlighting. This means it
can commit any preedit string. I guess the client can leave the
highlighting or remove it depending on the client limitations. Returning to
preedit can only work if the preedit state can be determined from the
characters alone, as there is no method for the client to send the
highlighting or previous preedit range to the input method.

I find it difficult to imagine an implementation that is capable of showing
the preedit string yet unable to commit it, so I don't see how any toolkit
could not support this, unless it cannot show spelling error highlight
unless the cursor is right next to them.

I may be misunderstanding how you intend spelling correction / completion
to work, however.

Delete surrounding text also works for pre-edit, i fixed the documentation.
I was curious how you intend for it to indicate a misspelling when the
input method is adding a space after a word that may have been typed
previously. Two methods I can think of are to have it delete the entire
word and replace it with the same word with the incorrect highlighting, or
to allow the incorrect highlighting range to be outside the preedit string
and include bytes already in the buffer.
Jan Arne Petersen
2016-02-02 13:33:21 UTC
Permalink
There were some shortcomings in the first version of the protocol which
makes it not really useful in real world applications. It is not really
possible to fix them in a compatible way so introduce a new v2 of the
protocol.

Fixes some shortcomings of the first version:

* Use only one wp_text_input per wl_seat (client side should be
handled by client toolkit)
* Allow focus tracking without wl_keyboard present
* Improve update state handling
* Allow state requests
---
unstable/text-input/text-input-unstable-v2.xml | 484 +++++++++++++++++++++++++
1 file changed, 484 insertions(+)
create mode 100644 unstable/text-input/text-input-unstable-v2.xml

diff --git a/unstable/text-input/text-input-unstable-v2.xml b/unstable/text-input/text-input-unstable-v2.xml
new file mode 100644
index 0000000..0cfa837
--- /dev/null
+++ b/unstable/text-input/text-input-unstable-v2.xml
@@ -0,0 +1,484 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<protocol name="text_input_unstable_v2">
+ <copyright>
+ Copyright © 2012, 2013 Intel Corporation
+ Copyright © 2015, 2016 Jan Arne Petersen
+
+ 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="zwp_text_input_v2" version="1">
+ <description summary="text input">
+ The zwp_text_input_v2 interface represents text input and input methods
+ associated with a seat. It provides enter/leave events to follow the
+ text input focus for a seat.
+
+ Requests are used to enable/disable the text-input object and set
+ state information like surrounding and selected text or the content type.
+ The information about the entered text is sent to the text-input object
+ 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.
+
+ Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices
+ have to always point to the first byte of an UTF-8 encoded code point.
+ Lengths are not allowed to contain just a part of an UTF-8 encoded code
+ point.
+
+ 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
+ update_state request and are used by the input method to indicate
+ the known text input state in events like preedit_string, commit_string,
+ and keysym. The text input can then ignore events from the input method
+ which are based on an outdated state (for example after a reset).
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input">
+ Destroy the wp_text_input object. Also disables all surfaces enabled
+ through this wp_text_input object
+ </description>
+ </request>
+
+ <request name="enable">
+ <description summary="enable text input for surface">
+ Enable text input in a surface (usually when a text entry inside of it
+ has focus).
+
+ This can be called before or after a surface gets text (or keyboard)
+ focus via the enter event. Text input to a surface is only active
+ when it has the current text (or keyboard) focus and is enabled.
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="disable">
+ <description summary="disable text input for surface">
+ Disable text input in a surface (typically when there is no focus on any
+ text entry inside the surface).
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
+
+ <request name="show_input_panel">
+ <description summary="show input panels">
+ Requests input panels (virtual keyboard) to show.
+
+ This should be used for example to show a virtual keyboard again
+ (with a tap) after it was closed by pressing on a close button on the
+ keyboard.
+ </description>
+ </request>
+
+ <request name="hide_input_panel">
+ <description summary="hide input panels">
+ Requests input panels (virtual keyboard) to hide.
+ </description>
+ </request>
+
+ <request name="set_surrounding_text">
+ <description summary="sets the surrounding text">
+ 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 is the same as
+ cursor.
+
+ Make sure to always send some text before and after the cursor
+ except when the cursor is at the beginning or end of text.
+
+ When there was a configure_surrounding_text event take the
+ before_cursor and after_cursor arguments into account for picking how
+ much surrounding text to send.
+
+ There is a maximum length of wayland messages so text can not be
+ longer than 4000 bytes.
+ </description>
+ <arg name="text" type="string"/>
+ <arg name="cursor" type="uint"/>
+ <arg name="anchor" type="int"/>
+ </request>
+
+ <enum name="content_hint" bitfield="true">
+ <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="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 dependent)"/>
+ <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" enum="content_hint"/>
+ <arg name="purpose" type="uint" enum="content_purpose"/>
+ </request>
+
+ <request name="set_cursor_rectangle">
+ <description summary="set cursor position">
+ Sets the cursor outline as a rectangle relative to the surface.
+
+ Allows the compositor to put a window with word suggestions near the
+ cursor.
+ </description>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </request>
+
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which
+ tracks languages of contacts.
+ </description>
+ <arg name="language" type="string"/>
+ </request>
+
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="full" value="1" summary="full state after demand_full_state event"/>
+ <entry name="reset" value="2" summary="full state after reset"/>
+ <entry name="enter" value="3" summary="full state after switching focus to a different widget on client side"/>
+ </enum>
+
+ <request name="update_state">
+ <description summary="update state">
+ Allows to atomically send state updates from client.
+
+ This request should follow after a batch of state updating requests
+ like set_surrounding_text, set_content_type, set_cursor_rectangle and
+ set_preferred_language.
+
+ The flags field indicates why an updated state is sent to the input
+ method.
+
+ Reset should be used by an editor widget after the text was changed
+ outside of the normal input method flow.
+
+ For "change" it is enough to send the changed state, else the full
+ state should be send.
+ </description>
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
+
+ <request name="invoke_action">
+ <description summary="invokes an action">
+ Allows to invoke an action when tapping or clicking the currently
+ composed word in the text input.
+
+ This can be used by input methods to offer more word suggestions.
+ </description>
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
+
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="leave">
+ <description summary="leave event">
+ Notification that this seat's text-input focus is no longer on
+ a certain surface.
+
+ The leave notification is sent before the enter notification
+ for the new focus.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </event>
+
+ <event name="modifiers_map">
+ <description summary="modifiers map">
+ Transfer 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>
+
+ <enum name="input_panel_visibility">
+ <entry name="hidden" value="0"
+ summary="the input panel (virtual keyboard) is hidden"/>
+ <entry name="visible" value="1"
+ summary="the input panel (virtual keyboard) is visible"/>
+ </enum>
+
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notification that the visibility of the input panel (virtual keyboard)
+ changed.
+
+ The rectangle x, y, width, height defines the bounding rectangle on
+ the surface with text focus which is overlapped by the input panel
+ (virtual keyboard). That can be used to make widgets with text focus
+ visible.
+ </description>
+ <arg name="state" type="uint" enum="input_panel_visibility"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </event>
+
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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 composing text in some cases
+ (for example when loosing focus).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occurring directly before preedit_string.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ <arg name="commit" type="string"/>
+ </event>
+
+ <enum name="preedit_style">
+ <entry name="default" value="0" summary="default style for composing text"/>
+ <entry name="none" value="1" summary="composing text should be shown the same as non-composing text"/>
+ <entry name="active" value="2" summary="composing text might be bold"/>
+ <entry name="inactive" value="3" summary="composing text might be cursive"/>
+ <entry name="highlight" value="4" summary="composing text might have a different background color"/>
+ <entry name="underline" value="5" summary="composing text might be underlined"/>
+ <entry name="selection" value="6" summary="composing text should be shown the same as selected text"/>
+ <entry name="incorrect" value="7" summary="composing text might be underlined with a red wavy line"/>
+ </enum>
+
+ <event name="preedit_styling">
+ <description summary="pre-edit styling">
+ Sets styling information on composing text. The style is applied for
+ 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 is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="uint"/>
+ <arg name="length" type="uint"/>
+ <arg name="style" type="uint" enum="preedit_style"/>
+ </event>
+
+ <event name="preedit_cursor">
+ <description summary="pre-edit cursor">
+ 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.
+
+ When no preedit_cursor event is sent the cursor will be at the end of
+ the composing text by default.
+
+ This event is handled as part of a following preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ </event>
+
+ <event name="commit_string">
+ <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 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>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="text" type="string"/>
+ </event>
+
+ <event name="cursor_position">
+ <description summary="set cursor to new position">
+ Notify when the cursor or anchor position should be modified.
+
+ This event should be handled as part of a following commit_string
+ event.
+
+ The text between anchor and index should be selected.
+ </description>
+ <arg name="index" type="int" summary="position of cursor"/>
+ <arg name="anchor" type="int" summary="position of selection anchor"/>
+ </event>
+
+ <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 (in bytes).
+ Length is the length of deleted text (in bytes).
+
+ This event should be handled as part of a following commit_string
+ or preedit_string event.
+ </description>
+ <arg name="index" type="int"/>
+ <arg name="length" type="uint"/>
+ </event>
+
+ <event name="keysym">
+ <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_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)
+ </description>
+ <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"/>
+ <arg name="modifiers" type="uint"/>
+ </event>
+
+ <event name="language">
+ <description summary="language">
+ Sets the language of the input text. The "language" argument is a RFC-3066
+ format language tag.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="language" type="string"/>
+ </event>
+
+ <enum name="text_direction">
+ <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
+ <entry name="ltr" value="1" summary="left-to-right"/>
+ <entry name="rtl" value="2" summary="right-to-left"/>
+ </enum>
+
+ <event name="text_direction">
+ <description summary="text direction">
+ Sets the text direction of input text.
+
+ It is mainly needed for showing input cursor on correct side of the
+ editor when there is no input yet done and making sure neutral
+ direction text is laid out properly.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="direction" type="uint" enum="text_direction"/>
+ </event>
+
+ <event name="configure_surrounding_text">
+ <description summary="configure amount of surrounding text to be sent from client">
+ Configure what amount of surrounding text is sent by the
+ set_surrounding_text request on the following state information updates.
+ </description>
+ <arg name="before_cursor" type="int"/>
+ <arg name="after_cursor" type="int"/>
+ </event>
+
+ <event name="demand_full_state">
+ <description summary="demand the full state from client">
+ Ask to get full current state information sent from the client via
+ state requests (set_surrounding_text, set_content_hint, ...) and
+ update_state.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint" summary="currently unused"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_text_input_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input_manager">
+ Destroy the wp_text_input_manager object.
+ </description>
+ </request>
+
+ <request name="get_text_input">
+ <description summary="create a new text input object">
+ Creates a new text-input object for a given seat.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_text_input_v2"/>
+ <arg name="seat" type="object" interface="wl_seat"/>
+ </request>
+ </interface>
+</protocol>
--
2.5.0
Rui Tiago Cação Matos
2016-02-08 15:38:04 UTC
Permalink
Hi,

Thanks for the update. I'm replying to both v4 and your reply to my
Post by Jan Arne Petersen
+ <request name="disable">
+ <description summary="disable text input for surface">
+ Disable text input in a surface (typically when there is no focus on any
+ text entry inside the surface).
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
This seems fine. But just to clarify. It's perfectly valid for an
application to never call the disable request even if it loses focus
on an enabled surface. Right?
Post by Jan Arne Petersen
+ <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.
Yes, they might be not relevant for all input methods. Removed the
defaults,
They are still there though. I think that when unset this should
default to "normal" purpose and "none" hint.
Post by Jan Arne Petersen
which should be handled by toolkits (what to set when nothing
special is specified on an input widget).
Sure, toolkits, or clients in general, might always default on their
side to always call this request but that's beyond the protocol. What
the protocol needs to be clear about is what's assumed by the
compositor/IM when clients don't make this request.

In fact, that brings up another issue: _when_ does the compositor/IM
revert to the default purpose and hints? Does it revert when the text
input focus moves to a different wl_surface? Is it kept since it was
last set for all wl_surfaces of a particular client? Does it revert
when a client calls "update_state" ? There's several options here.
Post by Jan Arne Petersen
+ <request name="set_cursor_rectangle">
+ <description summary="set cursor position">
+ Sets the cursor outline as a rectangle relative to the surface.
+
+ Allows the compositor to put a window with word suggestions near the
+ cursor.
+ </description>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
These arguments could, and perhaps should, all be type="uint" .
Post by Jan Arne Petersen
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which
+ tracks languages of contacts.
+ </description>
I think this request also needs to specify when the preferred language
reverts to the unset state.
Post by Jan Arne Petersen
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="full" value="1" summary="full state after demand_full_state event"/>
+ <entry name="reset" value="2" summary="full state after reset"/>
+ <entry name="enter" value="3" summary="full state after switching focus to a different widget on client side"/>
+ </enum>
+
+ <request name="update_state">
+ <description summary="update state">
+ Allows to atomically send state updates from client.
+
+ This request should follow after a batch of state updating requests
+ like set_surrounding_text, set_content_type, set_cursor_rectangle and
+ set_preferred_language.
+
+ The flags field indicates why an updated state is sent to the input
+ method.
+
+ Reset should be used by an editor widget after the text was changed
+ outside of the normal input method flow.
+
+ For "change" it is enough to send the changed state, else the full
+ state should be send.
+ </description>
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
I don't understand how the "flags" argument is useful. Can you give
examples of how it would change anything for the compositor/IM ?

I think this request should also specify all, if any, transient state
that should be considered reset after it. E.g. content hints and
purpose, preferred language, etc.
Post by Jan Arne Petersen
+ <request name="invoke_action">
+ <description summary="invokes an action">
+ Allows to invoke an action when tapping or clicking the currently
+ composed word in the text input.
+
+ This can be used by input methods to offer more word suggestions.
+ </description>
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
This is still underspecified. What is button and index? Is there a
list of actions missing? Can you provide us with the use case you have
in mind for this?
Post by Jan Arne Petersen
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
There might or might not be a keyboard focus. Sure, if a compositor
has both a keyboard focus and a text focus, it makes sense for the
compositor to set both together to the same surface but that's not
necessary and I don't see any reason why we should tangle them in the
protocol.
Post by Jan Arne Petersen
+ <event name="modifiers_map">
+ <event name="keysym">
Let's discuss these two together (btw, if they stay in the protocol,
they should be moved to be together IMO).
Post by Jan Arne Petersen
There might be no hardware keyboard present (so no wl_keyboard
interface). This is mostly useful for synthetic key events generated by
a virtual keyboard (enter, backspace, cursor, whatever), which cannot be
send via wl_keyboard.
Nothing prevents the compositor from exposing a wl_keyboard object
when there's no keyboard hardware and use it to send events generated
from a virtual keyboard.

Having these events here means that compositors would have to
duplicate to a great extent the code they already have to handle
wl_keyboard and just make things less clear in general.

If there's anything wl_keyboard doesn't allow us to do, by all means
let's add specific requests to this protocol. But these two requests
should be dropped IMO.
Post by Jan Arne Petersen
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notification that the visibility of the input panel (virtual keyboard)
+ changed.
+
+ The rectangle x, y, width, height defines the bounding rectangle on
+ the surface with text focus which is overlapped by the input panel
+ (virtual keyboard). That can be used to make widgets with text focus
+ visible.
+ </description>
+ <arg name="state" type="uint" enum="input_panel_visibility"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </event>
All the coordinates could be uint. Also, I think we should add that
"compositors should send this event right after an enter event" since
the virtual keyboard might already be visible.
Post by Jan Arne Petersen
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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 composing text in some cases
+ (for example when loosing focus).
Typo: "losing"
Post by Jan Arne Petersen
+ <event name="demand_full_state">
+ <description summary="demand the full state from client">
+ Ask to get full current state information sent from the client via
+ state requests (set_surrounding_text, set_content_hint, ...) and
+ update_state.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint" summary="currently unused"/>
+ </event>
+ </interface>
Can you provide an example of when should a compositor/IM send this event?
Post by Jan Arne Petersen
+ <interface name="zwp_text_input_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input_manager">
+ Destroy the wp_text_input_manager object.
+ </description>
+ </request>
Given that this a global singleton it doesn't make sense to have a
destructor for it.

Thanks,
Rui
Rui Tiago Cação Matos
2016-02-08 18:42:55 UTC
Permalink
The x and y have to be signed. Imagine if the client is scrolled in such a
way that the cursor rectangle is partially outside the surface.
Are you saying this is an acceptable case:

+----------------+
|compositor popup|
+----------------+

+-------------------+
| surface w/ |
| scrolled |
| contents |
+-------------------+

I would expect the application to scroll its contents automatically so
that the cursor is visible on the surface...

Rui
Bill Spitzak
2016-02-09 00:02:32 UTC
Permalink
Yes that is exactly what I expect.

The input method may, if it wants, clamp the region to the surface, or even
to the input area of the surface. It does not have to put it disconnected
from the visible area like you are showing, though it can if it wants.
Post by Rui Tiago Cação Matos
The x and y have to be signed. Imagine if the client is scrolled in such
a
way that the cursor rectangle is partially outside the surface.
+----------------+
|compositor popup|
+----------------+
+-------------------+
| surface w/ |
| scrolled |
| contents |
+-------------------+
I would expect the application to scroll its contents automatically so
that the cursor is visible on the surface...
Rui
Jan Arne Petersen
2016-02-17 05:13:00 UTC
Permalink
Hi,
Post by Rui Tiago Cação Matos
Hi,
Thanks for the update. I'm replying to both v4 and your reply to my
Post by Jan Arne Petersen
+ <request name="disable">
+ <description summary="disable text input for surface">
+ Disable text input in a surface (typically when there is no focus on any
+ text entry inside the surface).
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
This seems fine. But just to clarify. It's perfectly valid for an
application to never call the disable request even if it loses focus
on an enabled surface. Right?
Yes that is fine. The input method gets active then again next time the
surface gets text focus.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <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.
Yes, they might be not relevant for all input methods. Removed the
defaults,
They are still there though. I think that when unset this should
default to "normal" purpose and "none" hint.
Yes exactly "normal" purpose and "none" hint would be the default.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
which should be handled by toolkits (what to set when nothing
special is specified on an input widget).
Sure, toolkits, or clients in general, might always default on their
side to always call this request but that's beyond the protocol. What
the protocol needs to be clear about is what's assumed by the
compositor/IM when clients don't make this request.
In fact, that brings up another issue: _when_ does the compositor/IM
revert to the default purpose and hints? Does it revert when the text
input focus moves to a different wl_surface? Is it kept since it was
last set for all wl_surfaces of a particular client? Does it revert
when a client calls "update_state" ? There's several options here.
Yes all state gets lost when a client calls update_state with a flag !=
change. After a new surface gets active input focus it must send an
updated state. I will add it to the documentation.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="set_cursor_rectangle">
+ <description summary="set cursor position">
+ Sets the cursor outline as a rectangle relative to the surface.
+
+ Allows the compositor to put a window with word suggestions near the
+ cursor.
+ </description>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
These arguments could, and perhaps should, all be type="uint"
Yes I guess for width/height.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which
+ tracks languages of contacts.
+ </description>
I think this request also needs to specify when the preferred language
reverts to the unset state.
See above.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="full" value="1" summary="full state after demand_full_state event"/>
+ <entry name="reset" value="2" summary="full state after reset"/>
+ <entry name="enter" value="3" summary="full state after switching focus to a different widget on client side"/>
+ </enum>
+
+ <request name="update_state">
+ <description summary="update state">
+ Allows to atomically send state updates from client.
+
+ This request should follow after a batch of state updating requests
+ like set_surrounding_text, set_content_type, set_cursor_rectangle and
+ set_preferred_language.
+
+ The flags field indicates why an updated state is sent to the input
+ method.
+
+ Reset should be used by an editor widget after the text was changed
+ outside of the normal input method flow.
+
+ For "change" it is enough to send the changed state, else the full
+ state should be send.
+ </description>
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
I don't understand how the "flags" argument is useful. Can you give
examples of how it would change anything for the compositor/IM ?
A update_state(change) request is used when just a specific state is
changed on client side (for example surrounding text).

Update_state(full) is used after a demand_full_state event is sent from
compositor/input method. All previous set state is lost. That event
might be send when an input method gets switched on compositor side and
thenew input method does not have any state yet.

Update_state(reset) is used when a client side widget keeps the input
method active but the current input gets interrupted (i.e. copy/pasting
into current text widget). All previous set state is lost (That seems to
be easier than to require from the client to send just changed state).

Update_state(enter is used when a new client side widget gets the active
input method (either after switching focus inside the surface on client
side, or by gaining text focus to a surface). All previous set state is
lost. This is the case mentioned above.
Post by Rui Tiago Cação Matos
I think this request should also specify all, if any, transient state
that should be considered reset after it. E.g. content hints and
purpose, preferred language, etc.
Yes in all cases except for update_state(change).
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="invoke_action">
+ <description summary="invokes an action">
+ Allows to invoke an action when tapping or clicking the currently
+ composed word in the text input.
+
+ This can be used by input methods to offer more word suggestions.
+ </description>
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
This is still underspecified. What is button and index? Is there a
list of actions missing? Can you provide us with the use case you have
in mind for this?
Yes indeed I will add more documentation.

It is used to be able to interact with pre-edit text (move the cursor
within pre-edit text or touch-and-hold to get some more options).

Button is button from wl_pointer::button event (or equivalent for
touch). Index the index within pre-edit text at which the click/touch
happened.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
There might or might not be a keyboard focus. Sure, if a compositor
has both a keyboard focus and a text focus, it makes sense for the
compositor to set both together to the same surface but that's not
necessary and I don't see any reason why we should tangle them in the
protocol.
Yes we have the text focus in cases there is no keyboard available
(currently there is no way to have a focus then).

It does not make sense to have text and keyboard focus on different
surfaces at least not for the same seat. I do not see any case where you
would want hardware keyboard input and virtual keyboard input going into
different widgets/surfaces at the same time.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="modifiers_map">
+ <event name="keysym">
Let's discuss these two together (btw, if they stay in the protocol,
they should be moved to be together IMO).
Post by Jan Arne Petersen
There might be no hardware keyboard present (so no wl_keyboard
interface). This is mostly useful for synthetic key events generated by
a virtual keyboard (enter, backspace, cursor, whatever), which cannot be
send via wl_keyboard.
Nothing prevents the compositor from exposing a wl_keyboard object
when there's no keyboard hardware and use it to send events generated
from a virtual keyboard.
Having these events here means that compositors would have to
duplicate to a great extent the code they already have to handle
wl_keyboard and just make things less clear in general.
If there's anything wl_keyboard doesn't allow us to do, by all means
let's add specific requests to this protocol. But these two requests
should be dropped IMO.
wl_keyboard currently does not allow to send synthetic key events when
you want to just send keysyms.

I am not sure if it really makes sense to extend wl_keyboard to support
that.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notification that the visibility of the input panel (virtual keyboard)
+ changed.
+
+ The rectangle x, y, width, height defines the bounding rectangle on
+ the surface with text focus which is overlapped by the input panel
+ (virtual keyboard). That can be used to make widgets with text focus
+ visible.
+ </description>
+ <arg name="state" type="uint" enum="input_panel_visibility"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </event>
All the coordinates could be uint. Also, I think we should add that
"compositors should send this event right after an enter event" since
the virtual keyboard might already be visible.
Post by Jan Arne Petersen
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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 composing text in some cases
+ (for example when loosing focus).
Typo: "losing"
Fixed.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="demand_full_state">
+ <description summary="demand the full state from client">
+ Ask to get full current state information sent from the client via
+ state requests (set_surrounding_text, set_content_hint, ...) and
+ update_state.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint" summary="currently unused"/>
+ </event>
+ </interface>
Can you provide an example of when should a compositor/IM send this event?
That would be mostly used when you switch input method (language) while
input is happening, so we do not need to cache the state in
compositor/input method framework.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <interface name="zwp_text_input_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input_manager">
+ Destroy the wp_text_input_manager object.
+ </description>
+ </request>
Given that this a global singleton it doesn't make sense to have a
destructor for it.
Yes I will remove it.
Post by Rui Tiago Cação Matos
Thanks,
Rui
--
Jan Arne Petersen | ***@kdab.com | Senior Software Engineer
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel: +49-30-521325470
KDAB - The Qt Experts
Jonas Ådahl
2016-02-17 06:06:00 UTC
Permalink
Post by Jan Arne Petersen
Hi,
Post by Rui Tiago Cação Matos
Hi,
Thanks for the update. I'm replying to both v4 and your reply to my
Post by Jan Arne Petersen
+ <request name="disable">
+ <description summary="disable text input for surface">
+ Disable text input in a surface (typically when there is no focus on any
+ text entry inside the surface).
+ </description>
+ <arg name="surface" type="object" interface="wl_surface"/>
+ </request>
This seems fine. But just to clarify. It's perfectly valid for an
application to never call the disable request even if it loses focus
on an enabled surface. Right?
Yes that is fine. The input method gets active then again next time the
surface gets text focus.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <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.
Yes, they might be not relevant for all input methods. Removed the
defaults,
They are still there though. I think that when unset this should
default to "normal" purpose and "none" hint.
Yes exactly "normal" purpose and "none" hint would be the default.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
which should be handled by toolkits (what to set when nothing
special is specified on an input widget).
Sure, toolkits, or clients in general, might always default on their
side to always call this request but that's beyond the protocol. What
the protocol needs to be clear about is what's assumed by the
compositor/IM when clients don't make this request.
In fact, that brings up another issue: _when_ does the compositor/IM
revert to the default purpose and hints? Does it revert when the text
input focus moves to a different wl_surface? Is it kept since it was
last set for all wl_surfaces of a particular client? Does it revert
when a client calls "update_state" ? There's several options here.
Yes all state gets lost when a client calls update_state with a flag !=
change. After a new surface gets active input focus it must send an
updated state. I will add it to the documentation.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="set_cursor_rectangle">
+ <description summary="set cursor position">
+ Sets the cursor outline as a rectangle relative to the surface.
+
+ Allows the compositor to put a window with word suggestions near the
+ cursor.
+ </description>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
These arguments could, and perhaps should, all be type="uint"
Yes I guess for width/height.
No, all should be signed integers. It'll make it much easier to deal
with overflows. If you mix unsigned and signed, the client/server will
still convert the unsigned ints to signed ints immediately anyway.
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="set_preferred_language">
+ <description summary="sets preferred language">
+ Sets a specific language. This allows for example a virtual keyboard to
+ show a language specific layout. The "language" argument is a RFC-3066
+ format language tag.
+
+ It could be used for example in a word processor to indicate language of
+ currently edited document or in an instant message application which
+ tracks languages of contacts.
+ </description>
I think this request also needs to specify when the preferred language
reverts to the unset state.
See above.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <enum name="update_state">
+ <description summary="update_state flags">
+ Defines the reason for sending an updated state.
+ </description>
+ <entry name="change" value="0" summary="updated state because it changed"/>
+ <entry name="full" value="1" summary="full state after demand_full_state event"/>
+ <entry name="reset" value="2" summary="full state after reset"/>
+ <entry name="enter" value="3" summary="full state after switching focus to a different widget on client side"/>
+ </enum>
+
+ <request name="update_state">
+ <description summary="update state">
+ Allows to atomically send state updates from client.
+
+ This request should follow after a batch of state updating requests
+ like set_surrounding_text, set_content_type, set_cursor_rectangle and
+ set_preferred_language.
+
+ The flags field indicates why an updated state is sent to the input
+ method.
+
+ Reset should be used by an editor widget after the text was changed
+ outside of the normal input method flow.
+
+ For "change" it is enough to send the changed state, else the full
+ state should be send.
+ </description>
+ <arg name="serial" type="uint" summary="used to identify the known state"/>
+ <arg name="flags" type="uint" enum="update_state"/>
+ </request>
I don't understand how the "flags" argument is useful. Can you give
examples of how it would change anything for the compositor/IM ?
A update_state(change) request is used when just a specific state is
changed on client side (for example surrounding text).
Update_state(full) is used after a demand_full_state event is sent from
compositor/input method. All previous set state is lost. That event
might be send when an input method gets switched on compositor side and
thenew input method does not have any state yet.
Update_state(reset) is used when a client side widget keeps the input
method active but the current input gets interrupted (i.e. copy/pasting
into current text widget). All previous set state is lost (That seems to
be easier than to require from the client to send just changed state).
Update_state(enter is used when a new client side widget gets the active
input method (either after switching focus inside the surface on client
side, or by gaining text focus to a surface). All previous set state is
lost. This is the case mentioned above.
Post by Rui Tiago Cação Matos
I think this request should also specify all, if any, transient state
that should be considered reset after it. E.g. content hints and
purpose, preferred language, etc.
Yes in all cases except for update_state(change).
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="invoke_action">
+ <description summary="invokes an action">
+ Allows to invoke an action when tapping or clicking the currently
+ composed word in the text input.
+
+ This can be used by input methods to offer more word suggestions.
+ </description>
+ <arg name="button" type="uint"/>
+ <arg name="index" type="uint"/>
+ </request>
This is still underspecified. What is button and index? Is there a
list of actions missing? Can you provide us with the use case you have
in mind for this?
Yes indeed I will add more documentation.
It is used to be able to interact with pre-edit text (move the cursor
within pre-edit text or touch-and-hold to get some more options).
Button is button from wl_pointer::button event (or equivalent for
touch). Index the index within pre-edit text at which the click/touch
happened.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="enter">
+ <description summary="enter event">
+ Notification that this seat's text-input focus is on a certain surface.
+
+ When the seat has one or more keyboards the text-input focus follows the
+ keyboard focus.
There might or might not be a keyboard focus. Sure, if a compositor
has both a keyboard focus and a text focus, it makes sense for the
compositor to set both together to the same surface but that's not
necessary and I don't see any reason why we should tangle them in the
protocol.
Yes we have the text focus in cases there is no keyboard available
(currently there is no way to have a focus then).
It does not make sense to have text and keyboard focus on different
surfaces at least not for the same seat. I do not see any case where you
would want hardware keyboard input and virtual keyboard input going into
different widgets/surfaces at the same time.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="modifiers_map">
+ <event name="keysym">
Let's discuss these two together (btw, if they stay in the protocol,
they should be moved to be together IMO).
Post by Jan Arne Petersen
There might be no hardware keyboard present (so no wl_keyboard
interface). This is mostly useful for synthetic key events generated by
a virtual keyboard (enter, backspace, cursor, whatever), which cannot be
send via wl_keyboard.
Nothing prevents the compositor from exposing a wl_keyboard object
when there's no keyboard hardware and use it to send events generated
from a virtual keyboard.
Having these events here means that compositors would have to
duplicate to a great extent the code they already have to handle
wl_keyboard and just make things less clear in general.
If there's anything wl_keyboard doesn't allow us to do, by all means
let's add specific requests to this protocol. But these two requests
should be dropped IMO.
wl_keyboard currently does not allow to send synthetic key events when
you want to just send keysyms.
I am not sure if it really makes sense to extend wl_keyboard to support
that.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="input_panel_state">
+ <description summary="state of the input panel">
+ Notification that the visibility of the input panel (virtual keyboard)
+ changed.
+
+ The rectangle x, y, width, height defines the bounding rectangle on
+ the surface with text focus which is overlapped by the input panel
+ (virtual keyboard). That can be used to make widgets with text focus
+ visible.
+ </description>
+ <arg name="state" type="uint" enum="input_panel_visibility"/>
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
+ </event>
All the coordinates could be uint. Also, I think we should add that
"compositors should send this event right after an enter event" since
the virtual keyboard might already be visible.
Post by Jan Arne Petersen
+ <event name="preedit_string">
+ <description summary="pre-edit">
+ Notify 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 composing text in some cases
+ (for example when loosing focus).
Typo: "losing"
Fixed.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="demand_full_state">
+ <description summary="demand the full state from client">
+ Ask to get full current state information sent from the client via
+ state requests (set_surrounding_text, set_content_hint, ...) and
+ update_state.
+ </description>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
+ <arg name="flags" type="uint" summary="currently unused"/>
+ </event>
+ </interface>
Can you provide an example of when should a compositor/IM send this event?
That would be mostly used when you switch input method (language) while
input is happening, so we do not need to cache the state in
compositor/input method framework.
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <interface name="zwp_text_input_manager_v2" version="1">
+ <description summary="text input manager">
+ A factory for text-input objects. This object is a global singleton.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the wp_text_input_manager">
+ Destroy the wp_text_input_manager object.
+ </description>
+ </request>
Given that this a global singleton it doesn't make sense to have a
destructor for it.
Yes I will remove it.
No, don't remove it. Clients should be able to destroy globals when they
don't need to use it any more. All globals should have these
destructors.


Jonas
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Thanks,
Rui
--
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel: +49-30-521325470
KDAB - The Qt Experts
_______________________________________________
wayland-devel mailing list
https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Jonas Ådahl
2016-02-19 02:10:46 UTC
Permalink
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="set_cursor_rectangle">
...
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
These arguments could, and perhaps should, all be type="uint"
Yes I guess for width/height.
As Jonas pointed out, just leave them as "int". One thing I now
noticed is that the text says the coordinates are relative to the
surface but I think it's better to be explicit and use the main
wayland protocol terms "surface local coordinates" i.e. the
coordinates should take the surface scale into account.
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="invoke_action">
...
Post by Jan Arne Petersen
It is used to be able to interact with pre-edit text (move the cursor
within pre-edit text or touch-and-hold to get some more options).
Aren't those client side operations? This request just doesn't seem
right in this protocol. Perhaps it belongs in a different protocol for
specific environments/devices? The text protocol should be strictly
about text input IMO.
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="enter">
...
Post by Jan Arne Petersen
Yes we have the text focus in cases there is no keyboard available
(currently there is no way to have a focus then).
It does not make sense to have text and keyboard focus on different
surfaces at least not for the same seat. I do not see any case where you
would want hardware keyboard input and virtual keyboard input going into
different widgets/surfaces at the same time.
Perhaps it doesn't make sense but I don't see why we need to tie them
up here, just like wl_pointer's focus isn't necessarily tied to
wl_keyboard's focus in the main protocol.
In practice, sure, compositors will likely keep them all synced. In
any case, the sentence
"When the seat has one or more keyboards the text-input focus follows
the keyboard focus."
can't be worded like that because, again, even if a seat doesn't have
a hardware keyboard, the wl_keyboard object (and its focus) may exist
anyway. At least, it needs to be changed to
"The seat's text-input focus follows the keyboard focus."
if we indeed want to specify that they must be tied.
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="modifiers_map">
+ <event name="keysym">
...
Post by Jan Arne Petersen
wl_keyboard currently does not allow to send synthetic key events when
you want to just send keysyms.
Why do we need to send keysyms though? Isn't it enough to commit
(single character) strings?
One reason would be to match key presses without keycodes (such as when
they come from VNC or a hardware device outputting keysyms instead of
keycodes) with modifiers, so one can press Ctrl-Å. I suppose sending a
modifier keycode (assuming a keycode could represent the expected
modifier keysym given the keyboard layout), and let the client match
the current modifier state with single-character committed strings, but
that seems a bit like an abuse of what committed strings represent, i.e.
just changed content, not unlikely with unforseen consequences.


Jonas
Rui
_______________________________________________
wayland-devel mailing list
https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Jan Arne Petersen
2016-02-19 16:10:07 UTC
Permalink
Hi,
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="set_cursor_rectangle">
...
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <arg name="x" type="int"/>
+ <arg name="y" type="int"/>
+ <arg name="width" type="int"/>
+ <arg name="height" type="int"/>
These arguments could, and perhaps should, all be type="uint"
Yes I guess for width/height.
As Jonas pointed out, just leave them as "int". One thing I now
noticed is that the text says the coordinates are relative to the
surface but I think it's better to be explicit and use the main
wayland protocol terms "surface local coordinates" i.e. the
coordinates should take the surface scale into account.
Ok I will do.
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <request name="invoke_action">
...
Post by Jan Arne Petersen
It is used to be able to interact with pre-edit text (move the cursor
within pre-edit text or touch-and-hold to get some more options).
Aren't those client side operations? This request just doesn't seem
right in this protocol. Perhaps it belongs in a different protocol for
specific environments/devices? The text protocol should be strictly
about text input IMO.
Yes we can just leave that out for now. I will remove it from the protocol.
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="enter">
...
Post by Jan Arne Petersen
Yes we have the text focus in cases there is no keyboard available
(currently there is no way to have a focus then).
It does not make sense to have text and keyboard focus on different
surfaces at least not for the same seat. I do not see any case where you
would want hardware keyboard input and virtual keyboard input going into
different widgets/surfaces at the same time.
Perhaps it doesn't make sense but I don't see why we need to tie them
up here, just like wl_pointer's focus isn't necessarily tied to
wl_keyboard's focus in the main protocol.
Well pointer focus and keyboard focus are usually not in sync (pointer
focus is on the surface where the pointer currently is over, keyboard
focus where the keyboard input happens).

I do not know any toolkit supporting an extra text input focus beside
the keyboard focus. The current problem is the case when there is no
keyboard/wl_keyboard present in a wl_seat and then they do not have a
way to get a keyboard/text-input focus at all.

When we specify it is always the same as the keyboard focus, the
toolkits can easily use it for there text input/keyboard focus.

If you really want an extra independent text input focus that should
probably just be in an extra seat, which is of course also allowed from
this protocol.
In practice, sure, compositors will likely keep them all synced. In
any case, the sentence
"When the seat has one or more keyboards the text-input focus follows
the keyboard focus."
can't be worded like that because, again, even if a seat doesn't have
a hardware keyboard, the wl_keyboard object (and its focus) may exist
anyway. At least, it needs to be changed to
That is coming from wl_seat documentation of the keyboard capability:
"The seat has one or more keyboards", I can of course also write "When
the seat has the keyboard capability the seat's text-input ..."
"The seat's text-input focus follows the keyboard focus."
That is even better.
if we indeed want to specify that they must be tied.
Yes I really want to specify that, so clients/toolkits can rely on that
Post by Jan Arne Petersen
Post by Rui Tiago Cação Matos
Post by Jan Arne Petersen
+ <event name="modifiers_map">
+ <event name="keysym">
...
Post by Jan Arne Petersen
wl_keyboard currently does not allow to send synthetic key events when
you want to just send keysyms.
Why do we need to send keysyms though? Isn't it enough to commit
(single character) strings?
There is also things like backspace, cursor keys and escape (or
something like ctrl-c for a terminal) which you want to input in a
virtual keyboard and which can not be represented as text commits.

Thanks for the feedback. I will prepare an updated v5 soon.
Jan Arne
--
Jan Arne Petersen | ***@kdab.com | Senior Software Engineer
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel: +49-30-521325470
KDAB - The Qt Experts
Continue reading on narkive:
Loading...