doc/README.menu

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