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