Merge branch 'master' of http://git.denx.de/u-boot-sunxi
[platform/kernel/u-boot.git] / 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 }