1 /**
2  * @file lv_draw_label.h
3  *
4  */
5 
6 #ifndef LV_DRAW_LABEL_H
7 #define LV_DRAW_LABEL_H
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 /*********************
14  *      INCLUDES
15  *********************/
16 #include "lv_draw.h"
17 #include "lv_draw_rect.h"
18 #include "../misc/lv_bidi.h"
19 #include "../misc/lv_text.h"
20 #include "../misc/lv_color.h"
21 #include "../misc/lv_style.h"
22 
23 /*********************
24  *      DEFINES
25  *********************/
26 #define LV_DRAW_LABEL_NO_TXT_SEL (0xFFFF)
27 
28 /**********************
29  *      TYPEDEFS
30  **********************/
31 
32 typedef struct {
33     lv_draw_dsc_base_t base;
34 
35     const char * text;
36     uint32_t text_length;
37     const lv_font_t * font;
38     uint32_t sel_start;
39     uint32_t sel_end;
40     lv_color_t color;
41     lv_color_t sel_color;
42     lv_color_t sel_bg_color;
43     int32_t line_space;
44     int32_t letter_space;
45     int32_t ofs_x;
46     int32_t ofs_y;
47     int32_t rotation;
48     lv_opa_t opa;
49     lv_base_dir_t bidi_dir;
50     lv_text_align_t align;
51     lv_text_flag_t flag;
52     lv_text_decor_t decor : 3;
53     lv_blend_mode_t blend_mode : 3;
54     /**
55      * < 1: malloc buffer and copy `text` there.
56      * 0: `text` is const and it's pointer will be valid during rendering.*/
57     uint8_t text_local : 1;
58 
59     /**
60      * Indicate that the text is constant and its pointer can be safely saved e.g. in a cache.
61      */
62     uint8_t text_static : 1;
63     lv_draw_label_hint_t * hint;
64 } lv_draw_label_dsc_t;
65 
66 typedef struct {
67     lv_draw_dsc_base_t base;
68 
69     uint32_t unicode;
70     const lv_font_t * font;
71     lv_color_t color;
72 
73     int32_t rotation;
74     int32_t scale_x;
75     int32_t scale_y;
76     int32_t skew_x;
77     int32_t skew_y;
78     lv_point_t pivot;
79 
80     lv_opa_t opa;
81     lv_text_decor_t decor : 3;
82     lv_blend_mode_t blend_mode : 3;
83 } lv_draw_letter_dsc_t;
84 
85 /**
86  * Passed as a parameter to `lv_draw_label_iterate_characters` to
87  * draw the characters one by one
88  * @param draw_unit     pointer to a draw unit
89  * @param dsc           pointer to `lv_draw_glyph_dsc_t` to describe the character to draw
90  *                      if NULL don't draw character
91  * @param fill_dsc      pointer to a fill descriptor to draw a background for the character or
92  *                      underline or strike through
93  *                      if NULL do not fill anything
94  * @param fill_area     the area to fill
95  *                      if NULL do not fill anything
96  */
97 typedef void(*lv_draw_glyph_cb_t)(lv_draw_unit_t * draw_unit, lv_draw_glyph_dsc_t * dsc, lv_draw_fill_dsc_t * fill_dsc,
98                                   const lv_area_t * fill_area);
99 
100 /**********************
101  * GLOBAL PROTOTYPES
102  **********************/
103 
104 void /* LV_ATTRIBUTE_FAST_MEM */ lv_draw_letter_dsc_init(lv_draw_letter_dsc_t * dsc);
105 
106 /**
107  * Initialize a label draw descriptor
108  * @param dsc       pointer to a draw descriptor
109  */
110 void /* LV_ATTRIBUTE_FAST_MEM */ lv_draw_label_dsc_init(lv_draw_label_dsc_t * dsc);
111 
112 /**
113  * Try to get a label draw descriptor from a draw task.
114  * @param task      draw task
115  * @return          the task's draw descriptor or NULL if the task is not of type LV_DRAW_TASK_TYPE_LABEL
116  */
117 lv_draw_label_dsc_t * lv_draw_task_get_label_dsc(lv_draw_task_t * task);
118 
119 /**
120  * Initialize a glyph draw descriptor.
121  * Used internally.
122  * @param dsc       pointer to a draw descriptor
123  */
124 void lv_draw_glyph_dsc_init(lv_draw_glyph_dsc_t * dsc);
125 
126 /**
127  * Create a draw task to render a text
128  * @param layer         pointer to a layer
129  * @param dsc           pointer to draw descriptor
130  * @param coords        coordinates of the character
131  */
132 void /* LV_ATTRIBUTE_FAST_MEM */ lv_draw_label(lv_layer_t * layer, const lv_draw_label_dsc_t * dsc,
133                                                const lv_area_t * coords);
134 
135 /**
136  * Create a draw task to render a single character
137  * @param layer          pointer to a layer
138  * @param dsc            pointer to draw descriptor
139  * @param point          position of the label
140  * @param unicode_letter the letter to draw
141  */
142 void /* LV_ATTRIBUTE_FAST_MEM */ lv_draw_character(lv_layer_t * layer, lv_draw_label_dsc_t * dsc,
143                                                    const lv_point_t * point, uint32_t unicode_letter);
144 
145 /**
146  * Draw a single letter
147  * @param layer          pointer to a layer
148  * @param dsc            pointer to draw descriptor
149  * @param point          position of the label
150  */
151 void /* LV_ATTRIBUTE_FAST_MEM */ lv_draw_letter(lv_layer_t * layer, lv_draw_letter_dsc_t * dsc,
152                                                 const lv_point_t * point);
153 
154 /**
155  * Should be used during rendering the characters to get the position and other
156  * parameters of the characters
157  * @param draw_unit     pointer to a draw unit
158  * @param dsc           pointer to draw descriptor
159  * @param coords        coordinates of the label
160  * @param cb            a callback to call to draw each glyphs one by one
161  */
162 void lv_draw_label_iterate_characters(lv_draw_unit_t * draw_unit, const lv_draw_label_dsc_t * dsc,
163                                       const lv_area_t * coords, lv_draw_glyph_cb_t cb);
164 
165 /**
166  * @brief Draw a single letter using the provided draw unit, glyph descriptor, position, font, and callback.
167  *
168  * This function is responsible for rendering a single character from a text string,
169  * applying the necessary styling described by the glyph descriptor (`dsc`). It handles
170  * the retrieval of the glyph's description, checks its visibility within the clipping area,
171  * and invokes the callback (`cb`) to render the glyph at the specified position (`pos`)
172  * using the given font (`font`).
173  *
174  * @param draw_unit     Pointer to the drawing unit handling the rendering context.
175  * @param dsc           Pointer to the descriptor containing styling for the glyph to be drawn.
176  * @param pos           Pointer to the point coordinates where the letter should be drawn.
177  * @param font          Pointer to the font containing the glyph.
178  * @param letter        The Unicode code point of the letter to be drawn.
179  * @param cb            Callback function to execute the actual rendering of the glyph.
180  */
181 void lv_draw_unit_draw_letter(lv_draw_unit_t * draw_unit, lv_draw_glyph_dsc_t * dsc,  const lv_point_t * pos,
182                               const lv_font_t * font, uint32_t letter, lv_draw_glyph_cb_t cb);
183 
184 /***********************
185  * GLOBAL VARIABLES
186  ***********************/
187 
188 /**********************
189  *      MACROS
190  **********************/
191 
192 #ifdef __cplusplus
193 } /*extern "C"*/
194 #endif
195 
196 #endif /*LV_DRAW_LABEL_H*/
197