LXR uboot/doc/README.menu

   1/*
   2 * Copyright 2010-2011 Calxeda, Inc.
   3 *
   4 * SPDX-License-Identifier:     GPL-2.0+
   5 */
   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
  17If 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
  22Interfaces
  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 */
  42struct 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 */
  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/*
  58 * 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/*
  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 */
  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
  73/*
  74 * menu_display_statusline(struct menu *m);
  75 * shows a statusline for every menu_display call.
  76 */
  77void menu_display_statusline(struct menu *m);
  78
  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
  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
 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}
 126