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