notcurses_menu - operations on ncmenu objects

       nick black <nickblack@linux.com>.

                                                     v3.0.7                                    notcurses_menu(3)

       A  notcurses instance supports menu bars on the top or bottom row of a plane.  A menu is composed of sec‐
       tions, which are in turn composed of items.  Either no sections are visible, and the menu is  rolledup,
       or  exactly  one section is unrolled.  ncmenu_rollup places an ncmenu in the rolled up state.  ncmenu_un‐roll rolls up any unrolled section, and unrolls the specified one.  ncmenu_destroy removes  a  menu  bar,
       and frees all associated resources.

       ncmenu_selected return the selected item description, or NULL if no section is unrolled, or no valid item
       is  selected.   ncmenu_mouse_selected  returns  the  item selected by a mouse click (described in click),
       which must be on the actively unrolled section.  In either case, if there is a shortcut for the item  and
       ni is not NULL, ni will be filled in with the shortcut.

       The  menu  can  be  driven  either  entirely by the application, via direct calls to ncmenu_previtem, nc‐menu_prevsection, and the like, or ncinput objects can be handed to ncmenu_offer_input.   In  the  latter
       case,  the  menu will largely manage itself.  The application must handle item selection (usually via the
       Enter key and/or mouse click) itself, since the menu cannot arbitrarily call into the  application.   nc‐menu_offer_input  will  handle clicks to unroll menu sections, clicks to dismiss the menu, Escape to dis‐
       miss the menu, left and right to change menu sections, and up and down to change menu items (these latter
       are only consumed if there is an actively unrolled section).

       Items can be disabled with ncmenu_item_set_status.  Pass false to disable the item, or true to enable it.
       All items are enabled by default.  A disabled item will not be returned with  ncmenu_mouse_selected,  nor
       reached with ncmenu_nextsection nor ncmenu_prevsection.

       notcurses_menu - operations on ncmenu objects

ncmenu_create returns NULL on error, or a pointer to a valid new ncmenu.  Other functions return non-zero
       on error, or zero on success.  Almost all errors are due to invalid parameters.

       ncmenu_offer_input returns true if the menu "consumed" the input, i.e.  found it relevant and took an ac‐
       tion.  Otherwise, false is returned, and the ncinput should be considered irrelevant to the menu.

notcurses(3), notcurses_input(3), notcurses_plane(3)

#include<notcurses/notcurses.h>

              struct ncmenu;
              struct ncplane;
              struct notcurses;

              struct ncmenu_section {
                const char* name;   // utf-8 c string
                struct ncmenu_item {
                  const char* desc; // utf-8 menu item, NULL for horizontal separator
                  ncinput shortcut; // shortcut, all should be distinct
                }* items;
                int itemcount;
              };

              #define NCMENU_OPTION_BOTTOM 0x0001 // bottom row (as opposed to top row)
              #define NCMENU_OPTION_HIDING 0x0002 // hide the menu when not unrolled

              typedef struct ncmenu_options {
                struct ncmenu_section* sections; // 'sectioncount' menu_sections
                int sectioncount;         // must be positive
                uint64_t headerchannels;  // styling for header
                uint64_t sectionchannels; // styling for sections
                uint64_t flags;           // bitfield on NCMENU_OPTION_*
              } ncmenu_options;

       structncmenu*ncmenu_create(structnotcurses*nc,constmenu_options*opts);intncmenu_unroll(structncmenu*n,intsectionidx);intncmenu_rollup(structncmenu*n);intncmenu_nextsection(structncmenu*n);intncmenu_prevsection(structncmenu*n);intncmenu_nextitem(structncmenu*n);intncmenu_previtem(structncmenu*n);intncmenu_item_set_status(structncmenu*n,constchar*section,constchar*item,boolenabled);constchar*ncmenu_selected(conststructncmenu*n,ncinput*ni);constchar*ncmenu_mouse_selected(conststructncmenu*n,constncinput*click,ncinput*ni);structncplane*ncmenu_plane(structncmenu*n);boolncmenu_offer_input(structncmenu*n,constncinput*nc);voidncmenu_destroy(structncmenu*n);