notcurses/doc/man/man3/notcurses_menu.3.md

64 lines
1.9 KiB
Markdown
Raw Normal View History

2020-02-01 20:46:18 +00:00
% notcurses_menu(3)
% nick black <nickblack@linux.com>
% v1.1.3
# NAME
notcurses_menu - operations on menus
# SYNOPSIS
**#include <notcurses.h>**
2020-02-01 21:09:44 +00:00
```c
2020-02-01 21:06:46 +00:00
struct ncmenu;
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;
};
typedef struct ncmenu_options {
2020-02-02 11:57:10 +00:00
bool bottom; // on the bottom row, as opposed to top row
bool hiding; // hide the menu when not being used
struct ncmenu_section* sections; // 'sectioncount' menu_sections
int sectioncount; // must be positive
2020-02-01 21:06:46 +00:00
uint64_t headerchannels; // styling for header
uint64_t sectionchannels; // styling for sections
} ncmenu_options;
2020-02-01 21:06:46 +00:00
```
**struct ncmenu* ncmenu_create(struct notcurses* nc, const menu_options* opts);**
**int ncmenu_unroll(struct ncmenu* n, int sectionidx);**
**int ncmenu_rollup(struct ncmenu* n);**
2020-02-04 05:08:03 +00:00
**int ncmenu_destroy(struct notcurses* nc, struct ncmenu* n);**
2020-02-01 20:46:18 +00:00
# DESCRIPTION
2020-02-02 11:57:10 +00:00
A notcurses instance supports up to two menu bars, with one on the top and/or
bottom rows of the true screen. They are logically above other ncplanes on the
z-axis. Attempting to create a menu where one already exists is an error.
A menu is composed of sections, which are in turn composed of items. Either no
sections are visible, and the menu is *rolled up*, or exactly one section is
*unrolled*. **ncmenu_rollup** places an ncmenu in the rolled up state.
**ncmenu_unroll** rolls up any unrolled section, and unrolls the specified one.
**ncmenu_destroy** removes a menu bar, and frees all associated resources.
2020-02-01 20:46:18 +00:00
# RETURN VALUES
2020-02-02 11:57:10 +00:00
**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.
2020-02-01 20:46:18 +00:00
# SEE ALSO
**notcurses(3)**, **notcurses_input(3)**