blob: ad520ab3aad9ccf9f47fa4925301feeb1d83e68f [file] [log] [blame]
Jason Hobbsb69bf522011-08-23 11:06:49 +00001/*
2 * Copyright 2010-2011 Calxeda, Inc.
3 *
Wolfgang Denk1a459662013-07-08 09:37:19 +02004 * SPDX-License-Identifier: GPL-2.0+
Jason Hobbsb69bf522011-08-23 11:06:49 +00005 */
6
7U-boot provides a set of interfaces for creating and using simple, text
8based menus. Menus are displayed as lists of labeled entries on the
9console, and an entry can be selected by entering its label.
10
11To use the menu code, enable CONFIG_MENU, and include "menu.h" where
12the interfaces should be available.
13
14Menus are composed of items. Each item has a key used to identify it in
15the menu, and an opaque pointer to data controlled by the consumer.
16
Heiko Schocher317d6c52012-01-16 21:13:35 +000017If you want to show a menu, instead starting the shell, define
18CONFIG_MENU_SHOW. You have to code the int menu_show(int bootdelay)
19function, which handle your menu. This function returns the remaining
20bootdelay.
21
Jason Hobbsb69bf522011-08-23 11:06:49 +000022Interfaces
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 */
32struct 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 */
Jason Hobbsb41bc5a2011-08-23 11:06:50 +000042struct menu *menu_create(char *title, int timeout, int prompt,
Pali Rohárfc9d64f2013-03-23 14:50:40 +000043 void (*item_data_print)(void *),
44 char *(*item_choice)(void *),
45 void *item_choice_data);
Jason Hobbsb69bf522011-08-23 11:06:49 +000046
47/*
48 * menu_item_add() - Adds or replaces a menu item
49 */
50int 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 */
55int menu_default_set(struct menu *m, char *item_key);
56
57/*
Anatolij Gustschin6a3439f2013-03-23 14:52:04 +000058 * menu_default_choice() - Set *choice to point to the default item's data
59 */
60int menu_default_choice(struct menu *m, void **choice);
61
62/*
Jason Hobbsb69bf522011-08-23 11:06:49 +000063 * menu_get_choice() - Returns the user's selected menu entry, or the
Jason Hobbsb41bc5a2011-08-23 11:06:50 +000064 * default if the menu is set to not prompt or the timeout expires.
Jason Hobbsb69bf522011-08-23 11:06:49 +000065 */
66int menu_get_choice(struct menu *m, void **choice);
67
68/*
69 * menu_destroy() - frees the memory used by a menu and its items.
70 */
71int menu_destroy(struct menu *m);
72
Heiko Schochere0611dd2012-01-16 21:13:20 +000073/*
74 * menu_display_statusline(struct menu *m);
75 * shows a statusline for every menu_display call.
76 */
77void menu_display_statusline(struct menu *m);
Jason Hobbsb69bf522011-08-23 11:06:49 +000078
79Example Code
80------------
81This example creates a menu that always prompts, and allows the user
82to pick from a list of tools. The item key and data are the same.
83
84#include "menu.h"
85
86char *tools[] = {
87 "Hammer",
88 "Screwdriver",
89 "Nail gun",
90 NULL
91};
92
93char *pick_a_tool(void)
94{
95 struct menu *m;
96 int i;
97 char *tool = NULL;
98
Jason Hobbsb41bc5a2011-08-23 11:06:50 +000099 m = menu_create("Tools", 0, 1, NULL);
Jason Hobbsb69bf522011-08-23 11:06:49 +0000100
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;
Wolfgang Denk6b62b9a2011-12-19 12:03:40 +0100106 }
Jason Hobbsb69bf522011-08-23 11:06:49 +0000107 }
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
117void 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}