1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="input_method_unstable_v1">
3
4  <copyright>
5    Copyright © 2012, 2013 Intel Corporation
6
7    Permission is hereby granted, free of charge, to any person obtaining a
8    copy of this software and associated documentation files (the "Software"),
9    to deal in the Software without restriction, including without limitation
10    the rights to use, copy, modify, merge, publish, distribute, sublicense,
11    and/or sell copies of the Software, and to permit persons to whom the
12    Software is furnished to do so, subject to the following conditions:
13
14    The above copyright notice and this permission notice (including the next
15    paragraph) shall be included in all copies or substantial portions of the
16    Software.
17
18    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
21    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24    DEALINGS IN THE SOFTWARE.
25  </copyright>
26
27  <interface name="zwp_input_method_context_v1" version="1">
28    <description summary="input method context">
29      Corresponds to a text input on the input method side. An input method context
30      is created on text input activation on the input method side. It allows
31      receiving information about the text input from the application via events.
32      Input method contexts do not keep state after deactivation and should be
33      destroyed after deactivation is handled.
34
35      Text is generally UTF-8 encoded, indices and lengths are in bytes.
36
37      Serials are used to synchronize the state between the text input and
38      an input method. New serials are sent by the text input in the
39      commit_state request and are used by the input method to indicate
40      the known text input state in events like preedit_string, commit_string,
41      and keysym. The text input can then ignore events from the input method
42      which are based on an outdated state (for example after a reset).
43
44      Warning! The protocol described in this file is experimental and
45      backward incompatible changes may be made. Backward compatible changes
46      may be added together with the corresponding interface version bump.
47      Backward incompatible changes are done by bumping the version number in
48      the protocol and interface names and resetting the interface version.
49      Once the protocol is to be declared stable, the 'z' prefix and the
50      version number in the protocol and interface names are removed and the
51      interface version number is reset.
52    </description>
53
54    <request name="destroy" type="destructor"/>
55
56    <request name="commit_string">
57      <description summary="commit string">
58	Send the commit string text for insertion to the application.
59
60	The text to commit could be either just a single character after a key
61	press or the result of some composing (pre-edit). It could be also an
62	empty text when some text should be removed (see
63	delete_surrounding_text) or when the input cursor should be moved (see
64	cursor_position).
65
66	Any previously set composing text will be removed.
67      </description>
68      <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
69      <arg name="text" type="string"/>
70    </request>
71
72    <request name="preedit_string">
73      <description summary="pre-edit string">
74	Send the pre-edit string text to the application text input.
75
76	The commit text can be used to replace the pre-edit text on reset (for
77	example on unfocus).
78
79	Previously sent preedit_style and preedit_cursor requests are also
80	processed by the text_input.
81      </description>
82      <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
83      <arg name="text" type="string"/>
84      <arg name="commit" type="string"/>
85    </request>
86
87    <request name="preedit_styling">
88      <description summary="pre-edit styling">
89	Set the styling information on composing text. The style is applied for
90	length in bytes from index relative to the beginning of
91	the composing text (as byte offset). Multiple styles can
92	be applied to a composing text.
93
94	This request should be sent before sending a preedit_string request.
95      </description>
96      <arg name="index" type="uint"/>
97      <arg name="length" type="uint"/>
98      <arg name="style" type="uint"/>
99    </request>
100
101    <request name="preedit_cursor">
102      <description summary="pre-edit cursor">
103	Set the cursor position inside the composing text (as byte offset)
104	relative to the start of the composing text.
105
106	When index is negative no cursor should be displayed.
107
108	This request should be sent before sending a preedit_string request.
109      </description>
110      <arg name="index" type="int"/>
111    </request>
112
113    <request name="delete_surrounding_text">
114      <description summary="delete text">
115	Remove the surrounding text.
116
117	This request will be handled on the text_input side directly following
118	a commit_string request.
119      </description>
120      <arg name="index" type="int"/>
121      <arg name="length" type="uint"/>
122    </request>
123
124    <request name="cursor_position">
125      <description summary="set cursor to a new position">
126	Set the cursor and anchor to a new position. Index is the new cursor
127	position in bytes (when >= 0 this is relative to the end of the inserted text,
128	otherwise it is relative to the beginning of the inserted text). Anchor is
129	the new anchor position in bytes (when >= 0 this is relative to the end of the
130	inserted text, otherwise it is relative to the beginning of the inserted
131	text). When there should be no selected text, anchor should be the same
132	as index.
133
134	This request will be handled on the text_input side directly following
135	a commit_string request.
136      </description>
137      <arg name="index" type="int"/>
138      <arg name="anchor" type="int"/>
139    </request>
140
141    <request name="modifiers_map">
142      <arg name="map" type="array"/>
143    </request>
144
145    <request name="keysym">
146      <description summary="keysym">
147	Notify when a key event was sent. Key events should not be used for
148	normal text input operations, which should be done with commit_string,
149	delete_surrounding_text, etc. The key event follows the wl_keyboard key
150	event convention. Sym is an XKB keysym, state is a wl_keyboard key_state.
151      </description>
152      <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
153      <arg name="time" type="uint"/>
154      <arg name="sym" type="uint"/>
155      <arg name="state" type="uint"/>
156      <arg name="modifiers" type="uint"/>
157    </request>
158
159    <request name="grab_keyboard">
160      <description summary="grab hardware keyboard">
161	Allow an input method to receive hardware keyboard input and process
162	key events to generate text events (with pre-edit) over the wire. This
163	allows input methods which compose multiple key events for inputting
164	text like it is done for CJK languages.
165      </description>
166      <arg name="keyboard" type="new_id" interface="wl_keyboard"/>
167    </request>
168
169    <request name="key">
170      <description summary="forward key event">
171	Forward a wl_keyboard::key event to the client that was not processed
172	by the input method itself. Should be used when filtering key events
173	with grab_keyboard.  The arguments should be the ones from the
174	wl_keyboard::key event.
175
176	For generating custom key events use the keysym request instead.
177      </description>
178      <arg name="serial" type="uint" summary="serial from wl_keyboard::key"/>
179      <arg name="time" type="uint" summary="time from wl_keyboard::key"/>
180      <arg name="key" type="uint" summary="key from wl_keyboard::key"/>
181      <arg name="state" type="uint" summary="state from wl_keyboard::key"/>
182    </request>
183
184    <request name="modifiers">
185      <description summary="forward modifiers event">
186	Forward a wl_keyboard::modifiers event to the client that was not
187	processed by the input method itself.  Should be used when filtering
188	key events with grab_keyboard. The arguments should be the ones
189	from the wl_keyboard::modifiers event.
190      </description>
191      <arg name="serial" type="uint" summary="serial from wl_keyboard::modifiers"/>
192      <arg name="mods_depressed" type="uint" summary="mods_depressed from wl_keyboard::modifiers"/>
193      <arg name="mods_latched" type="uint" summary="mods_latched from wl_keyboard::modifiers"/>
194      <arg name="mods_locked" type="uint" summary="mods_locked from wl_keyboard::modifiers"/>
195      <arg name="group" type="uint" summary="group from wl_keyboard::modifiers"/>
196    </request>
197
198    <request name="language">
199      <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
200      <arg name="language" type="string"/>
201    </request>
202
203    <request name="text_direction">
204      <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
205      <arg name="direction" type="uint"/>
206    </request>
207
208    <event name="surrounding_text">
209      <description summary="surrounding text event">
210	The plain surrounding text around the input position. Cursor is the
211	position in bytes within the surrounding text relative to the beginning
212	of the text. Anchor is the position in bytes of the selection anchor
213	within the surrounding text relative to the beginning of the text. If
214	there is no selected text then anchor is the same as cursor.
215      </description>
216      <arg name="text" type="string"/>
217      <arg name="cursor" type="uint"/>
218      <arg name="anchor" type="uint"/>
219    </event>
220
221    <event name="reset">
222    </event>
223
224    <event name="content_type">
225      <arg name="hint" type="uint"/>
226      <arg name="purpose" type="uint"/>
227    </event>
228
229    <event name="invoke_action">
230      <arg name="button" type="uint"/>
231      <arg name="index" type="uint"/>
232    </event>
233
234    <event name="commit_state">
235      <arg name="serial" type="uint" summary="serial of text input state"/>
236    </event>
237
238    <event name="preferred_language">
239      <arg name="language" type="string"/>
240    </event>
241  </interface>
242
243  <interface name="zwp_input_method_v1" version="1">
244    <description summary="input method">
245      An input method object is responsible for composing text in response to
246      input from hardware or virtual keyboards. There is one input method
247      object per seat. On activate there is a new input method context object
248      created which allows the input method to communicate with the text input.
249    </description>
250
251    <event name="activate">
252      <description summary="activate event">
253	A text input was activated. Creates an input method context object
254	which allows communication with the text input.
255      </description>
256      <arg name="id" type="new_id" interface="zwp_input_method_context_v1"/>
257    </event>
258
259    <event name="deactivate">
260      <description summary="deactivate event">
261	The text input corresponding to the context argument was deactivated.
262	The input method context should be destroyed after deactivation is
263	handled.
264      </description>
265      <arg name="context" type="object" interface="zwp_input_method_context_v1"/>
266    </event>
267  </interface>
268
269  <interface name="zwp_input_panel_v1" version="1">
270    <description summary="interface for implementing keyboards">
271      Only one client can bind this interface at a time.
272    </description>
273
274    <request name="get_input_panel_surface">
275      <arg name="id" type="new_id" interface="zwp_input_panel_surface_v1"/>
276      <arg name="surface" type="object" interface="wl_surface"/>
277    </request>
278  </interface>
279
280  <interface name="zwp_input_panel_surface_v1" version="1">
281    <enum name="position">
282      <entry name="center_bottom" value="0"/>
283    </enum>
284
285    <request name="set_toplevel">
286      <description summary="set the surface type as a keyboard">
287	Set the input_panel_surface type to keyboard.
288
289	A keyboard surface is only shown when a text input is active.
290      </description>
291      <arg name="output" type="object" interface="wl_output"/>
292      <arg name="position" type="uint"/>
293    </request>
294
295    <request name="set_overlay_panel">
296      <description summary="set the surface type as an overlay panel">
297	Set the input_panel_surface to be an overlay panel.
298
299	This is shown near the input cursor above the application window when
300	a text input is active.
301      </description>
302    </request>
303  </interface>
304
305</protocol>
306