1 /**
2 * @file lv_kb.h
3 *
4 */
5
6 #ifndef LV_KB_H
7 #define LV_KB_H
8
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12
13 /*********************
14 * INCLUDES
15 *********************/
16 #ifdef LV_CONF_INCLUDE_SIMPLE
17 #include "lv_conf.h"
18 #else
19 #include "../../lv_conf.h"
20 #endif
21
22 #if LV_USE_KB != 0
23
24 /*Testing of dependencies*/
25 #if LV_USE_BTNM == 0
26 #error "lv_kb: lv_btnm is required. Enable it in lv_conf.h (LV_USE_BTNM 1) "
27 #endif
28
29 #if LV_USE_TA == 0
30 #error "lv_kb: lv_ta is required. Enable it in lv_conf.h (LV_USE_TA 1) "
31 #endif
32
33 #include "../lv_core/lv_obj.h"
34 #include "lv_btnm.h"
35
36 /*********************
37 * DEFINES
38 *********************/
39
40 /**********************
41 * TYPEDEFS
42 **********************/
43
44 /** Current keyboard mode. */
45 enum {
46 LV_KB_MODE_TEXT,
47 LV_KB_MODE_NUM,
48 };
49 typedef uint8_t lv_kb_mode_t;
50
51 /*Data of keyboard*/
52 typedef struct
53 {
54 lv_btnm_ext_t btnm; /*Ext. of ancestor*/
55 /*New data for this type */
56 lv_obj_t * ta; /*Pointer to the assigned text area*/
57 lv_kb_mode_t mode; /*Key map type*/
58 uint8_t cursor_mng : 1; /*1: automatically show/hide cursor when a text area is assigned or left*/
59 } lv_kb_ext_t;
60
61 enum {
62 LV_KB_STYLE_BG,
63 LV_KB_STYLE_BTN_REL,
64 LV_KB_STYLE_BTN_PR,
65 LV_KB_STYLE_BTN_TGL_REL,
66 LV_KB_STYLE_BTN_TGL_PR,
67 LV_KB_STYLE_BTN_INA,
68 };
69 typedef uint8_t lv_kb_style_t;
70
71 /**********************
72 * GLOBAL PROTOTYPES
73 **********************/
74
75 /**
76 * Create a keyboard objects
77 * @param par pointer to an object, it will be the parent of the new keyboard
78 * @param copy pointer to a keyboard object, if not NULL then the new object will be copied from it
79 * @return pointer to the created keyboard
80 */
81 lv_obj_t * lv_kb_create(lv_obj_t * par, const lv_obj_t * copy);
82
83 /*=====================
84 * Setter functions
85 *====================*/
86
87 /**
88 * Assign a Text Area to the Keyboard. The pressed characters will be put there.
89 * @param kb pointer to a Keyboard object
90 * @param ta pointer to a Text Area object to write there
91 */
92 void lv_kb_set_ta(lv_obj_t * kb, lv_obj_t * ta);
93
94 /**
95 * Set a new a mode (text or number map)
96 * @param kb pointer to a Keyboard object
97 * @param mode the mode from 'lv_kb_mode_t'
98 */
99 void lv_kb_set_mode(lv_obj_t * kb, lv_kb_mode_t mode);
100
101 /**
102 * Automatically hide or show the cursor of the current Text Area
103 * @param kb pointer to a Keyboard object
104 * @param en true: show cursor on the current text area, false: hide cursor
105 */
106 void lv_kb_set_cursor_manage(lv_obj_t * kb, bool en);
107
108 /**
109 * Set a new map for the keyboard
110 * @param kb pointer to a Keyboard object
111 * @param map pointer to a string array to describe the map.
112 * See 'lv_btnm_set_map()' for more info.
113 */
lv_kb_set_map(lv_obj_t * kb,const char * map[])114 static inline void lv_kb_set_map(lv_obj_t * kb, const char * map[])
115 {
116 lv_btnm_set_map(kb, map);
117 }
118
119 /**
120 * Set the button control map (hidden, disabled etc.) for the keyboard. The
121 * control map array will be copied and so may be deallocated after this
122 * function returns.
123 * @param kb pointer to a keyboard object
124 * @param ctrl_map pointer to an array of `lv_btn_ctrl_t` control bytes.
125 * See: `lv_btnm_set_ctrl_map` for more details.
126 */
lv_kb_set_ctrl_map(lv_obj_t * kb,const lv_btnm_ctrl_t ctrl_map[])127 static inline void lv_kb_set_ctrl_map(lv_obj_t * kb, const lv_btnm_ctrl_t ctrl_map[])
128 {
129 lv_btnm_set_ctrl_map(kb, ctrl_map);
130 }
131
132 /**
133 * Set a style of a keyboard
134 * @param kb pointer to a keyboard object
135 * @param type which style should be set
136 * @param style pointer to a style
137 */
138 void lv_kb_set_style(lv_obj_t * kb, lv_kb_style_t type, const lv_style_t * style);
139
140 /*=====================
141 * Getter functions
142 *====================*/
143
144 /**
145 * Assign a Text Area to the Keyboard. The pressed characters will be put there.
146 * @param kb pointer to a Keyboard object
147 * @return pointer to the assigned Text Area object
148 */
149 lv_obj_t * lv_kb_get_ta(const lv_obj_t * kb);
150
151 /**
152 * Set a new a mode (text or number map)
153 * @param kb pointer to a Keyboard object
154 * @return the current mode from 'lv_kb_mode_t'
155 */
156 lv_kb_mode_t lv_kb_get_mode(const lv_obj_t * kb);
157
158 /**
159 * Get the current cursor manage mode.
160 * @param kb pointer to a Keyboard object
161 * @return true: show cursor on the current text area, false: hide cursor
162 */
163 bool lv_kb_get_cursor_manage(const lv_obj_t * kb);
164
165 /**
166 * Get the current map of a keyboard
167 * @param kb pointer to a keyboard object
168 * @return the current map
169 */
lv_kb_get_map_array(const lv_obj_t * kb)170 static inline const char ** lv_kb_get_map_array(const lv_obj_t * kb)
171 {
172 return lv_btnm_get_map_array(kb);
173 }
174
175 /**
176 * Get a style of a keyboard
177 * @param kb pointer to a keyboard object
178 * @param type which style should be get
179 * @return style pointer to a style
180 */
181 const lv_style_t * lv_kb_get_style(const lv_obj_t * kb, lv_kb_style_t type);
182
183 /*=====================
184 * Other functions
185 *====================*/
186
187 /**
188 * Default keyboard event to add characters to the Text area and change the map.
189 * If a custom `event_cb` is added to the keyboard this function be called from it to handle the
190 * button clicks
191 * @param kb pointer to a keyboard
192 * @param event the triggering event
193 */
194 void lv_kb_def_event_cb(lv_obj_t * kb, lv_event_t event);
195
196 /**********************
197 * MACROS
198 **********************/
199
200 #endif /*LV_USE_KB*/
201
202 #ifdef __cplusplus
203 } /* extern "C" */
204 #endif
205
206 #endif /*LV_KB_H*/
207