Hi Just some typos I found (for now):
On Mon, Aug 06, 2018 at 03:00:21PM +0200, Dorota Czaplejewicz 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 > > 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. > + > + 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. > + > + 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 s/posision/position/ > + 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. > + > + 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 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. > + </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"/> > + </request> > + > + <event name="unavailable"> > + <description summray="input method unavailable"> s/summray/summary/ Thanks for the patch and protocol work! Cheers, Silvan _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
