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

Simon Ser contact at emersion.fr
Fri Sep 7 11:54:36 UTC 2018


On 6 August 2018 3:00 PM, Dorota Czaplejewicz <dorota.czaplejewicz at puri.sm> wrote:
> This protocol is based on v1, and current text-input-v3.
>
> 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,
>
> the third item on the path to well-supported virtual keyboard experience under
> Wayland comes from Purism. This one allows the compositor to delegate text
> input and composition duties to an application instead of handling it itself.
> Input-method-delegating compositor would typically become only a broker
> between the input method client and other applications.
>
> I took the existing input-method protocol, and after dissecting it with the
> help of wlroots developers, I came up with an improved version, which is
> attached for your (re)viewing pleasure.
>
> A large part of this protocol was taken from recent text-input-v3, and some
> description text was improved. Still, the protocol has a couple of rough
> edges, which is why it's titled RFC and not a patch.
>
> The issues I have had most trouble with are related to the handling of
> keyboard grabs. These are meant to allow traditional, keyboard-based input
> methods, to take over keyboard input in order to compose text in a different
> way.
>
> First, keyboard grabs are defined as unreliable. I'm not sure whether this is
> the right choice, but given that making them more reliable seems rather
> complicated, this is the default one.
>
> In addition, handling the keyboard events themselves is troublesome, because
> an input method, even if it has a surface, is not meant to have keyboard focus
> while it's in operation. Returning wl_keyboard as new_id seems not to be
> possible due to versioning. Should the request make an existing wl_keyboard
> instance change behaviour? Or perhaps there should be a new
> zwp_input_method_keyboard mimicking the wl_keyboard interface?
>
> I'm interested in your opinions.
>
> Thank you,
> Dorota Czaplejewicz

Thansk for your RFC!

>  Makefile.am                                        |   1 +
>  unstable/input-method/input-method-unstable-v2.xml | 403 +++++++++++++++++++++
>  2 files changed, 404 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..8cf8e29
> --- /dev/null
> +++ b/unstable/input-method/input-method-unstable-v2.xml
> @@ -0,0 +1,403 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="input_method_unstable_v2">
> +
> +  <copyright>
> +    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.
> +

Nit: there's trailing whitespace here (there are more of these below too).

> +    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 request must be issued every time a text input requests an input
> +        method.

s/request/event/ (also applies to below)

Can a compositor reject a text input request? If so, maybe replacing "must" with
"will" would soften the requirements.

> +        This request resets all state associated with previous enable, disable,
> +        set_surrounding_text, set_text_change_cause, set_content_type, and
> +        set_cursor_rectangle requests, as well as the state associated with
> +        preedit_string, commit_string, and delete_surrounding_text events. In
> +        addition, it marks the input method object as active.
> +
> +        The set_surrounding_text, set_content_type and set_cursor_rectangle
> +        requests 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 this seat's current text input requested the input
> +        method to be deactivated.
> +
> +        This event mrks the zwp_input_method_v2 object as inactive.
> +
> +        When the seat has the keyboard capability the text-input focus follows
> +        the keyboard focus.
> +
> +        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">
> +        Sets 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 request 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 posision, 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
> +        input_method_context 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.done event.

It would probably be better to mention the commit request here, rather than the
done event.

> +        The initial value of text is an empty string.
> +      </description>
> +      <arg name="text" type="string"/>
> +    </request>
> +
> +    <request name="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, 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 commit requests already issued on that object.
> +        When the compositor receives a done event with a serial different than

The compositor sends events, so it won't receive a done event. Is it a text
input serial?

> +        the number of past commit requests, it must proceed as normal, except
> +        it should not change the current state of the zwp_input_method_v2
> +        object.

I'm not sure I understand the purpose of serials here. The compositor can count
the number of incoming commit requests itself. What happens if the client sends
an invalid serial?

> +      </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.
> +      </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="wl_keyboard"/>

So noted above, this is not possible due to interface versioning. I'm not sure
it's possible to use an existing keyboard instead, because keyboard focus is
generally bound to a surface (see the enter/leave events).

What are the requirements here? Do we need to send a keymap? If most of
wl_keyboard is irrelevant here, it would probably be better to add a new
interface.

> +    </request>
> +
> +    <event name="unavailable">
> +      <description summray="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"/>

This should include details about what happens to objects created via this
interface.

> +  </interface>
> +
> +  <interface name="zwp_input_popup_surface_v2" version="1">
> +    <description summary="popup surface">
> +      This surface is a popup for interacting with an input method.

Does this give a role to the wl_surface? (To prevent it from being used for
another purpose)

> +      The compositor should place it near the active text input area.

What happens if the wl_surface is destroyed before this object? Is it allowed?

> +    </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_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 at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel


More information about the wayland-devel mailing list