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