[people/ms/u-boot.git] / doc / README.menu

/*
 * Copyright 2010-2011 Calxeda, Inc.
 *
 * SPDX-License-Identifier:	GPL-2.0+
 */

U-Boot provides a set of interfaces for creating and using simple, text
based menus. Menus are displayed as lists of labeled entries on the
console, and an entry can be selected by entering its label.

To use the menu code, enable CONFIG_MENU, and include "menu.h" where
the interfaces should be available.

Menus are composed of items. Each item has a key used to identify it in
the menu, and an opaque pointer to data controlled by the consumer.

If you want to show a menu, instead starting the shell, define
CONFIG_MENU_SHOW. You have to code the int menu_show(int bootdelay)
function, which handle your menu. This function returns the remaining
bootdelay.

Interfaces
----------
#include "menu.h"

/*
 * Consumers of the menu interfaces will use a struct menu * as the
 * handle for a menu. struct menu is only fully defined in menu.c,
 * preventing consumers of the menu interfaces from accessing its
 * contents directly.
 */
struct menu;

/*
 * NOTE: See comments in common/menu.c for more detailed documentation on
 * these interfaces.
 */

/*
 * menu_create() - Creates a menu handle with default settings
 */
struct menu *menu_create(char *title, int timeout, int prompt,
				void (*item_data_print)(void *),
				char *(*item_choice)(void *),
				void *item_choice_data);

/*
 * menu_item_add() - Adds or replaces a menu item
 */
int menu_item_add(struct menu *m, char *item_key, void *item_data);

/*
 * menu_default_set() - Sets the default choice for the menu
 */
int menu_default_set(struct menu *m, char *item_key);

/*
 * menu_default_choice() - Set *choice to point to the default item's data
 */
int menu_default_choice(struct menu *m, void **choice);

/*
 * menu_get_choice() - Returns the user's selected menu entry, or the
 * default if the menu is set to not prompt or the timeout expires.
 */
int menu_get_choice(struct menu *m, void **choice);

/*
 * menu_destroy() - frees the memory used by a menu and its items.
 */
int menu_destroy(struct menu *m);

/*
 * menu_display_statusline(struct menu *m);
 * shows a statusline for every menu_display call.
 */
void menu_display_statusline(struct menu *m);

Example Code
------------
This example creates a menu that always prompts, and allows the user
to pick from a list of tools.  The item key and data are the same.

#include "menu.h"

char *tools[] = {
	"Hammer",
	"Screwdriver",
	"Nail gun",
	NULL
};

char *pick_a_tool(void)
{
	struct menu *m;
	int i;
	char *tool = NULL;

	m = menu_create("Tools", 0, 1, NULL);

	for(i = 0; tools[i]; i++) {
		if (menu_item_add(m, tools[i], tools[i]) != 1) {
			printf("failed to add item!");
			menu_destroy(m);
			return NULL;
		}
	}

	if (menu_get_choice(m, (void **)&tool) != 1)
		printf("Problem picking tool!\n");

	menu_destroy(m);

	return tool;
}

void caller(void)
{
	char *tool = pick_a_tool();

	if (tool) {
		printf("picked a tool: %s\n", tool);
		use_tool(tool);
	}
}
Commit	Line	Data
b69bf52d JH	1	/*
	2	* Copyright 2010-2011 Calxeda, Inc.
	3	*
1a459660	4	* SPDX-License-Identifier: GPL-2.0+
b69bf52d JH	5	*/
b69bf52d JH	6
a187559e	7	U-Boot provides a set of interfaces for creating and using simple, text
b69bf52d JH	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
317d6c57 HS	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
b69bf52d JH	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	*/
b41bc5a8	42	struct menu menu_create(char title, int timeout, int prompt,
fc9d64ff PR	43	void (item_data_print)(void ),
	44	char (item_choice)(void *),
	45	void *item_choice_data);
b69bf52d JH	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
6a3439fd AG	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
b69bf52d JH	62	/*
b69bf52d JH	63	* menu_get_choice() - Returns the user's selected menu entry, or the
b41bc5a8	64	* default if the menu is set to not prompt or the timeout expires.
b69bf52d JH	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
e0611dd9 HS	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);
b69bf52d JH	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
b41bc5a8	99	m = menu_create("Tools", 0, 1, NULL);
b69bf52d JH	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;
6b62b9a3	106	}
b69bf52d JH	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	}