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 USE_LV_LABEL != 0
23

24
#include "../lv_core/lv_obj.h"
25
#include "../lv_misc/lv_font.h"
26
#include "../lv_misc/lv_txt.h"
27
#include "../lv_misc/lv_symbol_def.h"
28

29
/*********************
30
 *      DEFINES
31
 *********************/
32
#define LV_LABEL_DOT_NUM    3
33
#define LV_LABEL_POS_LAST   0xFFFF
34

35
/**********************
36
 *      TYPEDEFS
37
 **********************/
38

39
/*Long mode behaviors. Used in 'lv_label_ext_t' */
40
enum
41
{
42
    LV_LABEL_LONG_EXPAND,   /*Expand the object size to the text size*/
43
    LV_LABEL_LONG_BREAK,    /*Keep the object width, break the too long lines and expand the object height*/
44
    LV_LABEL_LONG_SCROLL,   /*Expand the object size and scroll the text on the parent (move the label object)*/
45
    LV_LABEL_LONG_DOT,      /*Keep the size and write dots at the end if the text is too long*/
46
    LV_LABEL_LONG_ROLL,     /*Keep the size and roll the text infinitely*/
47
    LV_LABEL_LONG_CROP,     /*Keep the size and crop the text out of it*/
48
};
49
typedef uint8_t lv_label_long_mode_t;
50

51
/*Label align policy*/
52
enum {
53
    LV_LABEL_ALIGN_LEFT,
54
    LV_LABEL_ALIGN_CENTER,
55
    LV_LABEL_ALIGN_RIGHT,
56
};
57
typedef uint8_t lv_label_align_t;
58

59
/*Data of label*/
60
typedef struct
61
{
62
    /*Inherited from 'base_obj' so no inherited ext.*/  /*Ext. of ancestor*/
63
    /*New data for this type */
64
    char * text;                            /*Text of the label*/
65
    lv_label_long_mode_t long_mode;         /*Determinate what to do with the long texts*/
66
#if LV_TXT_UTF8 == 0
67
    char dot_tmp[LV_LABEL_DOT_NUM + 1];     /*Store the character which are replaced by dots (Handled by the library)*/
68
#else
69
    char dot_tmp[LV_LABEL_DOT_NUM * 4 + 1]; /*Store the character which are replaced by dots (Handled by the library)*/
70
#endif
71

72
#if USE_LV_MULTI_LANG
73
    uint16_t lang_txt_id;            /*The ID of the text to display*/
74
#endif
75
    uint16_t dot_end;               /*The text end position in dot mode (Handled by the library)*/
76
    uint16_t anim_speed;            /*Speed of scroll and roll animation in px/sec unit*/
77
    lv_point_t offset;              /*Text draw position offset*/
78
    uint8_t static_txt  :1;         /*Flag to indicate the text is static*/
79
    uint8_t align       :2;         /*Align type from 'lv_label_align_t'*/
80
    uint8_t recolor     :1;         /*Enable in-line letter re-coloring*/
81
    uint8_t expand      :1;         /*Ignore real width (used by the library with LV_LABEL_LONG_ROLL)*/
82
    uint8_t body_draw   :1;         /*Draw background body*/
83
} lv_label_ext_t;
84

85
/**********************
86
 * GLOBAL PROTOTYPES
87
 **********************/
88

89

90
/**
91
 * Create a label objects
92
 * @param par pointer to an object, it will be the parent of the new label
93
 * @param copy pointer to a button object, if not NULL then the new object will be copied from it
94
 * @return pointer to the created button
95
 */
96
lv_obj_t * lv_label_create(lv_obj_t * par, const lv_obj_t * copy);
97

98
/*=====================
99
 * Setter functions
100
 *====================*/
101

102
/**
103
 * Set a new text for a label. Memory will be allocated to store the text by the label.
104
 * @param label pointer to a label object
105
 * @param text '\0' terminated character string. NULL to refresh with the current text.
106
 */
107
void lv_label_set_text(lv_obj_t * label, const char * text);
108

109
/**
110
 * Set a new text for a label from a character array. The array don't has to be '\0' terminated.
111
 * Memory will be allocated to store the array by the label.
112
 * @param label pointer to a label object
113
 * @param array array of characters or NULL to refresh the label
114
 * @param size the size of 'array' in bytes
115
 */
116
void lv_label_set_array_text(lv_obj_t * label, const char * array, uint16_t size);
117

118
/**
119
 * Set a static text. It will not be saved by the label so the 'text' variable
120
 * has to be 'alive' while the label exist.
121
 * @param label pointer to a label object
122
 * @param text pointer to a text. NULL to refresh with the current text.
123
 */
124
void lv_label_set_static_text(lv_obj_t * label, const char * text);
125

126
/**
127
 *Set a text ID which means a the same text but on different languages
128
 * @param label pointer to a label object
129
 * @param txt_id ID of the text
130
 */
131
#if USE_LV_MULTI_LANG
132
void lv_label_set_text_id(lv_obj_t * label, uint32_t txt_id);
133
#endif
134

135
/**
136
 * Set the behavior of the label with longer text then the object size
137
 * @param label pointer to a label object
138
 * @param long_mode the new mode from 'lv_label_long_mode' enum.
139
 *                  In LV_LONG_BREAK/LONG/ROLL the size of the label should be set AFTER this function
140
 */
141
void lv_label_set_long_mode(lv_obj_t * label, lv_label_long_mode_t long_mode);
142

143
/**
144
 * Set the align of the label (left or center)
145
 * @param label pointer to a label object
146
 * @param align 'LV_LABEL_ALIGN_LEFT' or 'LV_LABEL_ALIGN_LEFT'
147
 */
148
void lv_label_set_align(lv_obj_t *label, lv_label_align_t align);
149

150
/**
151
 * Enable the recoloring by in-line commands
152
 * @param label pointer to a label object
153
 * @param en true: enable recoloring, false: disable
154
 */
155
void lv_label_set_recolor(lv_obj_t * label, bool en);
156

157
/**
158
 * Set the label to draw (or not draw) background specified in its style's body
159
 * @param label pointer to a label object
160
 * @param en true: draw body; false: don't draw body
161
 */
162
void lv_label_set_body_draw(lv_obj_t *label, bool en);
163

164
/**
165
 * Set the label's animation speed in LV_LABEL_LONG_ROLL and SCROLL modes
166
 * @param label pointer to a label object
167
 * @param anim_speed speed of animation in px/sec unit
168
 */
169
void lv_label_set_anim_speed(lv_obj_t *label, uint16_t anim_speed);
170

171
/**
172
 * Set the style of an label
173
 * @param label pointer to an label object
174
 * @param style pointer to a style
175
 */
176
static inline void lv_label_set_style(lv_obj_t *label, lv_style_t *style)
177
{
178
    lv_obj_set_style(label, style);
179
}
180
/*=====================
181
 * Getter functions
182
 *====================*/
183

184
/**
185
 * Get the text of a label
186
 * @param label pointer to a label object
187
 * @return the text of the label
188
 */
189
char * lv_label_get_text(const lv_obj_t * label);
190

191
#if USE_LV_MULTI_LANG
192
/**
193
 * Get the text ID of the label. (Used by the multi-language feature)
194
 * @param label pointer to a label object
195
 * @return ID of the text
196
 */
197
uint16_t lv_label_get_text_id(lv_obj_t * label);
198
#endif
199

200
/**
201
 * Get the long mode of a label
202
 * @param label pointer to a label object
203
 * @return the long mode
204
 */
205
lv_label_long_mode_t lv_label_get_long_mode(const lv_obj_t * label);
206

207
/**
208
 * Get the align attribute
209
 * @param label pointer to a label object
210
 * @return LV_LABEL_ALIGN_LEFT or LV_LABEL_ALIGN_CENTER
211
 */
212
lv_label_align_t lv_label_get_align(const lv_obj_t * label);
213

214
/**
215
 * Get the recoloring attribute
216
 * @param label pointer to a label object
217
 * @return true: recoloring is enabled, false: disable
218
 */
219
bool lv_label_get_recolor(const lv_obj_t * label);
220

221
/**
222
 * Get the body draw attribute
223
 * @param label pointer to a label object
224
 * @return true: draw body; false: don't draw body
225
 */
226
bool lv_label_get_body_draw(const lv_obj_t *label);
227

228
/**
229
 * Get the label's animation speed in LV_LABEL_LONG_ROLL and SCROLL modes
230
 * @param label pointer to a label object
231
 * @return speed of animation in px/sec unit
232
 */
233
uint16_t lv_label_get_anim_speed(const lv_obj_t *label);
234

235
/**
236
 * Get the relative x and y coordinates of a letter
237
 * @param label pointer to a label object
238
 * @param index index of the letter [0 ... text length]. Expressed in character index, not byte index (different in UTF-8)
239
 * @param pos store the result here (E.g. index = 0 gives 0;0 coordinates)
240
 */
241
void lv_label_get_letter_pos(const lv_obj_t * label, uint16_t index, lv_point_t * pos);
242

243
/**
244
 * Get the index of letter on a relative point of a label
245
 * @param label pointer to label object
246
 * @param pos pointer to point with coordinates on a the label
247
 * @return the index of the letter on the 'pos_p' point (E.g. on 0;0 is the 0. letter)
248
 * Expressed in character index and not byte index (different in UTF-8)
249
 */
250
uint16_t lv_label_get_letter_on(const lv_obj_t * label, lv_point_t * pos);
251

252
/**
253
 * Get the style of an label object
254
 * @param label pointer to an label object
255
 * @return pointer to the label's style
256
 */
257
static inline lv_style_t* lv_label_get_style(const lv_obj_t *label)
258
{
259
    return lv_obj_get_style(label);
260
}
261

262
/*=====================
263
 * Other functions
264
 *====================*/
265

266
/**
267
 * Insert a text to the label. The label text can not be static.
268
 * @param label pointer to a label object
269
 * @param pos character index to insert. Expressed in character index and not byte index (Different in UTF-8)
270
 *            0: before first char.
271
 *            LV_LABEL_POS_LAST: after last char.
272
 * @param txt pointer to the text to insert
273
 */
274
void lv_label_ins_text(lv_obj_t * label, uint32_t pos,  const char * txt);
275

276
/**
277
 * Delete characters from a label. The label text can not be static.
278
 * @param label pointer to a label object
279
 * @param pos character index to insert. Expressed in character index and not byte index (Different in UTF-8)
280
 *            0: before first char.
281
 * @param cnt number of characters to cut
282
 */
283
void lv_label_cut_text(lv_obj_t * label, uint32_t pos,  uint32_t cnt);
284

285
/**********************
286
 *      MACROS
287
 **********************/
288

289
#endif  /*USE_LV_LABEL*/
290

291
#ifdef __cplusplus
292
} /* extern "C" */
293
#endif
294

295
#endif  /*LV_LABEL_H*/
296

297