1 /**
2  * @file lv_obj_pos.h
3  *
4  */
5 
6 #ifndef LV_OBJ_POS_H
7 #define LV_OBJ_POS_H
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 /*********************
14  *      INCLUDES
15  *********************/
16 #include "../misc/lv_area.h"
17 
18 /*********************
19  *      DEFINES
20  *********************/
21 
22 /**********************
23  *      TYPEDEFS
24  **********************/
25 
26 typedef enum {
27     /** No flags */
28     LV_OBJ_POINT_TRANSFORM_FLAG_NONE = 0x00,
29 
30     /** Consider the transformation properties of the parents too */
31     LV_OBJ_POINT_TRANSFORM_FLAG_RECURSIVE = 0x01,
32 
33     /** Execute the inverse of the transformation (-angle and 1/zoom) */
34     LV_OBJ_POINT_TRANSFORM_FLAG_INVERSE = 0x02,
35 
36     /** Both inverse and recursive*/
37     LV_OBJ_POINT_TRANSFORM_FLAG_INVERSE_RECURSIVE = 0x03,
38 } lv_obj_point_transform_flag_t;
39 
40 /**********************
41  * GLOBAL PROTOTYPES
42  **********************/
43 
44 /**
45  * Set the position of an object relative to the set alignment.
46  * @param obj       pointer to an object
47  * @param x         new x coordinate
48  * @param y         new y coordinate
49  * @note            With default alignment it's the distance from the top left corner
50  * @note            E.g. LV_ALIGN_CENTER alignment it's the offset from the center of the parent
51  * @note            The position is interpreted on the content area of the parent
52  * @note            The values can be set in pixel or in percentage of parent size with `lv_pct(v)`
53  */
54 void lv_obj_set_pos(lv_obj_t * obj, int32_t x, int32_t y);
55 
56 /**
57  * Set the x coordinate of an object
58  * @param obj       pointer to an object
59  * @param x         new x coordinate
60  * @note            With default alignment it's the distance from the top left corner
61  * @note            E.g. LV_ALIGN_CENTER alignment it's the offset from the center of the parent
62  * @note            The position is interpreted on the content area of the parent
63  * @note            The values can be set in pixel or in percentage of parent size with `lv_pct(v)`
64  */
65 void lv_obj_set_x(lv_obj_t * obj, int32_t x);
66 
67 /**
68  * Set the y coordinate of an object
69  * @param obj       pointer to an object
70  * @param y         new y coordinate
71  * @note            With default alignment it's the distance from the top left corner
72  * @note            E.g. LV_ALIGN_CENTER alignment it's the offset from the center of the parent
73  * @note            The position is interpreted on the content area of the parent
74  * @note            The values can be set in pixel or in percentage of parent size with `lv_pct(v)`
75  */
76 void lv_obj_set_y(lv_obj_t * obj, int32_t y);
77 
78 /**
79  * Set the size of an object.
80  * @param obj       pointer to an object
81  * @param w         the new width
82  * @param h         the new height
83  * @note            possible values are:
84  *                  pixel               simple set the size accordingly
85  *                  LV_SIZE_CONTENT     set the size to involve all children in the given direction
86  *                  lv_pct(x)           to set size in percentage of the parent's content area size (the size without paddings).
87  *                                      x should be in [0..1000]% range
88  */
89 void lv_obj_set_size(lv_obj_t * obj, int32_t w, int32_t h);
90 
91 /**
92  * Recalculate the size of the object
93  * @param obj       pointer to an object
94  * @return          true: the size has been changed
95  */
96 bool lv_obj_refr_size(lv_obj_t * obj);
97 
98 /**
99  * Set the width of an object
100  * @param obj       pointer to an object
101  * @param w         the new width
102  * @note            possible values are:
103  *                  pixel               simple set the size accordingly
104  *                  LV_SIZE_CONTENT     set the size to involve all children in the given direction
105  *                  lv_pct(x)           to set size in percentage of the parent's content area size (the size without paddings).
106  *                                      x should be in [0..1000]% range
107  */
108 void lv_obj_set_width(lv_obj_t * obj, int32_t w);
109 
110 /**
111  * Set the height of an object
112  * @param obj       pointer to an object
113  * @param h         the new height
114  * @note            possible values are:
115  *                  pixel               simple set the size accordingly
116  *                  LV_SIZE_CONTENT     set the size to involve all children in the given direction
117  *                  lv_pct(x)           to set size in percentage of the parent's content area size (the size without paddings).
118  *                                      x should be in [0..1000]% range
119  */
120 void lv_obj_set_height(lv_obj_t * obj, int32_t h);
121 
122 /**
123  * Set the width reduced by the left and right padding and the border width.
124  * @param obj       pointer to an object
125  * @param w         the width without paddings in pixels
126  */
127 void lv_obj_set_content_width(lv_obj_t * obj, int32_t w);
128 
129 /**
130  * Set the height reduced by the top and bottom padding and the border width.
131  * @param obj       pointer to an object
132  * @param h         the height without paddings in pixels
133  */
134 void lv_obj_set_content_height(lv_obj_t * obj, int32_t h);
135 
136 /**
137  * Set a layout for an object
138  * @param obj       pointer to an object
139  * @param layout    pointer to a layout descriptor to set
140  */
141 void lv_obj_set_layout(lv_obj_t * obj, uint32_t layout);
142 
143 /**
144  * Test whether the and object is positioned by a layout or not
145  * @param obj       pointer to an object to test
146  * @return true:    positioned by a layout; false: not positioned by a layout
147  */
148 bool lv_obj_is_layout_positioned(const lv_obj_t * obj);
149 
150 /**
151  * Mark the object for layout update.
152  * @param obj      pointer to an object whose children need to be updated
153  */
154 void lv_obj_mark_layout_as_dirty(lv_obj_t * obj);
155 
156 /**
157  * Update the layout of an object.
158  * @param obj      pointer to an object whose position and size needs to be updated
159  */
160 void lv_obj_update_layout(const lv_obj_t * obj);
161 
162 /**
163  * Change the alignment of an object.
164  * @param obj       pointer to an object to align
165  * @param align     type of alignment (see 'lv_align_t' enum) `LV_ALIGN_OUT_...` can't be used.
166  */
167 void lv_obj_set_align(lv_obj_t * obj, lv_align_t align);
168 
169 /**
170  * Change the alignment of an object and set new coordinates.
171  * Equivalent to:
172  * lv_obj_set_align(obj, align);
173  * lv_obj_set_pos(obj, x_ofs, y_ofs);
174  * @param obj       pointer to an object to align
175  * @param align     type of alignment (see 'lv_align_t' enum) `LV_ALIGN_OUT_...` can't be used.
176  * @param x_ofs     x coordinate offset after alignment
177  * @param y_ofs     y coordinate offset after alignment
178  */
179 void lv_obj_align(lv_obj_t * obj, lv_align_t align, int32_t x_ofs, int32_t y_ofs);
180 
181 /**
182  * Align an object to another object.
183  * @param obj       pointer to an object to align
184  * @param base      pointer to another object (if NULL `obj`s parent is used). 'obj' will be aligned to it.
185  * @param align     type of alignment (see 'lv_align_t' enum)
186  * @param x_ofs     x coordinate offset after alignment
187  * @param y_ofs     y coordinate offset after alignment
188  * @note            if the position or size of `base` changes `obj` needs to be aligned manually again
189  */
190 void lv_obj_align_to(lv_obj_t * obj, const lv_obj_t * base, lv_align_t align, int32_t x_ofs,
191                      int32_t y_ofs);
192 
193 /**
194  * Align an object to the center on its parent.
195  * @param obj       pointer to an object to align
196  * @note            if the parent size changes `obj` needs to be aligned manually again
197  */
198 void lv_obj_center(lv_obj_t * obj);
199 
200 /**
201  * Set the transform matrix of an object
202  * @param obj       pointer to an object
203  * @param matrix    pointer to a matrix to set
204  * @note `LV_DRAW_TRANSFORM_USE_MATRIX` needs to be enabled.
205  */
206 void lv_obj_set_transform(lv_obj_t * obj, const lv_matrix_t * matrix);
207 
208 /**
209  * Reset the transform matrix of an object to identity matrix
210  * @param obj       pointer to an object
211  * @note `LV_DRAW_TRANSFORM_USE_MATRIX` needs to be enabled.
212  */
213 void lv_obj_reset_transform(lv_obj_t * obj);
214 
215 /**
216  * Copy the coordinates of an object to an area
217  * @param obj       pointer to an object
218  * @param coords    pointer to an area to store the coordinates
219  */
220 void lv_obj_get_coords(const lv_obj_t * obj, lv_area_t * coords);
221 
222 /**
223  * Get the x coordinate of object.
224  * @param obj       pointer to an object
225  * @return          distance of `obj` from the left side of its parent plus the parent's left padding
226  * @note            The position of the object is recalculated only on the next redraw. To force coordinate recalculation
227  *                  call `lv_obj_update_layout(obj)`.
228  * @note            Zero return value means the object is on the left padding of the parent, and not on the left edge.
229  * @note            Scrolling of the parent doesn't change the returned value.
230  * @note            The returned value is always the distance from the parent even if `obj` is positioned by a layout.
231  */
232 int32_t lv_obj_get_x(const lv_obj_t * obj);
233 
234 /**
235  * Get the x2 coordinate of object.
236  * @param obj       pointer to an object
237  * @return          distance of `obj` from the right side of its parent plus the parent's right padding
238  * @note            The position of the object is recalculated only on the next redraw. To force coordinate recalculation
239  *                  call `lv_obj_update_layout(obj)`.
240  * @note            Zero return value means the object is on the right padding of the parent, and not on the right edge.
241  * @note            Scrolling of the parent doesn't change the returned value.
242  * @note            The returned value is always the distance from the parent even if `obj` is positioned by a layout.
243  */
244 int32_t lv_obj_get_x2(const lv_obj_t * obj);
245 
246 /**
247  * Get the y coordinate of object.
248  * @param obj       pointer to an object
249  * @return          distance of `obj` from the top side of its parent plus the parent's top padding
250  * @note            The position of the object is recalculated only on the next redraw. To force coordinate recalculation
251  *                  call `lv_obj_update_layout(obj)`.
252  * @note            Zero return value means the object is on the top padding of the parent, and not on the top edge.
253  * @note            Scrolling of the parent doesn't change the returned value.
254  * @note            The returned value is always the distance from the parent even if `obj` is positioned by a layout.
255  */
256 int32_t lv_obj_get_y(const lv_obj_t * obj);
257 
258 /**
259  * Get the y2 coordinate of object.
260  * @param obj       pointer to an object
261  * @return          distance of `obj` from the bottom side of its parent plus the parent's bottom padding
262  * @note            The position of the object is recalculated only on the next redraw. To force coordinate recalculation
263  *                  call `lv_obj_update_layout(obj)`.
264  * @note            Zero return value means the object is on the bottom padding of the parent, and not on the bottom edge.
265  * @note            Scrolling of the parent doesn't change the returned value.
266  * @note            The returned value is always the distance from the parent even if `obj` is positioned by a layout.
267  */
268 int32_t lv_obj_get_y2(const lv_obj_t * obj);
269 
270 /**
271  * Get the actually set x coordinate of object, i.e. the offset from the set alignment
272  * @param obj       pointer to an object
273  * @return          the set x coordinate
274  */
275 int32_t lv_obj_get_x_aligned(const lv_obj_t * obj);
276 
277 /**
278  * Get the actually set y coordinate of object, i.e. the offset from the set alignment
279  * @param obj       pointer to an object
280  * @return          the set y coordinate
281  */
282 int32_t lv_obj_get_y_aligned(const lv_obj_t * obj);
283 
284 /**
285  * Get the width of an object
286  * @param obj       pointer to an object
287  * @note            The position of the object is recalculated only on the next redraw. To force coordinate recalculation
288  *                  call `lv_obj_update_layout(obj)`.
289  * @return          the width in pixels
290  */
291 int32_t lv_obj_get_width(const lv_obj_t * obj);
292 
293 /**
294  * Get the height of an object
295  * @param obj       pointer to an object
296  * @note            The position of the object is recalculated only on the next redraw. To force coordinate recalculation
297  *                  call `lv_obj_update_layout(obj)`.
298  * @return          the height in pixels
299  */
300 int32_t lv_obj_get_height(const lv_obj_t * obj);
301 
302 /**
303  * Get the width reduced by the left and right padding and the border width.
304  * @param obj       pointer to an object
305  * @note            The position of the object is recalculated only on the next redraw. To force coordinate recalculation
306  *                  call `lv_obj_update_layout(obj)`.
307  * @return          the width which still fits into its parent without causing overflow (making the parent scrollable)
308  */
309 int32_t lv_obj_get_content_width(const lv_obj_t * obj);
310 
311 /**
312  * Get the height reduced by the top and bottom padding and the border width.
313  * @param obj       pointer to an object
314  * @note            The position of the object is recalculated only on the next redraw. To force coordinate recalculation
315  *                  call `lv_obj_update_layout(obj)`.
316  * @return          the height which still fits into the parent without causing overflow (making the parent scrollable)
317  */
318 int32_t lv_obj_get_content_height(const lv_obj_t * obj);
319 
320 /**
321  * Get the area reduced by the paddings and the border width.
322  * @param obj       pointer to an object
323  * @note            The position of the object is recalculated only on the next redraw. To force coordinate recalculation
324  *                  call `lv_obj_update_layout(obj)`.
325  * @param area      the area which still fits into the parent without causing overflow (making the parent scrollable)
326  */
327 void lv_obj_get_content_coords(const lv_obj_t * obj, lv_area_t * area);
328 
329 /**
330  * Get the width occupied by the "parts" of the widget. E.g. the width of all columns of a table.
331  * @param obj       pointer to an objects
332  * @return          the width of the virtually drawn content
333  * @note            This size independent from the real size of the widget.
334  *                  It just tells how large the internal ("virtual") content is.
335  */
336 int32_t lv_obj_get_self_width(const lv_obj_t * obj);
337 
338 /**
339  * Get the height occupied by the "parts" of the widget. E.g. the height of all rows of a table.
340  * @param obj       pointer to an objects
341  * @return          the width of the virtually drawn content
342  * @note            This size independent from the real size of the widget.
343  *                  It just tells how large the internal ("virtual") content is.
344  */
345 int32_t lv_obj_get_self_height(const lv_obj_t * obj);
346 
347 /**
348  * Handle if the size of the internal ("virtual") content of an object has changed.
349  * @param obj       pointer to an object
350  * @return          false: nothing happened; true: refresh happened
351  */
352 bool lv_obj_refresh_self_size(lv_obj_t * obj);
353 
354 void lv_obj_refr_pos(lv_obj_t * obj);
355 
356 void lv_obj_move_to(lv_obj_t * obj, int32_t x, int32_t y);
357 
358 void lv_obj_move_children_by(lv_obj_t * obj, int32_t x_diff, int32_t y_diff, bool ignore_floating);
359 
360 /**
361  * Get the transform matrix of an object
362  * @param obj       pointer to an object
363  * @return          pointer to the transform matrix or NULL if not set
364  */
365 const lv_matrix_t * lv_obj_get_transform(const lv_obj_t * obj);
366 
367 /**
368  * Transform a point using the angle and zoom style properties of an object
369  * @param obj           pointer to an object whose style properties should be used
370  * @param p             a point to transform, the result will be written back here too
371  * @param flags         OR-ed valued of :cpp:enum:`lv_obj_point_transform_flag_t`
372  */
373 void lv_obj_transform_point(const lv_obj_t * obj, lv_point_t * p, lv_obj_point_transform_flag_t flags);
374 
375 /**
376  * Transform an array of points using the angle and zoom style properties of an object
377  * @param obj           pointer to an object whose style properties should be used
378  * @param points        the array of points to transform, the result will be written back here too
379  * @param count         number of points in the array
380  * @param flags         OR-ed valued of :cpp:enum:`lv_obj_point_transform_flag_t`
381  */
382 void lv_obj_transform_point_array(const lv_obj_t * obj, lv_point_t points[], size_t count,
383                                   lv_obj_point_transform_flag_t flags);
384 
385 /**
386  * Transform an area using the angle and zoom style properties of an object
387  * @param obj           pointer to an object whose style properties should be used
388  * @param area          an area to transform, the result will be written back here too
389  * @param flags         OR-ed valued of :cpp:enum:`lv_obj_point_transform_flag_t`
390  */
391 void lv_obj_get_transformed_area(const lv_obj_t * obj, lv_area_t * area, lv_obj_point_transform_flag_t flags);
392 
393 /**
394  * Mark an area of an object as invalid.
395  * The area will be truncated to the object's area and marked for redraw.
396  * @param obj       pointer to an object
397  * @param           area the area to redraw
398  */
399 void lv_obj_invalidate_area(const lv_obj_t * obj, const lv_area_t * area);
400 
401 /**
402  * Mark the object as invalid to redrawn its area
403  * @param obj       pointer to an object
404  */
405 void lv_obj_invalidate(const lv_obj_t * obj);
406 
407 /**
408  * Tell whether an area of an object is visible (even partially) now or not
409  * @param obj       pointer to an object
410  * @param area      the are to check. The visible part of the area will be written back here.
411  * @return true     visible; false not visible (hidden, out of parent, on other screen, etc)
412  */
413 bool lv_obj_area_is_visible(const lv_obj_t * obj, lv_area_t * area);
414 
415 /**
416  * Tell whether an object is visible (even partially) now or not
417  * @param obj       pointer to an object
418  * @return      true: visible; false not visible (hidden, out of parent, on other screen, etc)
419  */
420 bool lv_obj_is_visible(const lv_obj_t * obj);
421 
422 /**
423  * Set the size of an extended clickable area
424  * @param obj       pointer to an object
425  * @param size      extended clickable area in all 4 directions [px]
426  */
427 void lv_obj_set_ext_click_area(lv_obj_t * obj, int32_t size);
428 
429 /**
430  * Get the an area where to object can be clicked.
431  * It's the object's normal area plus the extended click area.
432  * @param obj       pointer to an object
433  * @param area      store the result area here
434  */
435 void lv_obj_get_click_area(const lv_obj_t * obj, lv_area_t * area);
436 
437 /**
438  * Hit-test an object given a particular point in screen space.
439  * @param obj       object to hit-test
440  * @param point     screen-space point (absolute coordinate)
441  * @return          true: if the object is considered under the point
442  */
443 bool lv_obj_hit_test(lv_obj_t * obj, const lv_point_t * point);
444 
445 /**
446  * Clamp a width between min and max width. If the min/max width is in percentage value use the ref_width
447  * @param width         width to clamp
448  * @param min_width     the minimal width
449  * @param max_width     the maximal width
450  * @param ref_width     the reference width used when min/max width is in percentage
451  * @return              the clamped width
452  */
453 int32_t lv_clamp_width(int32_t width, int32_t min_width, int32_t max_width, int32_t ref_width);
454 
455 /**
456  * Clamp a height between min and max height. If the min/max height is in percentage value use the ref_height
457  * @param height         height to clamp
458  * @param min_height     the minimal height
459  * @param max_height     the maximal height
460  * @param ref_height     the reference height used when min/max height is in percentage
461  * @return              the clamped height
462  */
463 int32_t lv_clamp_height(int32_t height, int32_t min_height, int32_t max_height, int32_t ref_height);
464 
465 /**********************
466  *      MACROS
467  **********************/
468 
469 #ifdef __cplusplus
470 } /*extern "C"*/
471 #endif
472 
473 #endif /*LV_OBJ_POS_H*/
474