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