.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_menu" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_menu - operations on menus
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
struct ncmenu;
struct ncplane;
struct ncinput;
struct notcurses;

struct ncmenu_section {
  char* name;  // utf-8 c string
  struct ncmenu_item {
    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; // \[aq]sectioncount\[aq] 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;
\f[R]
.fi
.PP
\f[B]struct ncmenu* ncmenu_create(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B], const menu_options*
\f[R]\f[I]opts\f[R]\f[B]);\f[R]
.PP
\f[B]int ncmenu_unroll(struct ncmenu* \f[R]\f[I]n\f[R]\f[B], int
\f[R]\f[I]sectionidx\f[R]\f[B]);\f[R]
.PP
\f[B]int ncmenu_rollup(struct ncmenu* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncmenu_nextsection(struct ncmenu* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncmenu_prevsection(struct ncmenu* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncmenu_nextitem(struct ncmenu* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncmenu_previtem(struct ncmenu* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncmenu_item_set_status(struct ncmenu* \f[R]\f[I]n\f[R]\f[B],
const char* \f[R]\f[I]section\f[R]\f[B], const char*
\f[R]\f[I]item\f[R]\f[B], bool \f[R]\f[I]enabled\f[R]\f[B]);\f[R]
.PP
\f[B]const char* ncmenu_selected(const struct ncmenu*
\f[R]\f[I]n\f[R]\f[B], struct ncinput* \f[R]\f[I]ni\f[R]\f[B]);\f[R]
.PP
\f[B]const char* ncmenu_mouse_selected(const struct ncmenu*
\f[R]\f[I]n\f[R]\f[B], const struct ncinput* \f[R]\f[I]click\f[R]\f[B],
struct ncinput* \f[R]\f[I]ni\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncmenu_plane(struct ncmenu*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncmenu_offer_input(struct ncmenu* \f[R]\f[I]n\f[R]\f[B], const
struct ncinput* \f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int ncmenu_destroy(struct ncmenu* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.SH DESCRIPTION
.PP
A notcurses instance supports menu bars on the top or bottom row of the
true screen.
A menu is composed of sections, which are in turn composed of items.
Either no sections are visible, and the menu is \f[I]rolled up\f[R], or
exactly one section is \f[I]unrolled\f[R].
\f[B]ncmenu_rollup\f[R] places an ncmenu in the rolled up state.
\f[B]ncmenu_unroll\f[R] rolls up any unrolled section, and unrolls the
specified one.
\f[B]ncmenu_destroy\f[R] removes a menu bar, and frees all associated
resources.
.PP
\f[B]ncmenu_selected\f[R] return the selected item description, or NULL
if no section is unrolled, or no valid item is selected.
\f[B]ncmenu_mouse_selected\f[R] returns the item selected by a mouse
click (described in \f[B]click\f[R]), which must be on the actively
unrolled section.
In either case, if there is a shortcut for the item and \f[B]ni\f[R] is
not \f[B]NULL\f[R], \f[B]ni\f[R] will be filled in with the shortcut.
.PP
The menu can be driven either entirely by the application, via direct
calls to \f[B]ncmenu_previtem\f[R], \f[B]ncmenu_prevsection\f[R], and
the like, or \f[B]struct ncinput\f[R] objects can be handed to
\f[B]ncmenu_offer_input\f[R].
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.
\f[B]ncmenu_offer_input\f[R] will handle clicks to unroll menu sections,
clicks to dismiss the menu, Escape to dismiss 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).
.SH RETURN VALUES
.PP
\f[B]ncmenu_create\f[R] returns \f[B]NULL\f[R] 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.
.PP
\f[B]ncmenu_offer_input\f[R] returns \f[B]true\f[R] if the menu
\[lq]consumed\[rq] the input, i.e.
found it relevant and took an action.
Otherwise, \f[B]false\f[R] is returned, and the \f[B]struct ncinput\f[R]
should be considered irrelevant to the menu.
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_input(3)\f[R],
\f[B]notcurses_plane(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.