Fix handling of backspace key press
[profile/ivi/weekeyboard.git] / src / text-client-protocol.h
1 /* 
2  * Copyright © 2012, 2013 Intel Corporation
3  * 
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
14  * warranty.
15  * 
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
23  * THIS SOFTWARE.
24  */
25
26 #ifndef TEXT_CLIENT_PROTOCOL_H
27 #define TEXT_CLIENT_PROTOCOL_H
28
29 #ifdef  __cplusplus
30 extern "C" {
31 #endif
32
33 #include <stdint.h>
34 #include <stddef.h>
35 #include "wayland-client.h"
36
37 struct wl_client;
38 struct wl_resource;
39
40 struct wl_text_input;
41 struct wl_text_input_manager;
42
43 extern const struct wl_interface wl_text_input_interface;
44 extern const struct wl_interface wl_text_input_manager_interface;
45
46 #ifndef WL_TEXT_INPUT_CONTENT_HINT_ENUM
47 #define WL_TEXT_INPUT_CONTENT_HINT_ENUM
48 /**
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
52  *      capitalization
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
64  *      stored
65  * @WL_TEXT_INPUT_CONTENT_HINT_LATIN: just latin characters should be
66  *      entered
67  * @WL_TEXT_INPUT_CONTENT_HINT_MULTILINE: the text input is multiline
68  *
69  * Content hint is a bitmask to allow to modify the behavior of the text
70  * input.
71  */
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,
86 };
87 #endif /* WL_TEXT_INPUT_CONTENT_HINT_ENUM */
88
89 #ifndef WL_TEXT_INPUT_CONTENT_PURPOSE_ENUM
90 #define WL_TEXT_INPUT_CONTENT_PURPOSE_ENUM
91 /**
92  * wl_text_input_content_purpose - content purpose
93  * @WL_TEXT_INPUT_CONTENT_PURPOSE_NORMAL: default input, allowing all
94  *      characters
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
109  *
110  * The content purpose allows to specify the primary purpose of a text
111  * input.
112  *
113  * This allows an input method to show special purpose input panels with
114  * extra characters or to disallow some characters.
115  */
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,
130 };
131 #endif /* WL_TEXT_INPUT_CONTENT_PURPOSE_ENUM */
132
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,
144 };
145 #endif /* WL_TEXT_INPUT_PREEDIT_STYLE_ENUM */
146
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,
153 };
154 #endif /* WL_TEXT_INPUT_TEXT_DIRECTION_ENUM */
155
156 /**
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
168  * @keysym: keysym
169  * @language: language
170  * @text_direction: text direction
171  *
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.
181  *
182  * Text is generally UTF-8 encoded, indices and lengths are in bytes.
183  *
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).
190  */
191 struct wl_text_input_listener {
192         /**
193          * enter - enter event
194          * @surface: (none)
195          *
196          * Notify the text-input object when it received focus. Typically
197          * in response to an activate request.
198          */
199         void (*enter)(void *data,
200                       struct wl_text_input *wl_text_input,
201                       struct wl_surface *surface);
202         /**
203          * leave - leave event
204          *
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.
208          */
209         void (*leave)(void *data,
210                       struct wl_text_input *wl_text_input);
211         /**
212          * modifiers_map - modifiers map
213          * @map: (none)
214          *
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.
218          */
219         void (*modifiers_map)(void *data,
220                               struct wl_text_input *wl_text_input,
221                               struct wl_array *map);
222         /**
223          * input_panel_state - state of the input panel
224          * @state: (none)
225          *
226          * Notify when the visibility state of the input panel changed.
227          */
228         void (*input_panel_state)(void *data,
229                                   struct wl_text_input *wl_text_input,
230                                   uint32_t state);
231         /**
232          * preedit_string - pre-edit
233          * @serial: serial of the latest known text input state
234          * @text: (none)
235          * @commit: (none)
236          *
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.
240          *
241          * The commit text can be used to replace the preedit text on reset
242          * (for example on unfocus).
243          *
244          * The text input should also handle all preedit_style and
245          * preedit_cursor events occuring directly before preedit_string.
246          */
247         void (*preedit_string)(void *data,
248                                struct wl_text_input *wl_text_input,
249                                uint32_t serial,
250                                const char *text,
251                                const char *commit);
252         /**
253          * preedit_styling - pre-edit styling
254          * @index: (none)
255          * @length: (none)
256          * @style: (none)
257          *
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
262          * events.
263          *
264          * This event is handled as part of a following preedit_string
265          * event.
266          */
267         void (*preedit_styling)(void *data,
268                                 struct wl_text_input *wl_text_input,
269                                 uint32_t index,
270                                 uint32_t length,
271                                 uint32_t style);
272         /**
273          * preedit_cursor - pre-edit cursor
274          * @index: (none)
275          *
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.
279          *
280          * This event is handled as part of a following preedit_string
281          * event.
282          */
283         void (*preedit_cursor)(void *data,
284                                struct wl_text_input *wl_text_input,
285                                int32_t index);
286         /**
287          * commit_string - commit
288          * @serial: serial of the latest known text input state
289          * @text: (none)
290          *
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).
297          *
298          * Any previously set composing text should be removed.
299          */
300         void (*commit_string)(void *data,
301                               struct wl_text_input *wl_text_input,
302                               uint32_t serial,
303                               const char *text);
304         /**
305          * cursor_position - set cursor to new position
306          * @index: (none)
307          * @anchor: (none)
308          *
309          * Notify when the cursor or anchor position should be modified.
310          *
311          * This event should be handled as part of a following
312          * commit_string event.
313          */
314         void (*cursor_position)(void *data,
315                                 struct wl_text_input *wl_text_input,
316                                 int32_t index,
317                                 int32_t anchor);
318         /**
319          * delete_surrounding_text - delete surrounding text
320          * @index: (none)
321          * @length: (none)
322          *
323          * Notify when the text around the current cursor position should
324          * be deleted.
325          *
326          * Index is relative to the current cursor (in bytes). Length is
327          * the length of deleted text (in bytes).
328          *
329          * This event should be handled as part of a following
330          * commit_string event.
331          */
332         void (*delete_surrounding_text)(void *data,
333                                         struct wl_text_input *wl_text_input,
334                                         int32_t index,
335                                         uint32_t length);
336         /**
337          * keysym - keysym
338          * @serial: serial of the latest known text input state
339          * @time: (none)
340          * @sym: (none)
341          * @state: (none)
342          * @modifiers: (none)
343          *
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)
351          */
352         void (*keysym)(void *data,
353                        struct wl_text_input *wl_text_input,
354                        uint32_t serial,
355                        uint32_t time,
356                        uint32_t sym,
357                        uint32_t state,
358                        uint32_t modifiers);
359         /**
360          * language - language
361          * @serial: serial of the latest known text input state
362          * @language: (none)
363          *
364          * Sets the language of the input text. The "language" argument
365          * is a RFC-3066 format language tag.
366          */
367         void (*language)(void *data,
368                          struct wl_text_input *wl_text_input,
369                          uint32_t serial,
370                          const char *language);
371         /**
372          * text_direction - text direction
373          * @serial: serial of the latest known text input state
374          * @direction: (none)
375          *
376          * Sets the text direction of input text.
377          *
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.
381          */
382         void (*text_direction)(void *data,
383                                struct wl_text_input *wl_text_input,
384                                uint32_t serial,
385                                uint32_t direction);
386 };
387
388 static inline int
389 wl_text_input_add_listener(struct wl_text_input *wl_text_input,
390                            const struct wl_text_input_listener *listener, void *data)
391 {
392         return wl_proxy_add_listener((struct wl_proxy *) wl_text_input,
393                                      (void (**)(void)) listener, data);
394 }
395
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
407
408 static inline void
409 wl_text_input_set_user_data(struct wl_text_input *wl_text_input, void *user_data)
410 {
411         wl_proxy_set_user_data((struct wl_proxy *) wl_text_input, user_data);
412 }
413
414 static inline void *
415 wl_text_input_get_user_data(struct wl_text_input *wl_text_input)
416 {
417         return wl_proxy_get_user_data((struct wl_proxy *) wl_text_input);
418 }
419
420 static inline void
421 wl_text_input_destroy(struct wl_text_input *wl_text_input)
422 {
423         wl_proxy_destroy((struct wl_proxy *) wl_text_input);
424 }
425
426 static inline void
427 wl_text_input_activate(struct wl_text_input *wl_text_input, struct wl_seat *seat, struct wl_surface *surface)
428 {
429         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
430                          WL_TEXT_INPUT_ACTIVATE, seat, surface);
431 }
432
433 static inline void
434 wl_text_input_deactivate(struct wl_text_input *wl_text_input, struct wl_seat *seat)
435 {
436         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
437                          WL_TEXT_INPUT_DEACTIVATE, seat);
438 }
439
440 static inline void
441 wl_text_input_show_input_panel(struct wl_text_input *wl_text_input)
442 {
443         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
444                          WL_TEXT_INPUT_SHOW_INPUT_PANEL);
445 }
446
447 static inline void
448 wl_text_input_hide_input_panel(struct wl_text_input *wl_text_input)
449 {
450         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
451                          WL_TEXT_INPUT_HIDE_INPUT_PANEL);
452 }
453
454 static inline void
455 wl_text_input_reset(struct wl_text_input *wl_text_input)
456 {
457         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
458                          WL_TEXT_INPUT_RESET);
459 }
460
461 static inline void
462 wl_text_input_set_surrounding_text(struct wl_text_input *wl_text_input, const char *text, uint32_t cursor, uint32_t anchor)
463 {
464         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
465                          WL_TEXT_INPUT_SET_SURROUNDING_TEXT, text, cursor, anchor);
466 }
467
468 static inline void
469 wl_text_input_set_content_type(struct wl_text_input *wl_text_input, uint32_t hint, uint32_t purpose)
470 {
471         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
472                          WL_TEXT_INPUT_SET_CONTENT_TYPE, hint, purpose);
473 }
474
475 static inline void
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)
477 {
478         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
479                          WL_TEXT_INPUT_SET_CURSOR_RECTANGLE, x, y, width, height);
480 }
481
482 static inline void
483 wl_text_input_set_preferred_language(struct wl_text_input *wl_text_input, const char *language)
484 {
485         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
486                          WL_TEXT_INPUT_SET_PREFERRED_LANGUAGE, language);
487 }
488
489 static inline void
490 wl_text_input_commit_state(struct wl_text_input *wl_text_input, uint32_t serial)
491 {
492         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
493                          WL_TEXT_INPUT_COMMIT_STATE, serial);
494 }
495
496 static inline void
497 wl_text_input_invoke_action(struct wl_text_input *wl_text_input, uint32_t button, uint32_t index)
498 {
499         wl_proxy_marshal((struct wl_proxy *) wl_text_input,
500                          WL_TEXT_INPUT_INVOKE_ACTION, button, index);
501 }
502
503 #define WL_TEXT_INPUT_MANAGER_CREATE_TEXT_INPUT 0
504
505 static inline void
506 wl_text_input_manager_set_user_data(struct wl_text_input_manager *wl_text_input_manager, void *user_data)
507 {
508         wl_proxy_set_user_data((struct wl_proxy *) wl_text_input_manager, user_data);
509 }
510
511 static inline void *
512 wl_text_input_manager_get_user_data(struct wl_text_input_manager *wl_text_input_manager)
513 {
514         return wl_proxy_get_user_data((struct wl_proxy *) wl_text_input_manager);
515 }
516
517 static inline void
518 wl_text_input_manager_destroy(struct wl_text_input_manager *wl_text_input_manager)
519 {
520         wl_proxy_destroy((struct wl_proxy *) wl_text_input_manager);
521 }
522
523 static inline struct wl_text_input *
524 wl_text_input_manager_create_text_input(struct wl_text_input_manager *wl_text_input_manager)
525 {
526         struct wl_proxy *id;
527
528         id = wl_proxy_create((struct wl_proxy *) wl_text_input_manager,
529                              &wl_text_input_interface);
530         if (!id)
531                 return NULL;
532
533         wl_proxy_marshal((struct wl_proxy *) wl_text_input_manager,
534                          WL_TEXT_INPUT_MANAGER_CREATE_TEXT_INPUT, id);
535
536         return (struct wl_text_input *) id;
537 }
538
539 #ifdef  __cplusplus
540 }
541 #endif
542
543 #endif