1 /**
2 * @file lv_ta.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_PAGE == 0
22 #error "lv_ta: lv_page is required. Enable it in lv_conf.h (LV_USE_PAGE 1) "
23 #endif
24
25 #if LV_USE_LABEL == 0
26 #error "lv_ta: lv_label is required. Enable it in lv_conf.h (LV_USE_LABEL 1) "
27 #endif
28
29 #include "../lv_core/lv_obj.h"
30 #include "lv_page.h"
31 #include "lv_label.h"
32
33 /*********************
34 * DEFINES
35 *********************/
36 #define LV_TEXTAREA_CURSOR_LAST (0x7FFF) /*Put the cursor after the last character*/
37
38 LV_EXPORT_CONST_INT(LV_TEXTAREA_CURSOR_LAST);
39
40 /**********************
41 * TYPEDEFS
42 **********************/
43
44 /*Data of text area*/
45 typedef struct {
46 lv_page_ext_t page; /*Ext. of ancestor*/
47 /*New data for this type */
48 lv_obj_t * label; /*Label of the text area*/
49 char * placeholder_txt; /*Place holder label. only visible if text is an empty string*/
50 lv_style_list_t style_placeholder;
51 char * pwd_tmp; /*Used to store the original text in password mode*/
52 const char * accapted_chars; /*Only these characters will be accepted. NULL: accept all*/
53 uint32_t max_length; /*The max. number of characters. 0: no limit*/
54 uint16_t pwd_show_time; /*Time to show characters in password mode before change them to '*' */
55 struct {
56 lv_style_list_t style; /* Style of the cursor (NULL to use label's style)*/
57 lv_coord_t valid_x; /* Used when stepping up/down to a shorter line.
58 * (Used by the library)*/
59 uint32_t pos; /* The current cursor position
60 * (0: before 1st letter; 1: before 2nd letter ...)*/
61 uint16_t blink_time; /*Blink period*/
62 lv_area_t area; /* Cursor area relative to the Text Area*/
63 uint32_t txt_byte_pos; /* Byte index of the letter after (on) the cursor*/
64 uint8_t state : 1; /*Cursor is visible now or not (Handled by the library)*/
65 uint8_t hidden : 1; /*Cursor is hidden by he user */
66 uint8_t click_pos : 1; /*1: Enable positioning the cursor by clicking the text area*/
67 } cursor;
68 #if LV_LABEL_TEXT_SEL
69 uint32_t sel_start; /*Temporary values for text selection*/
70 uint32_t sel_end;
71 uint8_t text_sel_in_prog : 1; /*User is in process of selecting */
72 uint8_t text_sel_en : 1; /*Text can be selected on this text area*/
73 #endif
74 uint8_t pwd_mode : 1; /*Replace characters with '*' */
75 uint8_t one_line : 1; /*One line mode (ignore line breaks)*/
76 } lv_textarea_ext_t;
77
78 /** Possible text areas styles. */
79 enum {
80 LV_TEXTAREA_PART_BG = LV_PAGE_PART_BG, /**< Text area background style */
81 LV_TEXTAREA_PART_SCROLLBAR = LV_PAGE_PART_SCROLLBAR, /**< Scrollbar style */
82 LV_TEXTAREA_PART_EDGE_FLASH = LV_PAGE_PART_EDGE_FLASH, /**< Edge flash style */
83 LV_TEXTAREA_PART_CURSOR = _LV_PAGE_PART_VIRTUAL_LAST, /**< Cursor style */
84 LV_TEXTAREA_PART_PLACEHOLDER, /**< Placeholder style */
85 _LV_TEXTAREA_PART_VIRTUAL_LAST,
86
87 _LV_TEXTAREA_PART_REAL_LAST = _LV_PAGE_PART_REAL_LAST,
88 };
89 typedef uint8_t lv_textarea_style_t;
90
91 /**********************
92 * GLOBAL PROTOTYPES
93 **********************/
94
95 /**
96 * Create a text area objects
97 * @param par pointer to an object, it will be the parent of the new text area
98 * @param copy pointer to a text area object, if not NULL then the new object will be copied from it
99 * @return pointer to the created text area
100 */
101 lv_obj_t * lv_textarea_create(lv_obj_t * par, const lv_obj_t * copy);
102
103 /*======================
104 * Add/remove functions
105 *=====================*/
106
107 /**
108 * Insert a character to the current cursor position.
109 * To add a wide char, e.g. 'Á' use `_lv_txt_encoded_conv_wc('Á')`
110 * @param ta pointer to a text area object
111 * @param c a character (e.g. 'a')
112 */
113 void lv_textarea_add_char(lv_obj_t * ta, uint32_t c);
114
115 /**
116 * Insert a text to the current cursor position
117 * @param ta pointer to a text area object
118 * @param txt a '\0' terminated string to insert
119 */
120 void lv_textarea_add_text(lv_obj_t * ta, const char * txt);
121
122 /**
123 * Delete a the left character from the current cursor position
124 * @param ta pointer to a text area object
125 */
126 void lv_textarea_del_char(lv_obj_t * ta);
127
128 /**
129 * Delete the right character from the current cursor position
130 * @param ta pointer to a text area object
131 */
132 void lv_textarea_del_char_forward(lv_obj_t * ta);
133
134 /*=====================
135 * Setter functions
136 *====================*/
137
138 /**
139 * Set the text of a text area
140 * @param ta pointer to a text area
141 * @param txt pointer to the text
142 */
143 void lv_textarea_set_text(lv_obj_t * ta, const char * txt);
144
145 /**
146 * Set the placeholder text of a text area
147 * @param ta pointer to a text area
148 * @param txt pointer to the text
149 */
150 void lv_textarea_set_placeholder_text(lv_obj_t * ta, const char * txt);
151
152 /**
153 * Set the cursor position
154 * @param obj pointer to a text area object
155 * @param pos the new cursor position in character index
156 * < 0 : index from the end of the text
157 * LV_TEXTAREA_CURSOR_LAST: go after the last character
158 */
159 void lv_textarea_set_cursor_pos(lv_obj_t * ta, int32_t pos);
160
161 /**
162 * Hide/Unhide the cursor.
163 * @param ta pointer to a text area object
164 * @param hide: true: hide the cursor
165 */
166 void lv_textarea_set_cursor_hidden(lv_obj_t * ta, bool hide);
167
168 /**
169 * Enable/Disable the positioning of the the cursor by clicking the text on the text area.
170 * @param ta pointer to a text area object
171 * @param en true: enable click positions; false: disable
172 */
173 void lv_textarea_set_cursor_click_pos(lv_obj_t * ta, bool en);
174
175 /**
176 * Enable/Disable password mode
177 * @param ta pointer to a text area object
178 * @param en true: enable, false: disable
179 */
180 void lv_textarea_set_pwd_mode(lv_obj_t * ta, bool en);
181
182 /**
183 * Configure the text area to one line or back to normal
184 * @param ta pointer to a Text area object
185 * @param en true: one line, false: normal
186 */
187 void lv_textarea_set_one_line(lv_obj_t * ta, bool en);
188
189 /**
190 * Set the alignment of the text area.
191 * In one line mode the text can be scrolled only with `LV_LABEL_ALIGN_LEFT`.
192 * This function should be called if the size of text area changes.
193 * @param ta pointer to a text are object
194 * @param align the desired alignment from `lv_label_align_t`. (LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)
195 */
196 void lv_textarea_set_text_align(lv_obj_t * ta, lv_label_align_t align);
197
198 /**
199 * Set a list of characters. Only these characters will be accepted by the text area
200 * @param ta pointer to Text Area
201 * @param list list of characters. Only the pointer is saved. E.g. "+-.,0123456789"
202 */
203 void lv_textarea_set_accepted_chars(lv_obj_t * ta, const char * list);
204
205 /**
206 * Set max length of a Text Area.
207 * @param ta pointer to Text Area
208 * @param num the maximal number of characters can be added (`lv_textarea_set_text` ignores it)
209 */
210 void lv_textarea_set_max_length(lv_obj_t * ta, uint32_t num);
211
212 /**
213 * In `LV_EVENT_INSERT` the text which planned to be inserted can be replaced by an other text.
214 * It can be used to add automatic formatting to the text area.
215 * @param ta pointer to a text area.
216 * @param txt pointer to a new string to insert. If `""` no text will be added.
217 * The variable must be live after the `event_cb` exists. (Should be `global` or
218 * `static`)
219 */
220 void lv_textarea_set_insert_replace(lv_obj_t * ta, const char * txt);
221
222 /**
223 * Set the scroll bar mode of a text area
224 * @param ta pointer to a text area object
225 * @param sb_mode the new mode from 'lv_scrollbar_mode_t' enum
226 */
lv_textarea_set_scrollbar_mode(lv_obj_t * ta,lv_scrollbar_mode_t mode)227 static inline void lv_textarea_set_scrollbar_mode(lv_obj_t * ta, lv_scrollbar_mode_t mode)
228 {
229 lv_page_set_scrollbar_mode(ta, mode);
230 }
231
232 /**
233 * Enable the scroll propagation feature. If enabled then the Text area will move its parent if
234 * there is no more space to scroll.
235 * @param ta pointer to a Text area
236 * @param en true or false to enable/disable scroll propagation
237 */
lv_textarea_set_scroll_propagation(lv_obj_t * ta,bool en)238 static inline void lv_textarea_set_scroll_propagation(lv_obj_t * ta, bool en)
239 {
240 lv_page_set_scroll_propagation(ta, en);
241 }
242
243 /**
244 * Enable the edge flash effect. (Show an arc when the an edge is reached)
245 * @param page pointer to a Text Area
246 * @param en true or false to enable/disable end flash
247 */
lv_textarea_set_edge_flash(lv_obj_t * ta,bool en)248 static inline void lv_textarea_set_edge_flash(lv_obj_t * ta, bool en)
249 {
250 lv_page_set_edge_flash(ta, en);
251 }
252
253 /**
254 * Enable/disable selection mode.
255 * @param ta pointer to a text area object
256 * @param en true or false to enable/disable selection mode
257 */
258 void lv_textarea_set_text_sel(lv_obj_t * ta, bool en);
259
260 /**
261 * Set how long show the password before changing it to '*'
262 * @param ta pointer to Text area
263 * @param time show time in milliseconds. 0: hide immediately.
264 */
265 void lv_textarea_set_pwd_show_time(lv_obj_t * ta, uint16_t time);
266
267 /**
268 * Set cursor blink animation time
269 * @param ta pointer to Text area
270 * @param time blink period. 0: disable blinking
271 */
272 void lv_textarea_set_cursor_blink_time(lv_obj_t * ta, uint16_t time);
273
274 /*=====================
275 * Getter functions
276 *====================*/
277
278 /**
279 * Get the text of a text area. In password mode it gives the real text (not '*'s).
280 * @param ta pointer to a text area object
281 * @return pointer to the text
282 */
283 const char * lv_textarea_get_text(const lv_obj_t * ta);
284
285 /**
286 * Get the placeholder text of a text area
287 * @param ta pointer to a text area object
288 * @return pointer to the text
289 */
290 const char * lv_textarea_get_placeholder_text(lv_obj_t * ta);
291
292 /**
293 * Get the label of a text area
294 * @param ta pointer to a text area object
295 * @return pointer to the label object
296 */
297 lv_obj_t * lv_textarea_get_label(const lv_obj_t * ta);
298
299 /**
300 * Get the current cursor position in character index
301 * @param ta pointer to a text area object
302 * @return the cursor position
303 */
304 uint32_t lv_textarea_get_cursor_pos(const lv_obj_t * ta);
305
306 /**
307 * Get whether the cursor is hidden or not
308 * @param ta pointer to a text area object
309 * @return true: the cursor is hidden
310 */
311 bool lv_textarea_get_cursor_hidden(const lv_obj_t * ta);
312
313 /**
314 * Get whether the cursor click positioning is enabled or not.
315 * @param ta pointer to a text area object
316 * @return true: enable click positions; false: disable
317 */
318 bool lv_textarea_get_cursor_click_pos(lv_obj_t * ta);
319
320 /**
321 * Get the password mode attribute
322 * @param ta pointer to a text area object
323 * @return true: password mode is enabled, false: disabled
324 */
325 bool lv_textarea_get_pwd_mode(const lv_obj_t * ta);
326
327 /**
328 * Get the one line configuration attribute
329 * @param ta pointer to a text area object
330 * @return true: one line configuration is enabled, false: disabled
331 */
332 bool lv_textarea_get_one_line(const lv_obj_t * ta);
333
334 /**
335 * Get a list of accepted characters.
336 * @param ta pointer to Text Area
337 * @return list of accented characters.
338 */
339 const char * lv_textarea_get_accepted_chars(lv_obj_t * ta);
340
341 /**
342 * Get max length of a Text Area.
343 * @param ta pointer to Text Area
344 * @return the maximal number of characters to be add
345 */
346 uint32_t lv_textarea_get_max_length(lv_obj_t * ta);
347
348 /**
349 * Get the scroll bar mode of a text area
350 * @param ta pointer to a text area object
351 * @return scrollbar mode from 'lv_scrollbar_mode_t' enum
352 */
lv_textarea_get_scrollbar_mode(const lv_obj_t * ta)353 static inline lv_scrollbar_mode_t lv_textarea_get_scrollbar_mode(const lv_obj_t * ta)
354 {
355 return lv_page_get_scrollbar_mode(ta);
356 }
357
358 /**
359 * Get the scroll propagation property
360 * @param ta pointer to a Text area
361 * @return true or false
362 */
lv_textarea_get_scroll_propagation(lv_obj_t * ta)363 static inline bool lv_textarea_get_scroll_propagation(lv_obj_t * ta)
364 {
365 return lv_page_get_scroll_propagation(ta);
366 }
367
368 /**
369 * Get the scroll propagation property
370 * @param ta pointer to a Text area
371 * @return true or false
372 */
lv_textarea_get_edge_flash(lv_obj_t * ta)373 static inline bool lv_textarea_get_edge_flash(lv_obj_t * ta)
374 {
375 return lv_page_get_edge_flash(ta);
376 }
377
378 /**
379 * Find whether text is selected or not.
380 * @param ta Text area object
381 * @return whether text is selected or not
382 */
383 bool lv_textarea_text_is_selected(const lv_obj_t * ta);
384
385 /**
386 * Find whether selection mode is enabled.
387 * @param ta pointer to a text area object
388 * @return true: selection mode is enabled, false: disabled
389 */
390 bool lv_textarea_get_text_sel_en(lv_obj_t * ta);
391
392 /**
393 * Set how long show the password before changing it to '*'
394 * @param ta pointer to Text area
395 * @return show time in milliseconds. 0: hide immediately.
396 */
397 uint16_t lv_textarea_get_pwd_show_time(lv_obj_t * ta);
398
399 /**
400 * Set cursor blink animation time
401 * @param ta pointer to Text area
402 * @return time blink period. 0: disable blinking
403 */
404 uint16_t lv_textarea_get_cursor_blink_time(lv_obj_t * ta);
405
406 /*=====================
407 * Other functions
408 *====================*/
409
410 /**
411 * Clear the selection on the text area.
412 * @param ta Text area object
413 */
414 void lv_textarea_clear_selection(lv_obj_t * ta);
415
416 /**
417 * Move the cursor one character right
418 * @param ta pointer to a text area object
419 */
420 void lv_textarea_cursor_right(lv_obj_t * ta);
421
422 /**
423 * Move the cursor one character left
424 * @param ta pointer to a text area object
425 */
426 void lv_textarea_cursor_left(lv_obj_t * ta);
427
428 /**
429 * Move the cursor one line down
430 * @param ta pointer to a text area object
431 */
432 void lv_textarea_cursor_down(lv_obj_t * ta);
433
434 /**
435 * Move the cursor one line up
436 * @param ta pointer to a text area object
437 */
438 void lv_textarea_cursor_up(lv_obj_t * ta);
439
440 /**********************
441 * MACROS
442 **********************/
443
444 #endif /*LV_USE_TEXTAREA_H*/
445
446 #ifdef __cplusplus
447 } /* extern "C" */
448 #endif
449
450 #endif /*LV_TEXTAREA_H*/
451
