1.. SPDX-License-Identifier: GPL-2.0+
2.. Copyright 2010-2011 Calxeda, Inc.
3
4Menus
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_AUTOBOOT_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
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
82Example Code
83------------
84
85This example creates a menu that always prompts, and allows the user
86to 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    }
132