1 /**
2 * @file lv_page.h
3 *
4 */
5
6 #ifndef LV_PAGE_H
7 #define LV_PAGE_H
8
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12
13 /*********************
14 * INCLUDES
15 *********************/
16 #include "../lv_conf_internal.h"
17
18 #if LV_USE_PAGE != 0
19
20 /*Testing of dependencies*/
21 #if LV_USE_CONT == 0
22 #error "lv_page: lv_cont is required. Enable it in lv_conf.h (LV_USE_CONT 1) "
23 #endif
24
25 #include "lv_cont.h"
26 #include "../lv_core/lv_indev.h"
27 #include "../lv_misc/lv_anim.h"
28
29 /*********************
30 * DEFINES
31 *********************/
32
33 /**********************
34 * TYPEDEFS
35 **********************/
36
37 /** Scrollbar modes: shows when should the scrollbars be visible*/
38 enum {
39 LV_SCROLLBAR_MODE_OFF = 0x0, /**< Never show scroll bars*/
40 LV_SCROLLBAR_MODE_ON = 0x1, /**< Always show scroll bars*/
41 LV_SCROLLBAR_MODE_DRAG = 0x2, /**< Show scroll bars when page is being dragged*/
42 LV_SCROLLBAR_MODE_AUTO = 0x3, /**< Show scroll bars when the scrollable container is large enough to be scrolled*/
43 LV_SCROLLBAR_MODE_HIDE = 0x4, /**< Hide the scroll bar temporally*/
44 LV_SCROLLBAR_MODE_UNHIDE = 0x8, /**< Unhide the previously hidden scroll bar. Recover original mode too*/
45 };
46 typedef uint8_t lv_scrollbar_mode_t;
47
48 /** Edges: describes the four edges of the page*/
49 enum { LV_PAGE_EDGE_LEFT = 0x1, LV_PAGE_EDGE_TOP = 0x2, LV_PAGE_EDGE_RIGHT = 0x4, LV_PAGE_EDGE_BOTTOM = 0x8 };
50 typedef uint8_t lv_page_edge_t;
51
52 /*Data of page*/
53 typedef struct {
54 lv_cont_ext_t bg; /*Ext. of ancestor*/
55 /*New data for this type */
56 lv_obj_t * scrl; /*The scrollable object on the background*/
57 struct {
58 lv_style_list_t style; /*Style of scrollbars*/
59 lv_area_t hor_area; /*Horizontal scrollbar area relative to the page. (Handled by the library) */
60 lv_area_t ver_area; /*Vertical scrollbar area relative to the page (Handled by the library)*/
61 uint8_t hor_draw : 1; /*1: horizontal scrollbar is visible now (Handled by the library)*/
62 uint8_t ver_draw : 1; /*1: vertical scrollbar is visible now (Handled by the library)*/
63 lv_scrollbar_mode_t mode : 3; /*Scrollbar visibility from 'lv_scrollbar_mode_t'*/
64 } scrlbar;
65 #if LV_USE_ANIMATION
66 struct {
67 lv_anim_value_t state; /*Store the current size of the edge flash effect*/
68 lv_style_list_t style; /*Style of edge flash effect (usually homogeneous circle)*/
69 uint8_t enabled : 1; /*1: Show a flash animation on the edge*/
70 uint8_t top_ip : 1; /*Used internally to show that top most position is reached (flash is In
71 Progress)*/
72 uint8_t bottom_ip : 1; /*Used internally to show that bottom most position is reached (flash
73 is In Progress)*/
74 uint8_t right_ip : 1; /*Used internally to show that right most position is reached (flash
75 is In Progress)*/
76 uint8_t left_ip : 1; /*Used internally to show that left most position is reached (flash is
77 In Progress)*/
78 } edge_flash;
79
80 uint16_t anim_time; /*Scroll animation time*/
81 #endif
82 lv_obj_t * scroll_prop_obj; /*Pointer to child page from where the scroll is being propagated */
83 uint8_t scroll_prop : 1; /*The direction of the scroll propagation*/
84 } lv_page_ext_t;
85
86 enum {
87 LV_PAGE_PART_BG = LV_CONT_PART_MAIN,
88 LV_PAGE_PART_SCROLLBAR = _LV_OBJ_PART_VIRTUAL_LAST,
89 LV_PAGE_PART_EDGE_FLASH,
90 _LV_PAGE_PART_VIRTUAL_LAST,
91
92 LV_PAGE_PART_SCROLLABLE = _LV_OBJ_PART_REAL_LAST,
93 _LV_PAGE_PART_REAL_LAST,
94 };
95 typedef uint8_t lv_part_style_t;
96
97 /**********************
98 * GLOBAL PROTOTYPES
99 **********************/
100
101 /**
102 * Create a page objects
103 * @param par pointer to an object, it will be the parent of the new page
104 * @param copy pointer to a page object, if not NULL then the new object will be copied from it
105 * @return pointer to the created page
106 */
107 lv_obj_t * lv_page_create(lv_obj_t * par, const lv_obj_t * copy);
108
109 /**
110 * Delete all children of the scrl object, without deleting scrl child.
111 * @param page pointer to an object
112 */
113 void lv_page_clean(lv_obj_t * page);
114
115 /**
116 * Get the scrollable object of a page
117 * @param page pointer to a page object
118 * @return pointer to a container which is the scrollable part of the page
119 */
120 lv_obj_t * lv_page_get_scrollable(const lv_obj_t * page);
121
122 /**
123 * Get the animation time
124 * @param page pointer to a page object
125 * @return the animation time in milliseconds
126 */
127 uint16_t lv_page_get_anim_time(const lv_obj_t * page);
128
129 /*=====================
130 * Setter functions
131 *====================*/
132
133 /**
134 * Set the scroll bar mode on a page
135 * @param page pointer to a page object
136 * @param sb_mode the new mode from 'lv_page_sb.mode_t' enum
137 */
138 void lv_page_set_scrollbar_mode(lv_obj_t * page, lv_scrollbar_mode_t sb_mode);
139
140 /**
141 * Set the animation time for the page
142 * @param page pointer to a page object
143 * @param anim_time animation time in milliseconds
144 */
145 void lv_page_set_anim_time(lv_obj_t * page, uint16_t anim_time);
146
147 /**
148 * Enable the scroll propagation feature. If enabled then the page will move its parent if there is
149 * no more space to scroll.
150 * The page needs to have a page-like parent (e.g. `lv_page`, `lv_tabview` tab, `lv_win` content area etc)
151 * If enabled drag direction will be changed `LV_DRAG_DIR_ONE` automatically to allow scrolling only in one direction at one time.
152 * @param page pointer to a Page
153 * @param en true or false to enable/disable scroll propagation
154 */
155 void lv_page_set_scroll_propagation(lv_obj_t * page, bool en);
156
157 /**
158 * Enable the edge flash effect. (Show an arc when the an edge is reached)
159 * @param page pointer to a Page
160 * @param en true or false to enable/disable end flash
161 */
162 void lv_page_set_edge_flash(lv_obj_t * page, bool en);
163
164 /**
165 * Set the fit policy in all 4 directions separately.
166 * It tell how to change the page size automatically.
167 * @param page pointer to a page object
168 * @param left left fit policy from `lv_fit_t`
169 * @param right right fit policy from `lv_fit_t`
170 * @param top bottom fit policy from `lv_fit_t`
171 * @param bottom bottom fit policy from `lv_fit_t`
172 */
lv_page_set_scrollable_fit4(lv_obj_t * page,lv_fit_t left,lv_fit_t right,lv_fit_t top,lv_fit_t bottom)173 static inline void lv_page_set_scrollable_fit4(lv_obj_t * page, lv_fit_t left, lv_fit_t right, lv_fit_t top,
174 lv_fit_t bottom)
175 {
176 lv_cont_set_fit4(lv_page_get_scrollable(page), left, right, top, bottom);
177 }
178
179 /**
180 * Set the fit policy horizontally and vertically separately.
181 * It tell how to change the page size automatically.
182 * @param page pointer to a page object
183 * @param hot horizontal fit policy from `lv_fit_t`
184 * @param ver vertical fit policy from `lv_fit_t`
185 */
lv_page_set_scrollable_fit2(lv_obj_t * page,lv_fit_t hor,lv_fit_t ver)186 static inline void lv_page_set_scrollable_fit2(lv_obj_t * page, lv_fit_t hor, lv_fit_t ver)
187 {
188 lv_cont_set_fit2(lv_page_get_scrollable(page), hor, ver);
189 }
190
191 /**
192 * Set the fit policy in all 4 direction at once.
193 * It tell how to change the page size automatically.
194 * @param page pointer to a button object
195 * @param fit fit policy from `lv_fit_t`
196 */
lv_page_set_scrollable_fit(lv_obj_t * page,lv_fit_t fit)197 static inline void lv_page_set_scrollable_fit(lv_obj_t * page, lv_fit_t fit)
198 {
199 lv_cont_set_fit(lv_page_get_scrollable(page), fit);
200 }
201
202 /**
203 * Set width of the scrollable part of a page
204 * @param page pointer to a page object
205 * @param w the new width of the scrollable (it ha no effect is horizontal fit is enabled)
206 */
lv_page_set_scrl_width(lv_obj_t * page,lv_coord_t w)207 static inline void lv_page_set_scrl_width(lv_obj_t * page, lv_coord_t w)
208 {
209 lv_obj_set_width(lv_page_get_scrollable(page), w);
210 }
211
212 /**
213 * Set height of the scrollable part of a page
214 * @param page pointer to a page object
215 * @param h the new height of the scrollable (it ha no effect is vertical fit is enabled)
216 */
lv_page_set_scrl_height(lv_obj_t * page,lv_coord_t h)217 static inline void lv_page_set_scrl_height(lv_obj_t * page, lv_coord_t h)
218 {
219 lv_obj_set_height(lv_page_get_scrollable(page), h);
220 }
221
222 /**
223 * Set the layout of the scrollable part of the page
224 * @param page pointer to a page object
225 * @param layout a layout from 'lv_cont_layout_t'
226 */
lv_page_set_scrl_layout(lv_obj_t * page,lv_layout_t layout)227 static inline void lv_page_set_scrl_layout(lv_obj_t * page, lv_layout_t layout)
228 {
229 lv_cont_set_layout(lv_page_get_scrollable(page), layout);
230 }
231
232 /*=====================
233 * Getter functions
234 *====================*/
235
236 /**
237 * Set the scroll bar mode on a page
238 * @param page pointer to a page object
239 * @return the mode from 'lv_page_sb.mode_t' enum
240 */
241 lv_scrollbar_mode_t lv_page_get_scrollbar_mode(const lv_obj_t * page);
242
243 /**
244 * Get the scroll propagation property
245 * @param page pointer to a Page
246 * @return true or false
247 */
248 bool lv_page_get_scroll_propagation(lv_obj_t * page);
249
250 /**
251 * Get the edge flash effect property.
252 * @param page pointer to a Page
253 * return true or false
254 */
255 bool lv_page_get_edge_flash(lv_obj_t * page);
256
257 /**
258 * Get that width which can be set to the children to still not cause overflow (show scrollbars)
259 * @param page pointer to a page object
260 * @return the width which still fits into the page
261 */
262 lv_coord_t lv_page_get_width_fit(lv_obj_t * page);
263
264 /**
265 * Get that height which can be set to the children to still not cause overflow (show scrollbars)
266 * @param page pointer to a page object
267 * @return the height which still fits into the page
268 */
269 lv_coord_t lv_page_get_height_fit(lv_obj_t * page);
270
271 /**
272 * Divide the width of the object and get the width of a given number of columns.
273 * Take into account the paddings of the background and scrollable too.
274 * @param page pointer to an object
275 * @param div indicates how many columns are assumed.
276 * If 1 the width will be set the the parent's width
277 * If 2 only half parent width - inner padding of the parent
278 * If 3 only third parent width - 2 * inner padding of the parent
279 * @param span how many columns are combined
280 * @return the width according to the given parameters
281 */
282 lv_coord_t lv_page_get_width_grid(lv_obj_t * page, uint8_t div, uint8_t span);
283
284 /**
285 * Divide the height of the object and get the width of a given number of columns.
286 * Take into account the paddings of the background and scrollable too.
287 * @param page pointer to an object
288 * @param div indicates how many rows are assumed.
289 * If 1 the height will be set the the parent's height
290 * If 2 only half parent height - inner padding of the parent
291 * If 3 only third parent height - 2 * inner padding of the parent
292 * @param span how many rows are combined
293 * @return the height according to the given parameters
294 */
295 lv_coord_t lv_page_get_height_grid(lv_obj_t * page, uint8_t div, uint8_t span);
296
297 /**
298 * Get width of the scrollable part of a page
299 * @param page pointer to a page object
300 * @return the width of the scrollable
301 */
lv_page_get_scrl_width(const lv_obj_t * page)302 static inline lv_coord_t lv_page_get_scrl_width(const lv_obj_t * page)
303 {
304 return lv_obj_get_width(lv_page_get_scrollable(page));
305 }
306
307 /**
308 * Get height of the scrollable part of a page
309 * @param page pointer to a page object
310 * @return the height of the scrollable
311 */
lv_page_get_scrl_height(const lv_obj_t * page)312 static inline lv_coord_t lv_page_get_scrl_height(const lv_obj_t * page)
313 {
314 return lv_obj_get_height(lv_page_get_scrollable(page));
315 }
316
317 /**
318 * Get the layout of the scrollable part of a page
319 * @param page pointer to page object
320 * @return the layout from 'lv_cont_layout_t'
321 */
lv_page_get_scrl_layout(const lv_obj_t * page)322 static inline lv_layout_t lv_page_get_scrl_layout(const lv_obj_t * page)
323 {
324 return lv_cont_get_layout(lv_page_get_scrollable(page));
325 }
326
327 /**
328 * Get the left fit mode
329 * @param page pointer to a page object
330 * @return an element of `lv_fit_t`
331 */
lv_page_get_scrl_fit_left(const lv_obj_t * page)332 static inline lv_fit_t lv_page_get_scrl_fit_left(const lv_obj_t * page)
333 {
334 return lv_cont_get_fit_left(lv_page_get_scrollable(page));
335 }
336
337 /**
338 * Get the right fit mode
339 * @param page pointer to a page object
340 * @return an element of `lv_fit_t`
341 */
lv_page_get_scrl_fit_right(const lv_obj_t * page)342 static inline lv_fit_t lv_page_get_scrl_fit_right(const lv_obj_t * page)
343 {
344 return lv_cont_get_fit_right(lv_page_get_scrollable(page));
345 }
346
347 /**
348 * Get the top fit mode
349 * @param page pointer to a page object
350 * @return an element of `lv_fit_t`
351 */
lv_page_get_scrl_fit_top(const lv_obj_t * page)352 static inline lv_fit_t lv_page_get_scrl_fit_top(const lv_obj_t * page)
353 {
354 return lv_cont_get_fit_top(lv_page_get_scrollable(page));
355 }
356
357 /**
358 * Get the bottom fit mode
359 * @param page pointer to a page object
360 * @return an element of `lv_fit_t`
361 */
lv_page_get_scrl_fit_bottom(const lv_obj_t * page)362 static inline lv_fit_t lv_page_get_scrl_fit_bottom(const lv_obj_t * page)
363 {
364 return lv_cont_get_fit_bottom(lv_page_get_scrollable(page));
365 }
366
367 /*=====================
368 * Other functions
369 *====================*/
370
371 /**
372 * Find whether the page has been scrolled to a certain edge.
373 * @param page Page object
374 * @param edge Edge to check
375 * @return true if the page is on the specified edge
376 */
377 bool lv_page_on_edge(lv_obj_t * page, lv_page_edge_t edge);
378
379 /**
380 * Glue the object to the page. After it the page can be moved (dragged) with this object too.
381 * @param obj pointer to an object on a page
382 * @param glue true: enable glue, false: disable glue
383 */
384 void lv_page_glue_obj(lv_obj_t * obj, bool glue);
385
386 /**
387 * Focus on an object. It ensures that the object will be visible on the page.
388 * @param page pointer to a page object
389 * @param obj pointer to an object to focus (must be on the page)
390 * @param anim_en LV_ANIM_ON to focus with animation; LV_ANIM_OFF to focus without animation
391 */
392 void lv_page_focus(lv_obj_t * page, const lv_obj_t * obj, lv_anim_enable_t anim_en);
393
394 /**
395 * Scroll the page horizontally
396 * @param page pointer to a page object
397 * @param dist the distance to scroll (< 0: scroll left; > 0 scroll right)
398 */
399 void lv_page_scroll_hor(lv_obj_t * page, lv_coord_t dist);
400
401 /**
402 * Scroll the page vertically
403 * @param page pointer to a page object
404 * @param dist the distance to scroll (< 0: scroll down; > 0 scroll up)
405 */
406 void lv_page_scroll_ver(lv_obj_t * page, lv_coord_t dist);
407
408 /**
409 * Not intended to use directly by the user but by other object types internally.
410 * Start an edge flash animation.
411 * @param page
412 * @param edge the edge to flash. Can be `LV_PAGE_EDGE_LEFT/RIGHT/TOP/BOTTOM`
413 */
414 void lv_page_start_edge_flash(lv_obj_t * page, lv_page_edge_t edge);
415
416 /**********************
417 * MACROS
418 **********************/
419
420 #endif /*LV_USE_PAGE*/
421
422 #ifdef __cplusplus
423 } /* extern "C" */
424 #endif
425
426 #endif /*LV_PAGE_H*/
427