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