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 "../core/lv_obj.h" 22 #include "../font/lv_font.h" 23 #include "../font/lv_symbol_def.h" 24 #include "../misc/lv_txt.h" 25 #include "../draw/lv_draw.h" 26 27 /********************* 28 * DEFINES 29 *********************/ 30 #define LV_LABEL_WAIT_CHAR_COUNT 3 31 #define LV_LABEL_DOT_NUM 3 32 #define LV_LABEL_POS_LAST 0xFFFF 33 #define LV_LABEL_TEXT_SELECTION_OFF LV_DRAW_LABEL_NO_TXT_SEL 34 35 LV_EXPORT_CONST_INT(LV_LABEL_DOT_NUM); 36 LV_EXPORT_CONST_INT(LV_LABEL_POS_LAST); 37 LV_EXPORT_CONST_INT(LV_LABEL_TEXT_SELECTION_OFF); 38 39 /********************** 40 * TYPEDEFS 41 **********************/ 42 43 /** Long mode behaviors. Used in 'lv_label_ext_t'*/ 44 enum { 45 LV_LABEL_LONG_WRAP, /**< Keep the object width, wrap the too long lines and expand the object 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_SCROLL, /**< Keep the size and roll the text back and forth*/ 48 LV_LABEL_LONG_SCROLL_CIRCULAR, /**< Keep the size and roll the text circularly*/ 49 LV_LABEL_LONG_CLIP, /**< Keep the size and clip the text out of it*/ 50 }; 51 typedef uint8_t lv_label_long_mode_t; 52 53 typedef struct { 54 lv_obj_t obj; 55 char * text; 56 union { 57 char * tmp_ptr; /*Pointer to the allocated memory containing the character replaced by dots*/ 58 char tmp[LV_LABEL_DOT_NUM + 1]; /*Directly store the characters if <=4 characters*/ 59 } dot; 60 uint32_t dot_end; /*The real text length, used in dot mode*/ 61 62 #if LV_LABEL_LONG_TXT_HINT 63 lv_draw_label_hint_t hint; 64 #endif 65 66 #if LV_LABEL_TEXT_SELECTION 67 uint32_t sel_start; 68 uint32_t sel_end; 69 #endif 70 71 lv_point_t offset; /*Text draw position offset*/ 72 lv_label_long_mode_t long_mode : 3; /*Determine what to do with the long texts*/ 73 uint8_t static_txt : 1; /*Flag to indicate the text is static*/ 74 uint8_t recolor : 1; /*Enable in-line letter re-coloring*/ 75 uint8_t expand : 1; /*Ignore real width (used by the library with LV_LABEL_LONG_SCROLL)*/ 76 uint8_t dot_tmp_alloc : 1; /*1: dot is allocated, 0: dot directly holds up to 4 chars*/ 77 } lv_label_t; 78 79 extern const lv_obj_class_t lv_label_class; 80 81 /********************** 82 * GLOBAL PROTOTYPES 83 **********************/ 84 85 /** 86 * Create a label object 87 * @param parent pointer to an object, it will be the parent of the new label. 88 * @return pointer to the created button 89 */ 90 lv_obj_t * lv_label_create(lv_obj_t * parent); 91 92 /*===================== 93 * Setter functions 94 *====================*/ 95 96 /** 97 * Set a new text for a label. Memory will be allocated to store the text by the label. 98 * @param obj pointer to a label object 99 * @param text '\0' terminated character string. NULL to refresh with the current text. 100 */ 101 void lv_label_set_text(lv_obj_t * obj, const char * text); 102 103 /** 104 * Set a new formatted text for a label. Memory will be allocated to store the text by the label. 105 * @param obj pointer to a label object 106 * @param fmt `printf`-like format 107 * @example lv_label_set_text_fmt(label1, "%d user", user_num); 108 */ 109 void lv_label_set_text_fmt(lv_obj_t * obj, const char * fmt, ...) LV_FORMAT_ATTRIBUTE(2, 3); 110 111 /** 112 * Set a static text. It will not be saved by the label so the 'text' variable 113 * has to be 'alive' while the label exists. 114 * @param obj pointer to a label object 115 * @param text pointer to a text. NULL to refresh with the current text. 116 */ 117 void lv_label_set_text_static(lv_obj_t * obj, const char * text); 118 119 /** 120 * Set the behavior of the label with longer text then the object size 121 * @param obj pointer to a label object 122 * @param long_mode the new mode from 'lv_label_long_mode' enum. 123 * In LV_LONG_WRAP/DOT/SCROLL/SCROLL_CIRC the size of the label should be set AFTER this function 124 */ 125 void lv_label_set_long_mode(lv_obj_t * obj, lv_label_long_mode_t long_mode); 126 127 /** 128 * Enable the recoloring by in-line commands 129 * @param obj pointer to a label object 130 * @param en true: enable recoloring, false: disable 131 * @example "This is a #ff0000 red# word" 132 */ 133 void lv_label_set_recolor(lv_obj_t * obj, bool en); 134 135 /** 136 * Set where text selection should start 137 * @param obj pointer to a label object 138 * @param index character index from where selection should start. `LV_LABEL_TEXT_SELECTION_OFF` for no selection 139 */ 140 void lv_label_set_text_sel_start(lv_obj_t * obj, uint32_t index); 141 142 /** 143 * Set where text selection should end 144 * @param obj pointer to a label object 145 * @param index character index where selection should end. `LV_LABEL_TEXT_SELECTION_OFF` for no selection 146 */ 147 void lv_label_set_text_sel_end(lv_obj_t * obj, uint32_t index); 148 149 /*===================== 150 * Getter functions 151 *====================*/ 152 153 /** 154 * Get the text of a label 155 * @param obj pointer to a label object 156 * @return the text of the label 157 */ 158 char * lv_label_get_text(const lv_obj_t * obj); 159 160 /** 161 * Get the long mode of a label 162 * @param obj pointer to a label object 163 * @return the current long mode 164 */ 165 lv_label_long_mode_t lv_label_get_long_mode(const lv_obj_t * obj); 166 167 /** 168 * Get the recoloring attribute 169 * @param obj pointer to a label object 170 * @return true: recoloring is enabled, false: disable 171 */ 172 bool lv_label_get_recolor(const lv_obj_t * obj); 173 174 /** 175 * Get the relative x and y coordinates of a letter 176 * @param obj pointer to a label object 177 * @param index index of the character [0 ... text length - 1]. 178 * Expressed in character index, not byte index (different in UTF-8) 179 * @param pos store the result here (E.g. index = 0 gives 0;0 coordinates if the text if aligned to the left) 180 */ 181 void lv_label_get_letter_pos(const lv_obj_t * obj, uint32_t char_id, lv_point_t * pos); 182 183 /** 184 * Get the index of letter on a relative point of a label. 185 * @param obj pointer to label object 186 * @param pos pointer to point with coordinates on a the label 187 * @return The index of the letter on the 'pos_p' point (E.g. on 0;0 is the 0. letter if aligned to the left) 188 * Expressed in character index and not byte index (different in UTF-8) 189 */ 190 uint32_t lv_label_get_letter_on(const lv_obj_t * obj, lv_point_t * pos_in); 191 192 /** 193 * Check if a character is drawn under a point. 194 * @param obj pointer to a label object 195 * @param pos Point to check for character under 196 * @return whether a character is drawn under the point 197 */ 198 bool lv_label_is_char_under_pos(const lv_obj_t * obj, lv_point_t * pos); 199 200 /** 201 * @brief Get the selection start index. 202 * @param obj pointer to a label object. 203 * @return selection start index. `LV_LABEL_TEXT_SELECTION_OFF` if nothing is selected. 204 */ 205 uint32_t lv_label_get_text_selection_start(const lv_obj_t * obj); 206 207 /** 208 * @brief Get the selection end index. 209 * @param obj pointer to a label object. 210 * @return selection end index. `LV_LABEL_TXT_SEL_OFF` if nothing is selected. 211 */ 212 uint32_t lv_label_get_text_selection_end(const lv_obj_t * obj); 213 214 /*===================== 215 * Other functions 216 *====================*/ 217 218 /** 219 * Insert a text to a label. The label text can not be static. 220 * @param obj pointer to a label object 221 * @param pos character index to insert. Expressed in character index and not byte index. 222 * 0: before first char. LV_LABEL_POS_LAST: after last char. 223 * @param txt pointer to the text to insert 224 */ 225 void lv_label_ins_text(lv_obj_t * obj, uint32_t pos, const char * txt); 226 227 /** 228 * Delete characters from a label. The label text can not be static. 229 * @param obj pointer to a label object 230 * @param pos character index from where to cut. Expressed in character index and not byte index. 231 * 0: start in from of the first character 232 * @param cnt number of characters to cut 233 */ 234 void lv_label_cut_text(lv_obj_t * obj, uint32_t pos, uint32_t cnt); 235 236 /********************** 237 * MACROS 238 **********************/ 239 240 #endif /*LV_USE_LABEL*/ 241 242 #ifdef __cplusplus 243 } /*extern "C"*/ 244 #endif 245 246 #endif /*LV_LABEL_H*/ 247
