1 /**
2  * @file lv_scale.h
3  *
4  */
5 
6 #ifndef LV_SCALE_H
7 #define LV_SCALE_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_SCALE != 0
19 
20 #include "../../core/lv_obj.h"
21 #include "../line/lv_line.h"
22 #include "../image/lv_image.h"
23 
24 /*********************
25  *      DEFINES
26  *********************/
27 
28 /**Default value of total minor ticks. */
29 #define LV_SCALE_TOTAL_TICK_COUNT_DEFAULT (11U)
30 LV_EXPORT_CONST_INT(LV_SCALE_TOTAL_TICK_COUNT_DEFAULT);
31 
32 /**Default value of major tick every nth ticks. */
33 #define LV_SCALE_MAJOR_TICK_EVERY_DEFAULT (5U)
34 LV_EXPORT_CONST_INT(LV_SCALE_MAJOR_TICK_EVERY_DEFAULT);
35 
36 /**Default value of scale label enabled. */
37 #define LV_SCALE_LABEL_ENABLED_DEFAULT (1U)
38 LV_EXPORT_CONST_INT(LV_SCALE_LABEL_ENABLED_DEFAULT);
39 
40 /**********************
41  *      TYPEDEFS
42  **********************/
43 
44 /**
45  * Scale mode
46  */
47 typedef enum {
48     LV_SCALE_MODE_HORIZONTAL_TOP    = 0x00U,
49     LV_SCALE_MODE_HORIZONTAL_BOTTOM = 0x01U,
50     LV_SCALE_MODE_VERTICAL_LEFT     = 0x02U,
51     LV_SCALE_MODE_VERTICAL_RIGHT    = 0x04U,
52     LV_SCALE_MODE_ROUND_INNER       = 0x08U,
53     LV_SCALE_MODE_ROUND_OUTER      = 0x10U,
54     LV_SCALE_MODE_LAST
55 } lv_scale_mode_t;
56 
57 #define LV_SCALE_LABEL_ROTATE_MATCH_TICKS  0x100000
58 LV_EXPORT_CONST_INT(LV_SCALE_LABEL_ROTATE_MATCH_TICKS);
59 
60 #define LV_SCALE_LABEL_ROTATE_KEEP_UPRIGHT 0x80000
61 LV_EXPORT_CONST_INT(LV_SCALE_LABEL_ROTATE_KEEP_UPRIGHT);
62 
63 #define LV_SCALE_ROTATION_ANGLE_MASK 0x7FFFF
64 LV_EXPORT_CONST_INT(LV_SCALE_ROTATION_ANGLE_MASK);
65 
66 LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_scale_class;
67 
68 /**********************
69  * GLOBAL PROTOTYPES
70  **********************/
71 
72 /**
73  * Create an scale object
74  * @param parent    pointer to an object, it will be the parent of the new scale
75  * @return          pointer to created Scale Widget
76  */
77 lv_obj_t * lv_scale_create(lv_obj_t * parent);
78 
79 /*======================
80  * Add/remove functions
81  *=====================*/
82 
83 /*=====================
84  * Setter functions
85  *====================*/
86 
87 /**
88  * Set scale mode. See lv_scale_mode_t.
89  * @param obj       pointer to Scale Widget
90  * @param mode      the new scale mode
91  */
92 void lv_scale_set_mode(lv_obj_t * obj, lv_scale_mode_t mode);
93 
94 /**
95  * Set scale total tick count (including minor and major ticks).
96  * @param obj       pointer to Scale Widget
97  * @param total_tick_count    New total tick count
98  */
99 void lv_scale_set_total_tick_count(lv_obj_t * obj, uint32_t total_tick_count);
100 
101 /**
102  * Sets how often major ticks are drawn.
103  * @param obj                 pointer to Scale Widget
104  * @param major_tick_every    the new count for major tick drawing
105  */
106 void lv_scale_set_major_tick_every(lv_obj_t * obj, uint32_t major_tick_every);
107 
108 /**
109  * Sets label visibility.
110  * @param obj           pointer to Scale Widget
111  * @param show_label    true/false to enable tick label
112  */
113 void lv_scale_set_label_show(lv_obj_t * obj, bool show_label);
114 
115 /**
116  * Set minimum and maximum values on Scale.
117  * @param obj       pointer to Scale Widget
118  * @param min       minimum value of Scale
119  * @param max       maximum value of Scale
120  */
121 void lv_scale_set_range(lv_obj_t * obj, int32_t min, int32_t max);
122 
123 /**
124  * Set angle between the low end and the high end of the Scale.
125  * (Applies only to round Scales.)
126  * @param obj         pointer to Scale Widget
127  * @param max_angle   angle in degrees from Scale minimum where top end of Scale will be drawn
128  */
129 void lv_scale_set_angle_range(lv_obj_t * obj, uint32_t angle_range);
130 
131 /**
132  * Set angular offset from the 3-o'clock position of the low end of the Scale.
133  * (Applies only to round Scales.)
134  * @param obj       pointer to Scale Widget
135  * @param rotation  clockwise angular offset (in degrees) from the 3-o'clock position
136  *                  of the low end of the scale; negative and >360 values are first normalized
137  *                  to range [0..360].
138  *                  Examples:
139  *                      -   0 = 3 o'clock (right side)
140  *                      -  30 = 4 o'clock
141  *                      -  60 = 5 o'clock
142  *                      -  90 = 6 o'clock
143  *                      - 135 = midway between 7 and 8 o'clock (default)
144  *                      - 180 = 9 o'clock
145  *                      - 270 = 12 o'clock
146  *                      - 300 = 1 o'clock
147  *                      - 330 = 2 o'clock
148  *                      - -30 = 2 o'clock
149  *                      - 390 = 4 o'clock
150  */
151 void lv_scale_set_rotation(lv_obj_t * obj, int32_t rotation);
152 
153 /**
154  * Point line needle to specified value.
155  * @param obj              pointer to Scale Widget
156  * @param needle_line      needle_line of the Scale. The line points will be allocated and
157  *                         managed by the Scale unless the line point array was previously set
158  *                         using `lv_line_set_points_mutable`.
159  * @param needle_length    length of the needle
160  *                         - needle_length>0: needle_length=needle_length;
161  *                         - needle_length<0: needle_length=radius-|needle_length|;
162  * @param value            Scale value needle will point to
163  */
164 void lv_scale_set_line_needle_value(lv_obj_t * obj, lv_obj_t * needle_line, int32_t needle_length,
165                                     int32_t value);
166 
167 /**
168  * Point image needle to specified value;
169    image must point to the right. E.g. -O------>
170  * @param obj              pointer to Scale Widget
171  * @param needle_img       pointer to needle's Image
172  * @param value            Scale value needle will point to
173  */
174 void lv_scale_set_image_needle_value(lv_obj_t * obj, lv_obj_t * needle_img, int32_t value);
175 
176 /**
177  * Set custom text source for major ticks labels.
178  * @param obj       pointer to Scale Widget
179  * @param txt_src   pointer to an array of strings which will be display at major ticks;
180  *                  last element must be a NULL pointer.
181  */
182 void lv_scale_set_text_src(lv_obj_t * obj, const char * txt_src[]);
183 
184 /**
185  * Draw Scale after all its children are drawn.
186  * @param obj       pointer to Scale Widget
187  * @param en        true: enable post draw
188  */
189 void lv_scale_set_post_draw(lv_obj_t * obj, bool en);
190 
191 /**
192  * Draw Scale ticks on top of all other parts.
193  * @param obj       pointer to Scale Widget
194  * @param en        true: enable draw ticks on top of all parts
195  */
196 void lv_scale_set_draw_ticks_on_top(lv_obj_t * obj, bool en);
197 
198 /**
199  * Add a Section to specified Scale.  Section will not be drawn until
200  * a valid range is set for it using `lv_scale_section_set_range()`.
201  * @param obj       pointer to Scale Widget
202  * @return          pointer to new Section
203  */
204 lv_scale_section_t * lv_scale_add_section(lv_obj_t * obj);
205 
206 /**
207  * Set range for specified Scale Section
208  * @param section       pointer to Section
209  * @param range_min     Section new minimum value
210  * @param range_max     Section new maximum value
211  */
212 void lv_scale_section_set_range(lv_scale_section_t * section, int32_t min, int32_t max);
213 
214 /**
215  * Set style for specified part of Section.
216  * @param section             pointer to Section
217  * @param part                the part of the Scale the style will apply to, e.g. LV_PART_INDICATOR
218  * @param section_part_style  pointer to style to apply
219  */
220 void lv_scale_section_set_style(lv_scale_section_t * section, lv_part_t part, lv_style_t * section_part_style);
221 
222 /*=====================
223  * Getter functions
224  *====================*/
225 
226 /**
227  * Get scale mode. See lv_scale_mode_t
228  * @param obj   pointer to Scale Widget
229  * @return      Scale mode
230  */
231 lv_scale_mode_t lv_scale_get_mode(lv_obj_t * obj);
232 
233 /**
234  * Get scale total tick count (including minor and major ticks)
235  * @param obj   pointer to Scale Widget
236  * @return      Scale total tick count
237  */
238 int32_t lv_scale_get_total_tick_count(lv_obj_t * obj);
239 
240 /**
241  * Get how often the major tick will be drawn
242  * @param obj   pointer to Scale Widget
243  * @return      Scale major tick every count
244  */
245 int32_t lv_scale_get_major_tick_every(lv_obj_t * obj);
246 
247 /**
248  * Get angular location of low end of Scale.
249  * @param obj   pointer to Scale Widget
250  * @return      Scale major tick every count
251  */
252 lv_scale_mode_t lv_scale_get_rotation(lv_obj_t * obj);
253 
254 /**
255  * Gets label visibility
256  * @param obj   pointer to Scale Widget
257  * @return      true if tick label is enabled, false otherwise
258  */
259 bool lv_scale_get_label_show(lv_obj_t * obj);
260 
261 /**
262  * Get Scale's range in degrees
263  * @param obj   pointer to Scale Widget
264  * @return      Scale's angle_range
265  */
266 uint32_t lv_scale_get_angle_range(lv_obj_t * obj);
267 
268 /**
269  * Get minimum value for Scale
270  * @param obj   pointer to Scale Widget
271  * @return      Scale's minimum value
272  */
273 int32_t lv_scale_get_range_min_value(lv_obj_t * obj);
274 
275 /**
276  * Get maximum value for Scale
277  * @param obj   pointer to Scale Widget
278  * @return      Scale's maximum value
279  */
280 int32_t lv_scale_get_range_max_value(lv_obj_t * obj);
281 
282 /**********************
283  *      MACROS
284  **********************/
285 
286 #endif /*LV_USE_SCALE*/
287 
288 #ifdef __cplusplus
289 } /*extern "C"*/
290 #endif
291 
292 #endif /*LV_SCALE_H*/
293