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