include/expo.h

   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 __SCENE_H
   8 #define __SCENE_H
   9
  10 #include <linux/list.h>
  11
  12 struct udevice;
  13
  14 /**
  15  * enum expoact_type - types of actions reported by the expo
  16  *
  17  * @EXPOACT_NONE: no action
  18  * @EXPOACT_POINT: menu item was highlighted (@id indicates which)
  19  * @EXPOACT_SELECT: menu item was selected (@id indicates which)
  20  * @EXPOACT_QUIT: request to exit the menu
  21  */
  22 enum expoact_type {
  23         EXPOACT_NONE,
  24         EXPOACT_POINT,
  25         EXPOACT_SELECT,
  26         EXPOACT_QUIT,
  27 };
  28
  29 /**
  30  * struct expo_action - an action report by the expo
  31  *
  32  * @type: Action type (EXPOACT_NONE if there is no action)
  33  * @select: Used for EXPOACT_POINT and EXPOACT_SELECT
  34  * @id: ID number of the object affected.
  35  */
  36 struct expo_action {
  37         enum expoact_type type;
  38         union {
  39                 struct {
  40                         int id;
  41                 } select;
  42         };
  43 };
  44
  45 /**
  46  * struct expo - information about an expo
  47  *
  48  * A group of scenes which can be presented to the user, typically to obtain
  49  * input or to make a selection.
  50  *
  51  * @name: Name of the expo (allocated)
  52  * @display: Display to use (`UCLASS_VIDEO`), or NULL to use text mode
  53  * @scene_id: Current scene ID (0 if none)
  54  * @next_id: Next ID number to use, for automatic allocation
  55  * @action: Action selected by user. At present only one is supported, with the
  56  * type set to EXPOACT_NONE if there is no action
  57  * @text_mode: true to use text mode for the menu (no vidconsole)
  58  * @priv: Private data for the controller
  59  * @scene_head: List of scenes
  60  * @str_head: list of strings
  61  */
  62 struct expo {
  63         char *name;
  64         struct udevice *display;
  65         uint scene_id;
  66         uint next_id;
  67         struct expo_action action;
  68         bool text_mode;
  69         void *priv;
  70         struct list_head scene_head;
  71         struct list_head str_head;
  72 };
  73
  74 /**
  75  * struct expo_string - a string that can be used in an expo
  76  *
  77  * @id: ID number of the string
  78  * @str: String
  79  * @sibling: Node to link this object to its siblings
  80  */
  81 struct expo_string {
  82         uint id;
  83         const char *str;
  84         struct list_head sibling;
  85 };
  86
  87 /**
  88  * struct scene - information about a scene in an expo
  89  *
  90  * A collection of text/image/menu items in an expo
  91  *
  92  * @expo: Expo this scene is part of
  93  * @name: Name of the scene (allocated)
  94  * @id: ID number of the scene
  95  * @title: Title of the scene (allocated)
  96  * @sibling: Node to link this scene to its siblings
  97  * @obj_head: List of objects in the scene
  98  */
  99 struct scene {
 100         struct expo *expo;
 101         char *name;
 102         uint id;
 103         char *title;
 104         struct list_head sibling;
 105         struct list_head obj_head;
 106 };
 107
 108 /**
 109  * enum scene_obj_t - type of a scene object
 110  *
 111  * @SCENEOBJT_NONE: Used to indicate that the type does not matter
 112  * @SCENEOBJT_IMAGE: Image data to render
 113  * @SCENEOBJT_TEXT: Text line to render
 114  * @SCENEOBJT_MENU: Menu containing items the user can select
 115  */
 116 enum scene_obj_t {
 117         SCENEOBJT_NONE          = 0,
 118         SCENEOBJT_IMAGE,
 119         SCENEOBJT_TEXT,
 120         SCENEOBJT_MENU,
 121 };
 122
 123 /**
 124  * struct scene_obj - information about an object in a scene
 125  *
 126  * @scene: Scene that this object relates to
 127  * @name: Name of the object (allocated)
 128  * @id: ID number of the object
 129  * @type: Type of this object
 130  * @x: x position, in pixels from left side
 131  * @y: y position, in pixels from top
 132  * @hide: true if the object should be hidden
 133  * @sibling: Node to link this object to its siblings
 134  */
 135 struct scene_obj {
 136         struct scene *scene;
 137         char *name;
 138         uint id;
 139         enum scene_obj_t type;
 140         int x;
 141         int y;
 142         bool hide;
 143         struct list_head sibling;
 144 };
 145
 146 /**
 147  * struct scene_obj_img - information about an image object in a scene
 148  *
 149  * This is a rectangular image which is blitted onto the display
 150  *
 151  * @obj: Basic object information
 152  * @data: Image data in BMP format
 153  */
 154 struct scene_obj_img {
 155         struct scene_obj obj;
 156         char *data;
 157 };
 158
 159 /**
 160  * struct scene_obj_txt - information about a text object in a scene
 161  *
 162  * This is a single-line text object
 163  *
 164  * @obj: Basic object information
 165  * @str_id: ID of the text string to display
 166  * @font_name: Name of font (allocated by caller)
 167  * @font_size: Nominal size of font in pixels
 168  */
 169 struct scene_obj_txt {
 170         struct scene_obj obj;
 171         uint str_id;
 172         const char *font_name;
 173         uint font_size;
 174 };
 175
 176 /**
 177  * struct scene_obj_menu - information about a menu object in a scene
 178  *
 179  * A menu has a number of items which can be selected by the user
 180  *
 181  * It also has:
 182  *
 183  * - a text/image object (@pointer_id) which points to the current item
 184  *   (@cur_item_id)
 185  *
 186  * - a preview object which shows an image related to the current item
 187  *
 188  * @obj: Basic object information
 189  * @title_id: ID of the title text, or 0 if none
 190  * @cur_item_id: ID of the current menu item, or 0 if none
 191  * @pointer_id: ID of the object pointing to the current selection
 192  * @item_head: List of items in the menu
 193  */
 194 struct scene_obj_menu {
 195         struct scene_obj obj;
 196         uint title_id;
 197         uint cur_item_id;
 198         uint pointer_id;
 199         struct list_head item_head;
 200 };
 201
 202 /**
 203  * enum scene_menuitem_flags_t - flags for menu items
 204  *
 205  * @SCENEMIF_GAP_BEFORE: Add a gap before this item
 206  */
 207 enum scene_menuitem_flags_t {
 208         SCENEMIF_GAP_BEFORE     = 1 << 0,
 209 };
 210
 211 /**
 212  * struct scene_menitem - a menu item in a menu
 213  *
 214  * A menu item has:
 215  *
 216  * - text object holding the name (short) and description (can be longer)
 217  * - a text object holding the keypress
 218  *
 219  * @name: Name of the item (this is allocated by this call)
 220  * @id: ID number of the object
 221  * @key_id: ID of text object to use as the keypress to show
 222  * @label_id: ID of text object to use as the label text
 223  * @desc_id: ID of text object to use as the description text
 224  * @preview_id: ID of the preview object, or 0 if none
 225  * @flags: Flags for this item
 226  * @sibling: Node to link this item to its siblings
 227  */
 228 struct scene_menitem {
 229         char *name;
 230         uint id;
 231         uint key_id;
 232         uint label_id;
 233         uint desc_id;
 234         uint preview_id;
 235         uint flags;
 236         struct list_head sibling;
 237 };
 238
 239 /**
 240  * expo_new() - create a new expo
 241  *
 242  * Allocates a new expo
 243  *
 244  * @name: Name of expo (this is allocated by this call)
 245  * @priv: Private data for the controller
 246  * @expp: Returns a pointer to the new expo on success
 247  * Returns: 0 if OK, -ENOMEM if out of memory
 248  */
 249 int expo_new(const char *name, void *priv, struct expo **expp);
 250
 251 /**
 252  * expo_destroy() - Destroy an expo and free all its memory
 253  *
 254  * @exp: Expo to destroy
 255  */
 256 void expo_destroy(struct expo *exp);
 257
 258 /**
 259  * expo_str() - add a new string to an expo
 260  *
 261  * @exp: Expo to update
 262  * @name: Name to use (this is allocated by this call)
 263  * @id: ID to use for the new object (0 to allocate one)
 264  * @str: Pointer to text to display (allocated by caller)
 265  * Returns: ID number for the object (typically @id), or -ve on error
 266  */
 267 int expo_str(struct expo *exp, const char *name, uint id, const char *str);
 268
 269 /**
 270  * expo_get_str() - Get a string by ID
 271  *
 272  * @exp: Expo to use
 273  * @id: String ID to look up
 274  * @returns string, or NULL if not found
 275  */
 276 const char *expo_get_str(struct expo *exp, uint id);
 277
 278 /**
 279  * expo_set_display() - set the display to use for a expo
 280  *
 281  * @exp: Expo to update
 282  * @dev: Display to use (`UCLASS_VIDEO`), NULL to use text mode
 283  * Returns: 0 (always)
 284  */
 285 int expo_set_display(struct expo *exp, struct udevice *dev);
 286
 287 /**
 288  * expo_set_scene_id() - Set the current scene ID
 289  *
 290  * @exp: Expo to update
 291  * @scene_id: New scene ID to use (0 to select no scene)
 292  * Returns: 0 if OK, -ENOENT if there is no scene with that ID
 293  */
 294 int expo_set_scene_id(struct expo *exp, uint scene_id);
 295
 296 /**
 297  * expo_render() - render the expo on the display / console
 298  *
 299  * @exp: Expo to render
 300  *
 301  * Returns: 0 if OK, -ECHILD if there is no current scene, -ENOENT if the
 302  * current scene is not found, other error if something else goes wrong
 303  */
 304 int expo_render(struct expo *exp);
 305
 306 /**
 307  * exp_set_text_mode() - Controls whether the expo renders in text mode
 308  *
 309  * @exp: Expo to update
 310  * @text_mode: true to use text mode, false to use the console
 311  */
 312 void exp_set_text_mode(struct expo *exp, bool text_mode);
 313
 314 /**
 315  * scene_new() - create a new scene in a expo
 316  *
 317  * The scene is given the ID @id which must be unique across all scenes, objects
 318  * and items. The expo's @next_id is updated to at least @id + 1
 319  *
 320  * @exp: Expo to update
 321  * @name: Name to use (this is allocated by this call)
 322  * @id: ID to use for the new scene (0 to allocate one)
 323  * @scnp: Returns a pointer to the new scene on success
 324  * Returns: ID number for the scene (typically @id), or -ve on error
 325  */
 326 int scene_new(struct expo *exp, const char *name, uint id, struct scene **scnp);
 327
 328 /**
 329  * expo_lookup_scene_id() - Look up a scene by ID
 330  *
 331  * @exp: Expo to check
 332  * @scene_id: Scene ID to look up
 333  * @returns pointer to scene if found, else NULL
 334  */
 335 struct scene *expo_lookup_scene_id(struct expo *exp, uint scene_id);
 336
 337 /**
 338  * scene_title_set() - set the scene title
 339  *
 340  * @scn: Scene to update
 341  * @title: Title to set, NULL if none (this is allocated by this call)
 342  * Returns: 0 if OK, -ENOMEM if out of memory
 343  */
 344 int scene_title_set(struct scene *scn, const char *title);
 345
 346 /**
 347  * scene_obj_count() - Count the number of objects in a scene
 348  *
 349  * @scn: Scene to check
 350  * Returns: number of objects in the scene, 0 if none
 351  */
 352 int scene_obj_count(struct scene *scn);
 353
 354 /**
 355  * scene_img() - add a new image to a scene
 356  *
 357  * @scn: Scene to update
 358  * @name: Name to use (this is allocated by this call)
 359  * @id: ID to use for the new object (0 to allocate one)
 360  * @data: Pointer to image data
 361  * @imgp: If non-NULL, returns the new object
 362  * Returns: ID number for the object (typically @id), or -ve on error
 363  */
 364 int scene_img(struct scene *scn, const char *name, uint id, char *data,
 365               struct scene_obj_img **imgp);
 366
 367 /**
 368  * scene_txt() - add a new text object to a scene
 369  *
 370  * @scn: Scene to update
 371  * @name: Name to use (this is allocated by this call)
 372  * @id: ID to use for the new object (0 to allocate one)
 373  * @str_id: ID of the string to use
 374  * @txtp: If non-NULL, returns the new object
 375  * Returns: ID number for the object (typically @id), or -ve on error
 376  */
 377 int scene_txt(struct scene *scn, const char *name, uint id, uint str_id,
 378               struct scene_obj_txt **txtp);
 379
 380 /**
 381  * scene_txt_str() - add a new string to expr and text object to a scene
 382  *
 383  * @scn: Scene to update
 384  * @name: Name to use (this is allocated by this call)
 385  * @id: ID to use for the new object (0 to allocate one)
 386  * @str_id: ID of the string to use
 387  * @str: Pointer to text to display (allocated by caller)
 388  * @txtp: If non-NULL, returns the new object
 389  * Returns: ID number for the object (typically @id), or -ve on error
 390  */
 391 int scene_txt_str(struct scene *scn, const char *name, uint id, uint str_id,
 392                   const char *str, struct scene_obj_txt **txtp);
 393
 394 /**
 395  *  scene_menu() - create a menu
 396  *
 397  * @scn: Scene to update
 398  * @name: Name to use (this is allocated by this call)
 399  * @id: ID to use for the new object (0 to allocate one)
 400  * @menup: If non-NULL, returns the new object
 401  * Returns: ID number for the object (typically @id), or -ve on error
 402  */
 403 int scene_menu(struct scene *scn, const char *name, uint id,
 404                struct scene_obj_menu **menup);
 405
 406 /**
 407  * scene_txt_set_font() - Set the font for an object
 408  *
 409  * @scn: Scene to update
 410  * @id: ID of object to update
 411  * @font_name: Font name to use (allocated by caller)
 412  * @font_size: Font size to use (nominal height in pixels)
 413  */
 414 int scene_txt_set_font(struct scene *scn, uint id, const char *font_name,
 415                        uint font_size);
 416
 417 /**
 418  * scene_obj_set_pos() - Set the postion of an object
 419  *
 420  * @scn: Scene to update
 421  * @id: ID of object to update
 422  * @x: x position, in pixels from left side
 423  * @y: y position, in pixels from top
 424  * Returns: 0 if OK, -ENOENT if @id is invalid
 425  */
 426 int scene_obj_set_pos(struct scene *scn, uint id, int x, int y);
 427
 428 /**
 429  * scene_obj_set_hide() - Set whether an object is hidden
 430  *
 431  * The update happens when the expo is next rendered.
 432  *
 433  * @scn: Scene to update
 434  * @id: ID of object to update
 435  * @hide: true to hide the object, false to show it
 436  * Returns: 0 if OK, -ENOENT if @id is invalid
 437  */
 438 int scene_obj_set_hide(struct scene *scn, uint id, bool hide);
 439
 440 /**
 441  * scene_menu_set_title() - Set the title of a menu
 442  *
 443  * @scn: Scene to update
 444  * @id: ID of menu object to update
 445  * @title_id: ID of text object to use as the title
 446  * Returns: 0 if OK, -ENOENT if @id is invalid, -EINVAL if @title_id is invalid
 447  */
 448 int scene_menu_set_title(struct scene *scn, uint id, uint title_id);
 449
 450 /**
 451  * scene_menu_set_pointer() - Set the item pointer for a menu
 452  *
 453  * This is a visual indicator of the current item, typically a ">" character
 454  * which sits next to the current item and moves when the user presses the
 455  * up/down arrow keys
 456  *
 457  * @scn: Scene to update
 458  * @id: ID of menu object to update
 459  * @cur_item_id: ID of text or image object to use as a pointer to the current
 460  * item
 461  * Returns: 0 if OK, -ENOENT if @id is invalid, -EINVAL if @cur_item_id is invalid
 462  */
 463 int scene_menu_set_pointer(struct scene *scn, uint id, uint cur_item_id);
 464
 465 /**
 466  * scene_obj_get_hw() - Get width and height of an object in a scene
 467  *
 468  * @scn: Scene to check
 469  * @id: ID of menu object to check
 470  * @widthp: If non-NULL, returns width of object in pixels
 471  * Returns: Height of object in pixels
 472  */
 473 int scene_obj_get_hw(struct scene *scn, uint id, int *widthp);
 474
 475 /**
 476  * scene_menuitem() - Add an item to a menu
 477  *
 478  * @scn: Scene to update
 479  * @menu_id: ID of menu object to update
 480  * @name: Name to use (this is allocated by this call)
 481  * @id: ID to use for the new object (0 to allocate one)
 482  * @key_id: ID of text object to use as the keypress to show
 483  * @label_id: ID of text object to use as the label text
 484  * @desc_id: ID of text object to use as the description text
 485  * @preview_id: ID of object to use as the preview (text or image)
 486  * @flags: Flags for this item (enum scene_menuitem_flags_t)
 487  * @itemp: If non-NULL, returns the new object
 488  * Returns: ID number for the item (typically @id), or -ve on error
 489  */
 490 int scene_menuitem(struct scene *scn, uint menu_id, const char *name, uint id,
 491                    uint key_id, uint label_id, uint desc_id, uint preview_id,
 492                    uint flags, struct scene_menitem **itemp);
 493
 494 /**
 495  * scene_arrange() - Arrange the scene to deal with object sizes
 496  *
 497  * Updates any menus in the scene so that their objects are in the right place.
 498  *
 499  * @scn: Scene to arrange
 500  * Returns: 0 if OK, -ve on error
 501  */
 502 int scene_arrange(struct scene *scn);
 503
 504 /**
 505  * expo_send_key() - set a keypress to the expo
 506  *
 507  * @exp: Expo to receive the key
 508  * @key: Key to send (ASCII or enum bootmenu_key)
 509  * Returns: 0 if OK, -ECHILD if there is no current scene
 510  */
 511 int expo_send_key(struct expo *exp, int key);
 512
 513 /**
 514  * expo_action_get() - read user input from the expo
 515  *
 516  * @exp: Expo to check
 517  * @act: Returns action
 518  * Returns: 0 if OK, -EAGAIN if there was no action to return
 519  */
 520 int expo_action_get(struct expo *exp, struct expo_action *act);
 521
 522 #endif /*__SCENE_H */