1 /** 2 * @file lv_span.h 3 * 4 */ 5 6 #ifndef LV_SPAN_H 7 #define LV_SPAN_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 /********************* 14 * INCLUDES 15 *********************/ 16 #include "../../lv_conf_internal.h" 17 #include "../../core/lv_obj.h" 18 19 #if LV_USE_SPAN != 0 20 21 /********************* 22 * DEFINES 23 *********************/ 24 #ifndef LV_SPAN_SNIPPET_STACK_SIZE 25 #define LV_SPAN_SNIPPET_STACK_SIZE 64 26 #endif 27 28 /********************** 29 * TYPEDEFS 30 **********************/ 31 typedef enum { 32 LV_SPAN_OVERFLOW_CLIP, 33 LV_SPAN_OVERFLOW_ELLIPSIS, 34 LV_SPAN_OVERFLOW_LAST, /**< Fence member*/ 35 } lv_span_overflow_t; 36 37 typedef enum { 38 LV_SPAN_MODE_FIXED, /**< fixed the obj size */ 39 LV_SPAN_MODE_EXPAND, /**< Expand the object size to the text size */ 40 LV_SPAN_MODE_BREAK, /**< Keep width, break the too long lines and expand height */ 41 LV_SPAN_MODE_LAST /**< Fence member */ 42 } lv_span_mode_t; 43 44 /** Coords of a span */ 45 typedef struct _lv_span_coords_t { 46 lv_area_t heading; 47 lv_area_t middle; 48 lv_area_t trailing; 49 } lv_span_coords_t; 50 51 LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_spangroup_class; 52 53 /********************** 54 * GLOBAL PROTOTYPES 55 **********************/ 56 57 void lv_span_stack_init(void); 58 void lv_span_stack_deinit(void); 59 60 /** 61 * Create a spangroup object 62 * @param parent pointer to an object, it will be the parent of the new spangroup 63 * @return pointer to the created spangroup 64 */ 65 lv_obj_t * lv_spangroup_create(lv_obj_t * parent); 66 67 /** 68 * Create a span string descriptor and add to spangroup. 69 * @param obj pointer to a spangroup object. 70 * @return pointer to the created span. 71 */ 72 lv_span_t * lv_spangroup_new_span(lv_obj_t * obj); 73 74 /** 75 * Remove the span from the spangroup and free memory. 76 * @param obj pointer to a spangroup object. 77 * @param span pointer to a span. 78 */ 79 void lv_spangroup_delete_span(lv_obj_t * obj, lv_span_t * span); 80 81 /*===================== 82 * Setter functions 83 *====================*/ 84 85 /** 86 * Set a new text for a span. Memory will be allocated to store the text by the span. 87 * @param span pointer to a span. 88 * @param text pointer to a text. 89 */ 90 void lv_span_set_text(lv_span_t * span, const char * text); 91 92 /** 93 * Set a static text. It will not be saved by the span so the 'text' variable 94 * has to be 'alive' while the span exist. 95 * @param span pointer to a span. 96 * @param text pointer to a text. 97 */ 98 void lv_span_set_text_static(lv_span_t * span, const char * text); 99 100 /** 101 * Set the align of the spangroup. 102 * @param obj pointer to a spangroup object. 103 * @param align see lv_text_align_t for details. 104 */ 105 void lv_spangroup_set_align(lv_obj_t * obj, lv_text_align_t align); 106 107 /** 108 * Set the overflow of the spangroup. 109 * @param obj pointer to a spangroup object. 110 * @param overflow see lv_span_overflow_t for details. 111 */ 112 void lv_spangroup_set_overflow(lv_obj_t * obj, lv_span_overflow_t overflow); 113 114 /** 115 * Set the indent of the spangroup. 116 * @param obj pointer to a spangroup object. 117 * @param indent the first line indentation 118 */ 119 void lv_spangroup_set_indent(lv_obj_t * obj, int32_t indent); 120 121 /** 122 * Set the mode of the spangroup. 123 * @param obj pointer to a spangroup object. 124 * @param mode see lv_span_mode_t for details. 125 */ 126 void lv_spangroup_set_mode(lv_obj_t * obj, lv_span_mode_t mode); 127 128 /** 129 * Set maximum lines of the spangroup. 130 * @param obj pointer to a spangroup object. 131 * @param lines max lines that can be displayed in LV_SPAN_MODE_BREAK mode. < 0 means no limit. 132 */ 133 void lv_spangroup_set_max_lines(lv_obj_t * obj, int32_t lines); 134 135 /*===================== 136 * Getter functions 137 *====================*/ 138 139 /** 140 * Get a pointer to the style of a span 141 * @param span pointer to the span 142 * @return pointer to the style. valid as long as the span is valid 143 */ 144 lv_style_t * lv_span_get_style(lv_span_t * span); 145 146 /** 147 * Get a pointer to the text of a span 148 * @param span pointer to the span 149 * @return pointer to the text 150 */ 151 const char * lv_span_get_text(lv_span_t * span); 152 153 /** 154 * Get a spangroup child by its index. 155 * 156 * @param obj The spangroup object 157 * @param id the index of the child. 158 * 0: the oldest (firstly created) child 159 * 1: the second oldest 160 * child count-1: the youngest 161 * -1: the youngest 162 * -2: the second youngest 163 * @return The child span at index `id`, or NULL if the ID does not exist 164 */ 165 lv_span_t * lv_spangroup_get_child(const lv_obj_t * obj, int32_t id); 166 167 /** 168 * Get number of spans 169 * @param obj the spangroup object to get the child count of. 170 * @return the span count of the spangroup. 171 */ 172 uint32_t lv_spangroup_get_span_count(const lv_obj_t * obj); 173 174 /** 175 * Get the align of the spangroup. 176 * @param obj pointer to a spangroup object. 177 * @return the align value. 178 */ 179 lv_text_align_t lv_spangroup_get_align(lv_obj_t * obj); 180 181 /** 182 * Get the overflow of the spangroup. 183 * @param obj pointer to a spangroup object. 184 * @return the overflow value. 185 */ 186 lv_span_overflow_t lv_spangroup_get_overflow(lv_obj_t * obj); 187 188 /** 189 * Get the indent of the spangroup. 190 * @param obj pointer to a spangroup object. 191 * @return the indent value. 192 */ 193 int32_t lv_spangroup_get_indent(lv_obj_t * obj); 194 195 /** 196 * Get the mode of the spangroup. 197 * @param obj pointer to a spangroup object. 198 */ 199 lv_span_mode_t lv_spangroup_get_mode(lv_obj_t * obj); 200 201 /** 202 * Get maximum lines of the spangroup. 203 * @param obj pointer to a spangroup object. 204 * @return the max lines value. 205 */ 206 int32_t lv_spangroup_get_max_lines(lv_obj_t * obj); 207 208 /** 209 * Get max line height of all span in the spangroup. 210 * @param obj pointer to a spangroup object. 211 */ 212 int32_t lv_spangroup_get_max_line_height(lv_obj_t * obj); 213 214 /** 215 * Get the text content width when all span of spangroup on a line. 216 * @param obj pointer to a spangroup object. 217 * @param max_width if text content width >= max_width, return max_width 218 * to reduce computation, if max_width == 0, returns the text content width. 219 * @return text content width or max_width. 220 */ 221 uint32_t lv_spangroup_get_expand_width(lv_obj_t * obj, uint32_t max_width); 222 223 /** 224 * Get the text content height with width fixed. 225 * @param obj pointer to a spangroup object. 226 * @param width the width of the span group. 227 228 */ 229 int32_t lv_spangroup_get_expand_height(lv_obj_t * obj, int32_t width); 230 231 /** 232 * Get the span's coords in the spangroup. 233 * @note Before calling this function, please make sure that the layout of span group has been updated. 234 * Like calling lv_obj_update_layout() like function. 235 * 236 * +--------+ 237 * |Heading +--->------------------+ 238 * | Pos | | Heading | 239 * +--------+---+------------------+ 240 * | | 241 * | | 242 * | | 243 * | Middle +--------+| 244 * | |Trailing|| 245 * | +-| Pos || 246 * | | +--------+| 247 * +-------------------v-----------+ 248 * | Trailing | 249 * +-------------------+ 250 * @param obj pointer to a spangroup object. 251 * @param span pointer to a span. 252 * @return the span's coords in the spangroup. 253 */ 254 lv_span_coords_t lv_spangroup_get_span_coords(lv_obj_t * obj, const lv_span_t * span); 255 256 /** 257 * Get the span object by point. 258 * @param obj pointer to a spangroup object. 259 * @param point pointer to point containing absolute coordinates 260 * @return pointer to the span under the point or `NULL` if not found. 261 */ 262 lv_span_t * lv_spangroup_get_span_by_point(lv_obj_t * obj, const lv_point_t * point); 263 264 /*===================== 265 * Other functions 266 *====================*/ 267 268 /** 269 * Update the mode of the spangroup. 270 * @param obj pointer to a spangroup object. 271 */ 272 void lv_spangroup_refr_mode(lv_obj_t * obj); 273 274 /********************** 275 * MACROS 276 **********************/ 277 278 #endif /*LV_USE_SPAN*/ 279 280 #ifdef __cplusplus 281 } /* extern "C" */ 282 #endif 283 284 #endif /*LV_SPAN_H*/ 285
