doc/README.menu

   1 SPDX-License-Identifier: GPL-2.0+
   2 /*
   3  * Copyright 2010-2011 Calxeda, Inc.
   4  */
   5
   6 U-Boot provides a set of interfaces for creating and using simple, text
   7 based menus. Menus are displayed as lists of labeled entries on the
   8 console, and an entry can be selected by entering its label.
   9
  10 To use the menu code, enable CONFIG_MENU, and include "menu.h" where
  11 the interfaces should be available.
  12
  13 Menus are composed of items. Each item has a key used to identify it in
  14 the menu, and an opaque pointer to data controlled by the consumer.
  15
  16 If you want to show a menu, instead starting the shell, define
  17 CONFIG_MENU_SHOW. You have to code the int menu_show(int bootdelay)
  18 function, which handle your menu. This function returns the remaining
  19 bootdelay.
  20
  21 Interfaces
  22 ----------
  23 #include "menu.h"
  24
  25 /*
  26  * Consumers of the menu interfaces will use a struct menu * as the
  27  * handle for a menu. struct menu is only fully defined in menu.c,
  28  * preventing consumers of the menu interfaces from accessing its
  29  * contents directly.
  30  */
  31 struct menu;
  32
  33 /*
  34  * NOTE: See comments in common/menu.c for more detailed documentation on
  35  * these interfaces.
  36  */
  37
  38 /*
  39  * menu_create() - Creates a menu handle with default settings
  40  */
  41 struct menu *menu_create(char *title, int timeout, int prompt,
  42                                 void (*item_data_print)(void *),
  43                                 char *(*item_choice)(void *),
  44                                 void *item_choice_data);
  45
  46 /*
  47  * menu_item_add() - Adds or replaces a menu item
  48  */
  49 int menu_item_add(struct menu *m, char *item_key, void *item_data);
  50
  51 /*
  52  * menu_default_set() - Sets the default choice for the menu
  53  */
  54 int menu_default_set(struct menu *m, char *item_key);
  55
  56 /*
  57  * menu_default_choice() - Set *choice to point to the default item's data
  58  */
  59 int menu_default_choice(struct menu *m, void **choice);
  60
  61 /*
  62  * menu_get_choice() - Returns the user's selected menu entry, or the
  63  * default if the menu is set to not prompt or the timeout expires.
  64  */
  65 int menu_get_choice(struct menu *m, void **choice);
  66
  67 /*
  68  * menu_destroy() - frees the memory used by a menu and its items.
  69  */
  70 int menu_destroy(struct menu *m);
  71
  72 /*
  73  * menu_display_statusline(struct menu *m);
  74  * shows a statusline for every menu_display call.
  75  */
  76 void menu_display_statusline(struct menu *m);
  77
  78 Example Code
  79 ------------
  80 This example creates a menu that always prompts, and allows the user
  81 to pick from a list of tools.  The item key and data are the same.
  82
  83 #include "menu.h"
  84
  85 char *tools[] = {
  86         "Hammer",
  87         "Screwdriver",
  88         "Nail gun",
  89         NULL
  90 };
  91
  92 char *pick_a_tool(void)
  93 {
  94         struct menu *m;
  95         int i;
  96         char *tool = NULL;
  97
  98         m = menu_create("Tools", 0, 1, NULL);
  99
 100         for(i = 0; tools[i]; i++) {
 101                 if (menu_item_add(m, tools[i], tools[i]) != 1) {
 102                         printf("failed to add item!");
 103                         menu_destroy(m);
 104                         return NULL;
 105                 }
 106         }
 107
 108         if (menu_get_choice(m, (void **)&tool) != 1)
 109                 printf("Problem picking tool!\n");
 110
 111         menu_destroy(m);
 112
 113         return tool;
 114 }
 115
 116 void caller(void)
 117 {
 118         char *tool = pick_a_tool();
 119
 120         if (tool) {
 121                 printf("picked a tool: %s\n", tool);
 122                 use_tool(tool);
 123         }
 124 }