1 /** 2 * @file lv_textarea.h 3 * 4 */ 5 6 #ifndef LV_TEXTAREA_H 7 #define LV_TEXTAREA_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_TEXTAREA != 0 19 20 /*Testing of dependencies*/ 21 #if LV_USE_LABEL == 0 22 #error "lv_ta: lv_label is required. Enable it in lv_conf.h (LV_USE_LABEL 1)" 23 #endif 24 25 #include "../core/lv_obj.h" 26 #include "lv_label.h" 27 28 /********************* 29 * DEFINES 30 *********************/ 31 #define LV_TEXTAREA_CURSOR_LAST (0x7FFF) /*Put the cursor after the last character*/ 32 33 LV_EXPORT_CONST_INT(LV_TEXTAREA_CURSOR_LAST); 34 35 /********************** 36 * TYPEDEFS 37 **********************/ 38 39 /*Data of text area*/ 40 typedef struct { 41 lv_obj_t obj; 42 lv_obj_t * label; /*Label of the text area*/ 43 char * placeholder_txt; /*Place holder label. only visible if text is an empty string*/ 44 char * pwd_tmp; /*Used to store the original text in password mode*/ 45 char * pwd_bullet; /*Replacement characters displayed in password mode*/ 46 const char * accepted_chars; /*Only these characters will be accepted. NULL: accept all*/ 47 uint32_t max_length; /*The max. number of characters. 0: no limit*/ 48 uint16_t pwd_show_time; /*Time to show characters in password mode before change them to '*'*/ 49 struct { 50 lv_coord_t valid_x; /*Used when stepping up/down to a shorter line. 51 *(Used by the library)*/ 52 uint32_t pos; /*The current cursor position 53 *(0: before 1st letter; 1: before 2nd letter ...)*/ 54 lv_area_t area; /*Cursor area relative to the Text Area*/ 55 uint32_t txt_byte_pos; /*Byte index of the letter after (on) the cursor*/ 56 uint8_t show : 1; /*Cursor is visible now or not (Handled by the library)*/ 57 uint8_t click_pos : 1; /*1: Enable positioning the cursor by clicking the text area*/ 58 } cursor; 59 #if LV_LABEL_TEXT_SELECTION 60 uint32_t sel_start; /*Temporary values for text selection*/ 61 uint32_t sel_end; 62 uint8_t text_sel_in_prog : 1; /*User is in process of selecting*/ 63 uint8_t text_sel_en : 1; /*Text can be selected on this text area*/ 64 #endif 65 uint8_t pwd_mode : 1; /*Replace characters with '*'*/ 66 uint8_t one_line : 1; /*One line mode (ignore line breaks)*/ 67 } lv_textarea_t; 68 69 extern const lv_obj_class_t lv_textarea_class; 70 71 enum { 72 LV_PART_TEXTAREA_PLACEHOLDER = LV_PART_CUSTOM_FIRST, 73 }; 74 75 /********************** 76 * GLOBAL PROTOTYPES 77 **********************/ 78 79 /** 80 * Create a text area object 81 * @param parent pointer to an object, it will be the parent of the new text area 82 * @return pointer to the created text area 83 */ 84 lv_obj_t * lv_textarea_create(lv_obj_t * parent); 85 86 /*====================== 87 * Add/remove functions 88 *=====================*/ 89 90 /** 91 * Insert a character to the current cursor position. 92 * To add a wide char, e.g. 'Á' use `_lv_txt_encoded_conv_wc('Á')` 93 * @param obj pointer to a text area object 94 * @param c a character (e.g. 'a') 95 */ 96 void lv_textarea_add_char(lv_obj_t * obj, uint32_t c); 97 98 /** 99 * Insert a text to the current cursor position 100 * @param obj pointer to a text area object 101 * @param txt a '\0' terminated string to insert 102 */ 103 void lv_textarea_add_text(lv_obj_t * obj, const char * txt); 104 105 /** 106 * Delete a the left character from the current cursor position 107 * @param obj pointer to a text area object 108 */ 109 void lv_textarea_del_char(lv_obj_t * obj); 110 111 /** 112 * Delete the right character from the current cursor position 113 * @param obj pointer to a text area object 114 */ 115 void lv_textarea_del_char_forward(lv_obj_t * obj); 116 117 /*===================== 118 * Setter functions 119 *====================*/ 120 121 /** 122 * Set the text of a text area 123 * @param obj pointer to a text area object 124 * @param txt pointer to the text 125 */ 126 void lv_textarea_set_text(lv_obj_t * obj, const char * txt); 127 128 /** 129 * Set the placeholder text of a text area 130 * @param obj pointer to a text area object 131 * @param txt pointer to the text 132 */ 133 void lv_textarea_set_placeholder_text(lv_obj_t * obj, const char * txt); 134 135 /** 136 * Set the cursor position 137 * @param obj pointer to a text area object 138 * @param pos the new cursor position in character index 139 * < 0 : index from the end of the text 140 * LV_TEXTAREA_CURSOR_LAST: go after the last character 141 */ 142 void lv_textarea_set_cursor_pos(lv_obj_t * obj, int32_t pos); 143 144 /** 145 * Enable/Disable the positioning of the cursor by clicking the text on the text area. 146 * @param obj pointer to a text area object 147 * @param en true: enable click positions; false: disable 148 */ 149 void lv_textarea_set_cursor_click_pos(lv_obj_t * obj, bool en); 150 151 /** 152 * Enable/Disable password mode 153 * @param obj pointer to a text area object 154 * @param en true: enable, false: disable 155 */ 156 void lv_textarea_set_password_mode(lv_obj_t * obj, bool en); 157 158 /** 159 * Set the replacement characters to show in password mode 160 * @param obj pointer to a text area object 161 * @param bullet pointer to the replacement text 162 */ 163 void lv_textarea_set_password_bullet(lv_obj_t * obj, const char * bullet); 164 165 /** 166 * Configure the text area to one line or back to normal 167 * @param obj pointer to a text area object 168 * @param en true: one line, false: normal 169 */ 170 void lv_textarea_set_one_line(lv_obj_t * obj, bool en); 171 172 /** 173 * Set a list of characters. Only these characters will be accepted by the text area 174 * @param obj pointer to a text area object 175 * @param list list of characters. Only the pointer is saved. E.g. "+-.,0123456789" 176 */ 177 void lv_textarea_set_accepted_chars(lv_obj_t * obj, const char * list); 178 179 /** 180 * Set max length of a Text Area. 181 * @param obj pointer to a text area object 182 * @param num the maximal number of characters can be added (`lv_textarea_set_text` ignores it) 183 */ 184 void lv_textarea_set_max_length(lv_obj_t * obj, uint32_t num); 185 186 /** 187 * In `LV_EVENT_INSERT` the text which planned to be inserted can be replaced by an other text. 188 * It can be used to add automatic formatting to the text area. 189 * @param obj pointer to a text area object 190 * @param txt pointer to a new string to insert. If `""` no text will be added. 191 * The variable must be live after the `event_cb` exists. (Should be `global` or `static`) 192 */ 193 void lv_textarea_set_insert_replace(lv_obj_t * obj, const char * txt); 194 195 /** 196 * Enable/disable selection mode. 197 * @param obj pointer to a text area object 198 * @param en true or false to enable/disable selection mode 199 */ 200 void lv_textarea_set_text_selection(lv_obj_t * obj, bool en); 201 202 /** 203 * Set how long show the password before changing it to '*' 204 * @param obj pointer to a text area object 205 * @param time show time in milliseconds. 0: hide immediately. 206 */ 207 void lv_textarea_set_password_show_time(lv_obj_t * obj, uint16_t time); 208 209 /** 210 * Deprecated: use the normal text_align style property instead 211 * Set the label's alignment. 212 * It sets where the label is aligned (in one line mode it can be smaller than the text area) 213 * and how the lines of the area align in case of multiline text area 214 * @param obj pointer to a text area object 215 * @param align the align mode from ::lv_text_align_t 216 */ 217 void lv_textarea_set_align(lv_obj_t * obj, lv_text_align_t align); 218 219 /*===================== 220 * Getter functions 221 *====================*/ 222 223 /** 224 * Get the text of a text area. In password mode it gives the real text (not '*'s). 225 * @param obj pointer to a text area object 226 * @return pointer to the text 227 */ 228 const char * lv_textarea_get_text(const lv_obj_t * obj); 229 230 /** 231 * Get the placeholder text of a text area 232 * @param obj pointer to a text area object 233 * @return pointer to the text 234 */ 235 const char * lv_textarea_get_placeholder_text(lv_obj_t * obj); 236 237 /** 238 * Get the label of a text area 239 * @param obj pointer to a text area object 240 * @return pointer to the label object 241 */ 242 lv_obj_t * lv_textarea_get_label(const lv_obj_t * obj); 243 244 /** 245 * Get the current cursor position in character index 246 * @param obj pointer to a text area object 247 * @return the cursor position 248 */ 249 uint32_t lv_textarea_get_cursor_pos(const lv_obj_t * obj); 250 251 /** 252 * Get whether the cursor click positioning is enabled or not. 253 * @param obj pointer to a text area object 254 * @return true: enable click positions; false: disable 255 */ 256 bool lv_textarea_get_cursor_click_pos(lv_obj_t * obj); 257 258 /** 259 * Get the password mode attribute 260 * @param obj pointer to a text area object 261 * @return true: password mode is enabled, false: disabled 262 */ 263 bool lv_textarea_get_password_mode(const lv_obj_t * obj); 264 265 /** 266 * Get the replacement characters to show in password mode 267 * @param obj pointer to a text area object 268 * @return pointer to the replacement text 269 */ 270 const char * lv_textarea_get_password_bullet(lv_obj_t * obj); 271 272 /** 273 * Get the one line configuration attribute 274 * @param obj pointer to a text area object 275 * @return true: one line configuration is enabled, false: disabled 276 */ 277 bool lv_textarea_get_one_line(const lv_obj_t * obj); 278 279 /** 280 * Get a list of accepted characters. 281 * @param obj pointer to a text area object 282 * @return list of accented characters. 283 */ 284 const char * lv_textarea_get_accepted_chars(lv_obj_t * obj); 285 286 /** 287 * Get max length of a Text Area. 288 * @param obj pointer to a text area object 289 * @return the maximal number of characters to be add 290 */ 291 uint32_t lv_textarea_get_max_length(lv_obj_t * obj); 292 293 /** 294 * Find whether text is selected or not. 295 * @param obj pointer to a text area object 296 * @return whether text is selected or not 297 */ 298 bool lv_textarea_text_is_selected(const lv_obj_t * obj); 299 300 /** 301 * Find whether selection mode is enabled. 302 * @param obj pointer to a text area object 303 * @return true: selection mode is enabled, false: disabled 304 */ 305 bool lv_textarea_get_text_selection(lv_obj_t * obj); 306 307 /** 308 * Set how long show the password before changing it to '*' 309 * @param obj pointer to a text area object 310 * @return show time in milliseconds. 0: hide immediately. 311 */ 312 uint16_t lv_textarea_get_password_show_time(lv_obj_t * obj); 313 314 /*===================== 315 * Other functions 316 *====================*/ 317 318 /** 319 * Clear the selection on the text area. 320 * @param obj pointer to a text area object 321 */ 322 void lv_textarea_clear_selection(lv_obj_t * obj); 323 324 /** 325 * Move the cursor one character right 326 * @param obj pointer to a text area object 327 */ 328 void lv_textarea_cursor_right(lv_obj_t * obj); 329 330 /** 331 * Move the cursor one character left 332 * @param obj pointer to a text area object 333 */ 334 void lv_textarea_cursor_left(lv_obj_t * obj); 335 336 /** 337 * Move the cursor one line down 338 * @param obj pointer to a text area object 339 */ 340 void lv_textarea_cursor_down(lv_obj_t * obj); 341 342 /** 343 * Move the cursor one line up 344 * @param obj pointer to a text area object 345 */ 346 void lv_textarea_cursor_up(lv_obj_t * obj); 347 348 /********************** 349 * MACROS 350 **********************/ 351 352 #endif /*LV_USE_TEXTAREA_H*/ 353 354 #ifdef __cplusplus 355 } /*extern "C"*/ 356 #endif 357 358 #endif /*LV_TEXTAREA_H*/ 359
