input_method_experimental_v2

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.

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 xx_input_method_v1.commit event.

The initial value of text is an empty string. The initial value of cursor_begin, and cursor_end are both 0.

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 xx_input_method_v1.commit request.

The initial values of both before_length and after_length are 0.

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 xx_input_method_v1 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 xx_input_method_v1 object.

Creates a new xx_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.

Issuing this request before receiving a committed .activate causes the "inactive" error.

Destroys the zwp_text_input_v2 object and any associated child objects.

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, and destroys any existing input_popup_surface objects. In addition, it marks the xx_input_method_v1 object as active.

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 xx_input_method_v1.done event, and stay valid until changed.

Notification that no focused text input currently needs an active input method on this seat.

This event marks the xx_input_method_v1 object as inactive. The compositor must destroy all existing xx_input_popup_surface_v2 objects.

State set with this event is double-buffered. It will get applied on the next xx_input_method_v1.done event, and stay valid until changed.

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 xx_input_method_v1.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.

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 xx_input_method_v1.done event.

The initial value of cause is input_method.

Indicates the content type and hint for the current xx_input_method_v1 instance.

Values set with this event are double-buffered. They will get applied on the next xx_input_method_v1.done event.

The initial value for hint is none, and the initial value for purpose is normal.

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.

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.

This request notifies the compositor that the client updated its surface in response to a configure sequence.

The purpose of this request is to synchronize the updates of the surface geometry with the surface contents. For example, when the compositor assigns a size larger than prevously, the client must fill the additional space before the popup gets displayed to the user with the new size. When the compositor receives .ack_configure, it can proceed to draw the new size.

.ack_configure should be sent after every submitted configure sequence, passing along the serial received in it.

An .ack_configure request is conceptually double-buffered. Every request overrides the previous one. The request takes effect once the .commit request is sent on the corresponding surface.

If the client receives multiple configure sequences before it can respond to one, it may acknowledge only the last configure sequence by using its serial in the .ack_configure request.

Committing an .ack_configure request consumes the serial number sent with the request, as well as serial numbers sent by all configure sequences submitted on this input_popup_surface prior to the configure sequence referenced by the committed serial.

Committing this request with a serial that, for this surface, never appeared in a submitted configure sequence, or one that was already committed before, raises an invalid_serial error.

Reposition an already-mapped popup. The popup will be placed given the details in the passed input_popup_positioner object.

The request is processed immediately, without the need to issue wl_surface.commit, but the actual repositioning takes place later, after .ack_configure.

The compositor should reply with a configure sequence including:

• input_popup_surface.start_configure,
• input_popup_surface.repositioned, including the token passed in this request.

This will discard any parameters set by the previous positioner.

If multiple .reposition requests are sent before the .repositioned event is submitted as part of a configure sequence, the compositor may ignore all but the last one.

The new popup position will not take effect until the corresponding configure sequence is acknowledged by the client. See input_popup_surface.repositioned for details.

The token itself is opaque, and has no other special meaning.

This destroys the popup. Explicitly destroying the input_popup_surface object will also dismiss the popup, and unmap the surface.

The start_configure event updates the popup geometry and marks the start of a configure sequence.

The anchor_* arguments represent the geometry of the anchor to which the popup was attached, relative to the upper left corner of the popup's surface. Note that this makes anchor_x, anchor_y the reverse of the what they represent in xdg_popup.

A configure sequence is a set of one or more events configuring the state of the input_popup_surface, starting with this event and ending with input_method.done. After the input_method.done event, the configure sequence is considered submitted.

State set by event in a configure sequence is conceptually double-buffered. Every argument overwrites its previous value. The state change should get applied atomically with the input_method.done ending the sequence, and the value of serial should return to the undefined value.

Events on the input_popup_surface object received outside a configure sequence (while serial is undefined) must be ignored by the client.

A configure sequence shall be sent every time the compositor (re)positions the popup, or the shape of the anchor changes, for example after popup creation, or in response to text being typed and the text cursor moving.

The client may update the surface in response to input_method.done. Unless the popup is destroyed by the input_method.done, the client must reply with an .ack_configure request with the serial sent in the start_configure event at some point after the sequence ends and before committing the new surface.

If the client receives multiple configure sequences before it can respond to one, it is free to discard all but the last event it received.

The compositor sends the .repositioned event in response to the .reposition request to notify about its completion.

The new geometry of the popup can be communicated using additional events within a configure sequence including:

• input_popup_surface.start_configure, and
• the .anchor_position event to update the relative position to the anchor.

When responding to a .reposition request, the token argument is the token passed in the that request.

This event is sent as part of a configure sequence. State set by this event is conceptually double-buffered. Every argument overwrites its previous value. The state change should get applied atomically with the next input_method.done event.

The client should optionally update the content of the popup, but must acknowledge the new popup configuration for the new position to take effect. See input_popup_surface.ack_configure for details.

Notify the compositor that the positioner will no longer be used.

Set the size of the surface that is to be positioned with the positioner object. The size is in surface-local coordinates and corresponds to the window geometry. See xdg_surface.set_window_geometry.

If any dimension is set to zero, the invalid_input error is raised.

Defines the anchor point for the anchor rectangle. The specified anchor is used to derive an anchor point that the popup surface will be positioned relative to. If a corner anchor is set (e.g. 'top_left' or 'bottom_right'), the anchor point will be at the specified corner; otherwise, the derived anchor point will be centered on the specified edge, or in the center of the anchor rectangle if no edge is specified.

Defines in what direction the surface should be positioned, relative to the anchor point of the anchor rectangle. If a corner gravity is specified (e.g. 'bottom_right' or 'top_left'), then the surface will be placed towards the specified gravity; otherwise, the child surface will be centered over the anchor point on any axis that had no gravity specified. If the gravity is not in the ‘gravity’ enum, an invalid_input error is raised.

Specify how the popup should be positioned if the originally intended position caused the surface to be constrained, meaning at least partially outside positioning boundaries set by the compositor. The adjustment is set by constructing a bitmask describing the adjustment to be made when the surface is constrained on that axis.

If no bit for one axis is set, the compositor will assume that the child surface should not change its position on that axis when constrained.

If more than one bit for one axis is set, the order of how adjustments are applied is specified in the corresponding adjustment descriptions.

The default adjustment is none.

Specify the surface position offset relative to the position of the anchor on the anchor rectangle and the anchor on the surface. For example if the anchor of the anchor rectangle is at (x, y), the surface has the gravity bottom|right, and the offset is (ox, oy), the calculated surface position will be (x + ox, y + oy). The offset position of the surface is the one used for constraint testing. See set_constraint_adjustment.

An example use case is placing a popup menu on top of a user interface element, while aligning the user interface element of the parent surface with some user interface element placed somewhere in the popup surface.

When set reactive, the surface is reconstrained if the conditions used for constraining changed, e.g. the window containing the text input moved.

Whenever the conditions change and the popup gets reconstrained, a configure sequence is sent with updated geometry.

The constraint adjustment value define ways the compositor will adjust the position of the surface, if the unadjusted position would result in the surface being partly constrained.

Whether a surface is considered 'constrained' is left to the compositor to determine. For example, the surface may be partly outside the compositor's defined 'work area', thus necessitating the child surface's position be adjusted until it is entirely inside the work area.

The adjustments can be combined, according to a defined precedence: 1) Flip, 2) Slide, 3) Resize.

Request a new input xx_input_method_v1 object associated with a given seat.

Create a positioner object. A positioner object is used to position surfaces relative to some parent surface. See the interface description and xdg_surface.get_popup for details.

Destroys the xx_input_method_manager_v2 object.

The xx_input_method_v1 objects originating from it remain valid.