menu(3) | Library calls | menu(3)

# NAME

menu - curses extension for programming menus

# SYNOPSIS

#include <menu.h>

# DESCRIPTION

The menu library provides terminal-independent facilities for composing menu systems on character-cell terminals. The library includes: item routines, which create and modify menu items; and menu routines, which group items into menus, display menus on the screen, and handle interaction with the user.

The menu library uses the curses libraries, and a curses initialization routine such as initscr must be called before using any of these functions. To use the menu library, link with the options -lmenu -lcurses.

## Current Default Values for Item Attributes

The menu library maintains a default value for item attributes. You can get or set this default by calling the appropriate get_ or set_ routine with a NULL item pointer. Changing this default with a set_ function affects future item creations, but does not change the rendering of items already created.

## Routine Name Index

The following table lists each menu routine and the name of the manual page on which it is described.

curses Routine Name | Manual Page Name
current_item | mitem_current(3)
free_item | mitem_new(3)
free_menu | menu_new(3)
item_count | menu_items(3)
item_description | mitem_name(3)
item_index | mitem_current(3)
item_init | menu_hook(3)
item_name | mitem_name(3)
item_opts | mitem_opts(3)
item_opts_off | mitem_opts(3)
item_opts_on | mitem_opts(3)
item_term | menu_hook(3)
item_userptr | mitem_userptr(3)
item_value | mitem_value(3)
item_visible | mitem_visible(3)
menu_back | menu_attributes(3)
menu_driver | menu_driver(3)
menu_fore | menu_attributes(3)
menu_format | menu_format(3)
menu_grey | menu_attributes(3)
menu_init | menu_hook(3)
menu_items | menu_items(3)
menu_mark | menu_mark(3)
menu_opts | menu_opts(3)
menu_opts_off | menu_opts(3)
menu_opts_on | menu_opts(3)
menu_pad | menu_attributes(3)
menu_pattern | menu_pattern(3)
menu_request_by_name | menu_requestname(3)
menu_request_name | menu_requestname(3)
menu_spacing | menu_spacing(3)
menu_sub | menu_win(3)
menu_term | menu_hook(3)
menu_userptr | menu_userptr(3)
menu_win | menu_win(3)
new_item | mitem_new(3)
new_menu | menu_new(3)
pos_menu_cursor | menu_cursor(3)
post_menu | menu_post(3)
scale_menu | menu_win(3)
set_current_item | mitem_current(3)
set_item_init | menu_hook(3)
set_item_opts | mitem_opts(3)
set_item_term | menu_hook(3)
set_item_userptr | mitem_userptr(3)
set_item_value | mitem_value(3)
set_menu_back | menu_attributes(3)
set_menu_fore | menu_attributes(3)
set_menu_format | menu_format(3)
set_menu_grey | menu_attributes(3)
set_menu_init | menu_hook(3)
set_menu_items | menu_items(3)
set_menu_mark | menu_mark(3)
set_menu_opts | mitem_opts(3)
set_menu_pad | menu_attributes(3)
set_menu_pattern | menu_pattern(3)
set_menu_spacing | menu_spacing(3)
set_menu_sub | menu_win(3)
set_menu_term | menu_hook(3)
set_menu_userptr | menu_userptr(3)
set_menu_win | menu_win(3)
set_top_row | mitem_current(3)
top_row | mitem_current(3)
unpost_menu | menu_post(3)

# RETURN VALUE

Routines that return pointers return NULL on error. Routines that return an integer return one of the following error codes:

E_OK
  The routine succeeded.
E_BAD_ARGUMENT
  Routine detected an incorrect or out-of-range argument.
E_BAD_STATE
  Routine was called from an initialization or termination function.
E_NO_MATCH
  Character failed to match.
E_NO_ROOM
  Menu is too large for its window.
E_NOT_CONNECTED
  No items are connected to the menu.
E_NOT_POSTED
  The menu has not been posted.
E_NOT_SELECTABLE
  The designated item cannot be selected.
E_POSTED
  The menu is already posted.
E_REQUEST_DENIED
  The menu driver could not process the request.
E_SYSTEM_ERROR
  System error occurred (see errno(3)).
E_UNKNOWN_COMMAND
  The menu driver code saw an unknown request code.

# NOTES

The header file <menu.h> automatically includes the header files <curses.h> and <eti.h>.

In your library list, libmenu.a should be before libncurses.a; that is, you should say “-lmenu -lncurses”, not the other way around (which would give a link-error when using static libraries).

# PORTABILITY

These routines emulate the System V menu library. They were not supported on Version 7 or BSD versions.

The menu facility was documented in SVr4.2 in Character User Interface Programming (UNIX SVR4.2).

It is not part of X/Open Curses.

Aside from ncurses, there are few implementations:

- systems based on SVr4 source code, e.g., Solaris.
- NetBSD curses.

# AUTHORS

Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric S. Raymond.

# SEE ALSO

curses(3) and related pages whose names begin “menu_” for detailed descriptions of the entry points.

This describes ncurses version 6.4 (patch 20230826).

2023-08-19 | ncurses 6.4