Home | History | Annotate | Download | only in doc 
      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 }
    125