1 /**
2 * @file lv_ta.h
3 *
4 */
5
6 #ifndef LV_TA_H
7 #define LV_TA_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_TA != 0
23
24 /*Testing of dependencies*/
25 #if LV_USE_PAGE == 0
26 #error "lv_ta: lv_page is required. Enable it in lv_conf.h (LV_USE_PAGE 1) "
27 #endif
28
29 #if LV_USE_LABEL == 0
30 #error "lv_ta: lv_label is required. Enable it in lv_conf.h (LV_USE_LABEL 1) "
31 #endif
32
33 #include "../lv_core/lv_obj.h"
34 #include "lv_page.h"
35 #include "lv_label.h"
36
37 /*********************
38 * DEFINES
39 *********************/
40 #define LV_TA_CURSOR_LAST (0x7FFF) /*Put the cursor after the last character*/
41
42 /**********************
43 * TYPEDEFS
44 **********************/
45
46 /** Style of text area's cursor. */
47 enum {
48 LV_CURSOR_NONE, /**< No cursor */
49 LV_CURSOR_LINE, /**< Vertical line */
50 LV_CURSOR_BLOCK, /**< Rectangle */
51 LV_CURSOR_OUTLINE, /**< Outline around character */
52 LV_CURSOR_UNDERLINE, /**< Horizontal line under character */
53 LV_CURSOR_HIDDEN = 0x08, /**< This flag can be ORed to any of the other values to temporarily hide the cursor */
54 };
55 typedef uint8_t lv_cursor_type_t;
56
57 /*Data of text area*/
58 typedef struct
59 {
60 lv_page_ext_t page; /*Ext. of ancestor*/
61 /*New data for this type */
62 lv_obj_t * label; /*Label of the text area*/
63 lv_obj_t * placeholder; /*Place holder label. only visible if text is an empty string*/
64 char * pwd_tmp; /*Used to store the original text in password mode*/
65 const char * accapted_chars; /*Only these characters will be accepted. NULL: accept all*/
66 uint16_t max_length; /*The max. number of characters. 0: no limit*/
67 uint16_t pwd_show_time; /*Time to show characters in password mode before change them to '*' */
68 struct
69 {
70 const lv_style_t * style; /* Style of the cursor (NULL to use label's style)*/
71 lv_coord_t valid_x; /* Used when stepping up/down to a shorter line.
72 * (Used by the library)*/
73 uint16_t pos; /* The current cursor position
74 * (0: before 1st letter; 1: before 2nd letter ...)*/
75 uint16_t blink_time; /*Blink period*/
76 lv_area_t area; /* Cursor area relative to the Text Area*/
77 uint16_t txt_byte_pos; /* Byte index of the letter after (on) the cursor*/
78 lv_cursor_type_t type : 4; /* Shape of the cursor*/
79 uint8_t state : 1; /*Cursor is visible now or not (Handled by the library)*/
80 uint8_t click_pos : 1; /*1: Enable positioning the cursor by clicking the text area*/
81 } cursor;
82 #if LV_LABEL_TEXT_SEL
83 uint16_t tmp_sel_start; /*Temporary value*/
84 uint16_t tmp_sel_end; /*Temporary value*/
85 uint8_t text_sel_in_prog : 1; /*User is in process of selecting */
86 uint8_t text_sel_en : 1; /*Text can be selected on this text area*/
87 #endif
88 uint8_t pwd_mode : 1; /*Replace characters with '*' */
89 uint8_t one_line : 1; /*One line mode (ignore line breaks)*/
90 } lv_ta_ext_t;
91
92 /** Possible text areas tyles. */
93 enum {
94 LV_TA_STYLE_BG, /**< Text area background style */
95 LV_TA_STYLE_SB, /**< Scrollbar style */
96 LV_TA_STYLE_CURSOR, /**< Cursor style */
97 LV_TA_STYLE_EDGE_FLASH, /**< Edge flash style */
98 LV_TA_STYLE_PLACEHOLDER, /**< Placeholder style */
99 };
100 typedef uint8_t lv_ta_style_t;
101
102 /**********************
103 * GLOBAL PROTOTYPES
104 **********************/
105
106 /**
107 * Create a text area objects
108 * @param par pointer to an object, it will be the parent of the new text area
109 * @param copy pointer to a text area object, if not NULL then the new object will be copied from it
110 * @return pointer to the created text area
111 */
112 lv_obj_t * lv_ta_create(lv_obj_t * par, const lv_obj_t * copy);
113
114 /*======================
115 * Add/remove functions
116 *=====================*/
117
118 /**
119 * Insert a character to the current cursor position.
120 * To add a wide char, e.g. 'Á' use `lv_txt_encoded_conv_wc('Á')`
121 * @param ta pointer to a text area object
122 * @param c a character (e.g. 'a')
123 */
124 void lv_ta_add_char(lv_obj_t * ta, uint32_t c);
125
126 /**
127 * Insert a text to the current cursor position
128 * @param ta pointer to a text area object
129 * @param txt a '\0' terminated string to insert
130 */
131 void lv_ta_add_text(lv_obj_t * ta, const char * txt);
132
133 /**
134 * Delete a the left character from the current cursor position
135 * @param ta pointer to a text area object
136 */
137 void lv_ta_del_char(lv_obj_t * ta);
138
139 /**
140 * Delete the right character from the current cursor position
141 * @param ta pointer to a text area object
142 */
143 void lv_ta_del_char_forward(lv_obj_t * ta);
144
145 /*=====================
146 * Setter functions
147 *====================*/
148
149 /**
150 * Set the text of a text area
151 * @param ta pointer to a text area
152 * @param txt pointer to the text
153 */
154 void lv_ta_set_text(lv_obj_t * ta, const char * txt);
155
156 /**
157 * Set the placeholder text of a text area
158 * @param ta pointer to a text area
159 * @param txt pointer to the text
160 */
161 void lv_ta_set_placeholder_text(lv_obj_t * ta, const char * txt);
162
163 /**
164 * Set the cursor position
165 * @param obj pointer to a text area object
166 * @param pos the new cursor position in character index
167 * < 0 : index from the end of the text
168 * LV_TA_CURSOR_LAST: go after the last character
169 */
170 void lv_ta_set_cursor_pos(lv_obj_t * ta, int16_t pos);
171
172 /**
173 * Set the cursor type.
174 * @param ta pointer to a text area object
175 * @param cur_type: element of 'lv_cursor_type_t'
176 */
177 void lv_ta_set_cursor_type(lv_obj_t * ta, lv_cursor_type_t cur_type);
178
179 /**
180 * Enable/Disable the positioning of the the cursor by clicking the text on the text area.
181 * @param ta pointer to a text area object
182 * @param en true: enable click positions; false: disable
183 */
184 void lv_ta_set_cursor_click_pos(lv_obj_t * ta, bool en);
185
186 /**
187 * Enable/Disable password mode
188 * @param ta pointer to a text area object
189 * @param en true: enable, false: disable
190 */
191 void lv_ta_set_pwd_mode(lv_obj_t * ta, bool en);
192
193 /**
194 * Configure the text area to one line or back to normal
195 * @param ta pointer to a Text area object
196 * @param en true: one line, false: normal
197 */
198 void lv_ta_set_one_line(lv_obj_t * ta, bool en);
199
200 /**
201 * Set the alignment of the text area.
202 * In one line mode the text can be scrolled only with `LV_LABEL_ALIGN_LEFT`.
203 * This function should be called if the size of text area changes.
204 * @param ta pointer to a text are object
205 * @param align the desired alignment from `lv_label_align_t`. (LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)
206 */
207 void lv_ta_set_text_align(lv_obj_t * ta, lv_label_align_t align);
208
209 /**
210 * Set a list of characters. Only these characters will be accepted by the text area
211 * @param ta pointer to Text Area
212 * @param list list of characters. Only the pointer is saved. E.g. "+-.,0123456789"
213 */
214 void lv_ta_set_accepted_chars(lv_obj_t * ta, const char * list);
215
216 /**
217 * Set max length of a Text Area.
218 * @param ta pointer to Text Area
219 * @param num the maximal number of characters can be added (`lv_ta_set_text` ignores it)
220 */
221 void lv_ta_set_max_length(lv_obj_t * ta, uint16_t num);
222
223 /**
224 * In `LV_EVENT_INSERT` the text which planned to be inserted can be replaced by an other text.
225 * It can be used to add automatic formatting to the text area.
226 * @param ta pointer to a text area.
227 * @param txt pointer to a new string to insert. If `""` no text will be added.
228 * The variable must be live after the `event_cb` exists. (Should be `global` or
229 * `static`)
230 */
231 void lv_ta_set_insert_replace(lv_obj_t * ta, const char * txt);
232
233 /**
234 * Set the scroll bar mode of a text area
235 * @param ta pointer to a text area object
236 * @param sb_mode the new mode from 'lv_page_sb_mode_t' enum
237 */
lv_ta_set_sb_mode(lv_obj_t * ta,lv_sb_mode_t mode)238 static inline void lv_ta_set_sb_mode(lv_obj_t * ta, lv_sb_mode_t mode)
239 {
240 lv_page_set_sb_mode(ta, mode);
241 }
242
243 /**
244 * Enable the scroll propagation feature. If enabled then the Text area will move its parent if
245 * there is no more space to scroll.
246 * @param ta pointer to a Text area
247 * @param en true or false to enable/disable scroll propagation
248 */
lv_ta_set_scroll_propagation(lv_obj_t * ta,bool en)249 static inline void lv_ta_set_scroll_propagation(lv_obj_t * ta, bool en)
250 {
251 lv_page_set_scroll_propagation(ta, en);
252 }
253
254 /**
255 * Enable the edge flash effect. (Show an arc when the an edge is reached)
256 * @param page pointer to a Text Area
257 * @param en true or false to enable/disable end flash
258 */
lv_ta_set_edge_flash(lv_obj_t * ta,bool en)259 static inline void lv_ta_set_edge_flash(lv_obj_t * ta, bool en)
260 {
261 lv_page_set_edge_flash(ta, en);
262 }
263
264 /**
265 * Set a style of a text area
266 * @param ta pointer to a text area object
267 * @param type which style should be set
268 * @param style pointer to a style
269 */
270 void lv_ta_set_style(lv_obj_t * ta, lv_ta_style_t type, const lv_style_t * style);
271
272 /**
273 * Enable/disable selection mode.
274 * @param ta pointer to a text area object
275 * @param en true or false to enable/disable selection mode
276 */
277 void lv_ta_set_text_sel(lv_obj_t * ta, bool en);
278
279 /**
280 * Set how long show the password before changing it to '*'
281 * @param ta pointer to Text area
282 * @param time show time in milliseconds. 0: hide immediately.
283 */
284 void lv_ta_set_pwd_show_time(lv_obj_t * ta, uint16_t time);
285
286 /**
287 * Set cursor blink animation time
288 * @param ta pointer to Text area
289 * @param time blink period. 0: disable blinking
290 */
291 void lv_ta_set_cursor_blink_time(lv_obj_t * ta, uint16_t time);
292
293 /*=====================
294 * Getter functions
295 *====================*/
296
297 /**
298 * Get the text of a text area. In password mode it gives the real text (not '*'s).
299 * @param ta pointer to a text area object
300 * @return pointer to the text
301 */
302 const char * lv_ta_get_text(const lv_obj_t * ta);
303
304 /**
305 * Get the placeholder text of a text area
306 * @param ta pointer to a text area object
307 * @return pointer to the text
308 */
309 const char * lv_ta_get_placeholder_text(lv_obj_t * ta);
310
311 /**
312 * Get the label of a text area
313 * @param ta pointer to a text area object
314 * @return pointer to the label object
315 */
316 lv_obj_t * lv_ta_get_label(const lv_obj_t * ta);
317
318 /**
319 * Get the current cursor position in character index
320 * @param ta pointer to a text area object
321 * @return the cursor position
322 */
323 uint16_t lv_ta_get_cursor_pos(const lv_obj_t * ta);
324
325 /**
326 * Get the current cursor type.
327 * @param ta pointer to a text area object
328 * @return element of 'lv_cursor_type_t'
329 */
330 lv_cursor_type_t lv_ta_get_cursor_type(const lv_obj_t * ta);
331
332 /**
333 * Get whether the cursor click positioning is enabled or not.
334 * @param ta pointer to a text area object
335 * @return true: enable click positions; false: disable
336 */
337 bool lv_ta_get_cursor_click_pos(lv_obj_t * ta);
338
339 /**
340 * Get the password mode attribute
341 * @param ta pointer to a text area object
342 * @return true: password mode is enabled, false: disabled
343 */
344 bool lv_ta_get_pwd_mode(const lv_obj_t * ta);
345
346 /**
347 * Get the one line configuration attribute
348 * @param ta pointer to a text area object
349 * @return true: one line configuration is enabled, false: disabled
350 */
351 bool lv_ta_get_one_line(const lv_obj_t * ta);
352
353 /**
354 * Get a list of accepted characters.
355 * @param ta pointer to Text Area
356 * @return list of accented characters.
357 */
358 const char * lv_ta_get_accepted_chars(lv_obj_t * ta);
359
360 /**
361 * Set max length of a Text Area.
362 * @param ta pointer to Text Area
363 * @return the maximal number of characters to be add
364 */
365 uint16_t lv_ta_get_max_length(lv_obj_t * ta);
366
367 /**
368 * Get the scroll bar mode of a text area
369 * @param ta pointer to a text area object
370 * @return scrollbar mode from 'lv_page_sb_mode_t' enum
371 */
lv_ta_get_sb_mode(const lv_obj_t * ta)372 static inline lv_sb_mode_t lv_ta_get_sb_mode(const lv_obj_t * ta)
373 {
374 return lv_page_get_sb_mode(ta);
375 }
376
377 /**
378 * Get the scroll propagation property
379 * @param ta pointer to a Text area
380 * @return true or false
381 */
lv_ta_get_scroll_propagation(lv_obj_t * ta)382 static inline bool lv_ta_get_scroll_propagation(lv_obj_t * ta)
383 {
384 return lv_page_get_scroll_propagation(ta);
385 }
386
387 /**
388 * Get the scroll propagation property
389 * @param ta pointer to a Text area
390 * @return true or false
391 */
lv_ta_get_edge_flash(lv_obj_t * ta)392 static inline bool lv_ta_get_edge_flash(lv_obj_t * ta)
393 {
394 return lv_page_get_edge_flash(ta);
395 }
396
397 /**
398 * Get a style of a text area
399 * @param ta pointer to a text area object
400 * @param type which style should be get
401 * @return style pointer to a style
402 */
403 const lv_style_t * lv_ta_get_style(const lv_obj_t * ta, lv_ta_style_t type);
404
405 /**
406 * Find whether text is selected or not.
407 * @param ta Text area object
408 * @return whether text is selected or not
409 */
410 bool lv_ta_text_is_selected(const lv_obj_t * ta);
411
412 /**
413 * Find whether selection mode is enabled.
414 * @param ta pointer to a text area object
415 * @return true: selection mode is enabled, false: disabled
416 */
417 bool lv_ta_get_text_sel_en(lv_obj_t * ta);
418
419 /**
420 * Set how long show the password before changing it to '*'
421 * @param ta pointer to Text area
422 * @return show time in milliseconds. 0: hide immediately.
423 */
424 uint16_t lv_ta_get_pwd_show_time(lv_obj_t * ta);
425
426 /**
427 * Set cursor blink animation time
428 * @param ta pointer to Text area
429 * @return time blink period. 0: disable blinking
430 */
431 uint16_t lv_ta_get_cursor_blink_time(lv_obj_t * ta);
432
433 /*=====================
434 * Other functions
435 *====================*/
436
437 /**
438 * Clear the selection on the text area.
439 * @param ta Text area object
440 */
441 void lv_ta_clear_selection(lv_obj_t * ta);
442
443 /**
444 * Move the cursor one character right
445 * @param ta pointer to a text area object
446 */
447 void lv_ta_cursor_right(lv_obj_t * ta);
448
449 /**
450 * Move the cursor one character left
451 * @param ta pointer to a text area object
452 */
453 void lv_ta_cursor_left(lv_obj_t * ta);
454
455 /**
456 * Move the cursor one line down
457 * @param ta pointer to a text area object
458 */
459 void lv_ta_cursor_down(lv_obj_t * ta);
460
461 /**
462 * Move the cursor one line up
463 * @param ta pointer to a text area object
464 */
465 void lv_ta_cursor_up(lv_obj_t * ta);
466
467 /**********************
468 * MACROS
469 **********************/
470
471 #endif /*LV_USE_TA_H*/
472
473 #ifdef __cplusplus
474 } /* extern "C" */
475 #endif
476
477 #endif /*LV_TA_H*/
478