Differential D16735 Diff 45034 src/client/protocols/text-input-unstable-v3.xml

Changeset View

Standalone View

src/client/protocols/text-input-unstable-v3.xml

This file was added.

		1		<?xml version="1.0" encoding="UTF-8"?>
		2
		3		<protocol name="text_input_unstable_v3">
		4		<copyright>
		5		Copyright © 2012, 2013 Intel Corporation
		6		Copyright © 2015, 2016 Jan Arne Petersen
		7		Copyright © 2017, 2018 Red Hat, Inc.
		8		Copyright © 2018 Purism SPC
		9
		10		Permission to use, copy, modify, distribute, and sell this
		11		software and its documentation for any purpose is hereby granted
		12		without fee, provided that the above copyright notice appear in
		13		all copies and that both that copyright notice and this permission
		14		notice appear in supporting documentation, and that the name of
		15		the copyright holders not be used in advertising or publicity
		16		pertaining to distribution of the software without specific,
		17		written prior permission. The copyright holders make no
		18		representations about the suitability of this software for any
		19		purpose. It is provided "as is" without express or implied
		20		warranty.
		21
		22		THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
		23		SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
		24		FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
		25		SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
		26		WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
		27		AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
		28		ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
		29		THIS SOFTWARE.
		30		</copyright>
		31
		32		<description summary="Protocol for composing text">
		33		This protocol allows compositors to act as input methods and to send text
		34		to applications. A text input object is used to manage state of what are
		35		typically text entry fields in the application.
		36
		37		This document adheres to the RFC 2119 when using words like "must",
		38		"should", "may", etc.
		39
		40		Warning! The protocol described in this file is experimental and
		41		backward incompatible changes may be made. Backward compatible changes
		42		may be added together with the corresponding interface version bump.
		43		Backward incompatible changes are done by bumping the version number in
		44		the protocol and interface names and resetting the interface version.
		45		Once the protocol is to be declared stable, the 'z' prefix and the
		46		version number in the protocol and interface names are removed and the
		47		interface version number is reset.
		48		</description>
		49
		50		<interface name="zwp_text_input_v3" version="1">
		51		<description summary="text input">
		52		The zwp_text_input_v3 interface represents text input and input methods
		53		associated with a seat. It provides enter/leave events to follow the
		54		text input focus for a seat.
		55
		56		Requests are used to enable/disable the text-input object and set
		57		state information like surrounding and selected text or the content type.
		58		The information about the entered text is sent to the text-input object
		59		via the preedit_string and commit_string events.
		60
		61		Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices
		62		must not point to middle bytes inside a code point: they must either
		63		point to the first byte of a code point or to the end of the buffer.
		64		Lengths must be measured between two valid indices.
		65
		66		Focus moving throughout surfaces will result in the emission of
		67		zwp_text_input_v3.enter and zwp_text_input_v3.leave events. The focused
		68		surface must commit zwp_text_input_v3.enable and
		69		zwp_text_input_v3.disable requests as the keyboard focus moves across
		70		editable and non-editable elements of the UI. Those two requests are not
		71		expected to be paired with each other, the compositor must be able to
		72		handle consecutive series of the same request.
		73
		74		State is sent by the state requests (set_surrounding_text,
		75		set_content_type and set_cursor_rectangle) and a commit request. After an
		76		enter event or disable request all state information is invalidated and
		77		needs to be resent by the client.
		78		</description>
		79
		80		<request name="destroy" type="destructor">
		81		<description summary="Destroy the wp_text_input">
		82		Destroy the wp_text_input object. Also disables all surfaces enabled
		83		through this wp_text_input object.
		84		</description>
		85		</request>
		86
		87		<request name="enable">
		88		<description summary="Request text input to be enabled">
		89		Requests text input on the surface previously obtained from the enter
		90		event.
		91
		92		This request must be issued every time the active text input changes
		93		to a new one, including within the current surface. Use
		94		zwp_text_input_v3.disable when there is no longer any input focus on
		95		the current surface.
		96
		97		This request resets all state associated with previous enable, disable,
		98		set_surrounding_text, set_text_change_cause, set_content_type, and
		99		set_cursor_rectangle requests, as well as the state associated with
		100		preedit_string, commit_string, and delete_surrounding_text events.
		101
		102		The set_surrounding_text, set_content_type and set_cursor_rectangle
		103		requests must follow if the text input supports the necessary
		104		functionality.
		105
		106		State set with this request is double-buffered. It will get applied on
		107		the next zwp_text_input_v3.commit request, and stay valid until the
		108		next committed enable or disable request.
		109
		110		The changes must be applied by the compositor after issuing a
		111		zwp_text_input_v3.commit request.
		112		</description>
		113		</request>
		114
		115		<request name="disable">
		116		<description summary="Disable text input on a surface">
		117		Explicitly disable text input on the current surface (typically when
		118		there is no focus on any text entry inside the surface).
		119
		120		State set with this request is double-buffered. It will get applied on
		121		the next zwp_text_input_v3.commit request.
		122		</description>
		123		</request>
		124
		125		<request name="set_surrounding_text">
		126		<description summary="sets the surrounding text">
		127		Sets the surrounding plain text around the input, excluding the preedit
		128		text.
		129
		130		The client should notify the compositor of any changes in any of the
		131		values carried with this request, including changes caused by handling
		132		incoming text-input events as well as changes caused by other
		133		mechanisms like keyboard typing.
		134
		135		If the client is unaware of the text around the cursor, it should not
		136		issue this request, to signify lack of support to the compositor.
		137
		138		Text is UTF-8 encoded, and should include the cursor position, the
		139		complete selection and additional characters before and after them.
		140		There is a maximum length of wayland messages, so text can not be
		141		longer than 4000 bytes.
		142
		143		Cursor is the byte offset of the cursor within text buffer.
		144
		145		Anchor is the byte offset of the selection anchor within text buffer.
		146		If there is no selected text, anchor is the same as cursor.
		147
		148		If any preedit text is present, it is replaced with a cursor for the
		149		purpose of this event.
		150
		151		Values set with this request are double-buffered. They will get applied
		152		on the next zwp_text_input_v3.commit request, and stay valid until the
		153		next committed enable or disable request.
		154
		155		The initial state for affected fields is empty, meaning that the text
		156		input does not support sending surrounding text. If the empty values
		157		get applied, subsequent attempts to change them may have no effect.
		158		</description>
		159		<arg name="text" type="string"/>
		160		<arg name="cursor" type="int"/>
		161		<arg name="anchor" type="int"/>
		162		</request>
		163
		164		<enum name="change_cause">
		165		<description summary="text change reason">
		166		Reason for the change of surrounding text or cursor posision.
		167		</description>
		168		<entry name="input_method" value="0" summary="input method caused the change"/>
		169		<entry name="other" value="1" summary="something else than the input method caused the change"/>
		170		</enum>
		171
		172		<request name="set_text_change_cause">
		173		<description summary="indicates the cause of surrounding text change">
		174		Tells the compositor why the text surrounding the cursor changed.
		175
		176		Whenever the client detects an external change in text, cursor, or
		177		anchor posision, it must issue this request to the compositor. This
		178		request is intended to give the input method a chance to update the
		179		preedit text in an appropriate way, e.g. by removing it when the user
		180		starts typing with a keyboard.
		181
		182		cause describes the source of the change.
		183
		184		The value set with this request is double-buffered. It must be applied
		185		and reset to initial at the next zwp_text_input_v3.commit request.
		186
		187		The initial value of cause is input_method.
		188		</description>
		189		<arg name="cause" type="uint" enum="change_cause"/>
		190		</request>
		191
		192		<enum name="content_hint" bitfield="true">
		193		<description summary="content hint">
		194		Content hint is a bitmask to allow to modify the behavior of the text
		195		input.
		196		</description>
		197		<entry name="none" value="0x0" summary="no special behavior"/>
		198		<entry name="completion" value="0x1" summary="suggest word completions"/>
		199		<entry name="spellcheck" value="0x2" summary="suggest word corrections"/>
		200		<entry name="auto_capitalization" value="0x4" summary="switch to uppercase letters at the start of a sentence"/>
		201		<entry name="lowercase" value="0x8" summary="prefer lowercase letters"/>
		202		<entry name="uppercase" value="0x10" summary="prefer uppercase letters"/>
		203		<entry name="titlecase" value="0x20" summary="prefer casing for titles and headings (can be language dependent)"/>
		204		<entry name="hidden_text" value="0x40" summary="characters should be hidden"/>
		205		<entry name="sensitive_data" value="0x80" summary="typed text should not be stored"/>
		206		<entry name="latin" value="0x100" summary="just Latin characters should be entered"/>
		207		<entry name="multiline" value="0x200" summary="the text input is multiline"/>
		208		</enum>
		209
		210		<enum name="content_purpose">
		211		<description summary="content purpose">
		212		The content purpose allows to specify the primary purpose of a text
		213		input.
		214
		215		This allows an input method to show special purpose input panels with
		216		extra characters or to disallow some characters.
		217		</description>
		218		<entry name="normal" value="0" summary="default input, allowing all characters"/>
		219		<entry name="alpha" value="1" summary="allow only alphabetic characters"/>
		220		<entry name="digits" value="2" summary="allow only digits"/>
		221		<entry name="number" value="3" summary="input a number (including decimal separator and sign)"/>
		222		<entry name="phone" value="4" summary="input a phone number"/>
		223		<entry name="url" value="5" summary="input an URL"/>
		224		<entry name="email" value="6" summary="input an email address"/>
		225		<entry name="name" value="7" summary="input a name of a person"/>
		226		<entry name="password" value="8" summary="input a password (combine with sensitive_data hint)"/>
		227		<entry name="pin" value="9" summary="input is a numeric password (combine with sensitive_data hint)"/>
		228		<entry name="date" value="10" summary="input a date"/>
		229		<entry name="time" value="11" summary="input a time"/>
		230		<entry name="datetime" value="12" summary="input a date and time"/>
		231		<entry name="terminal" value="13" summary="input for a terminal"/>
		232		</enum>
		233
		234		<request name="set_content_type">
		235		<description summary="set content purpose and hint">
		236		Sets the content purpose and content hint. While the purpose is the
		237		basic purpose of an input field, the hint flags allow to modify some of
		238		the behavior.
		239
		240		Values set with this request are double-buffered. They will get applied
		241		on the next zwp_text_input_v3.commit request.
		242		Subsequent attempts to update them may have no effect. The values
		243		remain valid until the next committed enable or disable request.
		244
		245		The initial value for hint is none, and the initial value for purpose
		246		is normal.
		247		</description>
		248		<arg name="hint" type="uint" enum="content_hint"/>
		249		<arg name="purpose" type="uint" enum="content_purpose"/>
		250		</request>
		251
		252		<request name="set_cursor_rectangle">
		253		<description summary="set cursor position">
		254		Marks an area around the cursor as a x, y, width, height rectangle in
		255		surface local coordinates.
		256
		257		Allows the compositor to put a window with word suggestions near the
		258		cursor, without obstructing the text being input.
		259
		260		If the client is unaware of the position of edited text, it should not
		261		issue this request, to signify lack of support to the compositor.
		262
		263		Values set with this request are double-buffered. They will get applied
		264		on the next zwp_text_input_v3.commit request, and stay valid until the
		265		next committed enable or disable request.
		266
		267		The initial values describing a cursor rectangle are empty. That means
		268		the text input does not support describing the cursor area. If the
		269		empty values get applied, subsequent attempts to change them may have
		270		no effect.
		271		</description>
		272		<arg name="x" type="int"/>
		273		<arg name="y" type="int"/>
		274		<arg name="width" type="int"/>
		275		<arg name="height" type="int"/>
		276		</request>
		277
		278		<request name="commit">
		279		<description summary="commit state">
		280		Atomically applies state changes recently sent to the compositor.
		281
		282		The commit request establishes and updates the state of the client, and
		283		must be issued after any changes to apply them.
		284
		285		Text input state (enabled status, content purpose, content hint,
		286		surrounding text and change cause, cursor rectangle) is conceptually
		287		double-buffered within the context of a text input, i.e. between a
		288		committed enable request and the following committed enable or disable
		289		request.
		290
		291		Protocol requests modify the pending state, as opposed to the current
		292		state in use by the input method. A commit request atomically applies
		293		all pending state, replacing the current state. After commit, the new
		294		pending state is as documented for each related request.
		295
		296		Requests are applied in the order of arrival.
		297
		298		Neither current nor pending state are modified unless noted otherwise.
		299
		300		The compositor must count the number of commit requests coming from
		301		each zwp_text_input_v3 object and use the count as the serial in done
		302		events.
		303		</description>
		304		</request>
		305
		306		<event name="enter">
		307		<description summary="enter event">
		308		Notification that this seat's text-input focus is on a certain surface.
		309
		310		When the seat has the keyboard capability the text-input focus follows
		311		the keyboard focus. This event sets the current surface for the
		312		text-input object.
		313		</description>
		314		<arg name="surface" type="object" interface="wl_surface"/>
		315		</event>
		316
		317		<event name="leave">
		318		<description summary="leave event">
		319		Notification that this seat's text-input focus is no longer on a
		320		certain surface. The client should reset any preedit string previously
		321		set.
		322
		323		The leave notification clears the current surface. It is sent before
		324		the enter notification for the new focus.
		325
		326		When the seat has the keyboard capability the text-input focus follows
		327		the keyboard focus.
		328		</description>
		329		<arg name="surface" type="object" interface="wl_surface"/>
		330		</event>
		331
		332		<event name="preedit_string">
		333		<description summary="pre-edit">
		334		Notify when a new composing text (pre-edit) should be set at the
		335		current cursor position. Any previously set composing text must be
		336		removed. Any previously existing selected text must be removed.
		337
		338		The argument text contains the pre-edit string buffer.
		339
		340		The parameters cursor_begin and cursor_end are counted in bytes
		341		relative to the beginning of the submitted text buffer. Cursor should
		342		be hidden when both are equal to -1.
		343
		344		They could be represented by the client as a line if both values are
		345		the same, or as a text highlight otherwise.
		346
		347		Values set with this event are double-buffered. They must be applied
		348		and reset to initial on the next zwp_text_input_v3.done event.
		349
		350		The initial value of text is an empty string, and cursor_begin,
		351		cursor_end and cursor_hidden are all 0.
		352		</description>
		353		<arg name="text" type="string" allow-null="true"/>
		354		<arg name="cursor_begin" type="int"/>
		355		<arg name="cursor_end" type="int"/>
		356		</event>
		357
		358		<event name="commit_string">
		359		<description summary="text commit">
		360		Notify when text should be inserted into the editor widget. The text to
		361		commit could be either just a single character after a key press or the
		362		result of some composing (pre-edit).
		363
		364		Values set with this event are double-buffered. They must be applied
		365		and reset to initial on the next zwp_text_input_v3.done event.
		366
		367		The initial value of text is an empty string.
		368		</description>
		369		<arg name="text" type="string" allow-null="true"/>
		370		</event>
		371
		372		<event name="delete_surrounding_text">
		373		<description summary="delete surrounding text">
		374		Notify when the text around the current cursor position should be
		375		deleted.
		376
		377		Before_length and after_length are the number of bytes before and after
		378		the current cursor index (excluding the selection) to delete.
		379
		380		If a preedit text is present, in effect before_length is counted from
		381		the beginning of it, and after_length from its end (see done event
		382		sequence).
		383
		384		Values set with this event are double-buffered. They must be applied
		385		and reset to initial on the next zwp_text_input_v3.done event.
		386
		387		The initial values of both before_length and after_length are 0.
		388		</description>
		389		<arg name="before_length" type="uint" summary="length of text before current cursor position"/>
		390		<arg name="after_length" type="uint" summary="length of text after current cursor position"/>
		391		</event>
		392
		393		<event name="done">
		394		<description summary="apply changes">
		395		Instruct the application to apply changes to state requested by the
		396		preedit_string, commit_string and delete_surrounding_text events. The
		397		state relating to these events is double-buffered, and each one
		398		modifies the pending state. This event replaces the current state with
		399		the pending state.
		400
		401		The application must proceed by evaluating the changes in the following
		402		order:
		403
		404		1. Replace existing preedit string with the cursor.
		405		2. Delete requested surrounding text.
		406		3. Insert commit string with the cursor at its end.
		407		4. Calculate surrounding text to send.
		408		5. Insert new preedit text in cursor position.
		409		6. Place cursor inside preedit text.
		410
		411		The serial number reflects the last state of the zwp_text_input_v3
		412		object known to the compositor. The value of the serial argument must
		413		be equal to the number of commit requests already issued on that object.
		414		When the client receives a done event with a serial different than the
		415		number of past commit requests, it must proceed as normal, except it
		416		should not change the current state of the zwp_text_input_v3 object.
		417		</description>
		418		<arg name="serial" type="uint"/>
		419		</event>
		420		</interface>
		421
		422		<interface name="zwp_text_input_manager_v3" version="1">
		423		<description summary="text input manager">
		424		A factory for text-input objects. This object is a global singleton.
		425		</description>
		426
		427		<request name="destroy" type="destructor">
		428		<description summary="Destroy the wp_text_input_manager">
		429		Destroy the wp_text_input_manager object.
		430		</description>
		431		</request>
		432
		433		<request name="get_text_input">
		434		<description summary="create a new text input object">
		435		Creates a new text-input object for a given seat.
		436		</description>
		437		<arg name="id" type="new_id" interface="zwp_text_input_v3"/>
		438		<arg name="seat" type="object" interface="wl_seat"/>
		439		</request>
		440		</interface>
		441		</protocol>