1 /**
2 * @file lv_keyboard.h
3 *
4 */
5
6 #ifndef LV_KEYBOARD_H
7 #define LV_KEYBOARD_H
8
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12
13 /*********************
14 * INCLUDES
15 *********************/
16 #include "../lv_conf_internal.h"
17
18 #if LV_USE_KEYBOARD != 0
19
20 /*Testing of dependencies*/
21 #if LV_USE_BTNMATRIX == 0
22 #error "lv_kb: lv_btnm is required. Enable it in lv_conf.h (LV_USE_BTNMATRIX 1) "
23 #endif
24
25 #if LV_USE_TEXTAREA == 0
26 #error "lv_kb: lv_ta is required. Enable it in lv_conf.h (LV_USE_TEXTAREA 1) "
27 #endif
28
29 #include "../lv_core/lv_obj.h"
30 #include "lv_btnmatrix.h"
31
32 /*********************
33 * DEFINES
34 *********************/
35 #define LV_KEYBOARD_CTRL_BTN_FLAGS (LV_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_CLICK_TRIG)
36
37 /**********************
38 * TYPEDEFS
39 **********************/
40
41 /** Current keyboard mode. */
42 enum {
43 LV_KEYBOARD_MODE_TEXT_LOWER,
44 LV_KEYBOARD_MODE_TEXT_UPPER,
45 LV_KEYBOARD_MODE_SPECIAL,
46 LV_KEYBOARD_MODE_NUM,
47 };
48 typedef uint8_t lv_keyboard_mode_t;
49
50 /*Data of keyboard*/
51 typedef struct {
52 lv_btnmatrix_ext_t btnm; /*Ext. of ancestor*/
53 /*New data for this type */
54 lv_obj_t * ta; /*Pointer to the assigned text area*/
55 lv_keyboard_mode_t mode; /*Key map type*/
56 uint8_t cursor_mng : 1; /*1: automatically show/hide cursor when a text area is assigned or left*/
57 } lv_keyboard_ext_t;
58
59 enum {
60 LV_KEYBOARD_PART_BG,
61 LV_KEYBOARD_PART_BTN,
62 };
63 typedef uint8_t lv_keyboard_style_t;
64
65 /**********************
66 * GLOBAL PROTOTYPES
67 **********************/
68
69 /**
70 * Create a keyboard objects
71 * @param par pointer to an object, it will be the parent of the new keyboard
72 * @param copy pointer to a keyboard object, if not NULL then the new object will be copied from it
73 * @return pointer to the created keyboard
74 */
75 lv_obj_t * lv_keyboard_create(lv_obj_t * par, const lv_obj_t * copy);
76
77 /*=====================
78 * Setter functions
79 *====================*/
80
81 /**
82 * Assign a Text Area to the Keyboard. The pressed characters will be put there.
83 * @param kb pointer to a Keyboard object
84 * @param ta pointer to a Text Area object to write there
85 */
86 void lv_keyboard_set_textarea(lv_obj_t * kb, lv_obj_t * ta);
87
88 /**
89 * Set a new a mode (text or number map)
90 * @param kb pointer to a Keyboard object
91 * @param mode the mode from 'lv_keyboard_mode_t'
92 */
93 void lv_keyboard_set_mode(lv_obj_t * kb, lv_keyboard_mode_t mode);
94
95 /**
96 * Automatically hide or show the cursor of the current Text Area
97 * @param kb pointer to a Keyboard object
98 * @param en true: show cursor on the current text area, false: hide cursor
99 */
100 void lv_keyboard_set_cursor_manage(lv_obj_t * kb, bool en);
101
102 /**
103 * Set a new map for the keyboard
104 * @param kb pointer to a Keyboard object
105 * @param mode keyboard map to alter 'lv_keyboard_mode_t'
106 * @param map pointer to a string array to describe the map.
107 * See 'lv_btnmatrix_set_map()' for more info.
108 */
109 void lv_keyboard_set_map(lv_obj_t * kb, lv_keyboard_mode_t mode, const char * map[]);
110
111 /**
112 * Set the button control map (hidden, disabled etc.) for the keyboard. The
113 * control map array will be copied and so may be deallocated after this
114 * function returns.
115 * @param kb pointer to a keyboard object
116 * @param mode keyboard ctrl map to alter 'lv_keyboard_mode_t'
117 * @param ctrl_map pointer to an array of `lv_btn_ctrl_t` control bytes.
118 * See: `lv_btnmatrix_set_ctrl_map` for more details.
119 */
120 void lv_keyboard_set_ctrl_map(lv_obj_t * kb, lv_keyboard_mode_t mode, const lv_btnmatrix_ctrl_t ctrl_map[]);
121
122 /*=====================
123 * Getter functions
124 *====================*/
125
126 /**
127 * Assign a Text Area to the Keyboard. The pressed characters will be put there.
128 * @param kb pointer to a Keyboard object
129 * @return pointer to the assigned Text Area object
130 */
131 lv_obj_t * lv_keyboard_get_textarea(const lv_obj_t * kb);
132
133 /**
134 * Set a new a mode (text or number map)
135 * @param kb pointer to a Keyboard object
136 * @return the current mode from 'lv_keyboard_mode_t'
137 */
138 lv_keyboard_mode_t lv_keyboard_get_mode(const lv_obj_t * kb);
139
140 /**
141 * Get the current cursor manage mode.
142 * @param kb pointer to a Keyboard object
143 * @return true: show cursor on the current text area, false: hide cursor
144 */
145 bool lv_keyboard_get_cursor_manage(const lv_obj_t * kb);
146
147 /**
148 * Get the current map of a keyboard
149 * @param kb pointer to a keyboard object
150 * @return the current map
151 */
lv_keyboard_get_map_array(const lv_obj_t * kb)152 static inline const char ** lv_keyboard_get_map_array(const lv_obj_t * kb)
153 {
154 return lv_btnmatrix_get_map_array(kb);
155 }
156
157 /*=====================
158 * Other functions
159 *====================*/
160
161 /**
162 * Default keyboard event to add characters to the Text area and change the map.
163 * If a custom `event_cb` is added to the keyboard this function be called from it to handle the
164 * button clicks
165 * @param kb pointer to a keyboard
166 * @param event the triggering event
167 */
168 void lv_keyboard_def_event_cb(lv_obj_t * kb, lv_event_t event);
169
170 /**********************
171 * MACROS
172 **********************/
173
174 #endif /*LV_USE_KEYBOARD*/
175
176 #ifdef __cplusplus
177 } /* extern "C" */
178 #endif
179
180 #endif /*LV_KEYBOARD_H*/
181
