1 /**
2 * @file lv_win.h
3 *
4 */
5
6 #ifndef LV_WIN_H
7 #define LV_WIN_H
8
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12
13 /*********************
14 * INCLUDES
15 *********************/
16 #ifdef LV_CONF_INCLUDE_SIMPLE
17 #include "lv_conf.h"
18 #else
19 #include "../../lv_conf.h"
20 #endif
21
22 #if LV_USE_WIN != 0
23
24 /*Testing of dependencies*/
25 #if LV_USE_BTN == 0
26 #error "lv_win: lv_btn is required. Enable it in lv_conf.h (LV_USE_BTN 1) "
27 #endif
28
29 #if LV_USE_LABEL == 0
30 #error "lv_win: lv_label is required. Enable it in lv_conf.h (LV_USE_LABEL 1) "
31 #endif
32
33 #if LV_USE_IMG == 0
34 #error "lv_win: lv_img is required. Enable it in lv_conf.h (LV_USE_IMG 1) "
35 #endif
36
37 #if LV_USE_PAGE == 0
38 #error "lv_win: lv_page is required. Enable it in lv_conf.h (LV_USE_PAGE 1) "
39 #endif
40
41 #include "../lv_core/lv_obj.h"
42 #include "lv_cont.h"
43 #include "lv_btn.h"
44 #include "lv_label.h"
45 #include "lv_img.h"
46 #include "lv_page.h"
47
48 /*********************
49 * DEFINES
50 *********************/
51
52 /**********************
53 * TYPEDEFS
54 **********************/
55
56 /*Data of window*/
57 typedef struct
58 {
59 /*Ext. of ancestor*/
60 /*New data for this type */
61 lv_obj_t * page; /*Pointer to a page which holds the content*/
62 lv_obj_t * header; /*Pointer to the header container of the window*/
63 lv_obj_t * title; /*Pointer to the title label of the window*/
64 const lv_style_t * style_btn_rel; /*Control button releases style*/
65 const lv_style_t * style_btn_pr; /*Control button pressed style*/
66 lv_coord_t btn_size; /*Size of the control buttons (square)*/
67 } lv_win_ext_t;
68
69 /** Window styles. */
70 enum {
71 LV_WIN_STYLE_BG, /**< Window object background style. */
72 LV_WIN_STYLE_CONTENT, /**< Window content style. */
73 LV_WIN_STYLE_SB, /**< Window scrollbar style. */
74 LV_WIN_STYLE_HEADER, /**< Window titlebar background style. */
75 LV_WIN_STYLE_BTN_REL, /**< Same meaning as ordinary button styles. */
76 LV_WIN_STYLE_BTN_PR,
77 };
78 typedef uint8_t lv_win_style_t;
79
80 /**********************
81 * GLOBAL PROTOTYPES
82 **********************/
83
84 /**
85 * Create a window objects
86 * @param par pointer to an object, it will be the parent of the new window
87 * @param copy pointer to a window object, if not NULL then the new object will be copied from it
88 * @return pointer to the created window
89 */
90 lv_obj_t * lv_win_create(lv_obj_t * par, const lv_obj_t * copy);
91
92 /**
93 * Delete all children of the scrl object, without deleting scrl child.
94 * @param obj pointer to an object
95 */
96 void lv_win_clean(lv_obj_t * obj);
97
98 /*======================
99 * Add/remove functions
100 *=====================*/
101
102 /**
103 * Add control button to the header of the window
104 * @param win pointer to a window object
105 * @param img_src an image source ('lv_img_t' variable, path to file or a symbol)
106 * @return pointer to the created button object
107 */
108 lv_obj_t * lv_win_add_btn(lv_obj_t * win, const void * img_src);
109
110 /*=====================
111 * Setter functions
112 *====================*/
113
114 /**
115 * Can be assigned to a window control button to close the window
116 * @param btn pointer to the control button on teh widows header
117 * @param evet the event type
118 */
119 void lv_win_close_event_cb(lv_obj_t * btn, lv_event_t event);
120
121 /**
122 * Set the title of a window
123 * @param win pointer to a window object
124 * @param title string of the new title
125 */
126 void lv_win_set_title(lv_obj_t * win, const char * title);
127
128 /**
129 * Set the control button size of a window
130 * @param win pointer to a window object
131 * @return control button size
132 */
133 void lv_win_set_btn_size(lv_obj_t * win, lv_coord_t size);
134
135 /**
136 * Set the layout of the window
137 * @param win pointer to a window object
138 * @param layout the layout from 'lv_layout_t'
139 */
140 void lv_win_set_layout(lv_obj_t * win, lv_layout_t layout);
141
142 /**
143 * Set the scroll bar mode of a window
144 * @param win pointer to a window object
145 * @param sb_mode the new scroll bar mode from 'lv_sb_mode_t'
146 */
147 void lv_win_set_sb_mode(lv_obj_t * win, lv_sb_mode_t sb_mode);
148
149 /**
150 * Set focus animation duration on `lv_win_focus()`
151 * @param win pointer to a window object
152 * @param anim_time duration of animation [ms]
153 */
154 void lv_win_set_anim_time(lv_obj_t * win, uint16_t anim_time);
155
156 /**
157 * Set a style of a window
158 * @param win pointer to a window object
159 * @param type which style should be set
160 * @param style pointer to a style
161 */
162 void lv_win_set_style(lv_obj_t * win, lv_win_style_t type, const lv_style_t * style);
163
164 /**
165 * Set drag status of a window. If set to 'true' window can be dragged like on a PC.
166 * @param win pointer to a window object
167 * @param en whether dragging is enabled
168 */
169 void lv_win_set_drag(lv_obj_t * win, bool en);
170
171 /*=====================
172 * Getter functions
173 *====================*/
174
175 /**
176 * Get the title of a window
177 * @param win pointer to a window object
178 * @return title string of the window
179 */
180 const char * lv_win_get_title(const lv_obj_t * win);
181
182 /**
183 * Get the content holder object of window (`lv_page`) to allow additional customization
184 * @param win pointer to a window object
185 * @return the Page object where the window's content is
186 */
187 lv_obj_t * lv_win_get_content(const lv_obj_t * win);
188
189 /**
190 * Get the control button size of a window
191 * @param win pointer to a window object
192 * @return control button size
193 */
194 lv_coord_t lv_win_get_btn_size(const lv_obj_t * win);
195
196 /**
197 * Get the pointer of a widow from one of its control button.
198 * It is useful in the action of the control buttons where only button is known.
199 * @param ctrl_btn pointer to a control button of a window
200 * @return pointer to the window of 'ctrl_btn'
201 */
202 lv_obj_t * lv_win_get_from_btn(const lv_obj_t * ctrl_btn);
203
204 /**
205 * Get the layout of a window
206 * @param win pointer to a window object
207 * @return the layout of the window (from 'lv_layout_t')
208 */
209 lv_layout_t lv_win_get_layout(lv_obj_t * win);
210
211 /**
212 * Get the scroll bar mode of a window
213 * @param win pointer to a window object
214 * @return the scroll bar mode of the window (from 'lv_sb_mode_t')
215 */
216 lv_sb_mode_t lv_win_get_sb_mode(lv_obj_t * win);
217
218 /**
219 * Get focus animation duration
220 * @param win pointer to a window object
221 * @return duration of animation [ms]
222 */
223 uint16_t lv_win_get_anim_time(const lv_obj_t * win);
224
225 /**
226 * Get width of the content area (page scrollable) of the window
227 * @param win pointer to a window object
228 * @return the width of the content area
229 */
230 lv_coord_t lv_win_get_width(lv_obj_t * win);
231
232 /**
233 * Get a style of a window
234 * @param win pointer to a button object
235 * @param type which style window be get
236 * @return style pointer to a style
237 */
238 const lv_style_t * lv_win_get_style(const lv_obj_t * win, lv_win_style_t type);
239
240 /**
241 * Get drag status of a window. If set to 'true' window can be dragged like on a PC.
242 * @param win pointer to a window object
243 * @return whether window is draggable
244 */
lv_win_get_drag(const lv_obj_t * win)245 static inline bool lv_win_get_drag(const lv_obj_t * win)
246 {
247 return lv_obj_get_drag(win);
248 }
249
250 /*=====================
251 * Other functions
252 *====================*/
253
254 /**
255 * Focus on an object. It ensures that the object will be visible in the window.
256 * @param win pointer to a window object
257 * @param obj pointer to an object to focus (must be in the window)
258 * @param anim_en LV_ANIM_ON focus with an animation; LV_ANIM_OFF focus without animation
259 */
260 void lv_win_focus(lv_obj_t * win, lv_obj_t * obj, lv_anim_enable_t anim_en);
261
262 /**
263 * Scroll the window horizontally
264 * @param win pointer to a window object
265 * @param dist the distance to scroll (< 0: scroll right; > 0 scroll left)
266 */
lv_win_scroll_hor(lv_obj_t * win,lv_coord_t dist)267 static inline void lv_win_scroll_hor(lv_obj_t * win, lv_coord_t dist)
268 {
269 lv_win_ext_t * ext = (lv_win_ext_t *)lv_obj_get_ext_attr(win);
270 lv_page_scroll_hor(ext->page, dist);
271 }
272 /**
273 * Scroll the window vertically
274 * @param win pointer to a window object
275 * @param dist the distance to scroll (< 0: scroll down; > 0 scroll up)
276 */
lv_win_scroll_ver(lv_obj_t * win,lv_coord_t dist)277 static inline void lv_win_scroll_ver(lv_obj_t * win, lv_coord_t dist)
278 {
279 lv_win_ext_t * ext = (lv_win_ext_t *)lv_obj_get_ext_attr(win);
280 lv_page_scroll_ver(ext->page, dist);
281 }
282
283 /**********************
284 * MACROS
285 **********************/
286
287 #endif /*LV_USE_WIN*/
288
289 #ifdef __cplusplus
290 } /* extern "C" */
291 #endif
292
293 #endif /*LV_WIN_H*/
294