[wayland-protocols] input-method: Add zwp-input-method-v2

Submitted by Dorota Czaplejewicz on Oct. 4, 2018, 8 p.m.

Details

Message ID 20181004200013.3590-1-dorota.czaplejewicz@puri.sm
State New
Series "input-method: Add zwp-input-method-v2"
Headers show

Commit Message

Dorota Czaplejewicz Oct. 4, 2018, 8 p.m.
This protocol is based on v1, current text-input-v3, and wl_keyboard version 6.

The pieces passing data relevant to the application on the other side of the compositor are a mirror copy of text-input-v3 events and requests.

Compared to input-method-v1:
- assumes that once preedit is displayed, no selection can be active, removing some selection handling
- follow text-input and removes language indicators
- explicitly attaches to seats
- removes "commit" text which would replace the preedit string automatically in case it wasn't "confirmed" (whatever it means)
- adds double-buffering in the same places as text-input-v3
- drops input_method_context and places its functionality directly in input_method
- removes the ability to move the cursor position outside of preedit. It still allows to delete a larger chunk of text and replace it with a preedit
- doesn't allow for sending of keyboard events to the compositor
- doesn't define any surfaces except for a special compositor-positioned popup
---
Hi,

continuing the RFC, I think this protocol is actually workable now, and I'm sending this with the PATCH qualifier.

The practical verification came in the form of a partial wlroots implementation [0]. The formal issues (chiefly stemming from copy-pasting things at night) have been pointed out to me by Simon, and corrected.

The major unverified parts are keyboard grabs and popup surfaces, which I will verify next.

Changes compared to the RFC:

- fixed so many confusing typos
- renamed preedit_text request to set_preedit_text
- described what happens when things get destroyed
- defined the role of input_popup sorface and forbade it from being deleted
- copied wl_keyboard to serve as the keyboard grab interface

I hope you can help me find the remaining issues and turn this interface into reality!

Cheers,
Dorota Czaplejewicz

 Makefile.am                                        |   1 +
 unstable/input-method/input-method-unstable-v2.xml | 490 +++++++++++++++++++++
 2 files changed, 491 insertions(+)
 create mode 100644 unstable/input-method/input-method-unstable-v2.xml

Patch hide | download patch | download mbox

diff --git a/Makefile.am b/Makefile.am
index 6394e26..f3b9f80 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -7,6 +7,7 @@  unstable_protocols =								\
 	unstable/text-input/text-input-unstable-v1.xml				\
 	unstable/text-input/text-input-unstable-v3.xml				\
 	unstable/input-method/input-method-unstable-v1.xml			\
+	unstable/input-method/input-method-unstable-v2.xml			\
 	unstable/xdg-shell/xdg-shell-unstable-v5.xml				\
 	unstable/xdg-shell/xdg-shell-unstable-v6.xml				\
 	unstable/relative-pointer/relative-pointer-unstable-v1.xml		\
diff --git a/unstable/input-method/input-method-unstable-v2.xml b/unstable/input-method/input-method-unstable-v2.xml
new file mode 100644
index 0000000..62be9d9
--- /dev/null
+++ b/unstable/input-method/input-method-unstable-v2.xml
@@ -0,0 +1,490 @@ 
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="input_method_unstable_v2">
+
+  <copyright>
+    Copyright © 2008-2011 Kristian Høgsberg
+    Copyright © 2010-2011 Intel Corporation
+    Copyright © 2012-2013 Collabora, Ltd.
+    Copyright © 2012, 2013 Intel Corporation
+    Copyright © 2015, 2016 Jan Arne Petersen
+    Copyright © 2017, 2018 Red Hat, Inc.
+    Copyright © 2018       Purism SPC
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="Protocol for creating input methods">
+    This protocol allows applications to act as input methods for compositors.
+
+    An input method context is used to manage the state of the input method.
+
+    Text strings are UTF-8 encoded, their indices and lengths are in bytes.
+
+    This document adheres to the RFC 2119 when using words like "must",
+    "should", "may", etc.
+
+    Warning! The protocol described in this file is experimental and
+    backward incompatible changes may be made. Backward compatible changes
+    may be added together with the corresponding interface version bump.
+    Backward incompatible changes are done by bumping the version number in
+    the protocol and interface names and resetting the interface version.
+    Once the protocol is to be declared stable, the 'z' prefix and the
+    version number in the protocol and interface names are removed and the
+    interface version number is reset.
+  </description>
+
+  <interface name="zwp_input_method_v2" version="1">
+    <description summary="input method">
+      An input method object allows for clients to compose text.
+
+      The objects connects the client to a text input in an application, and
+      lets the client to serve as an input method for a seat.
+
+      The zwp_input_method_v2 object can occupy two distinct states: active and
+      inactive. In the active state, the object is associated to and
+      communicates with a text input. In the inactive state, there is no
+      associated text input, and the only communication is with the compositor.
+      Initially, the input method is in the inactive state.
+
+      Requests issued in the inactive state must be accepted by the compositor.
+      Because of the serial mechanism, and the state reset on activate event,
+      they will not have any effect on the state of the next text input.
+
+      There must be no more than one input method object per seat.
+    </description>
+
+    <event name="activate">
+      <description summary="input method has been requested">
+        Notification that a text input focused on this seat requested the input
+        method to be activated.
+
+        This event serves the purpose of providing the compositor with an
+        active input method.
+
+        This event resets all state associated with previous enable, disable,
+        surrounding_text, text_change_cause, and content_type events, as well
+        as the state associated with set_preedit_string, commit_string, and
+        delete_surrounding_text requests. In addition, it marks the
+        zwp_input_method_v2 object as active, and makes any existing
+        zwp_input_popup_surface_v2 objects visible.
+
+        The surrounding_text, and content_type events must follow before the
+        next done event if the text input supports the respective
+        functionality.
+
+        State set with this event is double-buffered. It will get applied on
+        the next zwp_input_method_v2.done event, and stay valid until changed.
+      </description>
+    </event>
+
+    <event name="deactivate">
+      <description summary="deactivate event">
+        Notification that no focused text input currently needs an active 
+        input method on this seat.
+
+        This event marks the zwp_input_method_v2 object as inactive. The
+        compositor must make all existing zwp_input_popup_surface_v2 objects
+        invisible until the next activate event.
+
+        State set with this event is double-buffered. It will get applied on
+        the next zwp_input_method_v2.done event, and stay valid until changed.
+      </description>
+    </event>
+
+    <event name="surrounding_text">
+      <description summary="surrounding text event">
+        Updates the surrounding plain text around the cursor, excluding the
+        preedit text.
+
+        If any preedit text is present, it is replaced with the cursor for the
+        purpose of this event.
+
+        The argument text is a buffer containing the preedit string, and must
+        include the cursor position, and the complete selection. It should
+        contain additional characters before and after these. There is a
+        maximum length of wayland messages, so text can not be longer than 4000
+        bytes.
+
+        cursor is the byte offset of the cursor within the text buffer.
+
+        anchor is the byte offset of the selection anchor within the text
+        buffer. If there is no selected text, anchor must be the same as
+        cursor.
+
+        If this event does not arrive before the first done event, the input
+        method may assume that the text input does not support this
+        functionality and ignore following surrounding_text events.
+
+        Values set with this event are double-buffered. They will get applied
+        and set to initial values on the next zwp_input_method_v2.done
+        event.
+
+        The initial state for affected fields is empty, meaning that the text
+        input does not support sending surrounding text. If the empty values
+        get applied, subsequent attempts to change them may have no effect.
+      </description>
+      <arg name="text" type="string"/>
+      <arg name="cursor" type="uint"/>
+      <arg name="anchor" type="uint"/>
+    </event>
+
+    <event name="text_change_cause">
+      <description summary="indicates the cause of surrounding text change">
+        Tells the input method why the text surrounding the cursor changed.
+
+        Whenever the client detects an external change in text, cursor, or
+        anchor position, it must issue this request to the compositor. This
+        request is intended to give the input method a chance to update the
+        preedit text in an appropriate way, e.g. by removing it when the user
+        starts typing with a keyboard.
+
+        cause describes the source of the change.
+
+        The value set with this event is double-buffered. It will get applied
+        and set to its initial value on the next zwp_input_method_v2.done
+        event.
+
+        The initial value of cause is input_method.
+      </description>
+      <arg name="cause" type="uint" enum="zwp_text_input_v3.change_cause"/>
+    </event>
+
+    <event name="content_type">
+      <description summary="content purpose and hint">
+        Indicates the content type and hint for the current
+        zwp_input_method_v2 instance.
+
+        Values set with this event are double-buffered. They will get applied
+        on the next zwp_input_method_v2.done event.
+
+        The initial value for hint is none, and the initial value for purpose
+        is normal.
+      </description>
+      <arg name="hint" type="uint" enum="zwp_text_input_v3.content_hint"/>
+      <arg name="purpose" type="uint" enum="zwp_text_input_v3.content_purpose"/>
+    </event>
+
+    <event name="done">
+      <description summary="apply state">
+        Atomically applies state changes recently sent to the client.
+
+        The done event establishes and updates the state of the client, and
+        must be issued after any changes to apply them.
+
+        Text input state (content purpose, content hint, surrounding text, and
+        change cause) is conceptually double-buffered within an input method
+        context.
+
+        Events modify the pending state, as opposed to the current state in use
+        by the input method. A done event atomically applies all pending state,
+        replacing the current state. After done, the new pending state is as
+        documented for each related request.
+
+        Events must be applied in the order of arrival.
+
+        Neither current nor pending state are modified unless noted otherwise.
+      </description>
+    </event>
+
+    <request name="commit_string">
+      <description summary="commit string">
+        Send the commit string text for insertion to the application.
+
+        Inserts a string at current cursor position (see commit event
+        sequence). The string to commit could be either just a single character
+        after a key press or the result of some composing.
+
+        The argument text is a buffer containing the string to insert. There is
+        a maximum length of wayland messages, so text can not be longer than
+        4000 bytes.
+
+        Values set with this event are double-buffered. They must be applied
+        and reset to initial on the next zwp_text_input_v3.commit request.
+
+        The initial value of text is an empty string.
+      </description>
+      <arg name="text" type="string"/>
+    </request>
+
+    <request name="set_preedit_string">
+      <description summary="pre-edit string">
+        Send the pre-edit string text to the application text input.
+
+        Place a new composing text (pre-edit) at the current cursor position.
+        Any previously set composing text must be removed. Any previously
+        existing selected text must be removed. The cursor is moved to a new
+        position within the preedit string.
+
+        The argument text is a buffer containing the preedit string. There is
+        a maximum length of wayland messages, so text can not be longer than
+        4000 bytes.
+
+        The arguments cursor_begin and cursor_end are counted in bytes relative
+        to the beginning of the submitted string buffer. Cursor should be
+        hidden by the text input when both are equal to -1.
+
+        cursor_begin indicates the beginning of the cursor. cursor_end
+        indicates the end of the cursor. It may be equal or different than
+        cursor_begin.
+
+        Values set with this event are double-buffered. They must be applied on
+        the next zwp_input_method_v2.commit event.
+
+        The initial value of text is an empty string. The initial value of
+        cursor_begin, and cursor_end are both 0.
+      </description>
+      <arg name="text" type="string"/>
+      <arg name="cursor_begin" type="int"/>
+      <arg name="cursor_end" type="int"/>
+    </request>
+
+    <request name="delete_surrounding_text">
+      <description summary="delete text">
+        Remove the surrounding text.
+
+        before_length and after_length are the number of bytes before and after
+        the current cursor index (excluding the preedit text) to delete.
+
+        If any preedit text is present, it is replaced with the cursor for the
+        purpose of this event. In effect before_length is counted from the
+        beginning of preedit text, and after_length from its end (see commit
+        event sequence).
+
+        Values set with this event are double-buffered. They must be applied
+        and reset to initial on the next zwp_input_method_v2.commit request.
+
+        The initial values of both before_length and after_length are 0.
+      </description>
+      <arg name="before_length" type="uint"/>
+      <arg name="after_length" type="uint"/>
+    </request>
+
+    <request name="commit">
+      <description summary="apply state">
+        Apply state changes from commit_string, set_preedit_string and
+        delete_surrounding_text requests.
+
+        The state relating to these events is double-buffered, and each one
+        modifies the pending state. This request replaces the current state
+        with the pending state.
+
+        The connected text input is expected to proceed by evaluating the
+        changes in the following order:
+
+        1. Replace existing preedit string with the cursor.
+        2. Delete requested surrounding text.
+        3. Insert commit string with the cursor at its end.
+        4. Calculate surrounding text to send.
+        5. Insert new preedit text in cursor position.
+        6. Place cursor inside preedit text.
+
+        The serial number reflects the last state of the zwp_input_method_v2
+        object known to the client. The value of the serial argument must be
+        equal to the number of done events already issued by that object. When
+        the compositor receives a commit request with a serial different than
+        the number of past done events, it must proceed as normal, except it
+        should not change the current state of the zwp_input_method_v2 object.
+      </description>
+      <arg name="serial" type="uint"/>
+    </request>
+
+    <request name="get_input_popup_surface">
+      <description summary="create popup surface">
+        Creates a new zwp_input_popup_surface_v2 object wrapping a given
+        surface.
+
+        The surface gets assigned the "input_popup" role. If the surface
+        already has an assigned role, the compositor must issue a protocol
+        error.
+      </description>
+      <arg name="id" type="new_id" interface="zwp_input_popup_surface_v2"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
+
+    <request name="grab_keyboard">
+      <description summary="grab hardware keyboard">
+        Allow an input method to receive hardware keyboard input and process
+        key events to generate text events (with pre-edit) over the wire. This
+        allows input methods which compose multiple key events for inputting
+        text like it is done for CJK languages.
+
+        The compositor should send all keyboard events on the seat to the grab
+        holder via the returned wl_keyboard object. Nevertheless, the
+        compositor may decide not to forward any particular event. The
+        compositor must not further process any event after it has been
+        forwarded to the grab holder.
+
+        Releasing the resulting wl_keyboard object releases the grab.
+      </description>
+      <arg name="keyboard" type="new_id"
+        interface="zwp_input_method_keyboard_grab_v2"/>
+    </request>
+
+    <event name="unavailable">
+      <description summary="input method unavailable">
+        The input method ceased to be available.
+
+        The compositor must issue this event as the only event on the object if
+        there was another input_method object associated with the same seat at
+        the time of its creation.
+
+        The compositor must issue this request when the object is no longer
+        useable, e.g. due to seat removal.
+
+        The input method context becomes inert and should be destroyed after
+        deactivation is handled. Any further requests and events except for the
+        destroy request must be ignored.
+      </description>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the text input">
+        Destroys the zwp_text_input_v2 object and any associated child
+        objects, i.e. zwp_input_popup_surface_v2 and
+        zwp_input_method_keyboard_grab_v2.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="zwp_input_popup_surface_v2" version="1">
+    <description summary="popup surface">
+      This interface marks a surface as a popup for interacting with an input
+      method.
+
+      The compositor should place it near the active text input area. It must
+      be visible if and only if the input method is in the active state.
+
+      The client must not destroy the underlying wl_surface while the
+      zwp_input_popup_surface_v2 object exists.
+    </description>
+
+    <event name="text_input_rectangle">
+      <description summary="set text input area position">
+        Notify about the position of the area of the text input expressed as a
+        rectangle in surface local coordinates.
+
+        This is a hint to the input method telling it the relative position of
+        the text being entered.
+      </description>
+      <arg name="x" type="int"/>
+      <arg name="y" type="int"/>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+    </event>
+
+    <request name="destroy" type="destructor"/>
+  </interface>
+
+  <interface name="zwp_input_method_keyboard_grab_v2" version="1">
+    <!-- Closely follows wl_keyboard version 6 -->
+    <description summary="keyboard grab">
+      The zwp_input_method_keyboard_grab_v2 interface represents an exclusive
+      grab of the wl_keyboard interface associated with the seat.
+    </description>
+
+    <event name="keymap">
+      <description summary="keyboard mapping">
+        This event provides a file descriptor to the client which can be
+        memory-mapped to provide a keyboard mapping description.
+      </description>
+      <arg name="format" type="uint" enum="wl_keyboard.keymap_format"
+        summary="keymap format"/>
+      <arg name="fd" type="fd" summary="keymap file descriptor"/>
+      <arg name="size" type="uint" summary="keymap size, in bytes"/>
+    </event>
+
+    <event name="key">
+      <description summary="key event">
+        A key was pressed or released.
+        The time argument is a timestamp with millisecond granularity, with an
+        undefined base.
+      </description>
+      <arg name="serial" type="uint" summary="serial number of the key event"/>
+      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+      <arg name="key" type="uint" summary="key that produced the event"/>
+      <arg name="state" type="uint" enum="wl_keyboard.key_state"
+        summary="physical state of the key"/>
+    </event>
+
+    <event name="modifiers">
+      <description summary="modifier and group state">
+        Notifies clients that the modifier and/or group state has changed, and
+        it should update its local state.
+      </description>
+      <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
+      <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
+      <arg name="mods_latched" type="uint" summary="latched modifiers"/>
+      <arg name="mods_locked" type="uint" summary="locked modifiers"/>
+      <arg name="group" type="uint" summary="keyboard layout"/>
+    </event>
+
+    <request name="release" type="destructor">
+      <description summary="release the grab object"/>
+    </request>
+
+    <event name="repeat_info">
+      <description summary="repeat rate and delay">
+        Informs the client about the keyboard's repeat rate and delay.
+
+        This event is sent as soon as the zwp_input_method_keyboard_grab_v2
+        object has been created, and is guaranteed to be received by the
+        client before any key press event.
+
+        Negative values for either rate or delay are illegal. A rate of zero
+        will disable any repeating (regardless of the value of delay).
+
+        This event can be sent later on as well with a new value if necessary,
+        so clients should continue listening for the event past the creation
+        of zwp_input_method_keyboard_grab_v2.
+      </description>
+      <arg name="rate" type="int"
+	   summary="the rate of repeating keys in characters per second"/>
+      <arg name="delay" type="int"
+	   summary="delay in milliseconds since key down until repeating starts"/>
+    </event>
+  </interface>
+
+  <interface name="zwp_input_method_manager_v2" version="1">
+    <description summary="input method manager">
+      The input method manager allows the client to become the input method on
+      a chosen seat.
+
+      No more than one input method must be associated with any seat at any
+      given time.
+    </description>
+
+    <request name="get_input_method">
+      <description summary="request an input method object">
+        Request a new input zwp_input_method_v2 object associated with a given
+        seat.
+      </description>
+      <arg name="seat" type="object" interface="wl_seat"/>
+      <arg name="input_method" type="new_id" interface="zwp_input_method_v2"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the input method manager">
+        Destroys the zwp_input_method_manager_v2 object.
+
+        The zwp_input_method_v2 objects originating from it remain valid.
+      </description>
+    </request>
+  </interface>
+</protocol>

Comments

Roman Gilg Nov. 9, 2018, 5:26 p.m.
Hi,

what's the current state of this patch?

I have a KWin patch up for review to implement the text-input v3
protocol, so I would be interested in pushing forward the input_method
v2 here.

If there are already some test applications speaking both ends of the
pipeline I could try it out in KWin.

Cheers
On Thu, Oct 4, 2018 at 10:01 PM Dorota Czaplejewicz
<dorota.czaplejewicz@puri.sm> wrote:
>
> This protocol is based on v1, current text-input-v3, and wl_keyboard version 6.
>
> The pieces passing data relevant to the application on the other side of the compositor are a mirror copy of text-input-v3 events and requests.
>
> Compared to input-method-v1:
> - assumes that once preedit is displayed, no selection can be active, removing some selection handling
> - follow text-input and removes language indicators
> - explicitly attaches to seats
> - removes "commit" text which would replace the preedit string automatically in case it wasn't "confirmed" (whatever it means)
> - adds double-buffering in the same places as text-input-v3
> - drops input_method_context and places its functionality directly in input_method
> - removes the ability to move the cursor position outside of preedit. It still allows to delete a larger chunk of text and replace it with a preedit
> - doesn't allow for sending of keyboard events to the compositor
> - doesn't define any surfaces except for a special compositor-positioned popup
> ---
> Hi,
>
> continuing the RFC, I think this protocol is actually workable now, and I'm sending this with the PATCH qualifier.
>
> The practical verification came in the form of a partial wlroots implementation [0]. The formal issues (chiefly stemming from copy-pasting things at night) have been pointed out to me by Simon, and corrected.
>
> The major unverified parts are keyboard grabs and popup surfaces, which I will verify next.
>
> Changes compared to the RFC:
>
> - fixed so many confusing typos
> - renamed preedit_text request to set_preedit_text
> - described what happens when things get destroyed
> - defined the role of input_popup sorface and forbade it from being deleted
> - copied wl_keyboard to serve as the keyboard grab interface
>
> I hope you can help me find the remaining issues and turn this interface into reality!
>
> Cheers,
> Dorota Czaplejewicz
>
>  Makefile.am                                        |   1 +
>  unstable/input-method/input-method-unstable-v2.xml | 490 +++++++++++++++++++++
>  2 files changed, 491 insertions(+)
>  create mode 100644 unstable/input-method/input-method-unstable-v2.xml
>
> diff --git a/Makefile.am b/Makefile.am
> index 6394e26..f3b9f80 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -7,6 +7,7 @@ unstable_protocols =                                                            \
>         unstable/text-input/text-input-unstable-v1.xml                          \
>         unstable/text-input/text-input-unstable-v3.xml                          \
>         unstable/input-method/input-method-unstable-v1.xml                      \
> +       unstable/input-method/input-method-unstable-v2.xml                      \
>         unstable/xdg-shell/xdg-shell-unstable-v5.xml                            \
>         unstable/xdg-shell/xdg-shell-unstable-v6.xml                            \
>         unstable/relative-pointer/relative-pointer-unstable-v1.xml              \
> diff --git a/unstable/input-method/input-method-unstable-v2.xml b/unstable/input-method/input-method-unstable-v2.xml
> new file mode 100644
> index 0000000..62be9d9
> --- /dev/null
> +++ b/unstable/input-method/input-method-unstable-v2.xml
> @@ -0,0 +1,490 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="input_method_unstable_v2">
> +
> +  <copyright>
> +    Copyright © 2008-2011 Kristian Høgsberg
> +    Copyright © 2010-2011 Intel Corporation
> +    Copyright © 2012-2013 Collabora, Ltd.
> +    Copyright © 2012, 2013 Intel Corporation
> +    Copyright © 2015, 2016 Jan Arne Petersen
> +    Copyright © 2017, 2018 Red Hat, Inc.
> +    Copyright © 2018       Purism SPC
> +
> +    Permission is hereby granted, free of charge, to any person obtaining a
> +    copy of this software and associated documentation files (the "Software"),
> +    to deal in the Software without restriction, including without limitation
> +    the rights to use, copy, modify, merge, publish, distribute, sublicense,
> +    and/or sell copies of the Software, and to permit persons to whom the
> +    Software is furnished to do so, subject to the following conditions:
> +
> +    The above copyright notice and this permission notice (including the next
> +    paragraph) shall be included in all copies or substantial portions of the
> +    Software.
> +
> +    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
> +    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
> +    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
> +    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
> +    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
> +    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
> +    DEALINGS IN THE SOFTWARE.
> +  </copyright>
> +
> +  <description summary="Protocol for creating input methods">
> +    This protocol allows applications to act as input methods for compositors.
> +
> +    An input method context is used to manage the state of the input method.
> +
> +    Text strings are UTF-8 encoded, their indices and lengths are in bytes.
> +
> +    This document adheres to the RFC 2119 when using words like "must",
> +    "should", "may", etc.
> +
> +    Warning! The protocol described in this file is experimental and
> +    backward incompatible changes may be made. Backward compatible changes
> +    may be added together with the corresponding interface version bump.
> +    Backward incompatible changes are done by bumping the version number in
> +    the protocol and interface names and resetting the interface version.
> +    Once the protocol is to be declared stable, the 'z' prefix and the
> +    version number in the protocol and interface names are removed and the
> +    interface version number is reset.
> +  </description>
> +
> +  <interface name="zwp_input_method_v2" version="1">
> +    <description summary="input method">
> +      An input method object allows for clients to compose text.
> +
> +      The objects connects the client to a text input in an application, and
> +      lets the client to serve as an input method for a seat.
> +
> +      The zwp_input_method_v2 object can occupy two distinct states: active and
> +      inactive. In the active state, the object is associated to and
> +      communicates with a text input. In the inactive state, there is no
> +      associated text input, and the only communication is with the compositor.
> +      Initially, the input method is in the inactive state.
> +
> +      Requests issued in the inactive state must be accepted by the compositor.
> +      Because of the serial mechanism, and the state reset on activate event,
> +      they will not have any effect on the state of the next text input.
> +
> +      There must be no more than one input method object per seat.
> +    </description>
> +
> +    <event name="activate">
> +      <description summary="input method has been requested">
> +        Notification that a text input focused on this seat requested the input
> +        method to be activated.
> +
> +        This event serves the purpose of providing the compositor with an
> +        active input method.
> +
> +        This event resets all state associated with previous enable, disable,
> +        surrounding_text, text_change_cause, and content_type events, as well
> +        as the state associated with set_preedit_string, commit_string, and
> +        delete_surrounding_text requests. In addition, it marks the
> +        zwp_input_method_v2 object as active, and makes any existing
> +        zwp_input_popup_surface_v2 objects visible.
> +
> +        The surrounding_text, and content_type events must follow before the
> +        next done event if the text input supports the respective
> +        functionality.
> +
> +        State set with this event is double-buffered. It will get applied on
> +        the next zwp_input_method_v2.done event, and stay valid until changed.
> +      </description>
> +    </event>
> +
> +    <event name="deactivate">
> +      <description summary="deactivate event">
> +        Notification that no focused text input currently needs an active
> +        input method on this seat.
> +
> +        This event marks the zwp_input_method_v2 object as inactive. The
> +        compositor must make all existing zwp_input_popup_surface_v2 objects
> +        invisible until the next activate event.
> +
> +        State set with this event is double-buffered. It will get applied on
> +        the next zwp_input_method_v2.done event, and stay valid until changed.
> +      </description>
> +    </event>
> +
> +    <event name="surrounding_text">
> +      <description summary="surrounding text event">
> +        Updates the surrounding plain text around the cursor, excluding the
> +        preedit text.
> +
> +        If any preedit text is present, it is replaced with the cursor for the
> +        purpose of this event.
> +
> +        The argument text is a buffer containing the preedit string, and must
> +        include the cursor position, and the complete selection. It should
> +        contain additional characters before and after these. There is a
> +        maximum length of wayland messages, so text can not be longer than 4000
> +        bytes.
> +
> +        cursor is the byte offset of the cursor within the text buffer.
> +
> +        anchor is the byte offset of the selection anchor within the text
> +        buffer. If there is no selected text, anchor must be the same as
> +        cursor.
> +
> +        If this event does not arrive before the first done event, the input
> +        method may assume that the text input does not support this
> +        functionality and ignore following surrounding_text events.
> +
> +        Values set with this event are double-buffered. They will get applied
> +        and set to initial values on the next zwp_input_method_v2.done
> +        event.
> +
> +        The initial state for affected fields is empty, meaning that the text
> +        input does not support sending surrounding text. If the empty values
> +        get applied, subsequent attempts to change them may have no effect.
> +      </description>
> +      <arg name="text" type="string"/>
> +      <arg name="cursor" type="uint"/>
> +      <arg name="anchor" type="uint"/>
> +    </event>
> +
> +    <event name="text_change_cause">
> +      <description summary="indicates the cause of surrounding text change">
> +        Tells the input method why the text surrounding the cursor changed.
> +
> +        Whenever the client detects an external change in text, cursor, or
> +        anchor position, it must issue this request to the compositor. This
> +        request is intended to give the input method a chance to update the
> +        preedit text in an appropriate way, e.g. by removing it when the user
> +        starts typing with a keyboard.
> +
> +        cause describes the source of the change.
> +
> +        The value set with this event is double-buffered. It will get applied
> +        and set to its initial value on the next zwp_input_method_v2.done
> +        event.
> +
> +        The initial value of cause is input_method.
> +      </description>
> +      <arg name="cause" type="uint" enum="zwp_text_input_v3.change_cause"/>
> +    </event>
> +
> +    <event name="content_type">
> +      <description summary="content purpose and hint">
> +        Indicates the content type and hint for the current
> +        zwp_input_method_v2 instance.
> +
> +        Values set with this event are double-buffered. They will get applied
> +        on the next zwp_input_method_v2.done event.
> +
> +        The initial value for hint is none, and the initial value for purpose
> +        is normal.
> +      </description>
> +      <arg name="hint" type="uint" enum="zwp_text_input_v3.content_hint"/>
> +      <arg name="purpose" type="uint" enum="zwp_text_input_v3.content_purpose"/>
> +    </event>
> +
> +    <event name="done">
> +      <description summary="apply state">
> +        Atomically applies state changes recently sent to the client.
> +
> +        The done event establishes and updates the state of the client, and
> +        must be issued after any changes to apply them.
> +
> +        Text input state (content purpose, content hint, surrounding text, and
> +        change cause) is conceptually double-buffered within an input method
> +        context.
> +
> +        Events modify the pending state, as opposed to the current state in use
> +        by the input method. A done event atomically applies all pending state,
> +        replacing the current state. After done, the new pending state is as
> +        documented for each related request.
> +
> +        Events must be applied in the order of arrival.
> +
> +        Neither current nor pending state are modified unless noted otherwise.
> +      </description>
> +    </event>
> +
> +    <request name="commit_string">
> +      <description summary="commit string">
> +        Send the commit string text for insertion to the application.
> +
> +        Inserts a string at current cursor position (see commit event
> +        sequence). The string to commit could be either just a single character
> +        after a key press or the result of some composing.
> +
> +        The argument text is a buffer containing the string to insert. There is
> +        a maximum length of wayland messages, so text can not be longer than
> +        4000 bytes.
> +
> +        Values set with this event are double-buffered. They must be applied
> +        and reset to initial on the next zwp_text_input_v3.commit request.
> +
> +        The initial value of text is an empty string.
> +      </description>
> +      <arg name="text" type="string"/>
> +    </request>
> +
> +    <request name="set_preedit_string">
> +      <description summary="pre-edit string">
> +        Send the pre-edit string text to the application text input.
> +
> +        Place a new composing text (pre-edit) at the current cursor position.
> +        Any previously set composing text must be removed. Any previously
> +        existing selected text must be removed. The cursor is moved to a new
> +        position within the preedit string.
> +
> +        The argument text is a buffer containing the preedit string. There is
> +        a maximum length of wayland messages, so text can not be longer than
> +        4000 bytes.
> +
> +        The arguments cursor_begin and cursor_end are counted in bytes relative
> +        to the beginning of the submitted string buffer. Cursor should be
> +        hidden by the text input when both are equal to -1.
> +
> +        cursor_begin indicates the beginning of the cursor. cursor_end
> +        indicates the end of the cursor. It may be equal or different than
> +        cursor_begin.
> +
> +        Values set with this event are double-buffered. They must be applied on
> +        the next zwp_input_method_v2.commit event.
> +
> +        The initial value of text is an empty string. The initial value of
> +        cursor_begin, and cursor_end are both 0.
> +      </description>
> +      <arg name="text" type="string"/>
> +      <arg name="cursor_begin" type="int"/>
> +      <arg name="cursor_end" type="int"/>
> +    </request>
> +
> +    <request name="delete_surrounding_text">
> +      <description summary="delete text">
> +        Remove the surrounding text.
> +
> +        before_length and after_length are the number of bytes before and after
> +        the current cursor index (excluding the preedit text) to delete.
> +
> +        If any preedit text is present, it is replaced with the cursor for the
> +        purpose of this event. In effect before_length is counted from the
> +        beginning of preedit text, and after_length from its end (see commit
> +        event sequence).
> +
> +        Values set with this event are double-buffered. They must be applied
> +        and reset to initial on the next zwp_input_method_v2.commit request.
> +
> +        The initial values of both before_length and after_length are 0.
> +      </description>
> +      <arg name="before_length" type="uint"/>
> +      <arg name="after_length" type="uint"/>
> +    </request>
> +
> +    <request name="commit">
> +      <description summary="apply state">
> +        Apply state changes from commit_string, set_preedit_string and
> +        delete_surrounding_text requests.
> +
> +        The state relating to these events is double-buffered, and each one
> +        modifies the pending state. This request replaces the current state
> +        with the pending state.
> +
> +        The connected text input is expected to proceed by evaluating the
> +        changes in the following order:
> +
> +        1. Replace existing preedit string with the cursor.
> +        2. Delete requested surrounding text.
> +        3. Insert commit string with the cursor at its end.
> +        4. Calculate surrounding text to send.
> +        5. Insert new preedit text in cursor position.
> +        6. Place cursor inside preedit text.
> +
> +        The serial number reflects the last state of the zwp_input_method_v2
> +        object known to the client. The value of the serial argument must be
> +        equal to the number of done events already issued by that object. When
> +        the compositor receives a commit request with a serial different than
> +        the number of past done events, it must proceed as normal, except it
> +        should not change the current state of the zwp_input_method_v2 object.
> +      </description>
> +      <arg name="serial" type="uint"/>
> +    </request>
> +
> +    <request name="get_input_popup_surface">
> +      <description summary="create popup surface">
> +        Creates a new zwp_input_popup_surface_v2 object wrapping a given
> +        surface.
> +
> +        The surface gets assigned the "input_popup" role. If the surface
> +        already has an assigned role, the compositor must issue a protocol
> +        error.
> +      </description>
> +      <arg name="id" type="new_id" interface="zwp_input_popup_surface_v2"/>
> +      <arg name="surface" type="object" interface="wl_surface"/>
> +    </request>
> +
> +    <request name="grab_keyboard">
> +      <description summary="grab hardware keyboard">
> +        Allow an input method to receive hardware keyboard input and process
> +        key events to generate text events (with pre-edit) over the wire. This
> +        allows input methods which compose multiple key events for inputting
> +        text like it is done for CJK languages.
> +
> +        The compositor should send all keyboard events on the seat to the grab
> +        holder via the returned wl_keyboard object. Nevertheless, the
> +        compositor may decide not to forward any particular event. The
> +        compositor must not further process any event after it has been
> +        forwarded to the grab holder.
> +
> +        Releasing the resulting wl_keyboard object releases the grab.
> +      </description>
> +      <arg name="keyboard" type="new_id"
> +        interface="zwp_input_method_keyboard_grab_v2"/>
> +    </request>
> +
> +    <event name="unavailable">
> +      <description summary="input method unavailable">
> +        The input method ceased to be available.
> +
> +        The compositor must issue this event as the only event on the object if
> +        there was another input_method object associated with the same seat at
> +        the time of its creation.
> +
> +        The compositor must issue this request when the object is no longer
> +        useable, e.g. due to seat removal.
> +
> +        The input method context becomes inert and should be destroyed after
> +        deactivation is handled. Any further requests and events except for the
> +        destroy request must be ignored.
> +      </description>
> +    </event>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the text input">
> +        Destroys the zwp_text_input_v2 object and any associated child
> +        objects, i.e. zwp_input_popup_surface_v2 and
> +        zwp_input_method_keyboard_grab_v2.
> +      </description>
> +    </request>
> +  </interface>
> +
> +  <interface name="zwp_input_popup_surface_v2" version="1">
> +    <description summary="popup surface">
> +      This interface marks a surface as a popup for interacting with an input
> +      method.
> +
> +      The compositor should place it near the active text input area. It must
> +      be visible if and only if the input method is in the active state.
> +
> +      The client must not destroy the underlying wl_surface while the
> +      zwp_input_popup_surface_v2 object exists.
> +    </description>
> +
> +    <event name="text_input_rectangle">
> +      <description summary="set text input area position">
> +        Notify about the position of the area of the text input expressed as a
> +        rectangle in surface local coordinates.
> +
> +        This is a hint to the input method telling it the relative position of
> +        the text being entered.
> +      </description>
> +      <arg name="x" type="int"/>
> +      <arg name="y" type="int"/>
> +      <arg name="width" type="int"/>
> +      <arg name="height" type="int"/>
> +    </event>
> +
> +    <request name="destroy" type="destructor"/>
> +  </interface>
> +
> +  <interface name="zwp_input_method_keyboard_grab_v2" version="1">
> +    <!-- Closely follows wl_keyboard version 6 -->
> +    <description summary="keyboard grab">
> +      The zwp_input_method_keyboard_grab_v2 interface represents an exclusive
> +      grab of the wl_keyboard interface associated with the seat.
> +    </description>
> +
> +    <event name="keymap">
> +      <description summary="keyboard mapping">
> +        This event provides a file descriptor to the client which can be
> +        memory-mapped to provide a keyboard mapping description.
> +      </description>
> +      <arg name="format" type="uint" enum="wl_keyboard.keymap_format"
> +        summary="keymap format"/>
> +      <arg name="fd" type="fd" summary="keymap file descriptor"/>
> +      <arg name="size" type="uint" summary="keymap size, in bytes"/>
> +    </event>
> +
> +    <event name="key">
> +      <description summary="key event">
> +        A key was pressed or released.
> +        The time argument is a timestamp with millisecond granularity, with an
> +        undefined base.
> +      </description>
> +      <arg name="serial" type="uint" summary="serial number of the key event"/>
> +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
> +      <arg name="key" type="uint" summary="key that produced the event"/>
> +      <arg name="state" type="uint" enum="wl_keyboard.key_state"
> +        summary="physical state of the key"/>
> +    </event>
> +
> +    <event name="modifiers">
> +      <description summary="modifier and group state">
> +        Notifies clients that the modifier and/or group state has changed, and
> +        it should update its local state.
> +      </description>
> +      <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
> +      <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
> +      <arg name="mods_latched" type="uint" summary="latched modifiers"/>
> +      <arg name="mods_locked" type="uint" summary="locked modifiers"/>
> +      <arg name="group" type="uint" summary="keyboard layout"/>
> +    </event>
> +
> +    <request name="release" type="destructor">
> +      <description summary="release the grab object"/>
> +    </request>
> +
> +    <event name="repeat_info">
> +      <description summary="repeat rate and delay">
> +        Informs the client about the keyboard's repeat rate and delay.
> +
> +        This event is sent as soon as the zwp_input_method_keyboard_grab_v2
> +        object has been created, and is guaranteed to be received by the
> +        client before any key press event.
> +
> +        Negative values for either rate or delay are illegal. A rate of zero
> +        will disable any repeating (regardless of the value of delay).
> +
> +        This event can be sent later on as well with a new value if necessary,
> +        so clients should continue listening for the event past the creation
> +        of zwp_input_method_keyboard_grab_v2.
> +      </description>
> +      <arg name="rate" type="int"
> +          summary="the rate of repeating keys in characters per second"/>
> +      <arg name="delay" type="int"
> +          summary="delay in milliseconds since key down until repeating starts"/>
> +    </event>
> +  </interface>
> +
> +  <interface name="zwp_input_method_manager_v2" version="1">
> +    <description summary="input method manager">
> +      The input method manager allows the client to become the input method on
> +      a chosen seat.
> +
> +      No more than one input method must be associated with any seat at any
> +      given time.
> +    </description>
> +
> +    <request name="get_input_method">
> +      <description summary="request an input method object">
> +        Request a new input zwp_input_method_v2 object associated with a given
> +        seat.
> +      </description>
> +      <arg name="seat" type="object" interface="wl_seat"/>
> +      <arg name="input_method" type="new_id" interface="zwp_input_method_v2"/>
> +    </request>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the input method manager">
> +        Destroys the zwp_input_method_manager_v2 object.
> +
> +        The zwp_input_method_v2 objects originating from it remain valid.
> +      </description>
> +    </request>
> +  </interface>
> +</protocol>
> --
> 2.14.4
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Dorota Czaplejewicz Nov. 9, 2018, 5:40 p.m.
Hi Roman,

I've been shown your KWin work last week - thanks for picking it up!

The tested parts of input_method_v2 are the parts which text-input-v3 is using [0]. There's an application [1] and a compositor [0] with examples [2,3] that you can use for verifying the KWin implementation. I think they are well-tested, but that may just mean I haven't seen 80% of the problems.

The untested-in-practice parts are about popups and keyboard grabs.

I hope this can help you.

Cheers,
Dorota Czaplejewicz

[0] https://github.com/swaywm/wlroots/pull/1203
[1] https://source.puri.sm/Librem5/virtboard
[2] https://github.com/swaywm/wlroots/blob/master/examples/input-method.c
[3] https://github.com/swaywm/wlroots/blob/master/examples/text-input.c

On Fri, 9 Nov 2018 18:26:18 +0100
Roman Gilg <subdiff@gmail.com> wrote:

> Hi,
> 
> what's the current state of this patch?
> 
> I have a KWin patch up for review to implement the text-input v3
> protocol, so I would be interested in pushing forward the input_method
> v2 here.
> 
> If there are already some test applications speaking both ends of the
> pipeline I could try it out in KWin.
> 
> Cheers
> On Thu, Oct 4, 2018 at 10:01 PM Dorota Czaplejewicz
> <dorota.czaplejewicz@puri.sm> wrote:
> >
> > This protocol is based on v1, current text-input-v3, and wl_keyboard version 6.
> >
> > The pieces passing data relevant to the application on the other side of the compositor are a mirror copy of text-input-v3 events and requests.
> >
> > Compared to input-method-v1:
> > - assumes that once preedit is displayed, no selection can be active, removing some selection handling
> > - follow text-input and removes language indicators
> > - explicitly attaches to seats
> > - removes "commit" text which would replace the preedit string automatically in case it wasn't "confirmed" (whatever it means)
> > - adds double-buffering in the same places as text-input-v3
> > - drops input_method_context and places its functionality directly in input_method
> > - removes the ability to move the cursor position outside of preedit. It still allows to delete a larger chunk of text and replace it with a preedit
> > - doesn't allow for sending of keyboard events to the compositor
> > - doesn't define any surfaces except for a special compositor-positioned popup
> > ---
> > Hi,
> >
> > continuing the RFC, I think this protocol is actually workable now, and I'm sending this with the PATCH qualifier.
> >
> > The practical verification came in the form of a partial wlroots implementation [0]. The formal issues (chiefly stemming from copy-pasting things at night) have been pointed out to me by Simon, and corrected.
> >
> > The major unverified parts are keyboard grabs and popup surfaces, which I will verify next.
> >
> > Changes compared to the RFC:
> >
> > - fixed so many confusing typos
> > - renamed preedit_text request to set_preedit_text
> > - described what happens when things get destroyed
> > - defined the role of input_popup sorface and forbade it from being deleted
> > - copied wl_keyboard to serve as the keyboard grab interface
> >
> > I hope you can help me find the remaining issues and turn this interface into reality!
> >
> > Cheers,
> > Dorota Czaplejewicz
> >
> >  Makefile.am                                        |   1 +
> >  unstable/input-method/input-method-unstable-v2.xml | 490 +++++++++++++++++++++
> >  2 files changed, 491 insertions(+)
> >  create mode 100644 unstable/input-method/input-method-unstable-v2.xml
> >
> > diff --git a/Makefile.am b/Makefile.am
> > index 6394e26..f3b9f80 100644
> > --- a/Makefile.am
> > +++ b/Makefile.am
> > @@ -7,6 +7,7 @@ unstable_protocols =                                                            \
> >         unstable/text-input/text-input-unstable-v1.xml                          \
> >         unstable/text-input/text-input-unstable-v3.xml                          \
> >         unstable/input-method/input-method-unstable-v1.xml                      \
> > +       unstable/input-method/input-method-unstable-v2.xml                      \
> >         unstable/xdg-shell/xdg-shell-unstable-v5.xml                            \
> >         unstable/xdg-shell/xdg-shell-unstable-v6.xml                            \
> >         unstable/relative-pointer/relative-pointer-unstable-v1.xml              \
> > diff --git a/unstable/input-method/input-method-unstable-v2.xml b/unstable/input-method/input-method-unstable-v2.xml
> > new file mode 100644
> > index 0000000..62be9d9
> > --- /dev/null
> > +++ b/unstable/input-method/input-method-unstable-v2.xml
> > @@ -0,0 +1,490 @@
> > +<?xml version="1.0" encoding="UTF-8"?>
> > +<protocol name="input_method_unstable_v2">
> > +
> > +  <copyright>
> > +    Copyright © 2008-2011 Kristian Høgsberg
> > +    Copyright © 2010-2011 Intel Corporation
> > +    Copyright © 2012-2013 Collabora, Ltd.
> > +    Copyright © 2012, 2013 Intel Corporation
> > +    Copyright © 2015, 2016 Jan Arne Petersen
> > +    Copyright © 2017, 2018 Red Hat, Inc.
> > +    Copyright © 2018       Purism SPC
> > +
> > +    Permission is hereby granted, free of charge, to any person obtaining a
> > +    copy of this software and associated documentation files (the "Software"),
> > +    to deal in the Software without restriction, including without limitation
> > +    the rights to use, copy, modify, merge, publish, distribute, sublicense,
> > +    and/or sell copies of the Software, and to permit persons to whom the
> > +    Software is furnished to do so, subject to the following conditions:
> > +
> > +    The above copyright notice and this permission notice (including the next
> > +    paragraph) shall be included in all copies or substantial portions of the
> > +    Software.
> > +
> > +    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
> > +    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
> > +    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
> > +    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
> > +    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
> > +    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
> > +    DEALINGS IN THE SOFTWARE.
> > +  </copyright>
> > +
> > +  <description summary="Protocol for creating input methods">
> > +    This protocol allows applications to act as input methods for compositors.
> > +
> > +    An input method context is used to manage the state of the input method.
> > +
> > +    Text strings are UTF-8 encoded, their indices and lengths are in bytes.
> > +
> > +    This document adheres to the RFC 2119 when using words like "must",
> > +    "should", "may", etc.
> > +
> > +    Warning! The protocol described in this file is experimental and
> > +    backward incompatible changes may be made. Backward compatible changes
> > +    may be added together with the corresponding interface version bump.
> > +    Backward incompatible changes are done by bumping the version number in
> > +    the protocol and interface names and resetting the interface version.
> > +    Once the protocol is to be declared stable, the 'z' prefix and the
> > +    version number in the protocol and interface names are removed and the
> > +    interface version number is reset.
> > +  </description>
> > +
> > +  <interface name="zwp_input_method_v2" version="1">
> > +    <description summary="input method">
> > +      An input method object allows for clients to compose text.
> > +
> > +      The objects connects the client to a text input in an application, and
> > +      lets the client to serve as an input method for a seat.
> > +
> > +      The zwp_input_method_v2 object can occupy two distinct states: active and
> > +      inactive. In the active state, the object is associated to and
> > +      communicates with a text input. In the inactive state, there is no
> > +      associated text input, and the only communication is with the compositor.
> > +      Initially, the input method is in the inactive state.
> > +
> > +      Requests issued in the inactive state must be accepted by the compositor.
> > +      Because of the serial mechanism, and the state reset on activate event,
> > +      they will not have any effect on the state of the next text input.
> > +
> > +      There must be no more than one input method object per seat.
> > +    </description>
> > +
> > +    <event name="activate">
> > +      <description summary="input method has been requested">
> > +        Notification that a text input focused on this seat requested the input
> > +        method to be activated.
> > +
> > +        This event serves the purpose of providing the compositor with an
> > +        active input method.
> > +
> > +        This event resets all state associated with previous enable, disable,
> > +        surrounding_text, text_change_cause, and content_type events, as well
> > +        as the state associated with set_preedit_string, commit_string, and
> > +        delete_surrounding_text requests. In addition, it marks the
> > +        zwp_input_method_v2 object as active, and makes any existing
> > +        zwp_input_popup_surface_v2 objects visible.
> > +
> > +        The surrounding_text, and content_type events must follow before the
> > +        next done event if the text input supports the respective
> > +        functionality.
> > +
> > +        State set with this event is double-buffered. It will get applied on
> > +        the next zwp_input_method_v2.done event, and stay valid until changed.
> > +      </description>
> > +    </event>
> > +
> > +    <event name="deactivate">
> > +      <description summary="deactivate event">
> > +        Notification that no focused text input currently needs an active
> > +        input method on this seat.
> > +
> > +        This event marks the zwp_input_method_v2 object as inactive. The
> > +        compositor must make all existing zwp_input_popup_surface_v2 objects
> > +        invisible until the next activate event.
> > +
> > +        State set with this event is double-buffered. It will get applied on
> > +        the next zwp_input_method_v2.done event, and stay valid until changed.
> > +      </description>
> > +    </event>
> > +
> > +    <event name="surrounding_text">
> > +      <description summary="surrounding text event">
> > +        Updates the surrounding plain text around the cursor, excluding the
> > +        preedit text.
> > +
> > +        If any preedit text is present, it is replaced with the cursor for the
> > +        purpose of this event.
> > +
> > +        The argument text is a buffer containing the preedit string, and must
> > +        include the cursor position, and the complete selection. It should
> > +        contain additional characters before and after these. There is a
> > +        maximum length of wayland messages, so text can not be longer than 4000
> > +        bytes.
> > +
> > +        cursor is the byte offset of the cursor within the text buffer.
> > +
> > +        anchor is the byte offset of the selection anchor within the text
> > +        buffer. If there is no selected text, anchor must be the same as
> > +        cursor.
> > +
> > +        If this event does not arrive before the first done event, the input
> > +        method may assume that the text input does not support this
> > +        functionality and ignore following surrounding_text events.
> > +
> > +        Values set with this event are double-buffered. They will get applied
> > +        and set to initial values on the next zwp_input_method_v2.done
> > +        event.
> > +
> > +        The initial state for affected fields is empty, meaning that the text
> > +        input does not support sending surrounding text. If the empty values
> > +        get applied, subsequent attempts to change them may have no effect.
> > +      </description>
> > +      <arg name="text" type="string"/>
> > +      <arg name="cursor" type="uint"/>
> > +      <arg name="anchor" type="uint"/>
> > +    </event>
> > +
> > +    <event name="text_change_cause">
> > +      <description summary="indicates the cause of surrounding text change">
> > +        Tells the input method why the text surrounding the cursor changed.
> > +
> > +        Whenever the client detects an external change in text, cursor, or
> > +        anchor position, it must issue this request to the compositor. This
> > +        request is intended to give the input method a chance to update the
> > +        preedit text in an appropriate way, e.g. by removing it when the user
> > +        starts typing with a keyboard.
> > +
> > +        cause describes the source of the change.
> > +
> > +        The value set with this event is double-buffered. It will get applied
> > +        and set to its initial value on the next zwp_input_method_v2.done
> > +        event.
> > +
> > +        The initial value of cause is input_method.
> > +      </description>
> > +      <arg name="cause" type="uint" enum="zwp_text_input_v3.change_cause"/>
> > +    </event>
> > +
> > +    <event name="content_type">
> > +      <description summary="content purpose and hint">
> > +        Indicates the content type and hint for the current
> > +        zwp_input_method_v2 instance.
> > +
> > +        Values set with this event are double-buffered. They will get applied
> > +        on the next zwp_input_method_v2.done event.
> > +
> > +        The initial value for hint is none, and the initial value for purpose
> > +        is normal.
> > +      </description>
> > +      <arg name="hint" type="uint" enum="zwp_text_input_v3.content_hint"/>
> > +      <arg name="purpose" type="uint" enum="zwp_text_input_v3.content_purpose"/>
> > +    </event>
> > +
> > +    <event name="done">
> > +      <description summary="apply state">
> > +        Atomically applies state changes recently sent to the client.
> > +
> > +        The done event establishes and updates the state of the client, and
> > +        must be issued after any changes to apply them.
> > +
> > +        Text input state (content purpose, content hint, surrounding text, and
> > +        change cause) is conceptually double-buffered within an input method
> > +        context.
> > +
> > +        Events modify the pending state, as opposed to the current state in use
> > +        by the input method. A done event atomically applies all pending state,
> > +        replacing the current state. After done, the new pending state is as
> > +        documented for each related request.
> > +
> > +        Events must be applied in the order of arrival.
> > +
> > +        Neither current nor pending state are modified unless noted otherwise.
> > +      </description>
> > +    </event>
> > +
> > +    <request name="commit_string">
> > +      <description summary="commit string">
> > +        Send the commit string text for insertion to the application.
> > +
> > +        Inserts a string at current cursor position (see commit event
> > +        sequence). The string to commit could be either just a single character
> > +        after a key press or the result of some composing.
> > +
> > +        The argument text is a buffer containing the string to insert. There is
> > +        a maximum length of wayland messages, so text can not be longer than
> > +        4000 bytes.
> > +
> > +        Values set with this event are double-buffered. They must be applied
> > +        and reset to initial on the next zwp_text_input_v3.commit request.
> > +
> > +        The initial value of text is an empty string.
> > +      </description>
> > +      <arg name="text" type="string"/>
> > +    </request>
> > +
> > +    <request name="set_preedit_string">
> > +      <description summary="pre-edit string">
> > +        Send the pre-edit string text to the application text input.
> > +
> > +        Place a new composing text (pre-edit) at the current cursor position.
> > +        Any previously set composing text must be removed. Any previously
> > +        existing selected text must be removed. The cursor is moved to a new
> > +        position within the preedit string.
> > +
> > +        The argument text is a buffer containing the preedit string. There is
> > +        a maximum length of wayland messages, so text can not be longer than
> > +        4000 bytes.
> > +
> > +        The arguments cursor_begin and cursor_end are counted in bytes relative
> > +        to the beginning of the submitted string buffer. Cursor should be
> > +        hidden by the text input when both are equal to -1.
> > +
> > +        cursor_begin indicates the beginning of the cursor. cursor_end
> > +        indicates the end of the cursor. It may be equal or different than
> > +        cursor_begin.
> > +
> > +        Values set with this event are double-buffered. They must be applied on
> > +        the next zwp_input_method_v2.commit event.
> > +
> > +        The initial value of text is an empty string. The initial value of
> > +        cursor_begin, and cursor_end are both 0.
> > +      </description>
> > +      <arg name="text" type="string"/>
> > +      <arg name="cursor_begin" type="int"/>
> > +      <arg name="cursor_end" type="int"/>
> > +    </request>
> > +
> > +    <request name="delete_surrounding_text">
> > +      <description summary="delete text">
> > +        Remove the surrounding text.
> > +
> > +        before_length and after_length are the number of bytes before and after
> > +        the current cursor index (excluding the preedit text) to delete.
> > +
> > +        If any preedit text is present, it is replaced with the cursor for the
> > +        purpose of this event. In effect before_length is counted from the
> > +        beginning of preedit text, and after_length from its end (see commit
> > +        event sequence).
> > +
> > +        Values set with this event are double-buffered. They must be applied
> > +        and reset to initial on the next zwp_input_method_v2.commit request.
> > +
> > +        The initial values of both before_length and after_length are 0.
> > +      </description>
> > +      <arg name="before_length" type="uint"/>
> > +      <arg name="after_length" type="uint"/>
> > +    </request>
> > +
> > +    <request name="commit">
> > +      <description summary="apply state">
> > +        Apply state changes from commit_string, set_preedit_string and
> > +        delete_surrounding_text requests.
> > +
> > +        The state relating to these events is double-buffered, and each one
> > +        modifies the pending state. This request replaces the current state
> > +        with the pending state.
> > +
> > +        The connected text input is expected to proceed by evaluating the
> > +        changes in the following order:
> > +
> > +        1. Replace existing preedit string with the cursor.
> > +        2. Delete requested surrounding text.
> > +        3. Insert commit string with the cursor at its end.
> > +        4. Calculate surrounding text to send.
> > +        5. Insert new preedit text in cursor position.
> > +        6. Place cursor inside preedit text.
> > +
> > +        The serial number reflects the last state of the zwp_input_method_v2
> > +        object known to the client. The value of the serial argument must be
> > +        equal to the number of done events already issued by that object. When
> > +        the compositor receives a commit request with a serial different than
> > +        the number of past done events, it must proceed as normal, except it
> > +        should not change the current state of the zwp_input_method_v2 object.
> > +      </description>
> > +      <arg name="serial" type="uint"/>
> > +    </request>
> > +
> > +    <request name="get_input_popup_surface">
> > +      <description summary="create popup surface">
> > +        Creates a new zwp_input_popup_surface_v2 object wrapping a given
> > +        surface.
> > +
> > +        The surface gets assigned the "input_popup" role. If the surface
> > +        already has an assigned role, the compositor must issue a protocol
> > +        error.
> > +      </description>
> > +      <arg name="id" type="new_id" interface="zwp_input_popup_surface_v2"/>
> > +      <arg name="surface" type="object" interface="wl_surface"/>
> > +    </request>
> > +
> > +    <request name="grab_keyboard">
> > +      <description summary="grab hardware keyboard">
> > +        Allow an input method to receive hardware keyboard input and process
> > +        key events to generate text events (with pre-edit) over the wire. This
> > +        allows input methods which compose multiple key events for inputting
> > +        text like it is done for CJK languages.
> > +
> > +        The compositor should send all keyboard events on the seat to the grab
> > +        holder via the returned wl_keyboard object. Nevertheless, the
> > +        compositor may decide not to forward any particular event. The
> > +        compositor must not further process any event after it has been
> > +        forwarded to the grab holder.
> > +
> > +        Releasing the resulting wl_keyboard object releases the grab.
> > +      </description>
> > +      <arg name="keyboard" type="new_id"
> > +        interface="zwp_input_method_keyboard_grab_v2"/>
> > +    </request>
> > +
> > +    <event name="unavailable">
> > +      <description summary="input method unavailable">
> > +        The input method ceased to be available.
> > +
> > +        The compositor must issue this event as the only event on the object if
> > +        there was another input_method object associated with the same seat at
> > +        the time of its creation.
> > +
> > +        The compositor must issue this request when the object is no longer
> > +        useable, e.g. due to seat removal.
> > +
> > +        The input method context becomes inert and should be destroyed after
> > +        deactivation is handled. Any further requests and events except for the
> > +        destroy request must be ignored.
> > +      </description>
> > +    </event>
> > +
> > +    <request name="destroy" type="destructor">
> > +      <description summary="destroy the text input">
> > +        Destroys the zwp_text_input_v2 object and any associated child
> > +        objects, i.e. zwp_input_popup_surface_v2 and
> > +        zwp_input_method_keyboard_grab_v2.
> > +      </description>
> > +    </request>
> > +  </interface>
> > +
> > +  <interface name="zwp_input_popup_surface_v2" version="1">
> > +    <description summary="popup surface">
> > +      This interface marks a surface as a popup for interacting with an input
> > +      method.
> > +
> > +      The compositor should place it near the active text input area. It must
> > +      be visible if and only if the input method is in the active state.
> > +
> > +      The client must not destroy the underlying wl_surface while the
> > +      zwp_input_popup_surface_v2 object exists.
> > +    </description>
> > +
> > +    <event name="text_input_rectangle">
> > +      <description summary="set text input area position">
> > +        Notify about the position of the area of the text input expressed as a
> > +        rectangle in surface local coordinates.
> > +
> > +        This is a hint to the input method telling it the relative position of
> > +        the text being entered.
> > +      </description>
> > +      <arg name="x" type="int"/>
> > +      <arg name="y" type="int"/>
> > +      <arg name="width" type="int"/>
> > +      <arg name="height" type="int"/>
> > +    </event>
> > +
> > +    <request name="destroy" type="destructor"/>
> > +  </interface>
> > +
> > +  <interface name="zwp_input_method_keyboard_grab_v2" version="1">
> > +    <!-- Closely follows wl_keyboard version 6 -->
> > +    <description summary="keyboard grab">
> > +      The zwp_input_method_keyboard_grab_v2 interface represents an exclusive
> > +      grab of the wl_keyboard interface associated with the seat.
> > +    </description>
> > +
> > +    <event name="keymap">
> > +      <description summary="keyboard mapping">
> > +        This event provides a file descriptor to the client which can be
> > +        memory-mapped to provide a keyboard mapping description.
> > +      </description>
> > +      <arg name="format" type="uint" enum="wl_keyboard.keymap_format"
> > +        summary="keymap format"/>
> > +      <arg name="fd" type="fd" summary="keymap file descriptor"/>
> > +      <arg name="size" type="uint" summary="keymap size, in bytes"/>
> > +    </event>
> > +
> > +    <event name="key">
> > +      <description summary="key event">
> > +        A key was pressed or released.
> > +        The time argument is a timestamp with millisecond granularity, with an
> > +        undefined base.
> > +      </description>
> > +      <arg name="serial" type="uint" summary="serial number of the key event"/>
> > +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
> > +      <arg name="key" type="uint" summary="key that produced the event"/>
> > +      <arg name="state" type="uint" enum="wl_keyboard.key_state"
> > +        summary="physical state of the key"/>
> > +    </event>
> > +
> > +    <event name="modifiers">
> > +      <description summary="modifier and group state">
> > +        Notifies clients that the modifier and/or group state has changed, and
> > +        it should update its local state.
> > +      </description>
> > +      <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
> > +      <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
> > +      <arg name="mods_latched" type="uint" summary="latched modifiers"/>
> > +      <arg name="mods_locked" type="uint" summary="locked modifiers"/>
> > +      <arg name="group" type="uint" summary="keyboard layout"/>
> > +    </event>
> > +
> > +    <request name="release" type="destructor">
> > +      <description summary="release the grab object"/>
> > +    </request>
> > +
> > +    <event name="repeat_info">
> > +      <description summary="repeat rate and delay">
> > +        Informs the client about the keyboard's repeat rate and delay.
> > +
> > +        This event is sent as soon as the zwp_input_method_keyboard_grab_v2
> > +        object has been created, and is guaranteed to be received by the
> > +        client before any key press event.
> > +
> > +        Negative values for either rate or delay are illegal. A rate of zero
> > +        will disable any repeating (regardless of the value of delay).
> > +
> > +        This event can be sent later on as well with a new value if necessary,
> > +        so clients should continue listening for the event past the creation
> > +        of zwp_input_method_keyboard_grab_v2.
> > +      </description>
> > +      <arg name="rate" type="int"
> > +          summary="the rate of repeating keys in characters per second"/>
> > +      <arg name="delay" type="int"
> > +          summary="delay in milliseconds since key down until repeating starts"/>
> > +    </event>
> > +  </interface>
> > +
> > +  <interface name="zwp_input_method_manager_v2" version="1">
> > +    <description summary="input method manager">
> > +      The input method manager allows the client to become the input method on
> > +      a chosen seat.
> > +
> > +      No more than one input method must be associated with any seat at any
> > +      given time.
> > +    </description>
> > +
> > +    <request name="get_input_method">
> > +      <description summary="request an input method object">
> > +        Request a new input zwp_input_method_v2 object associated with a given
> > +        seat.
> > +      </description>
> > +      <arg name="seat" type="object" interface="wl_seat"/>
> > +      <arg name="input_method" type="new_id" interface="zwp_input_method_v2"/>
> > +    </request>
> > +
> > +    <request name="destroy" type="destructor">
> > +      <description summary="destroy the input method manager">
> > +        Destroys the zwp_input_method_manager_v2 object.
> > +
> > +        The zwp_input_method_v2 objects originating from it remain valid.
> > +      </description>
> > +    </request>
> > +  </interface>
> > +</protocol>
> > --
> > 2.14.4
> >
> > _______________________________________________
> > wayland-devel mailing list
> > wayland-devel@lists.freedesktop.org
> > https://lists.freedesktop.org/mailman/listinfo/wayland-devel