1
/*
2
 * Copyright (c) 2019 CTCaer
3
 *
4
 * This program is free software; you can redistribute it and/or modify it
5
 * under the terms and conditions of the GNU General Public License,
6
 * version 2, as published by the Free Software Foundation.
7
 *
8
 * This program is distributed in the hope it will be useful, but WITHOUT
9
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
11
 * more details.
12
 *
13
 * You should have received a copy of the GNU General Public License
14
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
15
 */
16

17
/**
18
 * @file lv_page.h
19
 *
20
 */
21

22
#ifndef LV_PAGE_H
23
#define LV_PAGE_H
24

25
#ifdef __cplusplus
26
extern "C" {
27
#endif
28

29
/*********************
30
 *      INCLUDES
31
 *********************/
32
#ifdef LV_CONF_INCLUDE_SIMPLE
33
#include "lv_conf.h"
34
#else
35
#include "../../lv_conf.h"
36
#endif
37

38
#if USE_LV_PAGE != 0
39

40
/*Testing of dependencies*/
41
#if USE_LV_CONT == 0
42
#error "lv_page: lv_cont is required. Enable it in lv_conf.h (USE_LV_CONT  1) "
43
#endif
44

45
#include "lv_cont.h"
46
#include "../lv_core/lv_indev.h"
47

48
/*********************
49
 *      DEFINES
50
 *********************/
51

52
/**********************
53
 *      TYPEDEFS
54
 **********************/
55

56
/*Scrollbar modes: shows when should the scrollbars be visible*/
57
enum
58
{
59
    LV_SB_MODE_OFF  = 0x0,      /*Never show scrollbars*/
60
    LV_SB_MODE_ON   = 0x1,      /*Always show scrollbars*/
61
    LV_SB_MODE_DRAG = 0x2,      /*Show scrollbars when page is being dragged*/
62
    LV_SB_MODE_AUTO = 0x3,      /*Show scrollbars when the scrollable container is large enough to be scrolled*/
63
    LV_SB_MODE_HIDE = 0x4,      /*Hide the scroll bar temporally*/
64
    LV_SB_MODE_UNHIDE = 0x5,    /*Unhide the previously hidden scrollbar. Recover it's type too*/
65
};
66
typedef uint8_t lv_sb_mode_t;
67

68
/*Data of page*/
69
typedef struct
70
{
71
    lv_cont_ext_t bg; /*Ext. of ancestor*/
72
    /*New data for this type */
73
    lv_obj_t * scrl;            /*The scrollable object on the background*/
74
	lv_style_t *bgo;            /*The scrollable object on the background*/
75
	lv_style_t *pr;            /*The scrollable object on the background*/
76
    lv_action_t rel_action;     /*Function to call when the page is released*/
77
    lv_action_t pr_action;      /*Function to call when the page is pressed*/
78
    struct {
79
        lv_style_t *style;          /*Style of scrollbars*/
80
        lv_area_t hor_area;            /*Horizontal scrollbar area relative to the page. (Handled by the library) */
81
        lv_area_t ver_area;            /*Vertical scrollbar area relative to the page (Handled by the library)*/
82
        uint8_t hor_draw :1;        /*1: horizontal scrollbar is visible now (Handled by the library)*/
83
        uint8_t ver_draw :1;        /*1: vertical scrollbar is visible now (Handled by the library)*/
84
        lv_sb_mode_t mode:3;        /*Scrollbar visibility from 'lv_page_sb_mode_t'*/
85
    } sb;
86
    struct {
87
        uint16_t state;  /*Store the current size of the edge flash effect*/
88
        lv_style_t *style;    /*Style of edge flash effect (usually homogeneous circle)*/
89
        uint8_t enabled    :1;     /*1: Show a flash animation on the edge*/
90
        uint8_t top_ip     :1;     /*Used internally to show that top most position is reached (flash is In Progress)*/
91
        uint8_t bottom_ip  :1;     /*Used internally to show that bottom most position is reached (flash is In Progress)*/
92
        uint8_t right_ip   :1;     /*Used internally to show that right most position is reached (flash is In Progress)*/
93
        uint8_t left_ip    :1;     /*Used internally to show that left most position is reached (flash is In Progress)*/
94
    }edge_flash;
95

96
    uint8_t arrow_scroll   :1;        /*1: Enable scrolling with LV_GROUP_KEY_LEFT/RIGHT/UP/DOWN*/
97
    uint8_t scroll_prop    :1;        /*1: Propagate the scrolling the the parent if the edge is reached*/
98
    uint8_t scroll_prop_ip :1;        /*1: Scroll propagation is in progress (used by the library)*/
99
} lv_page_ext_t;
100

101
enum {
102
    LV_PAGE_STYLE_BG,
103
	LV_PAGE_STYLE_BGO,
104
	LV_PAGE_STYLE_PR,
105
    LV_PAGE_STYLE_SCRL,
106
    LV_PAGE_STYLE_SB,
107
    LV_PAGE_STYLE_EDGE_FLASH,
108
};
109
typedef uint8_t lv_page_style_t;
110

111
/**********************
112
 * GLOBAL PROTOTYPES
113
 **********************/
114

115
/**
116
 * Create a page objects
117
 * @param par pointer to an object, it will be the parent of the new page
118
 * @param copy pointer to a page object, if not NULL then the new object will be copied from it
119
 * @return pointer to the created page
120
 */
121
lv_obj_t * lv_page_create(lv_obj_t * par, const lv_obj_t * copy);
122

123
/**
124
 * Delete all children of the scrl object, without deleting scrl child.
125
 * @param obj pointer to an object
126
 */
127
void lv_page_clean(lv_obj_t *obj);
128

129
/**
130
 * Get the press action of the page
131
 * @param page pointer to a page object
132
 * @return a function to call when the page is pressed
133
 */
134
lv_action_t lv_page_get_pr_action(lv_obj_t * page);
135

136
/**
137
 * Get the release action of the page
138
 * @param page pointer to a page object
139
 * @return a function to call when the page is released
140
 */
141
lv_action_t lv_page_get_rel_action(lv_obj_t * page);
142

143
/**
144
 * Get the scrollable object of a page
145
 * @param page pointer to a page object
146
 * @return pointer to a container which is the scrollable part of the page
147
 */
148
lv_obj_t * lv_page_get_scrl(const lv_obj_t * page);
149

150
/*=====================
151
 * Setter functions
152
 *====================*/
153

154
/**
155
 * Set a release action for the page
156
 * @param page pointer to a page object
157
 * @param rel_action a function to call when the page is released
158
 */
159
void lv_page_set_rel_action(lv_obj_t * page, lv_action_t rel_action);
160

161
/**
162
 * Set a press action for the page
163
 * @param page pointer to a page object
164
 * @param pr_action a function to call when the page is pressed
165
 */
166
void lv_page_set_pr_action(lv_obj_t * page, lv_action_t pr_action);
167

168
/**
169
 * Set the scroll bar mode on a page
170
 * @param page pointer to a page object
171
 * @param sb_mode the new mode from 'lv_page_sb.mode_t' enum
172
 */
173
void lv_page_set_sb_mode(lv_obj_t * page, lv_sb_mode_t sb_mode);
174

175
/**
176
 * Enable/Disable scrolling with arrows if the page is in group (arrows: LV_GROUP_KEY_LEFT/RIGHT/UP/DOWN)
177
 * @param page pointer to a page object
178
 * @param en true: enable scrolling with arrows
179
 */
180
void lv_page_set_arrow_scroll(lv_obj_t * page, bool en);
181

182
/**
183
 * Enable the scroll propagation feature. If enabled then the page will move its parent if there is no more space to scroll.
184
 * @param page pointer to a Page
185
 * @param en true or false to enable/disable scroll propagation
186
 */
187
void lv_page_set_scroll_propagation(lv_obj_t * page, bool en);
188

189
/**
190
 * Enable the edge flash effect. (Show an arc when the an edge is reached)
191
 * @param page pointer to a Page
192
 * @param en true or false to enable/disable end flash
193
 */
194
void lv_page_set_edge_flash(lv_obj_t * page, bool en);
195

196
/**
197
 * Set the fit attribute of the scrollable part of a page.
198
 * It means it can set its size automatically to involve all children.
199
 * (Can be set separately horizontally and vertically)
200
 * @param page pointer to a page object
201
 * @param hor_en true: enable horizontal fit
202
 * @param ver_en true: enable vertical fit
203
 */
204
static inline void lv_page_set_scrl_fit(lv_obj_t *page, bool hor_en, bool ver_en)
205
{
206
    lv_cont_set_fit(lv_page_get_scrl(page), hor_en, ver_en);
207
}
208

209
/**
210
 * Set width of the scrollable part of a page
211
 * @param page pointer to a page object
212
 * @param w the new width of the scrollable (it ha no effect is horizontal fit is enabled)
213
 */
214
static inline void lv_page_set_scrl_width(lv_obj_t *page, lv_coord_t w)
215
{
216
    lv_obj_set_width(lv_page_get_scrl(page), w);
217
}
218

219
/**
220
 * Set height of the scrollable part of a page
221
 * @param page pointer to a page object
222
 * @param h the new height of the scrollable (it ha no effect is vertical fit is enabled)
223
 */
224
static inline void lv_page_set_scrl_height(lv_obj_t *page, lv_coord_t h)
225
{
226
    lv_obj_set_height(lv_page_get_scrl(page), h);
227

228
}
229

230
/**
231
* Set the layout of the scrollable part of the page
232
* @param page pointer to a page object
233
* @param layout a layout from 'lv_cont_layout_t'
234
*/
235
static inline void lv_page_set_scrl_layout(lv_obj_t * page, lv_layout_t layout)
236
{
237
    lv_cont_set_layout(lv_page_get_scrl(page), layout);
238
}
239

240
/**
241
 * Set a style of a page
242
 * @param page pointer to a page object
243
 * @param type which style should be set
244
 * @param style pointer to a style
245
 */
246
void lv_page_set_style(lv_obj_t *page, lv_page_style_t type, lv_style_t *style);
247

248
/*=====================
249
 * Getter functions
250
 *====================*/
251

252
/**
253
 * Set the scroll bar mode on a page
254
 * @param page pointer to a page object
255
 * @return the mode from 'lv_page_sb.mode_t' enum
256
 */
257
lv_sb_mode_t lv_page_get_sb_mode(const lv_obj_t * page);
258

259

260
/**
261
 * Get the the scrolling with arrows (LV_GROUP_KEY_LEFT/RIGHT/UP/DOWN) is enabled or not
262
 * @param page pointer to a page object
263
 * @return true: scrolling with arrows is enabled
264
 */
265
bool lv_page_get_arrow_scroll(const lv_obj_t * page);
266

267
/**
268
 * Get the scroll propagation property
269
 * @param page pointer to a Page
270
 * @return true or false
271
 */
272
bool lv_page_get_scroll_propagation(lv_obj_t * page);
273

274
/**
275
 * Get the edge flash effect property.
276
 * @param page pointer to a Page
277
 * return true or false
278
 */
279
bool lv_page_get_edge_flash(lv_obj_t * page);
280

281
/**
282
 * Get that width which can be set to the children to still not cause overflow (show scrollbars)
283
 * @param page pointer to a page object
284
 * @return the width which still fits into the page
285
 */
286
lv_coord_t lv_page_get_fit_width(lv_obj_t * page);
287

288
/**
289
 * Get that height which can be set to the children to still not cause overflow (show scrollbars)
290
 * @param page pointer to a page object
291
 * @return the height which still fits into the page
292
 */
293
lv_coord_t lv_page_get_fit_height(lv_obj_t * page);
294

295
/**
296
 * Get width of the scrollable part of a page
297
 * @param page pointer to a page object
298
 * @return the width of the scrollable
299
 */
300
static inline lv_coord_t lv_page_get_scrl_width(const lv_obj_t *page)
301
{
302
    return lv_obj_get_width(lv_page_get_scrl(page));
303
}
304

305
/**
306
 * Get height of the scrollable part of a page
307
 * @param page pointer to a page object
308
 * @return the height of the scrollable
309
 */
310
static inline lv_coord_t lv_page_get_scrl_height(const lv_obj_t *page)
311
{
312
    return lv_obj_get_height(lv_page_get_scrl(page));
313
}
314

315
/**
316
* Get the layout of the scrollable part of a page
317
* @param page pointer to page object
318
* @return the layout from 'lv_cont_layout_t'
319
*/
320
static inline lv_layout_t lv_page_get_scrl_layout(const lv_obj_t * page)
321
{
322
    return lv_cont_get_layout(lv_page_get_scrl(page));
323
}
324

325
/**
326
* Get horizontal fit attribute of the scrollable part of a page
327
* @param page pointer to a page object
328
* @return true: horizontal fit is enabled; false: disabled
329
*/
330
static inline bool lv_page_get_scrl_hor_fit(const lv_obj_t * page)
331
{
332
    return lv_cont_get_hor_fit(lv_page_get_scrl(page));
333
}
334

335
/**
336
* Get vertical fit attribute of the scrollable part of a page
337
* @param page pointer to a page object
338
* @return true: vertical fit is enabled; false: disabled
339
*/
340
static inline bool lv_page_get_scrl_fit_ver(const lv_obj_t * page)
341
{
342
    return lv_cont_get_ver_fit(lv_page_get_scrl(page));
343
}
344

345
/**
346
 * Get a style of a page
347
 * @param page pointer to page object
348
 * @param type which style should be get
349
 * @return style pointer to a style
350
 */
351
lv_style_t * lv_page_get_style(const lv_obj_t *page, lv_page_style_t type);
352

353
/*=====================
354
 * Other functions
355
 *====================*/
356

357
/**
358
 * Glue the object to the page. After it the page can be moved (dragged) with this object too.
359
 * @param obj pointer to an object on a page
360
 * @param glue true: enable glue, false: disable glue
361
 */
362
void lv_page_glue_obj(lv_obj_t * obj, bool glue);
363

364
/**
365
 * Focus on an object. It ensures that the object will be visible on the page.
366
 * @param page pointer to a page object
367
 * @param obj pointer to an object to focus (must be on the page)
368
 * @param anim_time scroll animation time in milliseconds (0: no animation)
369
 */
370
void lv_page_focus(lv_obj_t * page, const lv_obj_t * obj, uint16_t anim_time);
371

372
/**
373
 * Scroll the page horizontally
374
 * @param page pointer to a page object
375
 * @param dist the distance to scroll (< 0: scroll left; > 0 scroll right)
376
 */
377
void lv_page_scroll_hor(lv_obj_t * page, lv_coord_t dist);
378

379
/**
380
 * Scroll the page vertically
381
 * @param page pointer to a page object
382
 * @param dist the distance to scroll (< 0: scroll down; > 0 scroll up)
383
 */
384
void lv_page_scroll_ver(lv_obj_t * page, lv_coord_t dist);
385

386
/**
387
 * Not intended to use directly by the user but by other object types internally.
388
 * Start an edge flash animation. Exactly one `ext->edge_flash.xxx_ip` should be set
389
 * @param page
390
 */
391
void lv_page_start_edge_flash(lv_obj_t * page);
392
/**********************
393
 *      MACROS
394
 **********************/
395

396
#endif  /*USE_LV_PAGE*/
397

398
#ifdef __cplusplus
399
} /* extern "C" */
400
#endif
401

402
#endif  /*LV_PAGE_H*/
403

404