1 /**
2  * @file lv_meter.h
3  *
4  */
5 
6 #ifndef LV_METER_H
7 #define LV_METER_H
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 /*********************
14  *      INCLUDES
15  *********************/
16 #include "../../../lvgl.h"
17 
18 #if LV_USE_METER != 0
19 
20 /*Testing of dependencies*/
21 #if LV_DRAW_COMPLEX == 0
22 #error "lv_meter: Complex drawing is required. Enable it in lv_conf.h (LV_DRAW_COMPLEX 1)"
23 #endif
24 
25 /*********************
26  *      DEFINES
27  *********************/
28 
29 /**********************
30  *      TYPEDEFS
31  **********************/
32 
33 typedef struct {
34     lv_color_t tick_color;
35     uint16_t tick_cnt;
36     uint16_t tick_length;
37     uint16_t tick_width;
38 
39     lv_color_t tick_major_color;
40     uint16_t tick_major_nth;
41     uint16_t tick_major_length;
42     uint16_t tick_major_width;
43 
44     int16_t label_gap;
45 
46     int32_t min;
47     int32_t max;
48     int16_t r_mod;
49     uint16_t angle_range;
50     int16_t rotation;
51 } lv_meter_scale_t;
52 
53 enum {
54     LV_METER_INDICATOR_TYPE_NEEDLE_IMG,
55     LV_METER_INDICATOR_TYPE_NEEDLE_LINE,
56     LV_METER_INDICATOR_TYPE_SCALE_LINES,
57     LV_METER_INDICATOR_TYPE_ARC,
58 };
59 typedef uint8_t lv_meter_indicator_type_t;
60 
61 typedef struct {
62     lv_meter_scale_t * scale;
63     lv_meter_indicator_type_t type;
64     lv_opa_t opa;
65     int32_t start_value;
66     int32_t end_value;
67     union {
68         struct {
69             const void * src;
70             lv_point_t pivot;
71         } needle_img;
72         struct {
73             uint16_t width;
74             int16_t r_mod;
75             lv_color_t color;
76         } needle_line;
77         struct {
78             uint16_t width;
79             const void * src;
80             lv_color_t color;
81             int16_t r_mod;
82         } arc;
83         struct {
84             int16_t width_mod;
85             lv_color_t color_start;
86             lv_color_t color_end;
87             uint8_t local_grad  : 1;
88         } scale_lines;
89     } type_data;
90 } lv_meter_indicator_t;
91 
92 /*Data of line meter*/
93 typedef struct {
94     lv_obj_t obj;
95     lv_ll_t scale_ll;
96     lv_ll_t indicator_ll;
97 } lv_meter_t;
98 
99 extern const lv_obj_class_t lv_meter_class;
100 
101 /**
102  * `type` field in `lv_obj_draw_part_dsc_t` if `class_p = lv_meter_class`
103  * Used in `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END`
104  */
105 typedef enum {
106     LV_METER_DRAW_PART_ARC,             /**< The arc indicator*/
107     LV_METER_DRAW_PART_NEEDLE_LINE,     /**< The needle lines*/
108     LV_METER_DRAW_PART_NEEDLE_IMG,      /**< The needle images*/
109     LV_METER_DRAW_PART_TICK,            /**< The tick lines and labels*/
110 } lv_meter_draw_part_type_t;
111 
112 /**********************
113  * GLOBAL PROTOTYPES
114  **********************/
115 
116 /**
117  * Create a Meter object
118  * @param parent pointer to an object, it will be the parent of the new bar.
119  * @return pointer to the created meter
120  */
121 lv_obj_t * lv_meter_create(lv_obj_t * parent);
122 
123 /*=====================
124  * Add scale
125  *====================*/
126 
127 /**
128  * Add a new scale to the meter.
129  * @param obj   pointer to a meter object
130  * @return      the new scale
131  * @note        Indicators can be attached to scales.
132  */
133 lv_meter_scale_t * lv_meter_add_scale(lv_obj_t * obj);
134 
135 /**
136  * Set the properties of the ticks of a scale
137  * @param obj       pointer to a meter object
138  * @param scale     pointer to scale (added to `meter`)
139  * @param cnt       number of tick lines
140  * @param width     width of tick lines
141  * @param len       length of tick lines
142  * @param color     color of tick lines
143  */
144 void lv_meter_set_scale_ticks(lv_obj_t * obj, lv_meter_scale_t * scale, uint16_t cnt, uint16_t width, uint16_t len,
145                               lv_color_t color);
146 
147 /**
148  * Make some "normal" ticks major ticks and set their attributes.
149  * Texts with the current value are also added to the major ticks.
150  * @param obj           pointer to a meter object
151  * @param scale         pointer to scale (added to `meter`)
152  * @param nth           make every Nth normal tick major tick. (start from the first on the left)
153  * @param width         width of the major ticks
154  * @param len           length of the major ticks
155  * @param color         color of the major ticks
156  * @param label_gap     gap between the major ticks and the labels
157  */
158 void lv_meter_set_scale_major_ticks(lv_obj_t * obj, lv_meter_scale_t * scale, uint16_t nth, uint16_t width,
159                                     uint16_t len, lv_color_t color, int16_t label_gap);
160 
161 /**
162  * Set the value and angular range of a scale.
163  * @param obj           pointer to a meter object
164  * @param scale         pointer to scale (added to `meter`)
165  * @param min           the minimum value
166  * @param max           the maximal value
167  * @param angle_range   the angular range of the scale
168  * @param rotation      the angular offset from the 3 o'clock position (clock-wise)
169  */
170 void lv_meter_set_scale_range(lv_obj_t * obj, lv_meter_scale_t * scale, int32_t min, int32_t max, uint32_t angle_range,
171                               uint32_t rotation);
172 
173 /*=====================
174  * Add indicator
175  *====================*/
176 
177 /**
178  * Add a needle line indicator the scale
179  * @param obj           pointer to a meter object
180  * @param scale         pointer to scale (added to `meter`)
181  * @param width         width of the line
182  * @param color         color of the line
183  * @param r_mod         the radius modifier (added to the scale's radius) to get the lines length
184  * @return              the new indicator
185  */
186 lv_meter_indicator_t * lv_meter_add_needle_line(lv_obj_t * obj, lv_meter_scale_t * scale, uint16_t width,
187                                                 lv_color_t color, int16_t r_mod);
188 
189 /**
190  * Add a needle image indicator the scale
191  * @param obj           pointer to a meter object
192  * @param scale         pointer to scale (added to `meter`)
193  * @param src           the image source of the indicator. path or pointer to ::lv_img_dsc_t
194  * @param pivot_x       the X pivot point of the needle
195  * @param pivot_y       the Y pivot point of the needle
196  * @return              the new indicator
197  * @note                the needle image should point to the right, like -O----->
198  */
199 lv_meter_indicator_t * lv_meter_add_needle_img(lv_obj_t * obj, lv_meter_scale_t * scale, const void * src,
200                                                lv_coord_t pivot_x, lv_coord_t pivot_y);
201 
202 /**
203  * Add an arc indicator the scale
204  * @param obj           pointer to a meter object
205  * @param scale         pointer to scale (added to `meter`)
206  * @param width         width of the arc
207  * @param color         color of the arc
208  * @param r_mod         the radius modifier (added to the scale's radius) to get the outer radius of the arc
209  * @return              the new indicator
210  */
211 lv_meter_indicator_t * lv_meter_add_arc(lv_obj_t * obj, lv_meter_scale_t * scale, uint16_t width, lv_color_t color,
212                                         int16_t r_mod);
213 
214 /**
215  * Add a scale line indicator the scale. It will modify the ticks.
216  * @param obj           pointer to a meter object
217  * @param scale         pointer to scale (added to `meter`)
218  * @param color_start   the start color
219  * @param color_end     the end color
220  * @param local         tell how to map start and end color. true: the indicator's start and end_value; false: the scale's min max value
221  * @param width_mod     add this the affected tick's width
222  * @return              the new indicator
223  */
224 lv_meter_indicator_t * lv_meter_add_scale_lines(lv_obj_t * obj, lv_meter_scale_t * scale, lv_color_t color_start,
225                                                 lv_color_t color_end, bool local, int16_t width_mod);
226 
227 /*=====================
228  * Set indicator value
229  *====================*/
230 
231 /**
232  * Set the value of the indicator. It will set start and and value to the same value
233  * @param obj           pointer to a meter object
234  * @param indic         pointer to an indicator
235  * @param value         the new value
236  */
237 void lv_meter_set_indicator_value(lv_obj_t * obj, lv_meter_indicator_t * indic, int32_t value);
238 
239 /**
240  * Set the start value of the indicator.
241  * @param obj           pointer to a meter object
242  * @param indic         pointer to an indicator
243  * @param value         the new value
244  */
245 void lv_meter_set_indicator_start_value(lv_obj_t * obj, lv_meter_indicator_t * indic, int32_t value);
246 
247 /**
248  * Set the start value of the indicator.
249  * @param obj           pointer to a meter object
250  * @param indic         pointer to an indicator
251  * @param value         the new value
252  */
253 void lv_meter_set_indicator_end_value(lv_obj_t * obj, lv_meter_indicator_t * indic, int32_t value);
254 
255 /**********************
256  *      MACROS
257  **********************/
258 
259 #endif /*LV_USE_METER*/
260 
261 #ifdef __cplusplus
262 } /*extern "C"*/
263 #endif
264 
265 #endif /*LV_METER_H*/
266