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 30 /** Scrollbar modes: shows when should the scrollbars be visible*/ 31 typedef 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 Widget is being scrolled*/ 35 LV_SCROLLBAR_MODE_AUTO, /**< Show scroll bars when the content is large enough to be scrolled*/ 36 } lv_scrollbar_mode_t; 37 38 /** Scroll span align options. Tells where to align the snappable children when scroll stops.*/ 39 typedef enum { 40 LV_SCROLL_SNAP_NONE, /**< Do not align, leave where it is*/ 41 LV_SCROLL_SNAP_START, /**< Align to the left/top*/ 42 LV_SCROLL_SNAP_END, /**< Align to the right/bottom*/ 43 LV_SCROLL_SNAP_CENTER /**< Align to the center*/ 44 } lv_scroll_snap_t; 45 46 /********************** 47 * GLOBAL PROTOTYPES 48 **********************/ 49 50 /*===================== 51 * Setter functions 52 *====================*/ 53 54 /** 55 * Set how the scrollbars should behave. 56 * @param obj pointer to Widget 57 * @param mode LV_SCROLL_MODE_ON/OFF/AUTO/ACTIVE 58 */ 59 void lv_obj_set_scrollbar_mode(lv_obj_t * obj, lv_scrollbar_mode_t mode); 60 61 /** 62 * Set direction Widget can be scrolled 63 * @param obj pointer to Widget 64 * @param dir one or more bit-wise OR-ed values of `lv_dir_t` enumeration 65 */ 66 void lv_obj_set_scroll_dir(lv_obj_t * obj, lv_dir_t dir); 67 68 /** 69 * Set where to snap the children when scrolling ends horizontally 70 * @param obj pointer to Widget 71 * @param align value from `lv_scroll_snap_t` enumeration 72 */ 73 void lv_obj_set_scroll_snap_x(lv_obj_t * obj, lv_scroll_snap_t align); 74 75 /** 76 * Set where to snap the children when scrolling ends vertically 77 * @param obj pointer to Widget 78 * @param align value from `lv_scroll_snap_t` enumeration 79 */ 80 void lv_obj_set_scroll_snap_y(lv_obj_t * obj, lv_scroll_snap_t align); 81 82 /*===================== 83 * Getter functions 84 *====================*/ 85 86 /** 87 * Get the current scroll mode (when to hide the scrollbars) 88 * @param obj pointer to Widget 89 * @return the current scroll mode from `lv_scrollbar_mode_t` 90 */ 91 lv_scrollbar_mode_t lv_obj_get_scrollbar_mode(const lv_obj_t * obj); 92 93 /** 94 * Get directions Widget can be scrolled (set with `lv_obj_set_scroll_dir()`) 95 * @param obj pointer to Widget 96 * @return current scroll direction bit(s) 97 */ 98 lv_dir_t lv_obj_get_scroll_dir(const lv_obj_t * obj); 99 100 /** 101 * Get where to snap child Widgets when horizontal scrolling ends. 102 * @param obj pointer to Widget 103 * @return current snap value from `lv_scroll_snap_t` 104 */ 105 lv_scroll_snap_t lv_obj_get_scroll_snap_x(const lv_obj_t * obj); 106 107 /** 108 * Get where to snap child Widgets when vertical scrolling ends. 109 * @param obj pointer to Widget 110 * @return current snap value from `lv_scroll_snap_t` 111 */ 112 lv_scroll_snap_t lv_obj_get_scroll_snap_y(const lv_obj_t * obj); 113 114 /** 115 * Get current X scroll position. Identical to `lv_obj_get_scroll_left()`. 116 * @param obj pointer to scrollable container Widget 117 * @return current scroll position from left edge 118 * - If Widget is not scrolled return 0. 119 * - If scrolled return > 0. 120 * - If scrolled inside (elastic scroll) return < 0. 121 */ 122 int32_t lv_obj_get_scroll_x(const lv_obj_t * obj); 123 124 /** 125 * Get current Y scroll position. Identical to `lv_obj_get_scroll_top()`. 126 * @param obj pointer to scrollable container Widget 127 * @return current scroll position from top edge 128 * - If Widget is not scrolled return 0. 129 * - If scrolled return > 0. 130 * - If scrolled inside (elastic scroll) return < 0. 131 */ 132 int32_t lv_obj_get_scroll_y(const lv_obj_t * obj); 133 134 /** 135 * Number of pixels a scrollable container Widget can be scrolled down 136 * before its top edge appears. When LV_OBJ_FLAG_SCROLL_ELASTIC flag 137 * is set in Widget, this value can go negative while Widget is being 138 * dragged below its normal top-edge boundary. 139 * @param obj pointer to scrollable container Widget 140 * @return pixels Widget can be scrolled down before its top edge appears 141 */ 142 int32_t lv_obj_get_scroll_top(lv_obj_t * obj); 143 144 /** 145 * Number of pixels a scrollable container Widget can be scrolled up 146 * before its bottom edge appears. When LV_OBJ_FLAG_SCROLL_ELASTIC flag 147 * is set in Widget, this value can go negative while Widget is being 148 * dragged above its normal bottom-edge boundary. 149 * @param obj pointer to scrollable container Widget 150 * @return pixels Widget can be scrolled up before its bottom edge appears 151 */ 152 int32_t lv_obj_get_scroll_bottom(lv_obj_t * obj); 153 154 /** 155 * Number of pixels a scrollable container Widget can be scrolled right 156 * before its left edge appears. When LV_OBJ_FLAG_SCROLL_ELASTIC flag 157 * is set in Widget, this value can go negative while Widget is being 158 * dragged farther right than its normal left-edge boundary. 159 * @param obj pointer to scrollable container Widget 160 * @return pixels Widget can be scrolled right before its left edge appears 161 */ 162 int32_t lv_obj_get_scroll_left(lv_obj_t * obj); 163 164 /** 165 * Number of pixels a scrollable container Widget can be scrolled left 166 * before its right edge appears. When LV_OBJ_FLAG_SCROLL_ELASTIC flag 167 * is set in Widget, this value can go negative while Widget is being 168 * dragged farther left than its normal right-edge boundary. 169 * @param obj pointer to scrollable container Widget 170 * @return pixels Widget can be scrolled left before its right edge appears 171 */ 172 int32_t lv_obj_get_scroll_right(lv_obj_t * obj); 173 174 /** 175 * Get the X and Y coordinates where the scrolling will end for Widget 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 scrollable Widget 178 * @param end pointer to `lv_point_t` object in which to store result 179 */ 180 void lv_obj_get_scroll_end(lv_obj_t * obj, lv_point_t * end); 181 182 /*===================== 183 * Other functions 184 *====================*/ 185 186 /** 187 * Scroll by given amount of pixels. 188 * @param obj pointer to scrollable Widget 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(lv_obj_t * obj, int32_t dx, int32_t dy, lv_anim_enable_t anim_en); 196 197 /** 198 * Scroll by 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 scrollable Widget 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(lv_obj_t * obj, int32_t dx, int32_t dy, lv_anim_enable_t anim_en); 207 208 /** 209 * Scroll to given coordinate on Widget. 210 * `x` and `y` will be limited internally to allow scrolling only on the content area. 211 * @param obj pointer to scrollable Widget 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(lv_obj_t * obj, int32_t x, int32_t y, lv_anim_enable_t anim_en); 217 218 /** 219 * Scroll to X coordinate on Widget. 220 * `x` will be limited internally to allow scrolling only on the content area. 221 * @param obj pointer to scrollable Widget 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(lv_obj_t * obj, int32_t x, lv_anim_enable_t anim_en); 226 227 /** 228 * Scroll to Y coordinate on Widget. 229 * `y` will be limited internally to allow scrolling only on the content area. 230 * @param obj pointer to scrollable Widget 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(lv_obj_t * obj, int32_t y, lv_anim_enable_t anim_en); 235 236 /** 237 * Scroll `obj`'s parent Widget until `obj` becomes visible. 238 * @param obj pointer to Widget 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(lv_obj_t * obj, lv_anim_enable_t anim_en); 242 243 /** 244 * Scroll `obj`'s parent Widgets recursively until `obj` becomes visible. 245 * Widget will be scrolled into view even it has nested scrollable parents. 246 * @param obj pointer to Widget 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(lv_obj_t * obj, lv_anim_enable_t anim_en); 250 251 /** 252 * Tell whether Widget is being scrolled or not at this moment 253 * @param obj pointer to Widget 254 * @return true: `obj` is being scrolled 255 */ 256 bool lv_obj_is_scrolling(const lv_obj_t * obj); 257 258 /** 259 * Stop scrolling the current object 260 * 261 * @param obj The object being scrolled 262 */ 263 void lv_obj_stop_scroll_anim(const lv_obj_t * obj); 264 265 /** 266 * Check children of `obj` and scroll `obj` to fulfill scroll_snap settings. 267 * @param obj Widget whose children need to be checked and snapped 268 * @param anim_en LV_ANIM_ON/OFF 269 */ 270 void lv_obj_update_snap(lv_obj_t * obj, lv_anim_enable_t anim_en); 271 272 /** 273 * Get the area of the scrollbars 274 * @param obj pointer to Widget 275 * @param hor pointer to store the area of the horizontal scrollbar 276 * @param ver pointer to store the area of the vertical scrollbar 277 */ 278 void lv_obj_get_scrollbar_area(lv_obj_t * obj, lv_area_t * hor, lv_area_t * ver); 279 280 /** 281 * Invalidate the area of the scrollbars 282 * @param obj pointer to Widget 283 */ 284 void lv_obj_scrollbar_invalidate(lv_obj_t * obj); 285 286 /** 287 * Checks if the content is scrolled "in" and adjusts it to a normal position. 288 * @param obj pointer to Widget 289 * @param anim_en LV_ANIM_ON/OFF 290 */ 291 void lv_obj_readjust_scroll(lv_obj_t * obj, lv_anim_enable_t anim_en); 292 293 /********************** 294 * MACROS 295 **********************/ 296 297 #ifdef __cplusplus 298 } /*extern "C"*/ 299 #endif 300 301 #endif /*LV_OBJ_SCROLL_H*/ 302
