1notcurses_menu(3)                                            notcurses_menu(3)
2
3
4

NAME

6       notcurses_menu - operations on menus
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              struct ncmenu;
12              struct ncplane;
13              struct notcurses;
14
15              struct ncmenu_section {
16                char* name;  // utf-8 c string
17                struct ncmenu_item {
18                  char* desc;  // utf-8 menu item, NULL for horizontal separator
19                  ncinput shortcut;  // shortcut, all should be distinct
20                }* items;
21                int itemcount;
22              };
23
24              #define NCMENU_OPTION_BOTTOM 0x0001 // bottom row (as opposed to top row)
25              #define NCMENU_OPTION_HIDING 0x0002 // hide the menu when not unrolled
26
27              typedef struct ncmenu_options {
28                struct ncmenu_section* sections; // 'sectioncount' menu_sections
29                int sectioncount;         // must be positive
30                uint64_t headerchannels;  // styling for header
31                uint64_t sectionchannels; // styling for sections
32                uint64_t flags;           // bitfield on NCMENU_OPTION_*
33              } ncmenu_options;
34
35       struct  ncmenu* ncmenu_create(struct notcurses* nc, const menu_options*
36       opts);
37
38       int ncmenu_unroll(struct ncmenu* n, int sectionidx);
39
40       int ncmenu_rollup(struct ncmenu* n);
41
42       int ncmenu_nextsection(struct ncmenu* n);
43
44       int ncmenu_prevsection(struct ncmenu* n);
45
46       int ncmenu_nextitem(struct ncmenu* n);
47
48       int ncmenu_previtem(struct ncmenu* n);
49
50       int ncmenu_item_set_status(struct ncmenu* n, const char* section, const
51       char* item, bool enabled);
52
53       const char* ncmenu_selected(const struct ncmenu* n, ncinput* ni);
54
55       const  char*  ncmenu_mouse_selected(const struct ncmenu* n, const ncin‐
56       put* click, ncinput* ni);
57
58       struct ncplane* ncmenu_plane(struct ncmenu* n);
59
60       bool ncmenu_offer_input(struct ncmenu* n, const ncinput* nc);
61
62       int ncmenu_destroy(struct ncmenu* n);
63

DESCRIPTION

65       A notcurses instance supports menu bars on the top or bottom row of the
66       true  screen.   A  menu is composed of sections, which are in turn com‐
67       posed of items.  Either no sections are visible, and the menu is rolled
68       up, or exactly one section is unrolled.  ncmenu_rollup places an ncmenu
69       in the rolled up state.  ncmenu_unroll rolls up any  unrolled  section,
70       and  unrolls the specified one.  ncmenu_destroy removes a menu bar, and
71       frees all associated resources.
72
73       ncmenu_selected return the selected item description,  or  NULL  if  no
74       section  is  unrolled,  or no valid item is selected.  ncmenu_mouse_se‐
75       lected returns the item selected by a mouse click (described in click),
76       which  must  be  on  the actively unrolled section.  In either case, if
77       there is a shortcut for the item and ni is not NULL, ni will be  filled
78       in with the shortcut.
79
80       The  menu  can be driven either entirely by the application, via direct
81       calls to ncmenu_previtem, ncmenu_prevsection, and the like, or  ncinput
82       objects  can  be handed to ncmenu_offer_input.  In the latter case, the
83       menu will largely manage itself.  The application must handle item  se‐
84       lection  (usually  via  the Enter key and/or mouse click) itself, since
85       the menu cannot arbitrarily  call  into  the  application.   ncmenu_of‐
86       fer_input will handle clicks to unroll menu sections, clicks to dismiss
87       the menu, Escape to dismiss the menu, left and  right  to  change  menu
88       sections,  and  up and down to change menu items (these latter are only
89       consumed if there is an actively unrolled section).
90

RETURN VALUES

92       ncmenu_create returns NULL on error, or a pointer to a  valid  new  nc‐
93       menu.   Other  functions  return non-zero on error, or zero on success.
94       Almost all errors are due to invalid parameters.
95
96       ncmenu_offer_input returns true if the menu "consumed" the input,  i.e.
97       found  it  relevant  and took an action.  Otherwise, false is returned,
98       and the ncinput should be considered irrelevant to the menu.
99

SEE ALSO

101       notcurses(3), notcurses_input(3), notcurses_plane(3)
102

AUTHORS

104       nick black <nickblack@linux.com>.
105
106
107
108                                    v2.2.3                   notcurses_menu(3)
Impressum