doc/develop/menus.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2 .. Copyright 2010-2011 Calxeda, Inc.
   3
   4 Menus
   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_AUTOBOOT_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
  25 .. code-block:: c
  26
  27     #include "menu.h"
  28
  29     /*
  30      * Consumers of the menu interfaces will use a struct menu * as the
  31      * handle for a menu. struct menu is only fully defined in menu.c,
  32      * preventing consumers of the menu interfaces from accessing its
  33      * contents directly.
  34      */
  35     struct menu;
  36
  37     /*
  38      * NOTE: See comments in common/menu.c for more detailed documentation on
  39      * these interfaces.
  40      */
  41
  42     /*
  43      * menu_create() - Creates a menu handle with default settings
  44      */
  45     struct menu *menu_create(char *title, int timeout, int prompt,
  46                              void (*item_data_print)(void *),
  47                              char *(*item_choice)(void *),
  48                              void *item_choice_data);
  49
  50     /*
  51      * menu_item_add() - Adds or replaces a menu item
  52      */
  53     int menu_item_add(struct menu *m, char *item_key, void *item_data);
  54
  55     /*
  56      * menu_default_set() - Sets the default choice for the menu
  57      */
  58     int menu_default_set(struct menu *m, char *item_key);
  59
  60     /*
  61      * menu_default_choice() - Set *choice to point to the default item's data
  62      */
  63     int menu_default_choice(struct menu *m, void **choice);
  64
  65     /*
  66      * menu_get_choice() - Returns the user's selected menu entry, or the
  67      * default if the menu is set to not prompt or the timeout expires.
  68      */
  69     int menu_get_choice(struct menu *m, void **choice);
  70
  71     /*
  72      * menu_destroy() - frees the memory used by a menu and its items.
  73      */
  74     int menu_destroy(struct menu *m);
  75
  76     /*
  77      * menu_display_statusline(struct menu *m);
  78      * shows a statusline for every menu_display call.
  79      */
  80     void menu_display_statusline(struct menu *m);
  81
  82 Example Code
  83 ------------
  84
  85 This example creates a menu that always prompts, and allows the user
  86 to pick from a list of tools.  The item key and data are the same.
  87
  88 .. code-block:: c
  89
  90     #include "menu.h"
  91
  92     char *tools[] = {
  93         "Hammer",
  94         "Screwdriver",
  95         "Nail gun",
  96         NULL
  97     };
  98
  99     char *pick_a_tool(void)
 100     {
 101         struct menu *m;
 102         int i;
 103         char *tool = NULL;
 104
 105         m = menu_create("Tools", 0, 1, NULL);
 106
 107         for(i = 0; tools[i]; i++) {
 108             if (menu_item_add(m, tools[i], tools[i]) != 1) {
 109                 printf("failed to add item!");
 110                 menu_destroy(m);
 111                 return NULL;
 112             }
 113         }
 114
 115         if (menu_get_choice(m, (void **)&tool) != 1)
 116             printf("Problem picking tool!\n");
 117
 118         menu_destroy(m);
 119
 120         return tool;
 121     }
 122
 123     void caller(void)
 124     {
 125         char *tool = pick_a_tool();
 126
 127         if (tool) {
 128             printf("picked a tool: %s\n", tool);
 129             use_tool(tool);
 130         }
 131     }