1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3  * Internal header file for scenes
4  *
5  * Copyright 2022 Google LLC
6  * Written by Simon Glass <sjg@chromium.org>
7  */
8 
9 #ifndef __SCENE_INTERNAL_H
10 #define __SCENE_INTERNAL_H
11 
12 #include <linux/types.h>
13 
14 struct expo;
15 struct expo_action;
16 struct expo_arrange_info;
17 struct expo_theme;
18 struct scene_obj;
19 struct scene_obj_menu;
20 struct scene_obj_textline;
21 struct scene_obj_txtedit;
22 struct scene_txt_generic;
23 struct vidconsole_bbox;
24 
25 enum scene_obj_t;
26 
27 typedef int (*expo_scene_obj_iterator)(struct scene_obj *obj, void *priv);
28 
29 /**
30  * enum scene_bbox_t - Parts of an object which can have a bounding box
31  *
32  * Objects can provide any or all of these bounding boxes
33  *
34  * @SCENEBB_label: Menu-item label
35  * @SCENEBB_key: Menu-item key label
36  * @SCENEBB_desc: Menu-item Description
37  * @SCENEBB_curitem: Current item (pointed to)
38  * @SCENEBB_all: All the above objects combined
39  */
40 enum scene_bbox_t {
41 	SCENEBB_label,
42 	SCENEBB_key,
43 	SCENEBB_desc,
44 	SCENEBB_curitem,
45 	SCENEBB_all,
46 
47 	SCENEBB_count,
48 };
49 
50 /**
51  * expo_lookup_scene_id() - Look up a scene ID
52  *
53  * @exp: Expo to use
54  * @id: scene ID to look up
55  * Returns: Scene for that ID, or NULL if none
56  */
57 struct scene *expo_lookup_scene_id(struct expo *exp, uint scene_id);
58 
59 /**
60  * resolve_id() - Automatically allocate an ID if needed
61  *
62  * @exp: Expo to use
63  * @id: ID to use, or 0 to auto-allocate one
64  * Returns: Either @id, or the auto-allocated ID
65  */
66 uint resolve_id(struct expo *exp, uint id);
67 
68 /**
69  * scene_obj_find() - Find an object in a scene
70  *
71  * Note that @type is used to restrict the search when the object type is known.
72  * If any type is acceptable, set @type to SCENEOBJT_NONE
73  *
74  * @scn: Scene to search
75  * @id: ID of object to find
76  * @type: Type of the object, or SCENEOBJT_NONE to match any type
77  * Returns: Object found, or NULL if not found
78  */
79 void *scene_obj_find(const struct scene *scn, uint id, enum scene_obj_t type);
80 
81 /**
82  * scene_obj_find_by_name() - Find an object in a scene by name
83  *
84  * @scn: Scene to search
85  * @name: Name to search for
86  */
87 void *scene_obj_find_by_name(struct scene *scn, const char *name);
88 
89 /**
90  * scene_obj_add() - Add a new object to a scene
91  *
92  * @scn: Scene to update
93  * @name: Name to use (this is allocated by this call)
94  * @id: ID to use for the new object (0 to allocate one)
95  * @type: Type of object to add
96  * @size: Size to allocate for the object, in bytes
97  * @objp: Returns a pointer to the new object (must not be NULL)
98  * Returns: ID number for the object (generally @id), or -ve on error
99  */
100 int scene_obj_add(struct scene *scn, const char *name, uint id,
101 		  enum scene_obj_t type, uint size, struct scene_obj **objp);
102 
103 /**
104  * scene_obj_flag_clrset() - Adjust object flags
105  *
106  * @scn: Scene to update
107  * @id: ID of object to update
108  * @clr: Bits to clear in the object's flags
109  * @set: Bits to set in the object's flags
110  * Returns 0 if OK, -ENOENT if the object was not found
111  */
112 int scene_obj_flag_clrset(struct scene *scn, uint id, uint clr, uint set);
113 
114 /**
115  * scene_calc_dims() - Calculate the dimensions of the scene objects
116  *
117  * Updates the width and height of all objects based on their contents
118  *
119  * @scn: Scene to update
120  * @do_menus: true to calculate only menus, false to calculate everything else
121  * Returns 0 if OK, -ENOTSUPP if there is no graphical console
122  */
123 int scene_calc_dims(struct scene *scn, bool do_menus);
124 
125 /**
126  * scene_menu_arrange() - Set the position of things in the menu
127  *
128  * This updates any items associated with a menu to make sure they are
129  * positioned correctly relative to the menu. It also selects the first item
130  * if not already done
131  *
132  * @scn: Scene to update
133  * @arr: Arrangement information
134  * @menu: Menu to process
135  * Returns: 0 if OK, -ve on error
136  */
137 int scene_menu_arrange(struct scene *scn, struct expo_arrange_info *arr,
138 		       struct scene_obj_menu *menu);
139 
140 /**
141  * scene_textline_arrange() - Set the position of things in a textline
142  *
143  * This updates any items associated with a textline to make sure they are
144  * positioned correctly relative to the textline.
145  *
146  * @scn: Scene to update
147  * @arr: Arrangement information
148  * @tline: textline to process
149  * Returns: 0 if OK, -ve on error
150  */
151 int scene_textline_arrange(struct scene *scn, struct expo_arrange_info *arr,
152 			   struct scene_obj_textline *tline);
153 
154 /**
155  * scene_apply_theme() - Apply a theme to a scene
156  *
157  * @scn: Scene to update
158  * @theme: Theme to apply
159  * Returns: 0 if OK, -ve on error
160  */
161 int scene_apply_theme(struct scene *scn, struct expo_theme *theme);
162 
163 /**
164  * scene_menu_send_key() - Send a key to a menu for processing
165  *
166  * @scn: Scene to use
167  * @menu: Menu to use
168  * @key: Key code to send (KEY_...)
169  * @event: Place to put any event which is generated by the key
170  * Returns: 0 if OK, -ENOTTY if there is no current menu item, other -ve on other
171  *	error
172  */
173 int scene_menu_send_key(struct scene *scn, struct scene_obj_menu *menu, int key,
174 			struct expo_action *event);
175 
176 /**
177  * scene_textline_send_key() - Send a key to a textline for processing
178  *
179  * @scn: Scene to use
180  * @tline: textline to use
181  * @key: Key code to send (KEY_...)
182  * @event: Place to put any event which is generated by the key
183  * Returns: 0 if OK (always)
184  */
185 int scene_textline_send_key(struct scene *scn, struct scene_obj_textline *tline,
186 			    int key, struct expo_action *event);
187 
188 /**
189  * scene_menu_destroy() - Destroy a menu in a scene
190  *
191  * @scn: Scene to destroy
192  */
193 void scene_menu_destroy(struct scene_obj_menu *menu);
194 
195 /**
196  * scene_menu_display() - Display a menu as text
197  *
198  * @menu: Menu to display
199  * Returns: 0 if OK, -ENOENT if @id is invalid
200  */
201 int scene_menu_display(struct scene_obj_menu *menu);
202 
203 /**
204  * scene_destroy() - Destroy a scene and all its memory
205  *
206  * @scn: Scene to destroy
207  */
208 void scene_destroy(struct scene *scn);
209 
210 /**
211  * scene_render() - Render a scene
212  *
213  * This is called from expo_render()
214  *
215  * @scn: Scene to render
216  * Returns: 0 if OK, -ve on error
217  */
218 int scene_render(struct scene *scn);
219 
220 /**
221  * scene_send_key() - set a keypress to a scene
222  *
223  * @scn: Scene to receive the key
224  * @key: Key to send (KEYCODE_UP)
225  * @event: Returns resulting event from this keypress
226  * Returns: 0 if OK, -ve on error
227  */
228 int scene_send_key(struct scene *scn, int key, struct expo_action *event);
229 
230 /**
231  * scene_render_deps() - Render an object and its dependencies
232  *
233  * @scn: Scene to render
234  * @id: Object ID to render (or 0 for none)
235  * Returns: 0 if OK, -ve on error
236  */
237 int scene_render_deps(struct scene *scn, uint id);
238 
239 /**
240  * scene_menu_render_deps() - Render a menu and its dependencies
241  *
242  * Renders the menu and all of its attached objects
243  *
244  * @scn: Scene to render
245  * @menu: Menu to render
246  * Returns: 0 if OK, -ve on error
247  */
248 int scene_menu_render_deps(struct scene *scn, struct scene_obj_menu *menu);
249 
250 /**
251  * scene_textline_render_deps() - Render a textline and its dependencies
252  *
253  * Renders the textline and all of its attached objects
254  *
255  * @scn: Scene to render
256  * @tline: textline to render
257  * Returns: 0 if OK, -ve on error
258  */
259 int scene_textline_render_deps(struct scene *scn,
260 			       struct scene_obj_textline *tline);
261 
262 /**
263  * scene_menu_calc_dims() - Calculate the dimensions of a menu
264  *
265  * Updates the width and height of the menu based on its contents
266  *
267  * @menu: Menu to update
268  * Returns 0 if OK, -ENOTSUPP if there is no graphical console
269  */
270 int scene_menu_calc_dims(struct scene_obj_menu *menu);
271 
272 /**
273  * scene_iter_objs() - Iterate through all scene objects
274  *
275  * @scn: Scene to process
276  * @iter: Iterator to call on each object
277  * @priv: Private data to pass to the iterator, in addition to the object
278  * Return: 0 if OK, -ve on error
279  */
280 int scene_iter_objs(struct scene *scn, expo_scene_obj_iterator iter,
281 		    void *priv);
282 
283 /**
284  * expo_iter_scene_objects() - Iterate through all scene objects
285  *
286  * @exp: Expo to process
287  * @iter: Iterator to call on each object
288  * @priv: Private data to pass to the iterator, in addition to the object
289  * Return: 0 if OK, -ve on error
290  */
291 int expo_iter_scene_objs(struct expo *exp, expo_scene_obj_iterator iter,
292 			 void *priv);
293 
294 /**
295  * scene_menuitem_find() - Find the menu item for an ID
296  *
297  * Looks up the menu to find the item with the given ID
298  *
299  * @menu: Menu to check
300  * @id: ID to look for
301  * Return: Menu item, or NULL if not found
302  */
303 struct scene_menitem *scene_menuitem_find(const struct scene_obj_menu *menu,
304 					  int id);
305 
306 /**
307  * scene_menuitem_find_seq() - Find the menu item at a sequential position
308  *
309  * This numbers the items from 0 and returns the seq'th one
310  *
311  * @menu: Menu to check
312  * @seq: Sequence number to look for
313  * Return: menu item if found, else NULL
314  */
315 struct scene_menitem *scene_menuitem_find_seq(const struct scene_obj_menu *menu,
316 					      uint seq);
317 
318 /**
319  * scene_menuitem_find_val() - Find the menu item with a given value
320  *
321  * @menu: Menu to check
322  * @find_val: Value to look for
323  * Return: menu item if found, else NULL
324  */
325 struct scene_menitem *scene_menuitem_find_val(const struct scene_obj_menu *menu,
326 					      int val);
327 
328 /**
329  * scene_bbox_join() - update bouding box with a given src box
330  *
331  * Updates @dst so that it encompasses the bounding box @src
332  *
333  * @src: Input bounding box
334  * @inset: Amount of inset to use for width
335  * @dst: Bounding box to update
336  * Return: 0 if OK, -ve on error
337  */
338 int scene_bbox_join(const struct vidconsole_bbox *src, int inset,
339 		    struct vidconsole_bbox *dst);
340 
341 /**
342  * scene_bbox_union() - update bouding box with the demensions of an object
343  *
344  * Updates @bbox so that it encompasses the bounding box of object @id
345  *
346  * @snd: Scene containing object
347  * @id: Object id
348  * @inset: Amount of inset to use for width
349  * @bbox: Bounding box to update
350  * Return: 0 if OK, -ve on error
351  */
352 int scene_bbox_union(struct scene *scn, uint id, int inset,
353 		     struct vidconsole_bbox *bbox);
354 
355 /**
356  * scene_textline_calc_dims() - Calculate the dimensions of a textline
357  *
358  * Updates the width and height of the textline based on its contents
359  *
360  * @tline: Textline to update
361  * Returns 0 if OK, -ENOTSUPP if there is no graphical console
362  */
363 int scene_textline_calc_dims(struct scene_obj_textline *tline);
364 
365 /**
366  * scene_menu_calc_bbox() - Calculate bounding boxes for the menu
367  *
368  * @menu: Menu to process
369  * @bbox: List of bounding box to fill in
370  * Return: 0 if OK, -ve on error
371  */
372 void scene_menu_calc_bbox(struct scene_obj_menu *menu,
373 			  struct vidconsole_bbox *bbox);
374 
375 /**
376  * scene_textline_calc_bbox() - Calculate bounding box for the textline
377  *
378  * @textline: Menu to process
379  * @bbox: Returns bounding box of textline including prompt
380  * @edit_bbox: Returns bounding box of editable part
381  * Return: 0 if OK, -ve on error
382  */
383 void scene_textline_calc_bbox(struct scene_obj_textline *menu,
384 			      struct vidconsole_bbox *bbox,
385 			      struct vidconsole_bbox *label_bbox);
386 
387 /**
388  * scene_obj_calc_bbox() - Calculate bounding boxes for an object
389  *
390  * @obj: Object to process
391  * @bbox: Returns bounding boxes for object
392  * Return: 0 if OK, -ve on error
393  */
394 int scene_obj_calc_bbox(struct scene_obj *obj, struct vidconsole_bbox *bbox);
395 
396 /**
397  * scene_textline_open() - Open a textline object
398  *
399  * Set up the text editor ready for use
400  *
401  * @scn: Scene containing the textline
402  * @tline: textline object
403  * Return: 0 if OK, -ve on error
404  */
405 int scene_textline_open(struct scene *scn, struct scene_obj_textline *tline);
406 
407 /**
408  * scene_textline_close() - Close a textline object
409  *
410  * Close out the text editor after use
411  *
412  * @scn: Scene containing the textline
413  * @tline: textline object
414  * Return: 0 if OK, -ve on error
415  */
416 int scene_textline_close(struct scene *scn, struct scene_obj_textline *tline);
417 
418 /**
419  * scene_calc_arrange() - Calculate sizes needed to arrange a scene
420  *
421  * Checks the size of some objects and stores this info to help with a later
422  * scene arrangement
423  *
424  * @scn: Scene to check
425  * @arr: Place to put scene-arrangement info
426  * Returns: 0 if OK, -ve on error
427  */
428 int scene_calc_arrange(struct scene *scn, struct expo_arrange_info *arr);
429 
430 /**
431  * scene_txt_generic_init() - Set up the generic part of a text object
432  *
433  * @exp: Expo containing the object
434  * @gen: Generic text info
435  * @name: Object name
436  * @str_id: String ID for the text
437  * @str: Initial text string for the object, or NULL to just use str_id
438  */
439 int scene_txt_generic_init(struct expo *exp, struct scene_txt_generic *gen,
440 			   const char *name, uint str_id, const char *str);
441 
442 #endif /* __SCENE_INTERNAL_H */
443