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