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 #include "../lv_conf_internal.h"
17
18 #if LV_USE_WIN != 0
19
20 /*Testing of dependencies*/
21 #if LV_USE_BTN == 0
22 #error "lv_win: lv_btn is required. Enable it in lv_conf.h (LV_USE_BTN 1) "
23 #endif
24
25 #if LV_USE_LABEL == 0
26 #error "lv_win: lv_label is required. Enable it in lv_conf.h (LV_USE_LABEL 1) "
27 #endif
28
29 #if LV_USE_IMG == 0
30 #error "lv_win: lv_img is required. Enable it in lv_conf.h (LV_USE_IMG 1) "
31 #endif
32
33 #if LV_USE_PAGE == 0
34 #error "lv_win: lv_page is required. Enable it in lv_conf.h (LV_USE_PAGE 1) "
35 #endif
36
37 #include "../lv_core/lv_obj.h"
38 #include "lv_cont.h"
39 #include "lv_btn.h"
40 #include "lv_label.h"
41 #include "lv_img.h"
42 #include "lv_page.h"
43
44 /*********************
45 * DEFINES
46 *********************/
47
48 /**********************
49 * TYPEDEFS
50 **********************/
51
52 /*Data of window*/
53 typedef struct {
54 /*Ext. of ancestor*/
55 /*New data for this type */
56 lv_obj_t * page; /*Pointer to a page which holds the content*/
57 lv_obj_t * header; /*Pointer to the header container of the window*/
58 char * title_txt; /*Pointer to the title label of the window*/
59 lv_coord_t btn_w; /*Width of the control buttons*/
60 } lv_win_ext_t;
61
62 /** Window parts. */
63 enum {
64 LV_WIN_PART_BG = LV_OBJ_PART_MAIN, /**< Window object background style. */
65 _LV_WIN_PART_VIRTUAL_LAST,
66 LV_WIN_PART_HEADER = _LV_OBJ_PART_REAL_LAST, /**< Window titlebar background style. */
67 LV_WIN_PART_CONTENT_SCROLLABLE, /**< Window content style. */
68 LV_WIN_PART_SCROLLBAR, /**< Window scrollbar style. */
69 _LV_WIN_PART_REAL_LAST
70 };
71
72 /**********************
73 * GLOBAL PROTOTYPES
74 **********************/
75
76 /**
77 * Create a window objects
78 * @param par pointer to an object, it will be the parent of the new window
79 * @param copy pointer to a window object, if not NULL then the new object will be copied from it
80 * @return pointer to the created window
81 */
82 lv_obj_t * lv_win_create(lv_obj_t * par, const lv_obj_t * copy);
83
84 /**
85 * Delete all children of the scrl object, without deleting scrl child.
86 * @param win pointer to an object
87 */
88 void lv_win_clean(lv_obj_t * win);
89
90 /*======================
91 * Add/remove functions
92 *=====================*/
93
94 /**
95 * Add control button on the right side of the window header
96 * @param win pointer to a window object
97 * @param img_src an image source ('lv_img_t' variable, path to file or a symbol)
98 * @return pointer to the created button object
99 */
100 lv_obj_t * lv_win_add_btn_right(lv_obj_t * win, const void * img_src);
101
102 /**
103 * Add control button on the left side of the window header
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_left(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 the 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_header_height(lv_obj_t * win, lv_coord_t size);
134
135 /**
136 * Set the width of the control buttons on the header
137 * @param win pointer to a window object
138 * @param width width of the control button. 0: to make them square automatically.
139 */
140 void lv_win_set_btn_width(lv_obj_t * win, lv_coord_t width);
141
142 /**
143 * Set the size of the content area.
144 * @param win pointer to a window object
145 * @param w width
146 * @param h height (the window will be higher with the height of the header)
147 */
148 void lv_win_set_content_size(lv_obj_t * win, lv_coord_t w, lv_coord_t h);
149
150 /**
151 * Set the layout of the window
152 * @param win pointer to a window object
153 * @param layout the layout from 'lv_layout_t'
154 */
155 void lv_win_set_layout(lv_obj_t * win, lv_layout_t layout);
156
157 /**
158 * Set the scroll bar mode of a window
159 * @param win pointer to a window object
160 * @param sb_mode the new scroll bar mode from 'lv_scrollbar_mode_t'
161 */
162 void lv_win_set_scrollbar_mode(lv_obj_t * win, lv_scrollbar_mode_t sb_mode);
163
164 /**
165 * Set focus animation duration on `lv_win_focus()`
166 * @param win pointer to a window object
167 * @param anim_time duration of animation [ms]
168 */
169 void lv_win_set_anim_time(lv_obj_t * win, uint16_t anim_time);
170
171 /**
172 * Set drag status of a window. If set to 'true' window can be dragged like on a PC.
173 * @param win pointer to a window object
174 * @param en whether dragging is enabled
175 */
176 void lv_win_set_drag(lv_obj_t * win, bool en);
177
178 /*=====================
179 * Getter functions
180 *====================*/
181
182 /**
183 * Get the title of a window
184 * @param win pointer to a window object
185 * @return title string of the window
186 */
187 const char * lv_win_get_title(const lv_obj_t * win);
188
189 /**
190 * Get the content holder object of window (`lv_page`) to allow additional customization
191 * @param win pointer to a window object
192 * @return the Page object where the window's content is
193 */
194 lv_obj_t * lv_win_get_content(const lv_obj_t * win);
195
196 /**
197 * Get the header height
198 * @param win pointer to a window object
199 * @return header height
200 */
201 lv_coord_t lv_win_get_header_height(const lv_obj_t * win);
202
203
204 /**
205 * Get the width of the control buttons on the header
206 * @param win pointer to a window object
207 * @return width of the control button. 0: square.
208 */
209 lv_coord_t lv_win_get_btn_width(lv_obj_t * win);
210
211 /**
212 * Get the pointer of a widow from one of its control button.
213 * It is useful in the action of the control buttons where only button is known.
214 * @param ctrl_btn pointer to a control button of a window
215 * @return pointer to the window of 'ctrl_btn'
216 */
217 lv_obj_t * lv_win_get_from_btn(const lv_obj_t * ctrl_btn);
218
219 /**
220 * Get the layout of a window
221 * @param win pointer to a window object
222 * @return the layout of the window (from 'lv_layout_t')
223 */
224 lv_layout_t lv_win_get_layout(lv_obj_t * win);
225
226 /**
227 * Get the scroll bar mode of a window
228 * @param win pointer to a window object
229 * @return the scroll bar mode of the window (from 'lv_sb_mode_t')
230 */
231 lv_scrollbar_mode_t lv_win_get_sb_mode(lv_obj_t * win);
232
233 /**
234 * Get focus animation duration
235 * @param win pointer to a window object
236 * @return duration of animation [ms]
237 */
238 uint16_t lv_win_get_anim_time(const lv_obj_t * win);
239
240 /**
241 * Get width of the content area (page scrollable) of the window
242 * @param win pointer to a window object
243 * @return the width of the content area
244 */
245 lv_coord_t lv_win_get_width(lv_obj_t * win);
246
247 /**
248 * Get drag status of a window. If set to 'true' window can be dragged like on a PC.
249 * @param win pointer to a window object
250 * @return whether window is draggable
251 */
lv_win_get_drag(const lv_obj_t * win)252 static inline bool lv_win_get_drag(const lv_obj_t * win)
253 {
254 return lv_obj_get_drag(win);
255 }
256
257 /*=====================
258 * Other functions
259 *====================*/
260
261 /**
262 * Focus on an object. It ensures that the object will be visible in the window.
263 * @param win pointer to a window object
264 * @param obj pointer to an object to focus (must be in the window)
265 * @param anim_en LV_ANIM_ON focus with an animation; LV_ANIM_OFF focus without animation
266 */
267 void lv_win_focus(lv_obj_t * win, lv_obj_t * obj, lv_anim_enable_t anim_en);
268
269 /**
270 * Scroll the window horizontally
271 * @param win pointer to a window object
272 * @param dist the distance to scroll (< 0: scroll right; > 0 scroll left)
273 */
lv_win_scroll_hor(lv_obj_t * win,lv_coord_t dist)274 static inline void lv_win_scroll_hor(lv_obj_t * win, lv_coord_t dist)
275 {
276 lv_win_ext_t * ext = (lv_win_ext_t *)lv_obj_get_ext_attr(win);
277 lv_page_scroll_hor(ext->page, dist);
278 }
279 /**
280 * Scroll the window vertically
281 * @param win pointer to a window object
282 * @param dist the distance to scroll (< 0: scroll down; > 0 scroll up)
283 */
lv_win_scroll_ver(lv_obj_t * win,lv_coord_t dist)284 static inline void lv_win_scroll_ver(lv_obj_t * win, lv_coord_t dist)
285 {
286 lv_win_ext_t * ext = (lv_win_ext_t *)lv_obj_get_ext_attr(win);
287 lv_page_scroll_ver(ext->page, dist);
288 }
289
290 /**********************
291 * MACROS
292 **********************/
293
294 #endif /*LV_USE_WIN*/
295
296 #ifdef __cplusplus
297 } /* extern "C" */
298 #endif
299
300 #endif /*LV_WIN_H*/
301
