1notcurses_menu(3) notcurses_menu(3)
2
6 notcurses_menu - operations on ncmenu objects
7
9 #include <notcurses/notcurses.h>
10 struct ncmenu;
12 struct ncplane;
13 struct notcurses;
14 struct ncmenu_section {
16 const char* name; // utf-8 c string
17 struct ncmenu_item {
18 const 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 #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 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 struct ncmenu* ncmenu_create(struct notcurses* nc, const menu_options*
36 opts);
37 int ncmenu_unroll(struct ncmenu* n, int sectionidx);
39 int ncmenu_rollup(struct ncmenu* n);
41 int ncmenu_nextsection(struct ncmenu* n);
43 int ncmenu_prevsection(struct ncmenu* n);
45 int ncmenu_nextitem(struct ncmenu* n);
47 int ncmenu_previtem(struct ncmenu* n);
49 int ncmenu_item_set_status(struct ncmenu* n, const char* section, const
51 char* item, bool enabled);
52 const char* ncmenu_selected(const struct ncmenu* n, ncinput* ni);
54 const char* ncmenu_mouse_selected(const struct ncmenu* n, const ncin‐
56 put* click, ncinput* ni);
57 struct ncplane* ncmenu_plane(struct ncmenu* n);
59 bool ncmenu_offer_input(struct ncmenu* n, const ncinput* nc);
61 void ncmenu_destroy(struct ncmenu* n);
63
65 A notcurses instance supports menu bars on the top or bottom row of a
66 plane. A menu is composed of sections, which are in turn composed of
67 items. Either no sections are visible, and the menu is rolled up, or
68 exactly one section is unrolled. ncmenu_rollup places an ncmenu in the
69 rolled up state. ncmenu_unroll rolls up any unrolled section, and un‐
70 rolls the specified one. ncmenu_destroy removes a menu bar, and frees
71 all associated resources.
72 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 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 Items can be disabled with ncmenu_item_set_status. Pass false to dis‐
92 able the item, or true to enable it. All items are enabled by default.
93 A disabled item will not be returned with ncmenu_mouse_selected, nor
94 reached with ncmenu_nextsection nor ncmenu_prevsection.
95
97 ncmenu_create returns NULL on error, or a pointer to a valid new nc‐
98 menu. Other functions return non-zero on error, or zero on success.
99 Almost all errors are due to invalid parameters.
100 ncmenu_offer_input returns true if the menu "consumed" the input, i.e.
102 found it relevant and took an action. Otherwise, false is returned,
103 and the ncinput should be considered irrelevant to the menu.
104
106 notcurses(3), notcurses_input(3), notcurses_plane(3)
107
109 nick black <nickblack@linux.com>.
110 v3.0.8 notcurses_menu(3)