doc/README.menu

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