MENUS(3)                NetBSD 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 auto-
     matically 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 depar-
     tures 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 func-
                   tion.  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 consid-
                   ered 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 5.0_STABLE             September 10, 1999             NetBSD 5.0_STABLE
