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