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 /** 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 * Low level function to scroll by given x and y coordinates. 253 * `LV_EVENT_SCROLL` is sent. 254 * @param obj pointer to an object to scroll 255 * @param x pixels to scroll horizontally 256 * @param y pixels to scroll vertically 257 * @return `LV_RES_INV`: to object was deleted in `LV_EVENT_SCROLL`; 258 * `LV_RES_OK`: if the object is still valid 259 */ 260 lv_res_t _lv_obj_scroll_by_raw(struct _lv_obj_t * obj, lv_coord_t x, lv_coord_t y); 261 262 /** 263 * Tell whether an object is being scrolled or not at this moment 264 * @param obj pointer to an object 265 * @return true: `obj` is being scrolled 266 */ 267 bool lv_obj_is_scrolling(const struct _lv_obj_t * obj); 268 269 /** 270 * Check the children of `obj` and scroll `obj` to fulfill the scroll_snap settings 271 * @param obj an object whose children needs to checked and snapped 272 * @param anim_en LV_ANIM_ON/OFF 273 */ 274 void lv_obj_update_snap(struct _lv_obj_t * obj, lv_anim_enable_t anim_en); 275 276 /** 277 * Get the area of the scrollbars 278 * @param obj pointer to an object 279 * @param hor pointer to store the area of the horizontal scrollbar 280 * @param ver pointer to store the area of the vertical scrollbar 281 */ 282 void lv_obj_get_scrollbar_area(struct _lv_obj_t * obj, lv_area_t * hor, lv_area_t * ver); 283 284 /** 285 * Invalidate the area of the scrollbars 286 * @param obj pointer to an object 287 */ 288 void lv_obj_scrollbar_invalidate(struct _lv_obj_t * obj); 289 290 /** 291 * Checks if the content is scrolled "in" and adjusts it to a normal position. 292 * @param obj pointer to an object 293 * @param anim_en LV_ANIM_ON/OFF 294 */ 295 void lv_obj_readjust_scroll(struct _lv_obj_t * obj, lv_anim_enable_t anim_en); 296 297 /********************** 298 * MACROS 299 **********************/ 300 301 #ifdef __cplusplus 302 } /*extern "C"*/ 303 #endif 304 305 #endif /*LV_OBJ_SCROLL_H*/ 306
