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
12struct vidconsole_bbox;
13
14typedef int (*expo_scene_obj_iterator)(struct scene_obj *obj, void *priv);
15
16/**
17 * expo_lookup_scene_id() - Look up a scene ID
18 *
19 * @exp: Expo to use
20 * @id: scene ID to look up
21 * Returns: Scene for that ID, or NULL if none
22 */
23struct scene *expo_lookup_scene_id(struct expo *exp, uint scene_id);
24
25/**
26 * resolve_id() - Automatically allocate an ID if needed
27 *
28 * @exp: Expo to use
29 * @id: ID to use, or 0 to auto-allocate one
30 * Returns: Either @id, or the auto-allocated ID
31 */
32uint resolve_id(struct expo *exp, uint id);
33
34/**
35 * scene_obj_find() - Find an object in a scene
36 *
37 * Note that @type is used to restrict the search when the object type is known.
38 * If any type is acceptable, set @type to SCENEOBJT_NONE
39 *
40 * @scn: Scene to search
41 * @id: ID of object to find
42 * @type: Type of the object, or SCENEOBJT_NONE to match any type
43 * Returns: Object found, or NULL if not found
44 */
45void *scene_obj_find(const struct scene *scn, uint id, enum scene_obj_t type);
46
47/**
48 * scene_obj_find_by_name() - Find an object in a scene by name
49 *
50 * @scn: Scene to search
51 * @name: Name to search for
52 */
53void *scene_obj_find_by_name(struct scene *scn, const char *name);
54
55/**
56 * scene_obj_add() - Add a new object to a scene
57 *
58 * @scn: Scene to update
59 * @name: Name to use (this is allocated by this call)
60 * @id: ID to use for the new object (0 to allocate one)
61 * @type: Type of object to add
62 * @size: Size to allocate for the object, in bytes
63 * @objp: Returns a pointer to the new object (must not be NULL)
64 * Returns: ID number for the object (generally @id), or -ve on error
65 */
66int scene_obj_add(struct scene *scn, const char *name, uint id,
67		  enum scene_obj_t type, uint size, struct scene_obj **objp);
68
69/**
70 * scene_obj_flag_clrset() - Adjust object flags
71 *
72 * @scn: Scene to update
73 * @id: ID of object to update
74 * @clr: Bits to clear in the object's flags
75 * @set: Bits to set in the object's flags
76 * Returns 0 if OK, -ENOENT if the object was not found
77 */
78int scene_obj_flag_clrset(struct scene *scn, uint id, uint clr, uint set);
79
80/**
81 * scene_calc_dims() - Calculate the dimensions of the scene objects
82 *
83 * Updates the width and height of all objects based on their contents
84 *
85 * @scn: Scene to update
86 * @do_menus: true to calculate only menus, false to calculate everything else
87 * Returns 0 if OK, -ENOTSUPP if there is no graphical console
88 */
89int scene_calc_dims(struct scene *scn, bool do_menus);
90
91/**
92 * scene_menu_arrange() - Set the position of things in the menu
93 *
94 * This updates any items associated with a menu to make sure they are
95 * positioned correctly relative to the menu. It also selects the first item
96 * if not already done
97 *
98 * @scn: Scene to update
99 * @menu: Menu to process
100 * Returns: 0 if OK, -ve on error
101 */
102int scene_menu_arrange(struct scene *scn, struct scene_obj_menu *menu);
103
104/**
105 * scene_textline_arrange() - Set the position of things in a textline
106 *
107 * This updates any items associated with a textline to make sure they are
108 * positioned correctly relative to the textline.
109 *
110 * @scn: Scene to update
111 * @tline: textline to process
112 * Returns: 0 if OK, -ve on error
113 */
114int scene_textline_arrange(struct scene *scn, struct scene_obj_textline *tline);
115
116/**
117 * scene_apply_theme() - Apply a theme to a scene
118 *
119 * @scn: Scene to update
120 * @theme: Theme to apply
121 * Returns: 0 if OK, -ve on error
122 */
123int scene_apply_theme(struct scene *scn, struct expo_theme *theme);
124
125/**
126 * scene_menu_send_key() - Send a key to a menu for processing
127 *
128 * @scn: Scene to use
129 * @menu: Menu to use
130 * @key: Key code to send (KEY_...)
131 * @event: Place to put any event which is generated by the key
132 * Returns: 0 if OK, -ENOTTY if there is no current menu item, other -ve on other
133 *	error
134 */
135int scene_menu_send_key(struct scene *scn, struct scene_obj_menu *menu, int key,
136			struct expo_action *event);
137
138/**
139 * scene_textline_send_key() - Send a key to a textline for processing
140 *
141 * @scn: Scene to use
142 * @tline: textline to use
143 * @key: Key code to send (KEY_...)
144 * @event: Place to put any event which is generated by the key
145 * Returns: 0 if OK (always)
146 */
147int scene_textline_send_key(struct scene *scn, struct scene_obj_textline *tline,
148			    int key, struct expo_action *event);
149
150/**
151 * scene_menu_destroy() - Destroy a menu in a scene
152 *
153 * @scn: Scene to destroy
154 */
155void scene_menu_destroy(struct scene_obj_menu *menu);
156
157/**
158 * scene_menu_display() - Display a menu as text
159 *
160 * @menu: Menu to display
161 * Returns: 0 if OK, -ENOENT if @id is invalid
162 */
163int scene_menu_display(struct scene_obj_menu *menu);
164
165/**
166 * scene_destroy() - Destroy a scene and all its memory
167 *
168 * @scn: Scene to destroy
169 */
170void scene_destroy(struct scene *scn);
171
172/**
173 * scene_render() - Render a scene
174 *
175 * This is called from expo_render()
176 *
177 * @scn: Scene to render
178 * Returns: 0 if OK, -ve on error
179 */
180int scene_render(struct scene *scn);
181
182/**
183 * scene_send_key() - set a keypress to a scene
184 *
185 * @scn: Scene to receive the key
186 * @key: Key to send (KEYCODE_UP)
187 * @event: Returns resulting event from this keypress
188 * Returns: 0 if OK, -ve on error
189 */
190int scene_send_key(struct scene *scn, int key, struct expo_action *event);
191
192/**
193 * scene_render_deps() - Render an object and its dependencies
194 *
195 * @scn: Scene to render
196 * @id: Object ID to render (or 0 for none)
197 * Returns: 0 if OK, -ve on error
198 */
199int scene_render_deps(struct scene *scn, uint id);
200
201/**
202 * scene_menu_render_deps() - Render a menu and its dependencies
203 *
204 * Renders the menu and all of its attached objects
205 *
206 * @scn: Scene to render
207 * @menu: Menu to render
208 * Returns: 0 if OK, -ve on error
209 */
210int scene_menu_render_deps(struct scene *scn, struct scene_obj_menu *menu);
211
212/**
213 * scene_textline_render_deps() - Render a textline and its dependencies
214 *
215 * Renders the textline and all of its attached objects
216 *
217 * @scn: Scene to render
218 * @tline: textline to render
219 * Returns: 0 if OK, -ve on error
220 */
221int scene_textline_render_deps(struct scene *scn,
222			       struct scene_obj_textline *tline);
223
224/**
225 * scene_menu_calc_dims() - Calculate the dimensions of a menu
226 *
227 * Updates the width and height of the menu based on its contents
228 *
229 * @menu: Menu to update
230 * Returns 0 if OK, -ENOTSUPP if there is no graphical console
231 */
232int scene_menu_calc_dims(struct scene_obj_menu *menu);
233
234/**
235 * scene_iter_objs() - Iterate through all scene objects
236 *
237 * @scn: Scene to process
238 * @iter: Iterator to call on each object
239 * @priv: Private data to pass to the iterator, in addition to the object
240 * Return: 0 if OK, -ve on error
241 */
242int scene_iter_objs(struct scene *scn, expo_scene_obj_iterator iter,
243		    void *priv);
244
245/**
246 * expo_iter_scene_objects() - Iterate through all scene objects
247 *
248 * @exp: Expo to process
249 * @iter: Iterator to call on each object
250 * @priv: Private data to pass to the iterator, in addition to the object
251 * Return: 0 if OK, -ve on error
252 */
253int expo_iter_scene_objs(struct expo *exp, expo_scene_obj_iterator iter,
254			 void *priv);
255
256/**
257 * scene_menuitem_find() - Find the menu item for an ID
258 *
259 * Looks up the menu to find the item with the given ID
260 *
261 * @menu: Menu to check
262 * @id: ID to look for
263 * Return: Menu item, or NULL if not found
264 */
265struct scene_menitem *scene_menuitem_find(const struct scene_obj_menu *menu,
266					  int id);
267
268/**
269 * scene_menuitem_find_seq() - Find the menu item at a sequential position
270 *
271 * This numbers the items from 0 and returns the seq'th one
272 *
273 * @menu: Menu to check
274 * @seq: Sequence number to look for
275 * Return: menu item if found, else NULL
276 */
277struct scene_menitem *scene_menuitem_find_seq(const struct scene_obj_menu *menu,
278					      uint seq);
279
280/**
281 * scene_bbox_union() - update bouding box with the demensions of an object
282 *
283 * Updates @bbox so that it encompasses the bounding box of object @id
284 *
285 * @snd: Scene containing object
286 * @id: Object id
287 * @inset: Amount of inset to use for width
288 * @bbox: Bounding box to update
289 * Return: 0 if OK, -ve on error
290 */
291int scene_bbox_union(struct scene *scn, uint id, int inset,
292		     struct vidconsole_bbox *bbox);
293
294/**
295 * scene_textline_calc_dims() - Calculate the dimensions of a textline
296 *
297 * Updates the width and height of the textline based on its contents
298 *
299 * @tline: Textline to update
300 * Returns 0 if OK, -ENOTSUPP if there is no graphical console
301 */
302int scene_textline_calc_dims(struct scene_obj_textline *tline);
303
304/**
305 * scene_menu_calc_bbox() - Calculate bounding boxes for the menu
306 *
307 * @menu: Menu to process
308 * @bbox: Returns bounding box of menu including prompts
309 * @label_bbox: Returns bounding box of labels
310 * Return: 0 if OK, -ve on error
311 */
312void scene_menu_calc_bbox(struct scene_obj_menu *menu,
313			  struct vidconsole_bbox *bbox,
314			  struct vidconsole_bbox *label_bbox);
315
316/**
317 * scene_textline_calc_bbox() - Calculate bounding box for the textline
318 *
319 * @textline: Menu to process
320 * @bbox: Returns bounding box of textline including prompt
321 * @edit_bbox: Returns bounding box of editable part
322 * Return: 0 if OK, -ve on error
323 */
324void scene_textline_calc_bbox(struct scene_obj_textline *menu,
325			      struct vidconsole_bbox *bbox,
326			      struct vidconsole_bbox *label_bbox);
327
328/**
329 * scene_obj_calc_bbox() - Calculate bounding boxes for an object
330 *
331 * @obj: Object to process
332 * @bbox: Returns bounding box of object including prompts
333 * @label_bbox: Returns bounding box of labels (active area)
334 * Return: 0 if OK, -ve on error
335 */
336int scene_obj_calc_bbox(struct scene_obj *obj, struct vidconsole_bbox *bbox,
337			struct vidconsole_bbox *label_bbox);
338
339/**
340 * scene_textline_open() - Open a textline object
341 *
342 * Set up the text editor ready for use
343 *
344 * @scn: Scene containing the textline
345 * @tline: textline object
346 * Return: 0 if OK, -ve on error
347 */
348int scene_textline_open(struct scene *scn, struct scene_obj_textline *tline);
349
350/**
351 * scene_textline_close() - Close a textline object
352 *
353 * Close out the text editor after use
354 *
355 * @scn: Scene containing the textline
356 * @tline: textline object
357 * Return: 0 if OK, -ve on error
358 */
359int scene_textline_close(struct scene *scn, struct scene_obj_textline *tline);
360
361#endif /* __SCENE_INTERNAL_H */
362