doc/README.menu

/*
 * Copyright 2010-2011 Calxeda, Inc.
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the Free
 * Software Foundation; either version 2 of the License, or (at your option)
 * any later version.
 *
 * This program is distributed in the hope it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
 * more details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program.  If not, see <http://www.gnu.org/licenses/>.
 */

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.

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

struct menu;

struct menu *menu_create(char *title, int timeout, int prompt,
				void (*item_data_print)(void *));
int menu_item_add(struct menu *m, char *item_key, void *item_data);
int menu_default_set(struct menu *m, char *item_key);
int menu_get_choice(struct menu *m, void **choice);
int menu_destroy(struct menu *m);

menu_create() - Creates a menu handle with default settings

  title - If not NULL, points to a string that will be displayed before
  the list of menu items. It will be copied to internal storage, and is
  safe to discard after passing to menu_create().

  timeout - A delay in seconds to wait for user input. If 0, timeout is
  disabled, and the default choice will be returned unless prompt is 1.

  prompt - If 0, don't ask for user input unless there is an interrupted
  timeout. If 1, the user will be prompted for input regardless of the
  value of timeout.

  item_data_print - If not NULL, will be called for each item when
  the menu is displayed, with the pointer to the item's data passed
  as the argument. If NULL, each item's key will be printed instead.
  Since an item's key is what must be entered to select an item, the
  item_data_print function should make it obvious what the key for each
  entry is.

  Returns a pointer to the menu if successful, or NULL if there is
  insufficient memory available to create the menu.


menu_item_add() - Adds or replaces a menu item

  m - Points to a menu created by menu_create().

  item_key - Points to a string that will uniquely identify the item.
  The string will be copied to internal storage, and is safe to discard
  after passing to menu_item_add.

  item_data - An opaque pointer associated with an item. It is never
  dereferenced internally, but will be passed to the item_data_print,
  and will be returned from menu_get_choice if the menu item is
  selected.

  Returns 1 if successful, -EINVAL if m is NULL, or -ENOMEM if there is
  insufficient memory to add the menu item.


menu_default_set() - Sets the default choice for the menu. This is safe
  to call more than once.

  m - Points to a menu created by menu_create().

  item_key - Points to a string that, when compared using strcmp,
  matches the key for an existing item in the menu.

  Returns 1 if successful, -EINVAL if m is NULL, or -ENOENT if no item
  with a key matching item_key is found.


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.
  This is safe to call more than once.

  m - Points to a menu created by menu_create().

  choice - Points to a location that will store a pointer to the
  selected menu item. If no item is selected or there is an error, no
  value will be written at the location it points to.

  Returns 1 if successful, -EINVAL if m or choice is NULL, -ENOENT if
  no default has been set and the menu is set to not prompt or the
  timeout expires, or -EINTR if the user exits the menu via ctrl+c.


menu_destroy() - frees the memory used by a menu and its items.

  m - Points to a menu created by menu_create().

  Returns 1 if successful, or -EINVAL if m is NULL.

Example
-------
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);
	}
}