2 * Copyright © 2012, 2013 Intel Corporation
4 * Permission to use, copy, modify, distribute, and sell this
5 * software and its documentation for any purpose is hereby granted
6 * without fee, provided that the above copyright notice appear in
7 * all copies and that both that copyright notice and this permission
8 * notice appear in supporting documentation, and that the name of
9 * the copyright holders not be used in advertising or publicity
10 * pertaining to distribution of the software without specific,
11 * written prior permission. The copyright holders make no
12 * representations about the suitability of this software for any
13 * purpose. It is provided "as is" without express or implied
16 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
17 * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
18 * FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
19 * SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
21 * AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
22 * ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
26 #ifndef TEXT_CLIENT_PROTOCOL_H
27 #define TEXT_CLIENT_PROTOCOL_H
35 #include "wayland-client.h"
41 struct wl_text_input_manager;
43 extern const struct wl_interface wl_text_input_interface;
44 extern const struct wl_interface wl_text_input_manager_interface;
46 #ifndef WL_TEXT_INPUT_CONTENT_HINT_ENUM
47 #define WL_TEXT_INPUT_CONTENT_HINT_ENUM
49 * wl_text_input_content_hint - content hint
50 * @WL_TEXT_INPUT_CONTENT_HINT_NONE: no special behaviour
51 * @WL_TEXT_INPUT_CONTENT_HINT_DEFAULT: auto completion, correction and
53 * @WL_TEXT_INPUT_CONTENT_HINT_PASSWORD: hidden and sensitive text
54 * @WL_TEXT_INPUT_CONTENT_HINT_AUTO_COMPLETION: suggest word completions
55 * @WL_TEXT_INPUT_CONTENT_HINT_AUTO_CORRECTION: suggest word corrections
56 * @WL_TEXT_INPUT_CONTENT_HINT_AUTO_CAPITALIZATION: switch to uppercase
57 * letters at the start of a sentence
58 * @WL_TEXT_INPUT_CONTENT_HINT_LOWERCASE: prefer lowercase letters
59 * @WL_TEXT_INPUT_CONTENT_HINT_UPPERCASE: prefer uppercase letters
60 * @WL_TEXT_INPUT_CONTENT_HINT_TITLECASE: prefer casing for titles and
61 * headings (can be language dependent)
62 * @WL_TEXT_INPUT_CONTENT_HINT_HIDDEN_TEXT: characters should be hidden
63 * @WL_TEXT_INPUT_CONTENT_HINT_SENSITIVE_DATA: typed text should not be
65 * @WL_TEXT_INPUT_CONTENT_HINT_LATIN: just latin characters should be
67 * @WL_TEXT_INPUT_CONTENT_HINT_MULTILINE: the text input is multiline
69 * Content hint is a bitmask to allow to modify the behavior of the text
72 enum wl_text_input_content_hint {
73 WL_TEXT_INPUT_CONTENT_HINT_NONE = 0x0,
74 WL_TEXT_INPUT_CONTENT_HINT_DEFAULT = 0x7,
75 WL_TEXT_INPUT_CONTENT_HINT_PASSWORD = 0xc0,
76 WL_TEXT_INPUT_CONTENT_HINT_AUTO_COMPLETION = 0x1,
77 WL_TEXT_INPUT_CONTENT_HINT_AUTO_CORRECTION = 0x2,
78 WL_TEXT_INPUT_CONTENT_HINT_AUTO_CAPITALIZATION = 0x4,
79 WL_TEXT_INPUT_CONTENT_HINT_LOWERCASE = 0x8,
80 WL_TEXT_INPUT_CONTENT_HINT_UPPERCASE = 0x10,
81 WL_TEXT_INPUT_CONTENT_HINT_TITLECASE = 0x20,
82 WL_TEXT_INPUT_CONTENT_HINT_HIDDEN_TEXT = 0x40,
83 WL_TEXT_INPUT_CONTENT_HINT_SENSITIVE_DATA = 0x80,
84 WL_TEXT_INPUT_CONTENT_HINT_LATIN = 0x100,
85 WL_TEXT_INPUT_CONTENT_HINT_MULTILINE = 0x200,
87 #endif /* WL_TEXT_INPUT_CONTENT_HINT_ENUM */
89 #ifndef WL_TEXT_INPUT_CONTENT_PURPOSE_ENUM
90 #define WL_TEXT_INPUT_CONTENT_PURPOSE_ENUM
92 * wl_text_input_content_purpose - content purpose
93 * @WL_TEXT_INPUT_CONTENT_PURPOSE_NORMAL: default input, allowing all
95 * @WL_TEXT_INPUT_CONTENT_PURPOSE_ALPHA: allow only alphabetic characters
96 * @WL_TEXT_INPUT_CONTENT_PURPOSE_DIGITS: allow only digits
97 * @WL_TEXT_INPUT_CONTENT_PURPOSE_NUMBER: input a number (including
98 * decimal separator and sign)
99 * @WL_TEXT_INPUT_CONTENT_PURPOSE_PHONE: input a phone number
100 * @WL_TEXT_INPUT_CONTENT_PURPOSE_URL: input an URL
101 * @WL_TEXT_INPUT_CONTENT_PURPOSE_EMAIL: input an email address
102 * @WL_TEXT_INPUT_CONTENT_PURPOSE_NAME: input a name of a person
103 * @WL_TEXT_INPUT_CONTENT_PURPOSE_PASSWORD: input a password (combine
104 * with password or sensitive_data hint)
105 * @WL_TEXT_INPUT_CONTENT_PURPOSE_DATE: input a date
106 * @WL_TEXT_INPUT_CONTENT_PURPOSE_TIME: input a time
107 * @WL_TEXT_INPUT_CONTENT_PURPOSE_DATETIME: input a date and time
108 * @WL_TEXT_INPUT_CONTENT_PURPOSE_TERMINAL: input for a terminal
110 * The content purpose allows to specify the primary purpose of a text
113 * This allows an input method to show special purpose input panels with
114 * extra characters or to disallow some characters.
116 enum wl_text_input_content_purpose {
117 WL_TEXT_INPUT_CONTENT_PURPOSE_NORMAL = 0,
118 WL_TEXT_INPUT_CONTENT_PURPOSE_ALPHA = 1,
119 WL_TEXT_INPUT_CONTENT_PURPOSE_DIGITS = 2,
120 WL_TEXT_INPUT_CONTENT_PURPOSE_NUMBER = 3,
121 WL_TEXT_INPUT_CONTENT_PURPOSE_PHONE = 4,
122 WL_TEXT_INPUT_CONTENT_PURPOSE_URL = 5,
123 WL_TEXT_INPUT_CONTENT_PURPOSE_EMAIL = 6,
124 WL_TEXT_INPUT_CONTENT_PURPOSE_NAME = 7,
125 WL_TEXT_INPUT_CONTENT_PURPOSE_PASSWORD = 8,
126 WL_TEXT_INPUT_CONTENT_PURPOSE_DATE = 9,
127 WL_TEXT_INPUT_CONTENT_PURPOSE_TIME = 10,
128 WL_TEXT_INPUT_CONTENT_PURPOSE_DATETIME = 11,
129 WL_TEXT_INPUT_CONTENT_PURPOSE_TERMINAL = 12,
131 #endif /* WL_TEXT_INPUT_CONTENT_PURPOSE_ENUM */
133 #ifndef WL_TEXT_INPUT_PREEDIT_STYLE_ENUM
134 #define WL_TEXT_INPUT_PREEDIT_STYLE_ENUM
135 enum wl_text_input_preedit_style {
136 WL_TEXT_INPUT_PREEDIT_STYLE_DEFAULT = 0,
137 WL_TEXT_INPUT_PREEDIT_STYLE_NONE = 1,
138 WL_TEXT_INPUT_PREEDIT_STYLE_ACTIVE = 2,
139 WL_TEXT_INPUT_PREEDIT_STYLE_INACTIVE = 3,
140 WL_TEXT_INPUT_PREEDIT_STYLE_HIGHLIGHT = 4,
141 WL_TEXT_INPUT_PREEDIT_STYLE_UNDERLINE = 5,
142 WL_TEXT_INPUT_PREEDIT_STYLE_SELECTION = 6,
143 WL_TEXT_INPUT_PREEDIT_STYLE_INCORRECT = 7,
145 #endif /* WL_TEXT_INPUT_PREEDIT_STYLE_ENUM */
147 #ifndef WL_TEXT_INPUT_TEXT_DIRECTION_ENUM
148 #define WL_TEXT_INPUT_TEXT_DIRECTION_ENUM
149 enum wl_text_input_text_direction {
150 WL_TEXT_INPUT_TEXT_DIRECTION_AUTO = 0,
151 WL_TEXT_INPUT_TEXT_DIRECTION_LTR = 1,
152 WL_TEXT_INPUT_TEXT_DIRECTION_RTL = 2,
154 #endif /* WL_TEXT_INPUT_TEXT_DIRECTION_ENUM */
157 * wl_text_input - text input
158 * @enter: enter event
159 * @leave: leave event
160 * @modifiers_map: modifiers map
161 * @input_panel_state: state of the input panel
162 * @preedit_string: pre-edit
163 * @preedit_styling: pre-edit styling
164 * @preedit_cursor: pre-edit cursor
165 * @commit_string: commit
166 * @cursor_position: set cursor to new position
167 * @delete_surrounding_text: delete surrounding text
169 * @language: language
170 * @text_direction: text direction
172 * An object used for text input. Adds support for text input and input
173 * methods to applications. A text-input object is created from a
174 * wl_text_input_manager and corresponds typically to a text entry in an
175 * application. Requests are used to activate/deactivate the text-input
176 * object and set state information like surrounding and selected text or
177 * the content type. The information about entered text is sent to the
178 * text-input object via the pre-edit and commit events. Using this
179 * interface removes the need for applications to directly process hardware
180 * key events and compose text out of them.
182 * Text is generally UTF-8 encoded, indices and lengths are in bytes.
184 * Serials are used to synchronize the state between the text input and an
185 * input method. New serials are sent by the text input in the commit_state
186 * request and are used by the input method to indicate the known text
187 * input state in events like preedit_string, commit_string, and keysym.
188 * The text input can then ignore events from the input method which are
189 * based on an outdated state (for example after a reset).
191 struct wl_text_input_listener {
193 * enter - enter event
196 * Notify the text-input object when it received focus. Typically
197 * in response to an activate request.
199 void (*enter)(void *data,
200 struct wl_text_input *wl_text_input,
201 struct wl_surface *surface);
203 * leave - leave event
205 * Notify the text-input object when it lost focus. Either in
206 * response to a deactivate request or when the assigned surface
207 * lost focus or was destroyed.
209 void (*leave)(void *data,
210 struct wl_text_input *wl_text_input);
212 * modifiers_map - modifiers map
215 * Transfer an array of 0-terminated modifiers names. The
216 * position in the array is the index of the modifier as used in
217 * the modifiers bitmask in the keysym event.
219 void (*modifiers_map)(void *data,
220 struct wl_text_input *wl_text_input,
221 struct wl_array *map);
223 * input_panel_state - state of the input panel
226 * Notify when the visibility state of the input panel changed.
228 void (*input_panel_state)(void *data,
229 struct wl_text_input *wl_text_input,
232 * preedit_string - pre-edit
233 * @serial: serial of the latest known text input state
237 * Notify when a new composing text (pre-edit) should be set
238 * around the current cursor position. Any previously set composing
239 * text should be removed.
241 * The commit text can be used to replace the preedit text on reset
242 * (for example on unfocus).
244 * The text input should also handle all preedit_style and
245 * preedit_cursor events occuring directly before preedit_string.
247 void (*preedit_string)(void *data,
248 struct wl_text_input *wl_text_input,
253 * preedit_styling - pre-edit styling
258 * Sets styling information on composing text. The style is
259 * applied for length bytes from index relative to the beginning of
260 * the composing text (as byte offset). Multiple styles can be
261 * applied to a composing text by sending multiple preedit_styling
264 * This event is handled as part of a following preedit_string
267 void (*preedit_styling)(void *data,
268 struct wl_text_input *wl_text_input,
273 * preedit_cursor - pre-edit cursor
276 * Sets the cursor position inside the composing text (as byte
277 * offset) relative to the start of the composing text. When index
278 * is a negative number no cursor is shown.
280 * This event is handled as part of a following preedit_string
283 void (*preedit_cursor)(void *data,
284 struct wl_text_input *wl_text_input,
287 * commit_string - commit
288 * @serial: serial of the latest known text input state
291 * Notify when text should be inserted into the editor widget.
292 * The text to commit could be either just a single character after
293 * a key press or the result of some composing (pre-edit). It could
294 * be also an empty text when some text should be removed (see
295 * delete_surrounding_text) or when the input cursor should be
296 * moved (see cursor_position).
298 * Any previously set composing text should be removed.
300 void (*commit_string)(void *data,
301 struct wl_text_input *wl_text_input,
305 * cursor_position - set cursor to new position
309 * Notify when the cursor or anchor position should be modified.
311 * This event should be handled as part of a following
312 * commit_string event.
314 void (*cursor_position)(void *data,
315 struct wl_text_input *wl_text_input,
319 * delete_surrounding_text - delete surrounding text
323 * Notify when the text around the current cursor position should
326 * Index is relative to the current cursor (in bytes). Length is
327 * the length of deleted text (in bytes).
329 * This event should be handled as part of a following
330 * commit_string event.
332 void (*delete_surrounding_text)(void *data,
333 struct wl_text_input *wl_text_input,
338 * @serial: serial of the latest known text input state
344 * Notify when a key event was sent. Key events should not be
345 * used for normal text input operations, which should be done with
346 * commit_string, delete_surrounding_text, etc. The key event
347 * follows the wl_keyboard key event convention. Sym is a XKB
348 * keysym, state a wl_keyboard key_state. Modifiers are a mask for
349 * effective modifiers (where the modifier indices are set by the
350 * modifiers_map event)
352 void (*keysym)(void *data,
353 struct wl_text_input *wl_text_input,
360 * language - language
361 * @serial: serial of the latest known text input state
364 * Sets the language of the input text. The "language" argument
365 * is a RFC-3066 format language tag.
367 void (*language)(void *data,
368 struct wl_text_input *wl_text_input,
370 const char *language);
372 * text_direction - text direction
373 * @serial: serial of the latest known text input state
376 * Sets the text direction of input text.
378 * It is mainly needed for showing input cursor on correct side of
379 * the editor when there is no input yet done and making sure
380 * neutral direction text is laid out properly.
382 void (*text_direction)(void *data,
383 struct wl_text_input *wl_text_input,
389 wl_text_input_add_listener(struct wl_text_input *wl_text_input,
390 const struct wl_text_input_listener *listener, void *data)
392 return wl_proxy_add_listener((struct wl_proxy *) wl_text_input,
393 (void (**)(void)) listener, data);
396 #define WL_TEXT_INPUT_ACTIVATE 0
397 #define WL_TEXT_INPUT_DEACTIVATE 1
398 #define WL_TEXT_INPUT_SHOW_INPUT_PANEL 2
399 #define WL_TEXT_INPUT_HIDE_INPUT_PANEL 3
400 #define WL_TEXT_INPUT_RESET 4
401 #define WL_TEXT_INPUT_SET_SURROUNDING_TEXT 5
402 #define WL_TEXT_INPUT_SET_CONTENT_TYPE 6
403 #define WL_TEXT_INPUT_SET_CURSOR_RECTANGLE 7
404 #define WL_TEXT_INPUT_SET_PREFERRED_LANGUAGE 8
405 #define WL_TEXT_INPUT_COMMIT_STATE 9
406 #define WL_TEXT_INPUT_INVOKE_ACTION 10
409 wl_text_input_set_user_data(struct wl_text_input *wl_text_input, void *user_data)
411 wl_proxy_set_user_data((struct wl_proxy *) wl_text_input, user_data);
415 wl_text_input_get_user_data(struct wl_text_input *wl_text_input)
417 return wl_proxy_get_user_data((struct wl_proxy *) wl_text_input);
421 wl_text_input_destroy(struct wl_text_input *wl_text_input)
423 wl_proxy_destroy((struct wl_proxy *) wl_text_input);
427 wl_text_input_activate(struct wl_text_input *wl_text_input, struct wl_seat *seat, struct wl_surface *surface)
429 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
430 WL_TEXT_INPUT_ACTIVATE, seat, surface);
434 wl_text_input_deactivate(struct wl_text_input *wl_text_input, struct wl_seat *seat)
436 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
437 WL_TEXT_INPUT_DEACTIVATE, seat);
441 wl_text_input_show_input_panel(struct wl_text_input *wl_text_input)
443 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
444 WL_TEXT_INPUT_SHOW_INPUT_PANEL);
448 wl_text_input_hide_input_panel(struct wl_text_input *wl_text_input)
450 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
451 WL_TEXT_INPUT_HIDE_INPUT_PANEL);
455 wl_text_input_reset(struct wl_text_input *wl_text_input)
457 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
458 WL_TEXT_INPUT_RESET);
462 wl_text_input_set_surrounding_text(struct wl_text_input *wl_text_input, const char *text, uint32_t cursor, uint32_t anchor)
464 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
465 WL_TEXT_INPUT_SET_SURROUNDING_TEXT, text, cursor, anchor);
469 wl_text_input_set_content_type(struct wl_text_input *wl_text_input, uint32_t hint, uint32_t purpose)
471 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
472 WL_TEXT_INPUT_SET_CONTENT_TYPE, hint, purpose);
476 wl_text_input_set_cursor_rectangle(struct wl_text_input *wl_text_input, int32_t x, int32_t y, int32_t width, int32_t height)
478 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
479 WL_TEXT_INPUT_SET_CURSOR_RECTANGLE, x, y, width, height);
483 wl_text_input_set_preferred_language(struct wl_text_input *wl_text_input, const char *language)
485 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
486 WL_TEXT_INPUT_SET_PREFERRED_LANGUAGE, language);
490 wl_text_input_commit_state(struct wl_text_input *wl_text_input, uint32_t serial)
492 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
493 WL_TEXT_INPUT_COMMIT_STATE, serial);
497 wl_text_input_invoke_action(struct wl_text_input *wl_text_input, uint32_t button, uint32_t index)
499 wl_proxy_marshal((struct wl_proxy *) wl_text_input,
500 WL_TEXT_INPUT_INVOKE_ACTION, button, index);
503 #define WL_TEXT_INPUT_MANAGER_CREATE_TEXT_INPUT 0
506 wl_text_input_manager_set_user_data(struct wl_text_input_manager *wl_text_input_manager, void *user_data)
508 wl_proxy_set_user_data((struct wl_proxy *) wl_text_input_manager, user_data);
512 wl_text_input_manager_get_user_data(struct wl_text_input_manager *wl_text_input_manager)
514 return wl_proxy_get_user_data((struct wl_proxy *) wl_text_input_manager);
518 wl_text_input_manager_destroy(struct wl_text_input_manager *wl_text_input_manager)
520 wl_proxy_destroy((struct wl_proxy *) wl_text_input_manager);
523 static inline struct wl_text_input *
524 wl_text_input_manager_create_text_input(struct wl_text_input_manager *wl_text_input_manager)
528 id = wl_proxy_create((struct wl_proxy *) wl_text_input_manager,
529 &wl_text_input_interface);
533 wl_proxy_marshal((struct wl_proxy *) wl_text_input_manager,
534 WL_TEXT_INPUT_MANAGER_CREATE_TEXT_INPUT, id);
536 return (struct wl_text_input *) id;