1 /**
2  * @file lv_obj_scroll.h
3  *
4  */
5 
6 #ifndef LV_OBJ_SCROLL_H
7 #define LV_OBJ_SCROLL_H
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 /*********************
14  *      INCLUDES
15  *********************/
16 #include "../misc/lv_area.h"
17 #include "../misc/lv_anim.h"
18 
19 /*********************
20  *      DEFINES
21  *********************/
22 
23 /**********************
24  *      TYPEDEFS
25  **********************/
26 
27 /*Can't include lv_obj.h because it includes this header file*/
28 struct _lv_obj_t;
29 
30 /** Scrollbar modes: shows when should the scrollbars be visible*/
31 enum {
32     LV_SCROLLBAR_MODE_OFF,      /**< Never show scrollbars*/
33     LV_SCROLLBAR_MODE_ON,       /**< Always show scrollbars*/
34     LV_SCROLLBAR_MODE_ACTIVE,   /**< Show scroll bars when object is being scrolled*/
35     LV_SCROLLBAR_MODE_AUTO,     /**< Show scroll bars when the content is large enough to be scrolled*/
36 };
37 typedef uint8_t lv_scrollbar_mode_t;
38 
39 
40 /** Scroll span align options. Tells where to align the snappable children when scroll stops.*/
41 enum {
42     LV_SCROLL_SNAP_NONE,    /**< Do not align, leave where it is*/
43     LV_SCROLL_SNAP_START,   /**< Align to the left/top*/
44     LV_SCROLL_SNAP_END,     /**< Align to the right/bottom*/
45     LV_SCROLL_SNAP_CENTER   /**< Align to the center*/
46 };
47 typedef uint8_t lv_scroll_snap_t;
48 
49 /**********************
50  * GLOBAL PROTOTYPES
51  **********************/
52 
53 /*=====================
54  * Setter functions
55  *====================*/
56 
57 /**
58  * Set how the scrollbars should behave.
59  * @param obj       pointer to an object
60  * @param mode      LV_SCROLL_MODE_ON/OFF/AUTO/ACTIVE
61  */
62 void lv_obj_set_scrollbar_mode(struct _lv_obj_t * obj, lv_scrollbar_mode_t mode);
63 
64 /**
65  * Set the object in which directions can be scrolled
66  * @param obj       pointer to an object
67  * @param dir       the allow scroll directions. An element or OR-ed values of `lv_dir_t`
68  */
69 void lv_obj_set_scroll_dir(struct _lv_obj_t * obj, lv_dir_t dir);
70 
71 /**
72  * Set where to snap the children when scrolling ends horizontally
73  * @param obj       pointer to an object
74  * @param align     the snap align to set from `lv_scroll_snap_t`
75  */
76 void lv_obj_set_scroll_snap_x(struct _lv_obj_t * obj, lv_scroll_snap_t align);
77 
78 /**
79  * Set where to snap the children when scrolling ends vertically
80  * @param obj       pointer to an object
81  * @param align     the snap align to set from `lv_scroll_snap_t`
82  */
83 void lv_obj_set_scroll_snap_y(struct _lv_obj_t * obj, lv_scroll_snap_t align);
84 
85 /*=====================
86  * Getter functions
87  *====================*/
88 
89 /**
90  * Get the current scroll mode (when to hide the scrollbars)
91  * @param obj       pointer to an object
92  * @return          the current scroll mode from `lv_scrollbar_mode_t`
93  */
94 lv_scrollbar_mode_t lv_obj_get_scrollbar_mode(const struct _lv_obj_t * obj);
95 
96 /**
97  * Get the object in which directions can be scrolled
98  * @param obj       pointer to an object
99  * @param dir       the allow scroll directions. An element or OR-ed values of `lv_dir_t`
100  */
101 lv_dir_t lv_obj_get_scroll_dir(const struct _lv_obj_t * obj);
102 
103 /**
104  * Get where to snap the children when scrolling ends horizontally
105  * @param obj       pointer to an object
106  * @return          the current snap align from `lv_scroll_snap_t`
107  */
108 lv_scroll_snap_t lv_obj_get_scroll_snap_x(const struct _lv_obj_t * obj);
109 
110 /**
111  * Get where to snap the children when scrolling ends vertically
112  * @param  obj      pointer to an object
113  * @return          the current snap align from `lv_scroll_snap_t`
114  */
115 lv_scroll_snap_t lv_obj_get_scroll_snap_y(const struct _lv_obj_t * obj);
116 
117 /**
118  * Get current X scroll position.
119  * @param obj       pointer to an object
120  * @return          the current scroll position from the left edge.
121  *                  If the object is not scrolled return 0
122  *                  If scrolled return > 0
123  *                  If scrolled in (elastic scroll) return < 0
124  */
125 lv_coord_t lv_obj_get_scroll_x(const struct _lv_obj_t * obj);
126 
127 /**
128  * Get current Y scroll position.
129  * @param obj       pointer to an object
130  * @return          the current scroll position from the top edge.
131  *                  If the object is not scrolled return 0
132  *                  If scrolled return > 0
133  *                  If scrolled inside return < 0
134  */
135 lv_coord_t lv_obj_get_scroll_y(const struct _lv_obj_t * obj);
136 
137 /**
138  * Return the height of the area above the object.
139  * That is the number of pixels the object can be scrolled down.
140  * Normally positive but can be negative when scrolled inside.
141  * @param obj       pointer to an object
142  * @return          the scrollable area above the object in pixels
143  */
144 lv_coord_t lv_obj_get_scroll_top(struct _lv_obj_t * obj);
145 
146 /**
147  * Return the height of the area below the object.
148  * That is the number of pixels the object can be scrolled down.
149  * Normally positive but can be negative when scrolled inside.
150  * @param obj       pointer to an object
151  * @return          the scrollable area below the object in pixels
152  */
153 lv_coord_t lv_obj_get_scroll_bottom(struct _lv_obj_t * obj);
154 
155 /**
156  * Return the width of the area on the left the object.
157  * That is the number of pixels the object can be scrolled down.
158  * Normally positive but can be negative when scrolled inside.
159  * @param obj       pointer to an object
160  * @return          the scrollable area on the left the object in pixels
161  */
162 lv_coord_t lv_obj_get_scroll_left(struct _lv_obj_t * obj);
163 
164 /**
165  * Return the width of the area on the right the object.
166  * That is the number of pixels the object can be scrolled down.
167  * Normally positive but can be negative when scrolled inside.
168  * @param obj       pointer to an object
169  * @return          the scrollable area on the right the object in pixels
170  */
171 lv_coord_t lv_obj_get_scroll_right(struct _lv_obj_t * obj);
172 
173 /**
174  * Get the X and Y coordinates where the scrolling will end for this object if a scrolling animation is in progress.
175  * If no scrolling animation, give the current `x` or `y` scroll position.
176  * @param obj       pointer to an object
177  * @param end       pointer to store the result
178  */
179 void lv_obj_get_scroll_end(struct _lv_obj_t  * obj, lv_point_t * end);
180 
181 /*=====================
182  * Other functions
183  *====================*/
184 
185 /**
186  * Scroll by a given amount of pixels
187  * @param obj       pointer to an object to scroll
188  * @param dx         pixels to scroll horizontally
189  * @param dy         pixels to scroll vertically
190  * @param anim_en   LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately
191  * @note            > 0 value means scroll right/bottom (show the more content on the right/bottom)
192  * @note            e.g. dy = -20 means scroll down 20 px
193  */
194 void lv_obj_scroll_by(struct _lv_obj_t * obj, lv_coord_t x, lv_coord_t y, lv_anim_enable_t anim_en);
195 
196 /**
197  * Scroll by a given amount of pixels.
198  * `dx` and `dy` will be limited internally to allow scrolling only on the content area.
199  * @param obj       pointer to an object to scroll
200  * @param dx        pixels to scroll horizontally
201  * @param dy        pixels to scroll vertically
202  * @param anim_en   LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately
203  * @note            e.g. dy = -20 means scroll down 20 px
204  */
205 void lv_obj_scroll_by_bounded(struct _lv_obj_t * obj, lv_coord_t dx, lv_coord_t dy, lv_anim_enable_t anim_en);
206 
207 /**
208  * Scroll to a given coordinate on an object.
209  * `x` and `y` will be limited internally to allow scrolling only on the content area.
210  * @param obj       pointer to an object to scroll
211  * @param x         pixels to scroll horizontally
212  * @param y         pixels to scroll vertically
213  * @param anim_en   LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately
214  */
215 void lv_obj_scroll_to(struct _lv_obj_t * obj, lv_coord_t x, lv_coord_t y, lv_anim_enable_t anim_en);
216 
217 /**
218  * Scroll to a given X coordinate on an object.
219  * `x` will be limited internally to allow scrolling only on the content area.
220  * @param obj       pointer to an object to scroll
221  * @param x         pixels to scroll horizontally
222  * @param anim_en   LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately
223  */
224 void lv_obj_scroll_to_x(struct _lv_obj_t * obj, lv_coord_t x, lv_anim_enable_t anim_en);
225 
226 /**
227  * Scroll to a given Y coordinate on an object
228  * `y` will be limited internally to allow scrolling only on the content area.
229  * @param obj       pointer to an object to scroll
230  * @param y         pixels to scroll vertically
231  * @param anim_en   LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately
232  */
233 void lv_obj_scroll_to_y(struct _lv_obj_t * obj, lv_coord_t y, lv_anim_enable_t anim_en);
234 
235 /**
236  * Scroll to an object until it becomes visible on its parent
237  * @param obj       pointer to an object to scroll into view
238  * @param anim_en   LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately
239  */
240 void lv_obj_scroll_to_view(struct _lv_obj_t * obj, lv_anim_enable_t anim_en);
241 
242 /**
243  * Scroll to an object until it becomes visible on its parent.
244  * Do the same on the parent's parent, and so on.
245  * Therefore the object will be scrolled into view even it has nested scrollable parents
246  * @param obj       pointer to an object to scroll into view
247  * @param anim_en   LV_ANIM_ON: scroll with animation; LV_ANIM_OFF: scroll immediately
248  */
249 void lv_obj_scroll_to_view_recursive(struct _lv_obj_t * obj, lv_anim_enable_t anim_en);
250 
251 /**
252  * Tell whether an object is being scrolled or not at this moment
253  * @param obj   pointer to an object
254  * @return      true: `obj` is being scrolled
255  */
256 bool lv_obj_is_scrolling(const struct _lv_obj_t * obj);
257 
258 /**
259  * Check the children of `obj` and scroll `obj` to fulfill the scroll_snap settings
260  * @param obj       an object whose children needs to checked and snapped
261  * @param anim_en   LV_ANIM_ON/OFF
262  */
263 void lv_obj_update_snap(struct _lv_obj_t * obj, lv_anim_enable_t anim_en);
264 
265 /**
266  * Get the area of the scrollbars
267  * @param obj   pointer to an object
268  * @param hor   pointer to store the area of the horizontal scrollbar
269  * @param ver   pointer to store the area of the vertical  scrollbar
270  */
271 void lv_obj_get_scrollbar_area(struct _lv_obj_t * obj, lv_area_t * hor, lv_area_t * ver);
272 
273 /**
274  * Invalidate the area of the scrollbars
275  * @param obj       pointer to an object
276  */
277 void lv_obj_scrollbar_invalidate(struct _lv_obj_t * obj);
278 
279 /**
280  * Checked if the content is scrolled "in" and adjusts it to a normal position.
281  * @param obj       pointer to an object
282  * @param anim_en   LV_ANIM_ON/OFF
283  */
284 void lv_obj_readjust_scroll(struct _lv_obj_t * obj, lv_anim_enable_t anim_en);
285 
286 /**********************
287  *      MACROS
288  **********************/
289 
290 #ifdef __cplusplus
291 } /*extern "C"*/
292 #endif
293 
294 #endif /*LV_OBJ_SCROLL_H*/
295