menu(S) 6 January 1993 menu(S) Name menu - CRT menu routines Syntax cc . . . -lmenu -lcurses #include <menu.h> typedef void (*PTF_void)(); ITEM * current_item (m) MENU *m; int free_menu (m) MENU *m; int item_index (i) ITEM * i; PTF_void item_init (m) MENU *m; PTF_void item_term (m) MENU *m; int menu_back (m) MENU *m; int menu_driver (m, c) MENU *m; int c; int menu_fore (m) MENU *m; void menu_format (m, rp, cp) MENU *m; int *rp, *cp; int menu_grey (m) MENU *m; PTF_void menu_init (m) MENU *m; ITEM * menu_items (m) MENU * m; char *menu_mark (m) MENU *m; OPTIONS menu_opts (m) MENU *m; int menu_opts_off (m, o) MENU *m; OPTIONS o; int menu_opts_on (m, o) MENU *m; OPTIONS o; int menu_pad (m) MENU *m; char *menu_pattern (m) MENU *m; WINDOW *menu_sub (m) MENU *m; PTF_void menu_term (m) MENU *m; char *menu_userptr (m) MENU *m; WINDOW *menu_win (m) MENU *m; MENU *new_menu (ip) ITEM * ip; int pos_menu_cursor (m) MENU *m; int post_menu (m) MENU *m; int scale_menu (m, rp, cp) MENU *m; int *rp, *cp; int set_current_item (m, i) MENU *m; ITEM * item; int set_item_init (m, f) MENU *m; ITEM * item; PTF_void f; int set_item_term (m, f) MENU *m; PTF_void f; int set_menu_back (m, c) MENU *m; int c; int set_menu_fore (m, c) MENU *m; int c; int set_menu_format (m, c, r) MENU *m; int c, r; int set_menu_grey (m, c) MENU *m; int c; int set_menu_init (m, f) MENU *m; PTF_void f; int set_menu_items (m,i) MENU * m; ITEM * i; int set_menu_mark (m, n) MENU *m; char *n; int set_menu_opts (m, o) MENU *m; OPTIONS o; int set_menu_pad (m, c) MENU *m; int c; int set_menu_pattern (m, n) MENU *m; char *n; int set_menu_sub (m, w) MENU *m; WINDOW *w; int set_menu_term (m, f) MENU *m; PTF_void f; int set_menu_userptr (m, n) MENU *m; char *n; int set_menu_win (m, w) MENU *m; WINDOW *w; int set_top_row (m, c) MENU *m; int *c; int top_row (m) MENU *m; int unpost_menu (m) MENU *m; Description These routines allow you to create, display, and access menus. Menus can be displayed on any display device supported by the curses(S) library. Once you compile your program including the MENU header file menu.h, you should link it with the MENU and curses library routines. Functions The following is a list of MENU routines. newmenu (ip) creates a new menu connected to the given item pointer array and returns a pointer to the new menu. freemenu (m) disconnects the menu from its associated item pointer array and free the storage allocated for the menu. setmenuitems (m, i) changes the item pointer array connected to the given menu to item pointer array i. menuitems (m) returns a pointer to the item pointer array connected to menu m. setmenuformat (m, c, r) sets the maximum number of rows and columns of items that may be displayed at one time on a menu. menuformat (m, rp, cp) returns the maximum number of rows and columns that may be displayed at one time on a menu. rp and cp are pointers to the values used to return these numbers. The mark string distinguishes selected items in a multi-valued menu and the current item in a single-valued menu. setmenumark (m, n) sets the menu's mark string to n. menumark (m) returns a pointer to the menu's mark string. scalemenu (m, rp, cp) returns the minimum window size necessary for the given menu. rp and cp are pointers to the locations used to return the number of rows and columns for the menu. setmenuwin (m, w) sets window w as the window of menu m. menuwin (m) returns a pointer to the menu's window. setmenusub (m, w) sets window w as the subwindow of menu m. menusub (m) returns a pointer to the menu's subwindow. setmenufore (m, c) sets the menu's foreground attribute--the display attribute for the current item (if selectable) on single-valued menus and for selected items on multi-valued menus. This display attribute is a curses visual attribute. By default, this attribute is ASTANDOUT. menufore (m) returns the menu foreground attribute. setmenuback (m, c) sets the menu's background attribute--the display attribute for unselected, yet selectable, items. This display attribute is a curses visual attribute. By default, this attribute is ANORMAL. menuback (m) returns the menu background attribute. setmenugrey (m, c) sets the menu's grey attribute--the display attribute for nonselectable items in multi-valued menus. This display attribute is a curses visual attribute. By default, this attribute is AUNDERLINE. menugrey (m) returns the menu's grey attribute. The pad character is the character that fills the space between a menu item's name and description, if any. setmenupad (m, c) sets the pad character for menu m to c. menupad (m) returns the menu's pad character. postmenu (m) writes the menu in the menu's subwindow. unpostmenu (m) erases the menu from its associated subwindow. The workhorse of the menu subsystem, menudriver (m, c) checks if the character c is a menu request or data. If it is a request, the menu driver executes the request and reports the result. If it is data (a printable ASCII character), it enters the data into the current position in the current field. If the character is not recognized, the menu driver assumes it is an application-defined command and returns EUNKNOWNCOMMAND. The following set functions enable you to establish application routines to be executed automatically at initialization and termination points in your form application. You need not specify any application-defined ini- tialization or termination routines at all, but they may be helpful for displaying messages or page numbers and other chores. setiteminit (m, f) sets the application-defined function f to be called when the menu is posted and just after the current item changes. iteminit (m) returns a pointer to the item initialization routine, if any, called when the menu is posted and just after the current item changes. setitemterm (m, f) sets function f to be called when the menu is unposted and just before the current item changes. itemterm (m) returns a pointer to the termination function, if any, called when the menu is unposted and just before the current item changes. setmenuinit (m, f) sets the application-defined function f to be called when the menu is posted and just after the top row changes on a posted menu. menuinit (m) returns a pointer to the menu's initialization routine, if any, called when the menu is posted and just after the top row changes on a posted menu. setmenuterm (m, f) sets the application-defined function f to be called when the menu is unposted and just before the top row changes on a posted menu. menuterm (m) returns a pointer to the menu's termination routine, if any, called when the menu is unposted and just before the top row changes on a posted menu. The current item is the item where the cursor is currently positioned. setcurrentitem (m, i) sets the current menu item to the given item. currentitem (m) returns a pointer to the current item. itemindex (i) returns the index to the given item in the item pointer array. settoprow (m, c) sets the top of the menu to the named row. The left- most item on the new top row becomes the current item. toprow (m) returns the number of the menu row currently displayed at the top of the given menu. posmenucursor (m) moves the menu window's cursor to the correct posi- tion to resume menu processing. Every menu has a pattern buffer to match entered data with menu items. setmenupattern (m, p) sets the pattern buffer to the given pattern and tries to find the first item that matches the pattern. If it does, the matching item becomes the current item. If not, the current item does not change. menupattern (m) returns the string in the pattern buffer of the given menu. Every menu has an associated user pointer that you can use to store per- tinent information. setmenuuserptr (m, n) sets the menu's user pointer. menuuserptr (m) returns the menu's user pointer. setmenuopts (m, o) turns on the named options for the menu and turns off all its remaining options. Options are boolean values. Menu options are O_ONEVALUE, O_SHOWDESC, O_ROWMAJOR, O_IGNORECASE, and O_SHOWMATCH. menuopts (m) returns the menu's option setting. menuoptson (m, opts) turns on the named options for the menu. menuoptsoff (m, opts) turns off the named options for the menu. Diagnostics The following values are returned by one or more routines that return an integer. EBADSTATE routine called from an inappropriate routine EBADARGUMENT an incorrect argument was passed to the routine ECONNECTED one or more items are connected to another menu EOK routine returned normally ENOMATCH no match occurred ENOROOM menu does not fit within its subwindow ENOTCONNECTED no items are associated with the menu ENOTPOSTED menu has not yet been posted ENOTSELECTABLE item cannot be selected EPOSTED menu is already posted EREQUESTDENIED menu driver could not process the request ESYSTEMERROR system error EUNKNOWNCOMMAND unrecognizable request was given to the driver See also curses(S), field(S), fieldtype(S), form(S), item(S), panel(S), tam(S) Standards conformance menu is not part of any currently supported standard; it is an extension of AT&T System V provided by the Santa Cruz Operation.