1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3 * Copyright 2022 Google LLC
4 * Written by Simon Glass <sjg@chromium.org>
5 */
6
7 #ifndef __EXPO_H
8 #define __EXPO_H
9
10 #include <abuf.h>
11 #include <alist.h>
12 #include <dm/ofnode_decl.h>
13 #include <linux/bitops.h>
14 #include <linux/list.h>
15
16 struct udevice;
17
18 #include <cli.h>
19
20 /**
21 * enum expo_id_t - standard expo IDs
22 *
23 * These are assumed to be in use at all times. Expos should use IDs starting
24 * from EXPOID_BASE_ID,
25 *
26 * @EXPOID_NONE: Not used, invalid ID 0
27 * @EXPOID_SAVE: User has requested that the expo data be saved
28 * @EXPOID_DISCARD: User has requested that the expo data be discarded
29 * @EXPOID_BASE_ID: First ID which can be used for expo objects
30 */
31 enum expo_id_t {
32 EXPOID_NONE,
33
34 EXPOID_SAVE,
35 EXPOID_DISCARD,
36
37 EXPOID_BASE_ID = 5,
38 };
39
40 /**
41 * enum expoact_type - types of actions reported by the expo
42 *
43 * @EXPOACT_NONE: no action
44 * @EXPOACT_POINT_OBJ: object was highlighted (@id indicates which)
45 * @EXPOACT_POINT_ITEM: menu item was highlighted (@id indicates which)
46 * @EXPOACT_SELECT: menu item was selected (@id indicates which)
47 * @EXPOACT_OPEN: menu was opened, so an item can be selected (@id indicates
48 * which menu object)
49 * @EXPOACT_CLOSE: menu was closed (@id indicates which menu object)
50 * @EXPOACT_QUIT: request to exit the menu
51 */
52 enum expoact_type {
53 EXPOACT_NONE,
54 EXPOACT_POINT_OBJ,
55 EXPOACT_POINT_ITEM,
56 EXPOACT_SELECT,
57 EXPOACT_OPEN,
58 EXPOACT_CLOSE,
59 EXPOACT_QUIT,
60 };
61
62 /**
63 * struct expo_action - an action report by the expo
64 *
65 * @type: Action type (EXPOACT_NONE if there is no action)
66 * @select: Used for EXPOACT_POINT_ITEM and EXPOACT_SELECT
67 * @select.id: ID number of the object affected.
68 */
69 struct expo_action {
70 enum expoact_type type;
71 union {
72 struct {
73 int id;
74 } select;
75 };
76 };
77
78 /**
79 * struct expo_theme - theme for the expo
80 *
81 * @font_size: Default font size for all text
82 * @menu_inset: Inset width (on each side and top/bottom) for menu items
83 * @menuitem_gap_y: Gap between menu items in pixels
84 * @menu_title_margin_x: Gap between right side of menu title and left size of
85 * menu label
86 */
87 struct expo_theme {
88 u32 font_size;
89 u32 menu_inset;
90 u32 menuitem_gap_y;
91 u32 menu_title_margin_x;
92 };
93
94 /**
95 * struct expo - information about an expo
96 *
97 * A group of scenes which can be presented to the user, typically to obtain
98 * input or to make a selection.
99 *
100 * @name: Name of the expo (allocated)
101 * @display: Display to use (`UCLASS_VIDEO`), or NULL to use text mode
102 * @cons: Console to use (`UCLASS_VIDEO_CONSOLE`), or NULL to use text mode
103 * @scene_id: Current scene ID (0 if none)
104 * @next_id: Next ID number to use, for automatic allocation
105 * @action: Action selected by user. At present only one is supported, with the
106 * type set to EXPOACT_NONE if there is no action
107 * @text_mode: true to use text mode for the menu (no vidconsole)
108 * @popup: true to use popup menus, instead of showing all items
109 * @show_highlight: show a highlight bar on the selected menu item
110 * @priv: Private data for the controller
111 * @done: Indicates that a cedit session is complete and the user has quit
112 * @save: Indicates that cedit data should be saved, rather than discarded
113 * @theme: Information about fonts styles, etc.
114 * @scene_head: List of scenes
115 * @str_head: list of strings
116 * @cch: Keyboard context for input
117 */
118 struct expo {
119 char *name;
120 struct udevice *display;
121 struct udevice *cons;
122 uint scene_id;
123 uint next_id;
124 struct expo_action action;
125 bool text_mode;
126 bool popup;
127 bool show_highlight;
128 void *priv;
129 bool done;
130 bool save;
131 struct expo_theme theme;
132 struct list_head scene_head;
133 struct list_head str_head;
134 struct cli_ch_state cch;
135 };
136
137 /**
138 * struct expo_string - a string that can be used in an expo
139 *
140 * @id: ID number of the string
141 * @buf: String (contains nul terminator)
142 * @sibling: Node to link this object to its siblings
143 */
144 struct expo_string {
145 uint id;
146 struct abuf buf;
147 struct list_head sibling;
148 };
149
150 /**
151 * struct scene - information about a scene in an expo
152 *
153 * A collection of text/image/menu items in an expo
154 *
155 * @expo: Expo this scene is part of
156 * @name: Name of the scene (allocated)
157 * @id: ID number of the scene
158 * @title_id: String ID of title of the scene (allocated)
159 * @highlight_id: ID of highlighted object, if any
160 * @cls: cread state to use for input
161 * @buf: Buffer for input
162 * @entry_save: Buffer to hold vidconsole text-entry information
163 * @sibling: Node to link this scene to its siblings
164 * @obj_head: List of objects in the scene
165 */
166 struct scene {
167 struct expo *expo;
168 char *name;
169 uint id;
170 uint title_id;
171 uint highlight_id;
172 struct cli_line_state cls;
173 struct abuf buf;
174 struct abuf entry_save;
175 struct list_head sibling;
176 struct list_head obj_head;
177 };
178
179 /**
180 * enum scene_obj_t - type of a scene object
181 *
182 * @SCENEOBJT_NONE: Used to indicate that the type does not matter
183 * @SCENEOBJT_IMAGE: Image data to render
184 * @SCENEOBJT_BOX: Rectangular box
185 * @SCENEOBJT_TEXT: Text line to render
186 * @SCENEOBJT_MENU: Menu containing items the user can select
187 * @SCENEOBJT_TEXTLINE: Line of text the user can edit
188 * @SCENEOBJT_TEXTEDIT: Simple text editor
189 */
190 enum scene_obj_t {
191 SCENEOBJT_NONE = 0,
192 SCENEOBJT_IMAGE,
193 SCENEOBJT_TEXT,
194 SCENEOBJT_BOX,
195 SCENEOBJT_TEXTEDIT,
196
197 /* types from here on can be highlighted */
198 SCENEOBJT_MENU,
199 SCENEOBJT_TEXTLINE,
200 };
201
202 /**
203 * struct scene_obj_bbox - Dimensions of an object
204 *
205 * @x0: x position, in pixels from left side
206 * @y0: y position, in pixels from top
207 * @x1: x position of right size
208 * @y1: y position of bottom
209 */
210 struct scene_obj_bbox {
211 int x0;
212 int y0;
213 int x1;
214 int y1;
215 };
216
217 /**
218 * struct scene_obj_offset - Offsets for drawing the object
219 *
220 * Stores the offset from x0, x1 at which objects are drawn
221 *
222 * @xofs: x offset
223 * @yofs: y offset
224 */
225 struct scene_obj_offset {
226 int xofs;
227 int yofs;
228 };
229
230 /**
231 * struct scene_obj_dims - Dimensions of the object being drawn
232 *
233 * Image and text objects have a dimension which can change depending on what
234 * they contain. For images this stores the size. For text it stores the size as
235 * rendered on the display
236 *
237 * @x: x dimension
238 * @y: y dimension
239 */
240 struct scene_obj_dims {
241 int x;
242 int y;
243 };
244
245 /* special values for dimensions */
246 enum {
247 /* width/height of the display */
248 SCENEOB_DISPLAY_MAX = 0x7f000000,
249 };
250
251 /**
252 * enum scene_obj_halign - Horizontal alignment of objects
253 *
254 * Objects are normally drawn on the left size of their bounding box. This
255 * properly allows aligning on the right or having the object centred.
256 *
257 * @SCENEOA_LEFT: Left of object is aligned with its x coordinate
258 * @SCENEOA_RIGHT: Right of object is aligned with x + w
259 * @SCENEOA_CENTRE: Centre of object is aligned with centre of bounding box
260 * @SCENEOA_TOP: Left of object is aligned with its x coordinate
261 * @SCENEOA_BOTTOM: Right of object is aligned with x + w
262 *
263 * Note: It would be nice to make this a char type but Sphinx riddles:
264 * ./include/expo.h:258: error: Cannot parse enum!
265 * enum scene_obj_align : char {
266 */
267 enum scene_obj_align {
268 SCENEOA_LEFT,
269 SCENEOA_RIGHT,
270 SCENEOA_CENTRE,
271 SCENEOA_TOP = SCENEOA_LEFT,
272 SCENEOA_BOTTOM = SCENEOA_RIGHT,
273 };
274
275 /**
276 * enum scene_obj_flags_t - flags for objects
277 *
278 * @SCENEOF_HIDE: object should be hidden
279 * @SCENEOF_POINT: object should be highlighted
280 * @SCENEOF_OPEN: object should be opened (e.g. menu is opened so that an option
281 * can be selected)
282 * @SCENEOF_SIZE_VALID: object's size (width/height) is valid, so any adjustment
283 * to x0/y0 should maintain the width/height of the object
284 */
285 enum scene_obj_flags_t {
286 SCENEOF_HIDE = 1 << 0,
287 SCENEOF_POINT = 1 << 1,
288 SCENEOF_OPEN = 1 << 2,
289 SCENEOF_SIZE_VALID = BIT(3),
290 };
291
292 enum {
293 /* Maximum number of characters allowed in an line editor */
294 EXPO_MAX_CHARS = 250,
295 };
296
297 /**
298 * struct scene_obj - information about an object in a scene
299 *
300 * @scene: Scene that this object relates to
301 * @name: Name of the object (allocated)
302 * @id: ID number of the object
303 * @type: Type of this object
304 * @bbox: Bounding box for this object
305 * @ofs: Offset from x0, y0 where the object is drawn
306 * @dims: Dimensions of the text/image (may be smaller than bbox)
307 * @horiz: Horizonal alignment
308 * @vert: Vertical alignment
309 * @flags: Flags for this object
310 * @bit_length: Number of bits used for this object in CMOS RAM
311 * @start_bit: Start bit to use for this object in CMOS RAM
312 * @sibling: Node to link this object to its siblings
313 */
314 struct scene_obj {
315 struct scene *scene;
316 char *name;
317 uint id;
318 enum scene_obj_t type;
319 struct scene_obj_bbox bbox;
320 struct scene_obj_offset ofs;
321 struct scene_obj_dims dims;
322 enum scene_obj_align horiz;
323 enum scene_obj_align vert;
324 u8 flags;
325 u8 bit_length;
326 u16 start_bit;
327 struct list_head sibling;
328 };
329
330 /* object can be highlighted when moving around expo */
scene_obj_can_highlight(const struct scene_obj * obj)331 static inline bool scene_obj_can_highlight(const struct scene_obj *obj)
332 {
333 return obj->type >= SCENEOBJT_MENU;
334 }
335
336 /**
337 * struct scene_obj_img - information about an image object in a scene
338 *
339 * This is a rectangular image which is blitted onto the display
340 *
341 * @obj: Basic object information
342 * @data: Image data in BMP format
343 */
344 struct scene_obj_img {
345 struct scene_obj obj;
346 char *data;
347 };
348
349 /**
350 * struct scene_txt_generic - Generic information common to text objects
351 *
352 * @str_id: ID of the text string to display
353 * @font_name: Name of font (allocated by caller)
354 * @font_size: Nominal size of font in pixels
355 * @lines: alist of struct vidconsole_mline with a separate record for each
356 * line of text
357 */
358 struct scene_txt_generic {
359 uint str_id;
360 const char *font_name;
361 uint font_size;
362 struct alist lines;
363 };
364
365 /**
366 * struct scene_obj_txt - information about a text object in a scene
367 *
368 * This is a single-line text object
369 *
370 * @obj: Basic object information
371 * @gen: Generic information common to all objects which show text
372 */
373 struct scene_obj_txt {
374 struct scene_obj obj;
375 struct scene_txt_generic gen;
376 };
377
378 /**
379 * struct scene_obj_menu - information about a menu object in a scene
380 *
381 * A menu has a number of items which can be selected by the user
382 *
383 * It also has:
384 *
385 * - a text/image object (@pointer_id) which points to the current item
386 * (@cur_item_id)
387 *
388 * - a preview object which shows an image related to the current item
389 *
390 * @obj: Basic object information
391 * @title_id: ID of the title text, or 0 if none
392 * @cur_item_id: ID of the current menu item, or 0 if none
393 * @pointer_id: ID of the object pointing to the current selection
394 * @item_head: List of items in the menu
395 */
396 struct scene_obj_menu {
397 struct scene_obj obj;
398 uint title_id;
399 uint cur_item_id;
400 uint pointer_id;
401 struct list_head item_head;
402 };
403
404 /**
405 * enum scene_menuitem_flags_t - flags for menu items
406 *
407 * @SCENEMIF_GAP_BEFORE: Add a gap before this item
408 */
409 enum scene_menuitem_flags_t {
410 SCENEMIF_GAP_BEFORE = 1 << 0,
411 };
412
413 /**
414 * struct scene_menitem - a menu item in a menu
415 *
416 * A menu item has:
417 *
418 * - text object holding the name (short) and description (can be longer)
419 * - a text object holding the keypress
420 *
421 * @name: Name of the item (this is allocated by this call)
422 * @id: ID number of the object
423 * @key_id: ID of text object to use as the keypress to show
424 * @label_id: ID of text object to use as the label text
425 * @desc_id: ID of text object to use as the description text
426 * @preview_id: ID of the preview object, or 0 if none
427 * @flags: Flags for this item
428 * @value: Value for this item, or INT_MAX to use sequence
429 * @sibling: Node to link this item to its siblings
430 */
431 struct scene_menitem {
432 char *name;
433 uint id;
434 uint key_id;
435 uint label_id;
436 uint desc_id;
437 uint preview_id;
438 uint flags;
439 int value;
440 struct list_head sibling;
441 };
442
443 /**
444 * struct scene_obj_textline - information about a textline in a scene
445 *
446 * A textline has a prompt and a line of editable text
447 *
448 * @obj: Basic object information
449 * @label_id: ID of the label text, or 0 if none
450 * @edit_id: ID of the editable text
451 * @max_chars: Maximum number of characters allowed
452 * @buf: Text buffer containing current text
453 * @pos: Cursor position
454 */
455 struct scene_obj_textline {
456 struct scene_obj obj;
457 uint label_id;
458 uint edit_id;
459 uint max_chars;
460 struct abuf buf;
461 uint pos;
462 };
463
464 /**
465 * struct scene_obj_box - information about a box in a scene
466 *
467 * A box surrounds a part of the screen with a border
468 *
469 * @obj: Basic object information
470 * @width: Line-width in pixels
471 */
472 struct scene_obj_box {
473 struct scene_obj obj;
474 uint width;
475 };
476
477 /**
478 * struct scene_obj_txtedit - information about a box in a scene
479 *
480 * A text editor which allows users to edit a small text file
481 *
482 * @obj: Basic object information
483 * @gen: Generic information common to all objects which show text
484 * @buf: Text buffer containing current text
485 */
486 struct scene_obj_txtedit {
487 struct scene_obj obj;
488 struct scene_txt_generic gen;
489 struct abuf buf;
490 };
491
492 /**
493 * struct expo_arrange_info - Information used when arranging a scene
494 *
495 * @label_width: Maximum width of labels in scene
496 */
497 struct expo_arrange_info {
498 int label_width;
499 };
500
501 /**
502 * expo_new() - create a new expo
503 *
504 * Allocates a new expo
505 *
506 * @name: Name of expo (this is allocated by this call)
507 * @priv: Private data for the controller
508 * @expp: Returns a pointer to the new expo on success
509 * Returns: 0 if OK, -ENOMEM if out of memory
510 */
511 int expo_new(const char *name, void *priv, struct expo **expp);
512
513 /**
514 * expo_destroy() - Destroy an expo and free all its memory
515 *
516 * @exp: Expo to destroy
517 */
518 void expo_destroy(struct expo *exp);
519
520 /**
521 * expo_set_dynamic_start() - Set the start of the 'dynamic' IDs
522 *
523 * It is common for a set of 'static' IDs to be used to refer to objects in the
524 * expo. These typically use an enum so that they are defined in sequential
525 * order.
526 *
527 * Dynamic IDs (for objects not in the enum) are intended to be used for
528 * objects to which the code does not need to refer. These are ideally located
529 * above the static IDs.
530 *
531 * Use this function to set the start of the dynamic range, making sure that the
532 * value is higher than all the statically allocated IDs.
533 *
534 * @exp: Expo to update
535 * @dyn_start: Start ID that expo should use for dynamic allocation
536 */
537 void expo_set_dynamic_start(struct expo *exp, uint dyn_start);
538
539 /**
540 * expo_str() - add a new string to an expo
541 *
542 * @exp: Expo to update
543 * @name: Name to use (this is allocated by this call)
544 * @id: ID to use for the new object (0 to allocate one)
545 * @str: Pointer to text to display (allocated by caller)
546 * Returns: ID number for the object (typically @id), or -ve on error
547 */
548 int expo_str(struct expo *exp, const char *name, uint id, const char *str);
549
550 /**
551 * expo_get_str() - Get a string by ID
552 *
553 * @exp: Expo to use
554 * @id: String ID to look up
555 * @returns string, or NULL if not found
556 */
557 const char *expo_get_str(struct expo *exp, uint id);
558
559 /**
560 * expo_edit_str() - Make a string writeable
561 *
562 * This allows a string to be updated under the control of the caller. The
563 * buffer must remain valid while the expo is active.
564 *
565 * @exp: Expo to use
566 * @id: String ID to look up
567 * @orig: If non-NULL, returns the original buffer, which can be used by the
568 * caller. It is no-longer used by expo so must be uninited by the caller.
569 * It contains a snapshot of the string contents
570 * @copyp: Returns a pointer to the new, writeable buffer
571 * Return: 0 if OK, -ENOENT if the id was not found, -ENOMEM if out of memory
572 */
573 int expo_edit_str(struct expo *exp, uint id, struct abuf *orig,
574 struct abuf **copyp);
575
576 /**
577 * expo_set_display() - set the display to use for a expo
578 *
579 * @exp: Expo to update
580 * @dev: Display to use (`UCLASS_VIDEO`), NULL to use text mode
581 * Returns: 0 (always)
582 */
583 int expo_set_display(struct expo *exp, struct udevice *dev);
584
585 /**
586 * expo_calc_dims() - Calculate the dimensions of the objects
587 *
588 * Updates the width and height of all objects based on their contents
589 *
590 * @exp: Expo to update
591 * Returns 0 if OK, -ENOTSUPP if there is no graphical console
592 */
593 int expo_calc_dims(struct expo *exp);
594
595 /**
596 * expo_set_scene_id() - Set the current scene ID
597 *
598 * @exp: Expo to update
599 * @scene_id: New scene ID to use (0 to select no scene)
600 * Returns: 0 if OK, -ENOENT if there is no scene with that ID
601 */
602 int expo_set_scene_id(struct expo *exp, uint scene_id);
603
604 /**
605 * expo_first_scene_id() - Get the ID of the first scene
606 *
607 * @exp: Expo to check
608 * Returns: Scene ID of first scene, or -ENOENT if there are no scenes
609 */
610 int expo_first_scene_id(struct expo *exp);
611
612 /**
613 * expo_render() - render the expo on the display / console
614 *
615 * @exp: Expo to render
616 *
617 * Returns: 0 if OK, -ECHILD if there is no current scene, -ENOENT if the
618 * current scene is not found, other error if something else goes wrong
619 */
620 int expo_render(struct expo *exp);
621
622 /**
623 * expo_set_text_mode() - Controls whether the expo renders in text mode
624 *
625 * @exp: Expo to update
626 * @text_mode: true to use text mode, false to use the console
627 */
628 void expo_set_text_mode(struct expo *exp, bool text_mode);
629
630 /**
631 * scene_new() - create a new scene in a expo
632 *
633 * The scene is given the ID @id which must be unique across all scenes, objects
634 * and items. The expo's @next_id is updated to at least @id + 1
635 *
636 * @exp: Expo to update
637 * @name: Name to use (this is allocated by this call)
638 * @id: ID to use for the new scene (0 to allocate one)
639 * @scnp: Returns a pointer to the new scene on success
640 * Returns: ID number for the scene (typically @id), or -ve on error
641 */
642 int scene_new(struct expo *exp, const char *name, uint id, struct scene **scnp);
643
644 /**
645 * expo_lookup_scene_id() - Look up a scene by ID
646 *
647 * @exp: Expo to check
648 * @scene_id: Scene ID to look up
649 * @returns pointer to scene if found, else NULL
650 */
651 struct scene *expo_lookup_scene_id(struct expo *exp, uint scene_id);
652
653 /**
654 * scene_highlight_first() - Highlight the first item in a scene
655 *
656 * This highlights the first item, so that the user can see that it is pointed
657 * to
658 *
659 * @scn: Scene to update
660 */
661 void scene_highlight_first(struct scene *scn);
662
663 /**
664 * scene_set_highlight_id() - Set the object which is highlighted
665 *
666 * Sets a new object to highlight in the scene
667 *
668 * @scn: Scene to update
669 * @id: ID of object to highlight
670 */
671 void scene_set_highlight_id(struct scene *scn, uint id);
672
673 /**
674 * scene_set_open() - Set whether an item is open or not
675 *
676 * @scn: Scene to update
677 * @id: ID of object to update
678 * @open: true to open the object, false to close it
679 * Returns: 0 if OK, -ENOENT if @id is invalid
680 */
681 int scene_set_open(struct scene *scn, uint id, bool open);
682
683 /**
684 * scene_obj_count() - Count the number of objects in a scene
685 *
686 * @scn: Scene to check
687 * Returns: number of objects in the scene, 0 if none
688 */
689 int scene_obj_count(struct scene *scn);
690
691 /**
692 * scene_img() - add a new image to a scene
693 *
694 * @scn: Scene to update
695 * @name: Name to use (this is allocated by this call)
696 * @id: ID to use for the new object (0 to allocate one)
697 * @data: Pointer to image data
698 * @imgp: If non-NULL, returns the new object
699 * Returns: ID number for the object (typically @id), or -ve on error
700 */
701 int scene_img(struct scene *scn, const char *name, uint id, char *data,
702 struct scene_obj_img **imgp);
703
704 /**
705 * scene_txt() - add a new text object to a scene
706 *
707 * @scn: Scene to update
708 * @name: Name to use (this is allocated by this call)
709 * @id: ID to use for the new object (0 to allocate one)
710 * @str_id: ID of the string to use
711 * @txtp: If non-NULL, returns the new object
712 * Returns: ID number for the object (typically @id), or -ve on error
713 */
714 int scene_txt(struct scene *scn, const char *name, uint id, uint str_id,
715 struct scene_obj_txt **txtp);
716
717 /**
718 * scene_txt_str() - add a new string to expo and text object to a scene
719 *
720 * @scn: Scene to update
721 * @name: Name to use (this is allocated by this call)
722 * @id: ID to use for the new object (0 to allocate one)
723 * @str_id: ID of the string to use
724 * @str: Pointer to text to display (allocated by caller)
725 * @txtp: If non-NULL, returns the new object
726 * Returns: ID number for the object (typically @id), or -ve on error
727 */
728 int scene_txt_str(struct scene *scn, const char *name, uint id, uint str_id,
729 const char *str, struct scene_obj_txt **txtp);
730
731 /**
732 * scene_menu() - create a menu
733 *
734 * @scn: Scene to update
735 * @name: Name to use (this is allocated by this call)
736 * @id: ID to use for the new object (0 to allocate one)
737 * @menup: If non-NULL, returns the new object
738 * Returns: ID number for the object (typically @id), or -ve on error
739 */
740 int scene_menu(struct scene *scn, const char *name, uint id,
741 struct scene_obj_menu **menup);
742
743 /**
744 * scene_textline() - create a textline
745 *
746 * @scn: Scene to update
747 * @name: Name to use (this is allocated by this call)
748 * @id: ID to use for the new object (0 to allocate one)
749 * @max_chars: Maximum length of the textline in characters
750 * @tlinep: If non-NULL, returns the new object
751 * Returns: ID number for the object (typically @id), or -ve on error
752 */
753 int scene_textline(struct scene *scn, const char *name, uint id, uint max_chars,
754 struct scene_obj_textline **tlinep);
755
756 /**
757 * scene_box() - create a box
758 *
759 * @scn: Scene to update
760 * @name: Name to use (this is allocated by this call)
761 * @id: ID to use for the new object (0 to allocate one)
762 * @width: Line-width in pixels
763 * @boxp: If non-NULL, returns the new object
764 * Returns: ID number for the object (typically @id), or -ve on error
765 */
766 int scene_box(struct scene *scn, const char *name, uint id, uint width,
767 struct scene_obj_box **boxp);
768
769 /**
770 * scene_texted() - create a text editor
771 *
772 * @scn: Scene to update
773 * @name: Name to use (this is allocated by this call)
774 * @id: ID to use for the new object (0 to allocate one)
775 * @strid: ID of the string to edit
776 * @teditp: If non-NULL, returns the new object
777 * Returns: ID number for the object (typically @id), or -ve on error
778 */
779 int scene_texted(struct scene *scn, const char *name, uint id, uint strid,
780 struct scene_obj_txtedit **teditp);
781
782 /**
783 * scene_txt_set_font() - Set the font for an object
784 *
785 * @scn: Scene to update
786 * @id: ID of object to update
787 * @font_name: Font name to use (allocated by caller)
788 * @font_size: Font size to use (nominal height in pixels)
789 */
790 int scene_txt_set_font(struct scene *scn, uint id, const char *font_name,
791 uint font_size);
792
793 /**
794 * scene_txted_set_font() - Set the font for an object
795 *
796 * @scn: Scene to update
797 * @id: ID of object to update
798 * @font_name: Font name to use (allocated by caller)
799 * @font_size: Font size to use (nominal height in pixels)
800 */
801 int scene_txted_set_font(struct scene *scn, uint id, const char *font_name,
802 uint font_size);
803
804 /**
805 * scene_obj_set_pos() - Set the postion of an object
806 *
807 * @scn: Scene to update
808 * @id: ID of object to update
809 * @x: x position, in pixels from left side
810 * @y: y position, in pixels from top
811 * Returns: 0 if OK, -ENOENT if @id is invalid
812 */
813 int scene_obj_set_pos(struct scene *scn, uint id, int x, int y);
814
815 /**
816 * scene_obj_set_size() - Set the size of an object
817 *
818 * @scn: Scene to update
819 * @id: ID of object to update
820 * @w: width in pixels
821 * @h: height in pixels
822 * Returns: 0 if OK, -ENOENT if @id is invalid
823 */
824 int scene_obj_set_size(struct scene *scn, uint id, int w, int h);
825
826 /**
827 * scene_obj_set_width() - Set the width of an object
828 *
829 * @scn: Scene to update
830 * @id: ID of object to update
831 * @w: width in pixels
832 * Returns: 0 if OK, -ENOENT if @id is invalid
833 */
834 int scene_obj_set_width(struct scene *scn, uint id, int w);
835
836 /**
837 * scene_obj_set_bbox() - Set the bounding box of an object
838 *
839 * @scn: Scene to update
840 * @id: ID of object to update
841 * @x0: x position, in pixels from left side
842 * @y0: y position, in pixels from top
843 * @x1: ending x position (right side)
844 * @y1: ending y position (botton side)
845 * Returns: 0 if OK, -ENOENT if @id is invalid
846 */
847 int scene_obj_set_bbox(struct scene *scn, uint id, int x0, int y0, int x1,
848 int y1);
849
850 /**
851 * scene_obj_set_halign() - Set the horizontal alignment of an object
852 *
853 * @scn: Scene to update
854 * @id: ID of object to update
855 * @aln: Horizontal alignment to use
856 * Returns: 0 if OK, -ENOENT if @id is invalid
857 */
858 int scene_obj_set_halign(struct scene *scn, uint id, enum scene_obj_align aln);
859
860 /**
861 * scene_obj_set_valign() - Set the vertical alignment of an object
862 *
863 * @scn: Scene to update
864 * @id: ID of object to update
865 * @aln: Vertical alignment to use
866 * Returns: 0 if OK, -ENOENT if @id is invalid
867 */
868 int scene_obj_set_valign(struct scene *scn, uint id, enum scene_obj_align aln);
869
870 /**
871 * scene_obj_set_hide() - Set whether an object is hidden
872 *
873 * The update happens when the expo is next rendered.
874 *
875 * @scn: Scene to update
876 * @id: ID of object to update
877 * @hide: true to hide the object, false to show it
878 * Returns: 0 if OK, -ENOENT if @id is invalid
879 */
880 int scene_obj_set_hide(struct scene *scn, uint id, bool hide);
881
882 /**
883 * scene_menu_set_title() - Set the title of a menu
884 *
885 * @scn: Scene to update
886 * @id: ID of menu object to update
887 * @title_id: ID of text object to use as the title
888 * Returns: 0 if OK, -ENOENT if @id is invalid, -EINVAL if @title_id is invalid
889 */
890 int scene_menu_set_title(struct scene *scn, uint id, uint title_id);
891
892 /**
893 * scene_menu_set_pointer() - Set the item pointer for a menu
894 *
895 * This is a visual indicator of the current item, typically a ">" character
896 * which sits next to the current item and moves when the user presses the
897 * up/down arrow keys
898 *
899 * @scn: Scene to update
900 * @id: ID of menu object to update
901 * @cur_item_id: ID of text or image object to use as a pointer to the current
902 * item
903 * Returns: 0 if OK, -ENOENT if @id is invalid, -EINVAL if @cur_item_id is invalid
904 */
905 int scene_menu_set_pointer(struct scene *scn, uint id, uint cur_item_id);
906
907 /**
908 * scene_menu_select_item() - move the pointer/highlight to an item
909 *
910 * @scn: Scene to update
911 * @id: ID of menu object to update
912 * @sel_id: ID of the menuitem to select
913 * Return 0 on success, -ENOENT if there was no such item
914 */
915 int scene_menu_select_item(struct scene *scn, uint id, uint sel_id);
916
917 /**
918 * scene_menu_get_cur_item() - get the currently pointed-to item
919 *
920 * @scn: Scene to update
921 * @id: ID of menu object to update
922 * Return ID of the current item the menu is pointing to, -ENOENT if @id is not
923 * valid, 0 if no item is pointed to
924 */
925 int scene_menu_get_cur_item(struct scene *scn, uint id);
926
927 /**
928 * scene_obj_get_hw() - Get width and height of an object in a scene
929 *
930 * @scn: Scene to check
931 * @id: ID of menu object to check
932 * @widthp: If non-NULL, returns width of object in pixels
933 * Returns: Height of object in pixels
934 */
935 int scene_obj_get_hw(struct scene *scn, uint id, int *widthp);
936
937 /**
938 * scene_menuitem() - Add an item to a menu
939 *
940 * @scn: Scene to update
941 * @menu_id: ID of menu object to update
942 * @name: Name to use (this is allocated by this call)
943 * @id: ID to use for the new object (0 to allocate one)
944 * @key_id: ID of text object to use as the keypress to show
945 * @label_id: ID of text object to use as the label text
946 * @desc_id: ID of text object to use as the description text
947 * @preview_id: ID of object to use as the preview (text or image)
948 * @flags: Flags for this item (enum scene_menuitem_flags_t)
949 * @itemp: If non-NULL, returns the new object
950 * Returns: ID number for the item (typically @id), or -ve on error
951 */
952 int scene_menuitem(struct scene *scn, uint menu_id, const char *name, uint id,
953 uint key_id, uint label_id, uint desc_id, uint preview_id,
954 uint flags, struct scene_menitem **itemp);
955
956 /**
957 * scene_arrange() - Arrange the scene to deal with object sizes
958 *
959 * Updates any menus in the scene so that their objects are in the right place.
960 *
961 * @scn: Scene to arrange
962 * Returns: 0 if OK, -ve on error
963 */
964 int scene_arrange(struct scene *scn);
965
966 /**
967 * expo_send_key() - set a keypress to the expo
968 *
969 * @exp: Expo to receive the key
970 * @key: Key to send (ASCII or enum bootmenu_key)
971 * Returns: 0 if OK, -ECHILD if there is no current scene
972 */
973 int expo_send_key(struct expo *exp, int key);
974
975 /**
976 * expo_action_get() - read user input from the expo
977 *
978 * @exp: Expo to check
979 * @act: Returns action
980 * Returns: 0 if OK, -EAGAIN if there was no action to return
981 */
982 int expo_action_get(struct expo *exp, struct expo_action *act);
983
984 /**
985 * expo_apply_theme() - Apply a theme to an expo
986 *
987 * @exp: Expo to update
988 * @node: Node containing the theme
989 */
990 int expo_apply_theme(struct expo *exp, ofnode node);
991
992 /**
993 * expo_build() - Build an expo from an FDT description
994 *
995 * Build a complete expo from a description in the provided devicetree.
996 *
997 * See doc/develop/expo.rst for a description of the format
998 *
999 * @root: Root node for expo description
1000 * @expp: Returns the new expo
1001 * Returns: 0 if OK, -ENOMEM if out of memory, -EINVAL if there is a format
1002 * error, -ENOENT if there is a references to a non-existent string
1003 */
1004 int expo_build(ofnode root, struct expo **expp);
1005
1006 /**
1007 * cb_expo_build() - Build an expo for coreboot CMOS RAM
1008 *
1009 * @expp: Returns the expo created
1010 * Return: 0 if OK, -ve on error
1011 */
1012 int cb_expo_build(struct expo **expp);
1013
1014 /**
1015 * expo_poll() - see if the user takes an action
1016 *
1017 * This checks for a keypress. If there is one, it is processed and the
1018 * resulting action returned, if any.
1019 *
1020 * Note that expo_render() should normally be called immediately before this
1021 * function so that the user can see the latest state.
1022 *
1023 * @exp: Expo to poll
1024 * @act: Returns action on success
1025 * Return: 0 if an action was obtained, -EAGAIN if not, other error if something
1026 * went wrong
1027 */
1028 int expo_poll(struct expo *exp, struct expo_action *act);
1029
1030 #endif /*__EXPO_H */
1031