1 /**
2 * @file lv_gauge.h
3 *
4 */
5
6 #ifndef LV_GAUGE_H
7 #define LV_GAUGE_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_GAUGE != 0
19
20 /*Testing of dependencies*/
21 #if LV_USE_LINEMETER == 0
22 #error "lv_gauge: lv_linemeter is required. Enable it in lv_conf.h (LV_USE_LINEMETER 1) "
23 #endif
24
25 #include "../lv_core/lv_obj.h"
26 #include "lv_linemeter.h"
27 #include "lv_label.h"
28 #include "lv_line.h"
29
30 /*********************
31 * DEFINES
32 *********************/
33
34 /**********************
35 * TYPEDEFS
36 **********************/
37
38 typedef void (*lv_gauge_format_cb_t)(lv_obj_t * gauge, char * buf, int bufsize, int32_t value);
39
40 /*Data of gauge*/
41 typedef struct {
42 lv_linemeter_ext_t lmeter; /*Ext. of ancestor*/
43 /*New data for this type */
44 int32_t * values; /*Array of the set values (for needles) */
45 const lv_color_t * needle_colors; /*Color of the needles (lv_color_t my_colors[needle_num])*/
46 const void * needle_img;
47 lv_point_t needle_img_pivot;
48 lv_style_list_t style_needle;
49 lv_style_list_t style_strong;
50 uint8_t needle_count; /*Number of needles*/
51 uint8_t label_count; /*Number of labels on the scale*/
52 lv_gauge_format_cb_t format_cb;
53 } lv_gauge_ext_t;
54
55 /*Styles*/
56 enum {
57 LV_GAUGE_PART_MAIN = LV_LINEMETER_PART_MAIN,
58 LV_GAUGE_PART_MAJOR = _LV_LINEMETER_PART_VIRTUAL_LAST,
59 LV_GAUGE_PART_NEEDLE,
60 _LV_GAUGE_PART_VIRTUAL_LAST = _LV_LINEMETER_PART_VIRTUAL_LAST,
61 _LV_GAUGE_PART_REAL_LAST = _LV_LINEMETER_PART_REAL_LAST,
62 };
63 typedef uint8_t lv_gauge_style_t;
64
65 /**********************
66 * GLOBAL PROTOTYPES
67 **********************/
68
69 /**
70 * Create a gauge objects
71 * @param par pointer to an object, it will be the parent of the new gauge
72 * @param copy pointer to a gauge object, if not NULL then the new object will be copied from it
73 * @return pointer to the created gauge
74 */
75 lv_obj_t * lv_gauge_create(lv_obj_t * par, const lv_obj_t * copy);
76
77 /*=====================
78 * Setter functions
79 *====================*/
80
81 /**
82 * Set the number of needles
83 * @param gauge pointer to gauge object
84 * @param needle_cnt new count of needles
85 * @param colors an array of colors for needles (with 'num' elements)
86 */
87 void lv_gauge_set_needle_count(lv_obj_t * gauge, uint8_t needle_cnt, const lv_color_t colors[]);
88
89 /**
90 * Set the value of a needle
91 * @param gauge pointer to a gauge
92 * @param needle_id the id of the needle
93 * @param value the new value
94 */
95 void lv_gauge_set_value(lv_obj_t * gauge, uint8_t needle_id, int32_t value);
96
97 /**
98 * Set minimum and the maximum values of a gauge
99 * @param gauge pointer to he gauge object
100 * @param min minimum value
101 * @param max maximum value
102 */
lv_gauge_set_range(lv_obj_t * gauge,int32_t min,int32_t max)103 static inline void lv_gauge_set_range(lv_obj_t * gauge, int32_t min, int32_t max)
104 {
105 lv_linemeter_set_range(gauge, min, max);
106 }
107
108 /**
109 * Set a critical value on the scale. After this value 'line.color' scale lines will be drawn
110 * @param gauge pointer to a gauge object
111 * @param value the critical value
112 */
lv_gauge_set_critical_value(lv_obj_t * gauge,int32_t value)113 static inline void lv_gauge_set_critical_value(lv_obj_t * gauge, int32_t value)
114 {
115 lv_linemeter_set_value(gauge, value);
116 }
117
118 /**
119 * Set the scale settings of a gauge
120 * @param gauge pointer to a gauge object
121 * @param angle angle of the scale (0..360)
122 * @param line_cnt count of scale lines.
123 * To get a given "subdivision" lines between labels:
124 * `line_cnt = (sub_div + 1) * (label_cnt - 1) + 1 `
125 * @param label_cnt count of scale labels.
126 */
127 void lv_gauge_set_scale(lv_obj_t * gauge, uint16_t angle, uint8_t line_cnt, uint8_t label_cnt);
128
129 /**
130 * Set the set an offset for the gauge's angles to rotate it.
131 * @param gauge pointer to a line meter object
132 * @param angle angle offset (0..360), rotates clockwise
133 */
lv_gauge_set_angle_offset(lv_obj_t * gauge,uint16_t angle)134 static inline void lv_gauge_set_angle_offset(lv_obj_t * gauge, uint16_t angle)
135 {
136 lv_linemeter_set_angle_offset(gauge, angle);
137 }
138
139 /**
140 * Set an image to display as needle(s).
141 * The needle image should be horizontal and pointing to the right (`--->`).
142 * @param gauge pointer to a gauge object
143 * @param img_src pointer to an `lv_img_dsc_t` variable or a path to an image
144 * (not an `lv_img` object)
145 * @param pivot_x the X coordinate of rotation center of the image
146 * @param pivot_y the Y coordinate of rotation center of the image
147 */
148 void lv_gauge_set_needle_img(lv_obj_t * gauge, const void * img, lv_coord_t pivot_x, lv_coord_t pivot_y);
149
150 /**
151 * Assign a function to format gauge values
152 * @param gauge pointer to a gauge object
153 * @param format_cb pointer to function of lv_gauge_format_cb_t
154 */
155 void lv_gauge_set_formatter_cb(lv_obj_t * gauge, lv_gauge_format_cb_t format_cb);
156
157 /*=====================
158 * Getter functions
159 *====================*/
160
161 /**
162 * Get the value of a needle
163 * @param gauge pointer to gauge object
164 * @param needle the id of the needle
165 * @return the value of the needle [min,max]
166 */
167 int32_t lv_gauge_get_value(const lv_obj_t * gauge, uint8_t needle);
168
169 /**
170 * Get the count of needles on a gauge
171 * @param gauge pointer to gauge
172 * @return count of needles
173 */
174 uint8_t lv_gauge_get_needle_count(const lv_obj_t * gauge);
175
176 /**
177 * Get the minimum value of a gauge
178 * @param gauge pointer to a gauge object
179 * @return the minimum value of the gauge
180 */
lv_gauge_get_min_value(const lv_obj_t * lmeter)181 static inline int32_t lv_gauge_get_min_value(const lv_obj_t * lmeter)
182 {
183 return lv_linemeter_get_min_value(lmeter);
184 }
185
186 /**
187 * Get the maximum value of a gauge
188 * @param gauge pointer to a gauge object
189 * @return the maximum value of the gauge
190 */
lv_gauge_get_max_value(const lv_obj_t * lmeter)191 static inline int32_t lv_gauge_get_max_value(const lv_obj_t * lmeter)
192 {
193 return lv_linemeter_get_max_value(lmeter);
194 }
195
196 /**
197 * Get a critical value on the scale.
198 * @param gauge pointer to a gauge object
199 * @return the critical value
200 */
lv_gauge_get_critical_value(const lv_obj_t * gauge)201 static inline int32_t lv_gauge_get_critical_value(const lv_obj_t * gauge)
202 {
203 return lv_linemeter_get_value(gauge);
204 }
205
206 /**
207 * Set the number of labels (and the thicker lines too)
208 * @param gauge pointer to a gauge object
209 * @return count of labels
210 */
211 uint8_t lv_gauge_get_label_count(const lv_obj_t * gauge);
212
213 /**
214 * Get the scale number of a gauge
215 * @param gauge pointer to a gauge object
216 * @return number of the scale units
217 */
lv_gauge_get_line_count(const lv_obj_t * gauge)218 static inline uint16_t lv_gauge_get_line_count(const lv_obj_t * gauge)
219 {
220 return lv_linemeter_get_line_count(gauge);
221 }
222
223 /**
224 * Get the scale angle of a gauge
225 * @param gauge pointer to a gauge object
226 * @return angle of the scale
227 */
lv_gauge_get_scale_angle(const lv_obj_t * gauge)228 static inline uint16_t lv_gauge_get_scale_angle(const lv_obj_t * gauge)
229 {
230 return lv_linemeter_get_scale_angle(gauge);
231 }
232
233 /**
234 * Get the offset for the gauge.
235 * @param gauge pointer to a gauge object
236 * @return angle offset (0..360)
237 */
lv_gauge_get_angle_offset(lv_obj_t * gauge)238 static inline uint16_t lv_gauge_get_angle_offset(lv_obj_t * gauge)
239 {
240 return lv_linemeter_get_angle_offset(gauge);
241 }
242
243 /**
244 * Get an image to display as needle(s).
245 * @param gauge pointer to a gauge object
246 * @return pointer to an `lv_img_dsc_t` variable or a path to an image
247 * (not an `lv_img` object). `NULL` if not used.
248 */
249 const void * lv_gauge_get_needle_img(lv_obj_t * gauge);
250
251 /**
252 * Get the X coordinate of the rotation center of the needle image
253 * @param gauge pointer to a gauge object
254 * @return the X coordinate of rotation center of the image
255 */
256 lv_coord_t lv_gauge_get_needle_img_pivot_x(lv_obj_t * gauge);
257
258 /**
259 * Get the Y coordinate of the rotation center of the needle image
260 * @param gauge pointer to a gauge object
261 * @return the X coordinate of rotation center of the image
262 */
263 lv_coord_t lv_gauge_get_needle_img_pivot_y(lv_obj_t * gauge);
264
265 /**********************
266 * MACROS
267 **********************/
268
269 #endif /*LV_USE_GAUGE*/
270
271 #ifdef __cplusplus
272 } /* extern "C" */
273 #endif
274
275 #endif /*LV_GAUGE_H*/
276
