Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


MENUS(3)                   Library Functions Manual                   MENUS(3)

NAME
     menus - menu library

LIBRARY
     Curses Menu Library (libmenu, -lmenu)

SYNOPSIS
     #include <menu.h>

DESCRIPTION
     The menus library provides a terminal independent menu system using the
     curses(3) library.  Before using the menus functions the terminal must be
     set up by curses(3) using the initscr() function or similar.  Programs
     using menus functions must be linked with the curses(3) library.

     The menus library provides facilities for defining menu items, placing a
     menu on the terminal screen, assign pre- and post-change operations and
     setting the attributes of both the menu and its items.

   Defining default attributes for menus and items
     The menus library allows any settable attribute or option of both the
     menu and item objects to be defined such that any new menu or item
     automatically inherits the value as default.  Setting the default value
     will not affect any item or menu that has already been created but will
     be applied to subsequent objects.  To set the default attribute or option
     the set routine is passed a NULL pointer in the item or menu parameter
     when calling the set routine.  The current default value can be retrieved
     by calling the get routine with a NULL pointer for the item or menu
     parameter.

     function name     manual page name
     current_item      menu_item_current(3)
     free_item         menu_item_new(3)
     free_menu         menu_new(3)
     item_count        menu_items(3)
     item_description  menu_item_name(3)
     item_index        menu_item_current(3)
     item_init         menu_hook(3)
     item_name         menu_item_name(3)
     item_opts         menu_item_opts(3)
     item_opts_off     menu_item_opts(3)
     item_opts_on      menu_item_opts(3)
     item_selected     menu_item_value(3)
     item_term         menu_hook(3)
     item_userptr      menu_item_userptr(3)
     item_value        menu_item_value(3)
     item_visible      menu_item_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_sub          menu_win(3)
     menu_term         menu_hook(3)
     menu_unmark       menu_mark(3)
     menu_userptr      menu_userptr(3)
     men_win           menu_win(3)
     new_item          menu_item_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  menu_item_current(3)
     set_item_init     menu_hook(3)
     set_item_opts     menu_item_opts(3)
     set_item_term     menu_hook(3)
     set_item_userptr  menu_item_userptr(3)
     set_item_value    menu_item_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     menu_opts(3)
     set_menu_pad      menu_attributes(3)
     set_menu_pattern  menu_pattern(3)
     set_menu_sub      menu_win(3)
     set_menu_term     menu_hook(3)
     set_menu_unmark   menu_mark(3)
     set_menu_userptr  menu_userptr(3)
     set_menu_win      menu_win(3)
     set_top_row       menu_item_current(3)
     top_row           menu_item_current(3)
     unpost_menu       menu_post(3)

RETURN VALUES
     Any function returning a string pointer will return NULL if an error
     occurs.  Functions returning an integer will return one of the following:

     E_OK               The function was successful.
     E_SYSTEM_ERROR     There was a system error during the call.
     E_BAD_ARGUMENT     One or more of the arguments passed to the function
                        was incorrect.
     E_POSTED           The menu is already posted.
     E_CONNECTED        An item was already connected to a menu.
     E_BAD_STATE        The function was called from within an initialization
                        or termination routine.
     E_NO_ROOM          The menu does not fit within the subwindow.
     E_NOT_POSTED       The menu is not posted.
     E_UNKNOWN_COMMAND  The menu driver does not recognize the request passed
                        to it.
     E_NO_MATCH         The character search failed to find a match.
     E_NOT_SELECTABLE   The item could not be selected.
     E_NOT_CONNECTED    The item is not connected to a menu.
     E_REQUEST_DENIED   The menu driver could not process the request.

SEE ALSO
     curses(3), menu_attributes(3), menu_cursor(3), menu_driver(3),
     menu_format(3), menu_hook(3), menu_item_current(3), menu_item_name(3),
     menu_item_new(3), menu_item_opts(3), menu_item_userptr(3),
     menu_item_value(3), menu_item_visible(3), menu_items(3), menu_mark(3),
     menu_new(3), menu_opts(3), menu_pattern(3), menu_post(3),
     menu_userptr(3), menu_win(3)

NOTES
     This implementation of the menus library does depart in behaviour subtly
     from the original AT & T implementation.  Some of the more notable
     departures are:

     unmark        The original implementation did not have a marker for an
                   unmarked field the mark was only displayed next to a field
                   when it had been marked using the REQ_TOGGLE_ITEM.  In this
                   implementation a separate marker can be used to indicate an
                   unmarked item.  This can be set using set_menu_unmark
                   function.  There is no requirement for the mark and unmark
                   strings to be the same length.  Room will be left for the
                   longest of the two.  The unmark string is optional, if it
                   is not set then menus defaults to the old behaviour.
     item marking  In the original implementation the current item was
                   considered selected and hence had the mark string displayed
                   next to it.  This implementation does not do this because
                   the Author considers the effect too confusing.  Especially
                   in the case of a multiple selection menu because there was
                   no way to tell if the current item is selected or not
                   without shifting off of it.  Since the current item is
                   displayed using the foreground attribute it was deemed
                   unnecessary to also display the mark string against the
                   current item.

     The option O_RADIO and the function item_selected() are NetBSD extensions
     and must not be used in portable code.

NetBSD 10.99                  September 10, 1999                  NetBSD 10.99