1 /**
2 * @file lv_rect.h
3 *
4 */
5
6 #ifndef LV_LABEL_H
7 #define LV_LABEL_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_LABEL != 0
23
24 #include "../lv_core/lv_obj.h"
25 #include "../lv_font/lv_font.h"
26 #include "../lv_font/lv_symbol_def.h"
27 #include "../lv_misc/lv_txt.h"
28 #include "../lv_draw/lv_draw.h"
29
30 /*********************
31 * DEFINES
32 *********************/
33 #define LV_LABEL_DOT_NUM 3
34 #define LV_LABEL_POS_LAST 0xFFFF
35 #define LV_LABEL_TEXT_SEL_OFF 0xFFFF
36
37 /**********************
38 * TYPEDEFS
39 **********************/
40
41 /** Long mode behaviors. Used in 'lv_label_ext_t' */
42 enum {
43 LV_LABEL_LONG_EXPAND, /**< Expand the object size to the text size*/
44 LV_LABEL_LONG_BREAK, /**< Keep the object width, break the too long lines and expand the object
45 height*/
46 LV_LABEL_LONG_DOT, /**< Keep the size and write dots at the end if the text is too long*/
47 LV_LABEL_LONG_SROLL, /**< Keep the size and roll the text back and forth*/
48 LV_LABEL_LONG_SROLL_CIRC, /**< Keep the size and roll the text circularly*/
49 LV_LABEL_LONG_CROP, /**< Keep the size and crop the text out of it*/
50 };
51 typedef uint8_t lv_label_long_mode_t;
52
53 /** Label align policy*/
54 enum {
55 LV_LABEL_ALIGN_LEFT, /**< Align text to left */
56 LV_LABEL_ALIGN_CENTER, /**< Align text to center */
57 LV_LABEL_ALIGN_RIGHT, /**< Align text to right */
58 };
59 typedef uint8_t lv_label_align_t;
60
61 /** Data of label*/
62 typedef struct
63 {
64 /*Inherited from 'base_obj' so no inherited ext.*/ /*Ext. of ancestor*/
65 /*New data for this type */
66 char * text; /*Text of the label*/
67 union
68 {
69 char * tmp_ptr; /* Pointer to the allocated memory containing the character which are replaced by dots (Handled
70 by the library)*/
71 char tmp[sizeof(char *)]; /* Directly store the characters if <=4 characters */
72 } dot;
73 uint16_t dot_end; /*The text end position in dot mode (Handled by the library)*/
74 lv_point_t offset; /*Text draw position offset*/
75 #if LV_LABEL_LONG_TXT_HINT
76 lv_draw_label_hint_t hint; /*Used to buffer info about large text*/
77 #endif
78
79 #if LV_USE_ANIMATION
80 uint16_t anim_speed; /*Speed of scroll and roll animation in px/sec unit*/
81 #endif
82
83 #if LV_LABEL_TEXT_SEL
84 uint16_t txt_sel_start; /*Left-most selection character*/
85 uint16_t txt_sel_end; /*Right-most selection character*/
86 #endif
87
88 lv_label_long_mode_t long_mode : 3; /*Determinate what to do with the long texts*/
89 uint8_t static_txt : 1; /*Flag to indicate the text is static*/
90 uint8_t align : 2; /*Align type from 'lv_label_align_t'*/
91 uint8_t recolor : 1; /*Enable in-line letter re-coloring*/
92 uint8_t expand : 1; /*Ignore real width (used by the library with LV_LABEL_LONG_ROLL)*/
93 uint8_t body_draw : 1; /*Draw background body*/
94 uint8_t dot_tmp_alloc : 1; /*True if dot_tmp has been allocated. False if dot_tmp directly holds up to 4 bytes of
95 characters */
96 } lv_label_ext_t;
97
98 /** Label styles*/
99 enum {
100 LV_LABEL_STYLE_MAIN,
101 };
102 typedef uint8_t lv_label_style_t;
103
104 /**********************
105 * GLOBAL PROTOTYPES
106 **********************/
107
108 /**
109 * Create a label objects
110 * @param par pointer to an object, it will be the parent of the new label
111 * @param copy pointer to a button object, if not NULL then the new object will be copied from it
112 * @return pointer to the created button
113 */
114 lv_obj_t * lv_label_create(lv_obj_t * par, const lv_obj_t * copy);
115
116 /*=====================
117 * Setter functions
118 *====================*/
119
120 /**
121 * Set a new text for a label. Memory will be allocated to store the text by the label.
122 * @param label pointer to a label object
123 * @param text '\0' terminated character string. NULL to refresh with the current text.
124 */
125 void lv_label_set_text(lv_obj_t * label, const char * text);
126
127 /**
128 * Set a new text for a label from a character array. The array don't has to be '\0' terminated.
129 * Memory will be allocated to store the array by the label.
130 * @param label pointer to a label object
131 * @param array array of characters or NULL to refresh the label
132 * @param size the size of 'array' in bytes
133 */
134 void lv_label_set_array_text(lv_obj_t * label, const char * array, uint16_t size);
135
136 /**
137 * Set a static text. It will not be saved by the label so the 'text' variable
138 * has to be 'alive' while the label exist.
139 * @param label pointer to a label object
140 * @param text pointer to a text. NULL to refresh with the current text.
141 */
142 void lv_label_set_static_text(lv_obj_t * label, const char * text);
143
144 /**
145 * Set the behavior of the label with longer text then the object size
146 * @param label pointer to a label object
147 * @param long_mode the new mode from 'lv_label_long_mode' enum.
148 * In LV_LONG_BREAK/LONG/ROLL the size of the label should be set AFTER this
149 * function
150 */
151 void lv_label_set_long_mode(lv_obj_t * label, lv_label_long_mode_t long_mode);
152
153 /**
154 * Set the align of the label (left or center)
155 * @param label pointer to a label object
156 * @param align 'LV_LABEL_ALIGN_LEFT' or 'LV_LABEL_ALIGN_LEFT'
157 */
158 void lv_label_set_align(lv_obj_t * label, lv_label_align_t align);
159
160 /**
161 * Enable the recoloring by in-line commands
162 * @param label pointer to a label object
163 * @param en true: enable recoloring, false: disable
164 */
165 void lv_label_set_recolor(lv_obj_t * label, bool en);
166
167 /**
168 * Set the label to draw (or not draw) background specified in its style's body
169 * @param label pointer to a label object
170 * @param en true: draw body; false: don't draw body
171 */
172 void lv_label_set_body_draw(lv_obj_t * label, bool en);
173
174 /**
175 * Set the label's animation speed in LV_LABEL_LONG_SROLL/SCROLL_CIRC modes
176 * @param label pointer to a label object
177 * @param anim_speed speed of animation in px/sec unit
178 */
179 void lv_label_set_anim_speed(lv_obj_t * label, uint16_t anim_speed);
180
181 /**
182 * Set the style of an label
183 * @param label pointer to an label object
184 * @param type which style should be get (can be only `LV_LABEL_STYLE_MAIN`)
185 * @param style pointer to a style
186 */
lv_label_set_style(lv_obj_t * label,lv_label_style_t type,const lv_style_t * style)187 static inline void lv_label_set_style(lv_obj_t * label, lv_label_style_t type, const lv_style_t * style)
188 {
189 (void)type; /*Unused*/
190 lv_obj_set_style(label, style);
191 }
192
193 /**
194 * @brief Set the selection start index.
195 * @param label pointer to a label object.
196 * @param index index to set. `LV_LABEL_TXT_SEL_OFF` to select nothing.
197 */
198 void lv_label_set_text_sel_start(lv_obj_t * label, uint16_t index);
199
200 /**
201 * @brief Set the selection end index.
202 * @param label pointer to a label object.
203 * @param index index to set. `LV_LABEL_TXT_SEL_OFF` to select nothing.
204 */
205 void lv_label_set_text_sel_end(lv_obj_t * label, uint16_t index);
206
207 /*=====================
208 * Getter functions
209 *====================*/
210
211 /**
212 * Get the text of a label
213 * @param label pointer to a label object
214 * @return the text of the label
215 */
216 char * lv_label_get_text(const lv_obj_t * label);
217
218 /**
219 * Get the long mode of a label
220 * @param label pointer to a label object
221 * @return the long mode
222 */
223 lv_label_long_mode_t lv_label_get_long_mode(const lv_obj_t * label);
224
225 /**
226 * Get the align attribute
227 * @param label pointer to a label object
228 * @return LV_LABEL_ALIGN_LEFT or LV_LABEL_ALIGN_CENTER
229 */
230 lv_label_align_t lv_label_get_align(const lv_obj_t * label);
231
232 /**
233 * Get the recoloring attribute
234 * @param label pointer to a label object
235 * @return true: recoloring is enabled, false: disable
236 */
237 bool lv_label_get_recolor(const lv_obj_t * label);
238
239 /**
240 * Get the body draw attribute
241 * @param label pointer to a label object
242 * @return true: draw body; false: don't draw body
243 */
244 bool lv_label_get_body_draw(const lv_obj_t * label);
245
246 /**
247 * Get the label's animation speed in LV_LABEL_LONG_ROLL and SCROLL modes
248 * @param label pointer to a label object
249 * @return speed of animation in px/sec unit
250 */
251 uint16_t lv_label_get_anim_speed(const lv_obj_t * label);
252
253 /**
254 * Get the relative x and y coordinates of a letter
255 * @param label pointer to a label object
256 * @param index index of the letter [0 ... text length]. Expressed in character index, not byte
257 * index (different in UTF-8)
258 * @param pos store the result here (E.g. index = 0 gives 0;0 coordinates)
259 */
260 void lv_label_get_letter_pos(const lv_obj_t * label, uint16_t index, lv_point_t * pos);
261
262 /**
263 * Get the index of letter on a relative point of a label
264 * @param label pointer to label object
265 * @param pos pointer to point with coordinates on a the label
266 * @return the index of the letter on the 'pos_p' point (E.g. on 0;0 is the 0. letter)
267 * Expressed in character index and not byte index (different in UTF-8)
268 */
269 uint16_t lv_label_get_letter_on(const lv_obj_t * label, lv_point_t * pos);
270
271 /**
272 * Check if a character is drawn under a point.
273 * @param label Label object
274 * @param pos Point to check for characte under
275 * @return whether a character is drawn under the point
276 */
277 bool lv_label_is_char_under_pos(const lv_obj_t * label, lv_point_t * pos);
278
279 /**
280 * Get the style of an label object
281 * @param label pointer to an label object
282 * @param type which style should be get (can be only `LV_LABEL_STYLE_MAIN`)
283 * @return pointer to the label's style
284 */
lv_label_get_style(const lv_obj_t * label,lv_label_style_t type)285 static inline const lv_style_t * lv_label_get_style(const lv_obj_t * label, lv_label_style_t type)
286 {
287 (void)type; /*Unused*/
288 return lv_obj_get_style(label);
289 }
290
291 /**
292 * @brief Get the selection start index.
293 * @param label pointer to a label object.
294 * @return selection start index. `LV_LABEL_TXT_SEL_OFF` if nothing is selected.
295 */
296 uint16_t lv_label_get_text_sel_start(const lv_obj_t * label);
297
298 /**
299 * @brief Get the selection end index.
300 * @param label pointer to a label object.
301 * @return selection end index. `LV_LABEL_TXT_SEL_OFF` if nothing is selected.
302 */
303 uint16_t lv_label_get_text_sel_end(const lv_obj_t * label);
304
305 /*=====================
306 * Other functions
307 *====================*/
308
309 /**
310 * Insert a text to the label. The label text can not be static.
311 * @param label pointer to a label object
312 * @param pos character index to insert. Expressed in character index and not byte index (Different
313 * in UTF-8) 0: before first char. LV_LABEL_POS_LAST: after last char.
314 * @param txt pointer to the text to insert
315 */
316 void lv_label_ins_text(lv_obj_t * label, uint32_t pos, const char * txt);
317
318 /**
319 * Delete characters from a label. The label text can not be static.
320 * @param label pointer to a label object
321 * @param pos character index to insert. Expressed in character index and not byte index (Different
322 * in UTF-8) 0: before first char.
323 * @param cnt number of characters to cut
324 */
325 void lv_label_cut_text(lv_obj_t * label, uint32_t pos, uint32_t cnt);
326
327 /**********************
328 * MACROS
329 **********************/
330
331 #endif /*LV_USE_LABEL*/
332
333 #ifdef __cplusplus
334 } /* extern "C" */
335 #endif
336
337 #endif /*LV_LABEL_H*/
338