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 "../../../widgets/lv_btnmatrix.h"
17
18 #if LV_USE_KEYBOARD
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 /*********************
30 * DEFINES
31 *********************/
32 #define LV_KEYBOARD_CTRL_BTN_FLAGS (LV_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_CLICK_TRIG | LV_BTNMATRIX_CTRL_CHECKED)
33
34 /**********************
35 * TYPEDEFS
36 **********************/
37
38 /** Current keyboard mode.*/
39 enum {
40 LV_KEYBOARD_MODE_TEXT_LOWER,
41 LV_KEYBOARD_MODE_TEXT_UPPER,
42 LV_KEYBOARD_MODE_SPECIAL,
43 LV_KEYBOARD_MODE_NUMBER,
44 LV_KEYBOARD_MODE_USER_1,
45 LV_KEYBOARD_MODE_USER_2,
46 LV_KEYBOARD_MODE_USER_3,
47 LV_KEYBOARD_MODE_USER_4,
48 };
49 typedef uint8_t lv_keyboard_mode_t;
50
51 /*Data of keyboard*/
52 typedef struct {
53 lv_btnmatrix_t btnm;
54 lv_obj_t * ta; /*Pointer to the assigned text area*/
55 lv_keyboard_mode_t mode; /*Key map type*/
56 uint8_t popovers : 1; /*Show button titles in popovers on press*/
57 } lv_keyboard_t;
58
59 extern const lv_obj_class_t lv_keyboard_class;
60
61 /**********************
62 * GLOBAL PROTOTYPES
63 **********************/
64
65 /**
66 * Create a Keyboard object
67 * @param parent pointer to an object, it will be the parent of the new keyboard
68 * @return pointer to the created keyboard
69 */
70 lv_obj_t * lv_keyboard_create(lv_obj_t * parent);
71
72 /*=====================
73 * Setter functions
74 *====================*/
75
76 /**
77 * Assign a Text Area to the Keyboard. The pressed characters will be put there.
78 * @param kb pointer to a Keyboard object
79 * @param ta pointer to a Text Area object to write there
80 */
81 void lv_keyboard_set_textarea(lv_obj_t * kb, lv_obj_t * ta);
82
83 /**
84 * Set a new a mode (text or number map)
85 * @param kb pointer to a Keyboard object
86 * @param mode the mode from 'lv_keyboard_mode_t'
87 */
88 void lv_keyboard_set_mode(lv_obj_t * kb, lv_keyboard_mode_t mode);
89
90 /**
91 * Show the button title in a popover when pressed.
92 * @param kb pointer to a Keyboard object
93 * @param en whether "popovers" mode is enabled
94 */
95 void lv_keyboard_set_popovers(lv_obj_t * kb, bool en);
96
97 /**
98 * Set a new map for the keyboard
99 * @param kb pointer to a Keyboard object
100 * @param mode keyboard map to alter 'lv_keyboard_mode_t'
101 * @param map pointer to a string array to describe the map.
102 * See 'lv_btnmatrix_set_map()' for more info.
103 */
104 void lv_keyboard_set_map(lv_obj_t * kb, lv_keyboard_mode_t mode, const char * map[],
105 const lv_btnmatrix_ctrl_t ctrl_map[]);
106
107 /*=====================
108 * Getter functions
109 *====================*/
110
111 /**
112 * Assign a Text Area to the Keyboard. The pressed characters will be put there.
113 * @param kb pointer to a Keyboard object
114 * @return pointer to the assigned Text Area object
115 */
116 lv_obj_t * lv_keyboard_get_textarea(const lv_obj_t * kb);
117
118 /**
119 * Set a new a mode (text or number map)
120 * @param kb pointer to a Keyboard object
121 * @return the current mode from 'lv_keyboard_mode_t'
122 */
123 lv_keyboard_mode_t lv_keyboard_get_mode(const lv_obj_t * kb);
124
125 /**
126 * Tell whether "popovers" mode is enabled or not.
127 * @param kb pointer to a Keyboard object
128 * @return true: "popovers" mode is enabled; false: disabled
129 */
130 bool lv_btnmatrix_get_popovers(const lv_obj_t * obj);
131
132 /**
133 * Get the current map of a keyboard
134 * @param kb pointer to a keyboard object
135 * @return the current map
136 */
lv_keyboard_get_map_array(const lv_obj_t * kb)137 static inline const char ** lv_keyboard_get_map_array(const lv_obj_t * kb)
138 {
139 return lv_btnmatrix_get_map(kb);
140 }
141
142 /**
143 * Get the index of the lastly "activated" button by the user (pressed, released, focused etc)
144 * Useful in the `event_cb` to get the text of the button, check if hidden etc.
145 * @param obj pointer to button matrix object
146 * @return index of the last released button (LV_BTNMATRIX_BTN_NONE: if unset)
147 */
lv_keyboard_get_selected_btn(const lv_obj_t * obj)148 static inline uint16_t lv_keyboard_get_selected_btn(const lv_obj_t * obj)
149 {
150 return lv_btnmatrix_get_selected_btn(obj);
151 }
152
153 /**
154 * Get the button's text
155 * @param obj pointer to button matrix object
156 * @param btn_id the index a button not counting new line characters.
157 * @return text of btn_index` button
158 */
lv_keyboard_get_btn_text(const lv_obj_t * obj,uint16_t btn_id)159 static inline const char * lv_keyboard_get_btn_text(const lv_obj_t * obj, uint16_t btn_id)
160 {
161 return lv_btnmatrix_get_btn_text(obj, btn_id);
162 }
163
164 /*=====================
165 * Other functions
166 *====================*/
167
168 /**
169 * Default keyboard event to add characters to the Text area and change the map.
170 * If a custom `event_cb` is added to the keyboard this function can be called from it to handle the
171 * button clicks
172 * @param kb pointer to a keyboard
173 * @param event the triggering event
174 */
175 void lv_keyboard_def_event_cb(lv_event_t * e);
176
177 /**********************
178 * MACROS
179 **********************/
180
181 #endif /*LV_USE_KEYBOARD*/
182
183 #ifdef __cplusplus
184 } /*extern "C"*/
185 #endif
186
187 #endif /*LV_KEYBOARD_H*/
188
