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 "../buttonmatrix/lv_buttonmatrix.h" 17 18 #if LV_USE_KEYBOARD 19 20 /*Testing of dependencies*/ 21 #if LV_USE_BUTTONMATRIX == 0 22 #error "lv_buttonmatrix is required. Enable it in lv_conf.h (LV_USE_BUTTONMATRIX 1) " 23 #endif 24 25 #if LV_USE_TEXTAREA == 0 26 #error "lv_textarea is required. Enable it in lv_conf.h (LV_USE_TEXTAREA 1) " 27 #endif 28 29 /********************* 30 * DEFINES 31 *********************/ 32 #define LV_KEYBOARD_CTRL_BUTTON_FLAGS (LV_BUTTONMATRIX_CTRL_NO_REPEAT | LV_BUTTONMATRIX_CTRL_CLICK_TRIG | LV_BUTTONMATRIX_CTRL_CHECKED) 33 34 /********************** 35 * TYPEDEFS 36 **********************/ 37 38 /** Current keyboard mode.*/ 39 typedef 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 #if LV_USE_ARABIC_PERSIAN_CHARS == 1 49 LV_KEYBOARD_MODE_TEXT_ARABIC 50 #endif 51 } lv_keyboard_mode_t; 52 53 #if LV_USE_OBJ_PROPERTY 54 enum { 55 LV_PROPERTY_ID(KEYBOARD, TEXTAREA, LV_PROPERTY_TYPE_OBJ, 0), 56 LV_PROPERTY_ID(KEYBOARD, MODE, LV_PROPERTY_TYPE_INT, 1), 57 LV_PROPERTY_ID(KEYBOARD, POPOVERS, LV_PROPERTY_TYPE_INT, 2), 58 LV_PROPERTY_ID(KEYBOARD, SELECTED_BUTTON, LV_PROPERTY_TYPE_INT, 3), 59 LV_PROPERTY_KEYBOARD_END, 60 }; 61 #endif 62 63 LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_keyboard_class; 64 65 /********************** 66 * GLOBAL PROTOTYPES 67 **********************/ 68 69 /** 70 * Create a Keyboard object 71 * @param parent pointer to an object, it will be the parent of the new keyboard 72 * @return pointer to the created keyboard 73 */ 74 lv_obj_t * lv_keyboard_create(lv_obj_t * parent); 75 76 /*===================== 77 * Setter functions 78 *====================*/ 79 80 /** 81 * Assign a Text Area to the Keyboard. The pressed characters will be put there. 82 * @param kb pointer to a Keyboard object 83 * @param ta pointer to a Text Area object to write there 84 */ 85 void lv_keyboard_set_textarea(lv_obj_t * kb, lv_obj_t * ta); 86 87 /** 88 * Set a new a mode (text or number map) 89 * @param kb pointer to a Keyboard object 90 * @param mode the mode from 'lv_keyboard_mode_t' 91 */ 92 void lv_keyboard_set_mode(lv_obj_t * kb, lv_keyboard_mode_t mode); 93 94 /** 95 * Show the button title in a popover when pressed. 96 * @param kb pointer to a Keyboard object 97 * @param en whether "popovers" mode is enabled 98 */ 99 void lv_keyboard_set_popovers(lv_obj_t * kb, bool en); 100 101 /** 102 * Set a new map for the keyboard 103 * @param kb pointer to a Keyboard object 104 * @param mode keyboard map to alter 'lv_keyboard_mode_t' 105 * @param map pointer to a string array to describe the map. 106 * See 'lv_buttonmatrix_set_map()' for more info. 107 * @param ctrl_map See 'lv_buttonmatrix_set_ctrl_map()' for more info. 108 109 */ 110 void lv_keyboard_set_map(lv_obj_t * kb, lv_keyboard_mode_t mode, const char * const map[], 111 const lv_buttonmatrix_ctrl_t ctrl_map[]); 112 113 /*===================== 114 * Getter functions 115 *====================*/ 116 117 /** 118 * Assign a Text Area to the Keyboard. The pressed characters will be put there. 119 * @param kb pointer to a Keyboard object 120 * @return pointer to the assigned Text Area object 121 */ 122 lv_obj_t * lv_keyboard_get_textarea(const lv_obj_t * kb); 123 124 /** 125 * Set a new a mode (text or number map) 126 * @param kb pointer to a Keyboard object 127 * @return the current mode from 'lv_keyboard_mode_t' 128 */ 129 lv_keyboard_mode_t lv_keyboard_get_mode(const lv_obj_t * kb); 130 131 /** 132 * Tell whether "popovers" mode is enabled or not. 133 * @param obj pointer to a Keyboard object 134 * @return true: "popovers" mode is enabled; false: disabled 135 */ 136 bool lv_keyboard_get_popovers(const lv_obj_t * obj); 137 138 /** 139 * Get the current map of a keyboard 140 * @param kb pointer to a keyboard object 141 * @return the current map 142 */ 143 const char * const * lv_keyboard_get_map_array(const lv_obj_t * kb); 144 145 /** 146 * Get the index of the lastly "activated" button by the user (pressed, released, focused etc) 147 * Useful in the `event_cb` to get the text of the button, check if hidden etc. 148 * @param obj pointer to button matrix object 149 * @return index of the last released button (LV_BUTTONMATRIX_BUTTON_NONE: if unset) 150 */ 151 uint32_t lv_keyboard_get_selected_button(const lv_obj_t * obj); 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 */ 159 const char * lv_keyboard_get_button_text(const lv_obj_t * obj, uint32_t btn_id); 160 161 /*===================== 162 * Other functions 163 *====================*/ 164 165 /** 166 * Default keyboard event to add characters to the Text area and change the map. 167 * If a custom `event_cb` is added to the keyboard this function can be called from it to handle the 168 * button clicks 169 * @param e the triggering event 170 */ 171 void lv_keyboard_def_event_cb(lv_event_t * e); 172 173 /********************** 174 * MACROS 175 **********************/ 176 177 #endif /*LV_USE_KEYBOARD*/ 178 179 #ifdef __cplusplus 180 } /*extern "C"*/ 181 #endif 182 183 #endif /*LV_KEYBOARD_H*/ 184
