Source Code 1992 March

home *** CD-ROM | disk | FTP | other *** search

/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 1 / 1144 < prev next >

Wrap

Internet Message Format | 1990-12-28 | 39.3 KB

From: pjc@pcbox.UUCP (Paul J. Condie) Newsgroups: alt.sources Subject: menu(1) part 2 of 11 Message-ID: <424@pcbox.UUCP> Date: 6 Apr 90 17:30:40 GMT #!/bin/sh # this is part 2 of a multipart archive # do not concatenate these parts, unpack them in order with /bin/sh # file menu.1 continued # CurArch=2 if test ! -r s2_seq_.tmp then echo "Please unpack part 1 first!" exit 1; fi ( read Scheck if test "$Scheck" != $CurArch then echo "Please unpack part $Scheck next!" exit 1; else exit 0; fi ) < s2_seq_.tmp || exit 1 echo "x - Continuing file menu.1" sed 's/^X//' << 'SHAR_EOF' >> menu.1 X Option description text. X.fi X.IP "" 6 XDefines this option as a sub-menu. When user selects this option Xthe menu defined in "menufile" will be parsed and displayed. X XThe [ GETINPUT ] option allows you to display a screen and prompt a user for Xinput. The screen is displayed before parseing of the new menu is begun. XThis could be used to prompt a user for a password with a .UNIX in the calling Xmenu using checkpass(1) to check permission to run the menu. XCompliments of Victoria. X XA environment variable may be specified in the Option description text. X.br X XThe optional variables are environment variables that will be set equal to Xthe value specified when the user selects this option. This can be used Xto pass data to a sub menu. Maximum length of the .MENU line is 700 bytes. X XNot supported in a \fI.POPMENU\fP menu. X. \ -------------------------------------------------------------------------- X X.PP X.nf X \fB.POPMENU\fP [ NoDim ] menufile [ row column ] [ [!]variable=value ... ] [ \\ ] X Option description text. X.fi X.IP "" 6 XDefines this option as a pop-up menu. When user selects this option Xthe script file "menufile" will be parsed and displayed. XThe optional row and column (upper left corner) is where you want the pop-up Xmenu to pop-up. If row and column is omitted then the menu will be placed Xas close to the option, that is selecting it, as possible. XSee \fI.SETENV\fP for \fIvariable=value\fP. X XThe [ NoDim ] flag tells menu not to dim the box on a inactive menu. The Xdefault is to dim inactive menus. That way the user can easily see what Xmenu they are working with. X XA environment variable may be specified in the Option description text. X XThe options in a pop-up menu can be selected by hi-lighting the option Xand pressing return, or ESC to cancel. The pop-up menu goes away after Xan option has been selected and you are put back in your calling menu X(the calling menu is reparsed). XThis keyword was provided for those options where the user would go over to Xa menu select an item then return back. A printer select menu would be ideal Xfor this keyword. X. \ -------------------------------------------------------------------------- X X.PP X.nf X \fB.SETENV\fP [ BELL ] [!]variable=value [ [!]variable=value ... ] [ message ] [ \\ ] X Option description text. X.fi X.IP "" 6 XWhen the user selects this option it will set Xa variable to a value in the the current environment (i.e. the menu Xenvironment). This is useful if you want something like a printer menu Xlisting available printers and changing the $LPDEST so all print jobs Xwill go to the new printer. XThe \fImessage\fP argument is what is printed to the screen so the user Xcan get feed back that his selection did something. XThe \fIBELL\fP argument provides an audible beep if the variables were Xset successfully. X Xnote: X.br X If the message has a "=" sign in it menu will think it is a X "variable=value" and will try to set a environment variable. X. \ -------------------------------------------------------------------------- X X.PP X.nf X \fB.SPACE\fP X.fi X.IP "" 6 XPut a space in between options. X XNot supported in a \fI.POPMENU\fP menu. X. \ -------------------------------------------------------------------------- X X.PP X.nf X \fB.SYSTEM\fP [ [ variable=value ... ] GETINPUT screen_name ] command [ \\ ] X Option description text. X.fi X.IP "" 6 XDefines this option as a system call. When user selects this option Xa system call will be executed, with command as the argument. Since the command Xis a argument to system(3S) anything you can type at the $ prompt you can Xput in the command. XMaximum length of \fIcommand\fP is 1k. XA environment variable may be specified in the Option description text. X XThe [ GETINPUT ] option allows you to display a screen and prompt a user for Xinput that could be used as command line arguments to the command. XThe screen_name is a defined screen name. XSee .GETINPUT and .DEFINE_SCREEN for more information. X.br XThe optional \fIvariable=value\fP arguments associated with the GETINPUT Xare set at runtime, when the user selects this option. This could be Xused to have a dynamic window_title in your getinput screen. X XExample: Say you need to prompt the user for a $DATA field then pass that Xfield into Xyour program, lock the program so that program cannot be run until this one Xfinishes Xand you want to kick the program off in the back ground. You Xcould try something like this (see lock(1),unlock(1)): X.nf X .SYSTEM GETINPUT screen1 \\ X lock program_name; \\ X if [ $? -eq 0 ] \\ X then (nohup program_name $DATA; nohup unlock program_name)& \\ X else echo "Program Already Running."; \\ X echo "Press [ Return ] to continue ...\\c"; \\ X read reply \\ X fi X Option Description Text. X X X XNote: No error checking is done for \fIcommand\fP. If error checking is Ximportant for your application you will need to build it into Xyour \fIcommand\fP. X.fi X. \ -------------------------------------------------------------------------- X X.PP X.nf X \fB.TEXT\fP [-]row [-]column X Text goes on this line. X.fi X.IP "" 6 XAllows you to put any text at a specified row and column on the \fIstdscr\fP Xscreen (base 0). XA negative row and/or column indicates number of rows from the bottom of the Xscreen or number of columns from the right of the screen (relative addressing). XFor example, \fI.TEXT -4 -20\fP will display text on the 4th row from the Xbottom and the 20th column from the right. This could be useful if your users Xare using different sized terminals/windows. If the row and/or column are Xgreater than the window size the text will get displayed on the last row or Xlast column of the screen. X XThis keyword could be used to Xplace a prompt text next to the cursor. The \fI.TEXT\fP is only active for Xthe current menu. If you want the same text to appear in every menu you Xwill need to put a \fI.TEXT\fP in every menu. XTerminal attributes may be placed in the text line (see Terminal Attributes). X XA environment variable may be specified within the text. X XThe last line of the screen is used to report error messages, like X\fIInvalid Option\fP. Your text will probably get erased if put on the last Xline. X. \ -------------------------------------------------------------------------- X X.PP X.nf X \fB.TITLE\fP X Title Line text. X.fi X.IP "" 6 XDisplay a title line top of menu. XTitle lines will start at row zero. XMultiple .TITLE lines may be defined up to MAXTITLE (6) defined in Xmenu.h file. X XThe title line consists of three sections defined as follows: X.br Xleft text...center text...right text X.br XText you place in the three sections will be either left justified, Xcentered, or right justified on the screen. The "\fB...\fP" are used to Xseparate the sections. X X.RS 6 X.PP XA substitutable variable may be specified within the title line text. XThe character $ is used to introduce substitutable Xparameters, in the form of ${\fIparameter\fP}. XThe value, if any, of the \fIparameter\fP is substituted. The braces are Xrequired only when \fIparameter\fP is followed by a letter, digit, or Xunderscore that is not to be interpreted as part of its name. See sh(1) Xfor more info. X.TP 6 X$DATE Xmay be placed anywhere in title text and the system date (mm/dd/yy) will Xbe displayed. X.TP 6 X$TIME Xmay be placed anywhere in title text and the system time (hh:mm zz) will Xbe displayed. X X.TP 6 X$MAIL XThe \fI$MAIL\fP is a special environment variable. This turns on the mail Xnotification facility. $MAIL may be placed anywhere in the title text and when Xthe user has mail to be read the word "\fBMAIL\fP" will be displayed in Xreverse video at that location in the title line, with an audible beep. XThe MAIL environment variable needs to be set to the users mail file, ex. X"MAIL=/usr/mail/pjc". The environment variable \fIMAILCHECK\fP is used to Xdetermine how often to check for mail. See mail(1). X.br XIf you have a hierarchy of menus for your application \fI$MAIL\fP only needs Xto be in the first menu. X XWarning: If menu is run with the set uid bit set, menu will be unable to Xdetermine if your mail is being forwarded, because it won't have read Xpermission on your mail file, and \fIMAIL\fP will be displayed all the time. X.TP XTerminal Attributes XAttributes may be specified anywhere in the title text as follows: X.nf X\\S = Standout X\\B = Bold X\\U = Underline X\\D = Dim X\\R = Reverse Video X\\L = Blink X\\N = Normal X Xexample: \\RThis text is reverse video.\\N Now normal. X Xnote: Terminal attributes are terminal dependent. XBerkeleys' version of curses only supports Standout. Attributes may Xalso be combined. X.fi X XFor \fI.POPMENU\fP there is no left,center,right sections. The title is Xcentered. You can have only one \fI.TITLE\fP in a pop-up menu. No attributes Xand/or environment variables are supported in the title for pop-up menus. X.RE X. \ -------------------------------------------------------------------------- X X.PP X \fB.UNIX\fP [ REDRAW ] [ GETINPUT screen_name ] command [ \\ ] X.IP "" 6 XA system(3) call with command as the argument is executed immediately Xwhen found while parsing the Xmenufile. Can be used to set function keys on terminal. Warning: if Xyou use this to set function keys and the function keys are changed in Xanother program, they do not get reset back to what they were in the menu. XMaximum length of command is 700 characters. X XThe [ GETINPUT ] option allows you to display a screen and prompt a user for Xinput, before the command is run. XThe window_pos argument to DEFINE_SCREEN must be specified in order to use Xthe screen here, because, menu is unable to automatically figure out where to Xput the screen because this is happing during the parsing stage. X XThe [ REDRAW ] flag instructs menu to redraw the screen after your command Xhas been executed. This is recommended if your command writes anything to Xthe screen. X XDiagnostics X.RS 10 XThe following actions are taken by menu depending on what exit code your Xcommand uses. X.TP 15 X0 XAOK. Continue to parse the next keyword. X.TP 15 X1 XQuit/Exit the menu program. X.TP 15 X4 XReturn to previous menu and display the error message X"Not Authorized to run menu.". X.TP 15 Xanything else XQuit parsing this menu and return to previous menu. No message. X.RE X X.RS 6 XExample: Authorize menu access. X.nf X .UNIX grep $LOGNAME access_table >/dev/null 2>/dev/null \\ X [ $? -ne 0 ] exit 4 \\ X exit 0 X.fi X XExample: Build a menu script file at run time. X.nf X ### Printer Selection Menu X ### Build a .POPMENU of available printers connected to a system. X X .UNIX echo ".TITLE" > printers.m; \\ X echo "Printer Menu" >> printers.m; \\ X echo ".TEXT 23 0" >> printers.m; \\ X echo "Select A Printer." >> printers.m; \\ X lpstat -p | awk '{ print $2 }' | \\ X for i in `cat` \\ X do \\ X echo ".SETENV LPDEST=$i Printer ($i) selected." >>printers.m; \\ X echo "$i" >> printers.m; \\ X done; \\ X exit 0 X X .POPMENU printers.m 10 50 X Select Default Printer. X.fi X.RE X. \ -------------------------------------------------------------------------- X X.PP X \fB.WINDOW\fP first_row last_row first_col last_col [ heading ] X.IP "" 6 XDefines a window area (rectangle) to display the options that follow this Xkeyword (up to the next \fI.WINDOW\fP or end of file). XThe options are centered between first_row / last_row Xand between first_col / last_col. XThe \fIrows\fR and \fIcolumns\fR are absolute (base 0) and inclusive. XIt is up to you Xto make sure they don't overlap (unless that's what you want), and Xthat it is large enough to hold the options that follow. XThe optional \fIheading\fR is text you wish centered over the window area X(rectangle). XIt is Xdisplayed on \fIfirst_row\fR minus one. XThe heading may contain terminal attributes as described under \fI.TITLE\fR. XYour \fI.WINDOW\fP keywords should be placed after all \fI.TITLE\fP(s). X.br XFor example suppose you want two columns of options on the screen, one Xof which will have a heading: X.nf X .WINDOW 0 23 0 39 X1. this option in left column X2. this option in left column X .WINDOW 10 23 40 79 \\R REPORTS \\N X3. this option in right column X X.fi XIf no .WINDOW is used a default of .WINDOW 0 screen_rows 0 screen_cols Xis used for all options. X XNot supported in a \fI.POPMENU\fP menu. X. \ -------------------------------------------------------------------------- X X.SH HELP SCREENS XThe default help file for menu(1) is \fImenu.hlp\fP. Additional help files Xmay be used in a GETINPUT screen. The following describes the the syntax of Xa help file. X X\fBtagname\fP X.br X[ .TITLE A Title May Be Placed Here. ] X.br XA tagname identifies a help screen and must be on a line by itself. X.br XThe text (with optional terminal attributes) to be displayed for this tagname Xis placed between the two tags. Don't use tabs to space the text X(it don't work), you have to put in hard spaces. XMore than one tagname may be placed in a help file. XAny text outside of a tagname is ignored. X.br X\fBtagname\fP X X XThe \fITABLE_OF_CONTENTS\fP tagname is a special tag describing what Xis to be contained in the table of contents for help. The following is the Xsyntax for this tagname. X.nf X\fBTABLE_OF_CONTENTS\fP Xhelpfile tagname description Xhelpfile tagname description X etc... X\fBTABLE_OF_CONTENTS\fP X.fi X X XBelow is shown the default help file for menu(1) (menu.hlp). XIt has four tagnames in it (TABLE_OF_CONTENTS, menu, popmenu, GETINPUT Xand help). This file may be customized to fit your needs. X X.nf X\fBTABLE_OF_CONTENTS\fP Xmenu.hlp menu Menus - Help using menus. Xmenu.hlp popmenu Pop-menus - Help using popmenus. Xmenu.hlp GETINPUT Input - Editing commands. Xmenu.hlp help Help - Using help. X\fBTABLE_OF_CONTENTS\fP X X X\fBmenu\fP X .TITLE Menu Help X X \\RMENU COMMANDS:\\N X M \\D- Go directly to main menu.\\N X P \\D- Return to previous menu.\\N X G or ^g \\D- Go directly to a specific menu.\\N X H or ? \\D- This help screen.\\N X ^r \\D- Redraw the screen.\\N X E \\D- Exit.\N X ! \\D- Enter a unix command.\\N X X \\RSELECTING OPTIONS:\\N X - Use "up arrow key", "^k", "down arrow key", "^j" or X "tab key" to place bar on option and press "return". X X or X X - Enter option number and press "return". X X\fBmenu\fP X X\fBpopmenu\fP X .TITLE Pop-Up Menu Help XSELECTING OPTIONS: X To select an option press the "up arrow key", X "k", "down arrow key", "j" to place bar on X option and press "return". X X KEY_CANCEL (esc) - Cancel selection. X\fBpopmenu\fP X X\fBGETINPUT\fP X .TITLE GETINPUT Help XMover Keys: X KEY_RETURN (^m) Traverse forwards through the fields. X . X . (etc. see GETINPUT) X . X KEY_PRINT (^p) Print screen to lp. X\fBGETINPUT\fP X X\fBhelp\fP X .TITLE Using Help XHelp displays consist of a description displayed in a window. XIf the description doesn't fit in the window, the Up Arrow and XDown Arrow keys can be used to view a few more lines of the Xdisplay. Exiting the help system will return the display to Xthe state it was in when you asked for help. X X The following keys are active in help: X KEY_CANCEL (esc) Exit help. X KEY_DOWN (^j) View a few more lines. X KEY_UP (^k) View the previous lines. X KEY_BEG (^b) Display first page. X KEY_END (^e) Display last page. X KEY_TOC (^t) Display help table of contents. X\fBhelp\fP X.fi X X.SH MENU INITIALIZATION FILE - (.menuinit) XA menu initialization file can be provided that Xcontains initialization commands Xto menu. This file is read when menu is first started. The \fI.menuinit\fP Xfile is first looked for in the current directory then in getenv("HOME") Xthen in getenv("MENUDIR"). This file is not needed if the default settings Xsuffice. X XBelow is listed a .menuinit Xfile with all the various initialization commands and their associated default Xvalue. The decimal value is what is returned from a curses getch() call. X\fITry menu -keys\fP. Setting a key value to minus one disables the key, Xalthough the associated curses key, if any, is still active. X XNote: Menu(1) does character matching (case insensitive) on the option Xdescription, Xin addition to entering the number Xof the option, to select a option. The character matching is done after it Xhas checked for any of the following keys. So, for example, if you use the Xdefault setting for KEY_EXITMENU (e) and you have a option titled "Enter ...". XThe user will not be able to press a "e" for character matching on "Enter ...". XThe exit menu process will be enabled. This should be considered in Xselecting your key values if full character matching is important. X X X.nf X KEY_EXITMENU = 101 # (e) Exit Menu Program. X KEY_MAINMENU = 109 # (m) Go to main menu. X KEY_PREVMENU = 112 # (p) Go to previous menu. X HOTKEYS # This causes the above menu keys to work without a carraige return. X X KEY_GNAME = 103 # (g) Go to a specific menu prompt. X KEY_POPGNAME = 7 # (^g) Display "\fIGoto Menu\fP", GNAME pop menu. X KEY_RETURN = 13 # (^m) Select hi-lighted menu option or traverse forwards through GETINPUT fields. X KEY_DOWN = 10 # (^j) Traverse forwards through menu options or GETINPUT fields. X Scroll help screen. X KEY_UP = 11 # (^k) Traverse backwards through menu options or GETINPUT fields. X Scroll help screen. X KEY_TAB = 9 # (^i) Fast forward through menu options or GETINPUT fields. X KEY_BTAB = -1 # Fast reverse through menu options or GETINPUT fields. X KEY_BEG = 2 # (^b) Place cursor at beginning of a GETINPUT field. X Display first page of help screen. X KEY_END = 5 # (^e) Place cursor at end of input in a GETINPUT field. X Display last page of help screen. X KEY_RIGHT = 12 # (^l) Forward space within the GETINPUT field. X KEY_LEFT = 8 # (^h) Backspace within the GETINPUT field (non-destructive). X KEY_BACKSPACE = 8 # (^h) Same as KEY_LEFT. X KEY_EOL = 4 # (^d) Delete from cursor to end of GETINPUT field. X KEY_DL = 3 # (^c) Clear GETINPUT field and home cursor. X KEY_DC = 24 # (^x) Delete a character in a GETINPUT field. X KEY_IC = 20 # (^t) Toggle between type-over and insert mode in GETINPUT. X KEY_HELP = 63 # (?) Display help screen. X KEY_TOC = 20 # (^t) When in help display table of contents for help. X KEY_REFRESH = 18 # (^r) Redraw the screen. X KEY_ACCEPT = 1 # (^a) Accept all input from a GETINPUT screen. X KEY_CANCEL = 27 # (esc) Cancel all input from a GETINPUT screen or cancel a pop-up menu selection. X Exit a help screen. X KEY_SAVE = 6 # (^f) Save a GETINPUT screen to a file. X KEY_PRINT = 16 # (^p) Print a GETINPUT screen to lp. X.fi X X.SH EXAMPLE menufile X.nf X\fB###\fR This is a example of a menu script file. X X\fB .AUTHORIZE\fR pjc nortons boink mozart X X\fB###\fR Initialize function keys for TERM=5425 X\fB .UNIX\fR echo "\\033[1;2;0;0q HELP h\\r\\c" X X\fB###\fR Define goto menu names. X\fB .GNAME\fR main main.m X\fB .GNAME\fR reports reports.m X X\fB###\fR Title Lines Section. X\fB .TITLE\fR X Version 3.00...\\RPACIFIC * BELL\\N...$DATE X\fB .TITLE\fR X $MAIL...Sample Menu...\\S$TIME\\N X\fB .TITLE\fR X ...MAIN MENU... X\fB .LINE\fR X X\fB###\fR Left column of screen - Options X\fB .WINDOW\fR 0 23 0 39 X\fB .SYSTEM\fR who XList who is on the system. X\fB .SYSTEM\fR ps -ef; \\ X echo "Press [ Return ] to continue.\\c"; read reply XPrint process status table. X X\fB###\fR Right column of screen - Options X\fB .WINDOW\fR 0 23 40 79 \\R SUB MENU \\N X\fB .MENU\fR reports.m XGo to report menu. X X\fB .TEXT\fP 22 50 XSelection [ ? for help ] X.fi X X.SH GENERALLY ACCEPTED GUIDELINES X.PD 0.1 X.IP -> 3 XPut a meaningful title on the top of every menu. X.IP -> 3 XProvide symmetric balance by centering the title and the menu options Xaround the center axis of the screen. X.IP -> 3 XChoose an organizing principle for the menu options. XOrganize menu hierarchies according to the tasks users will perform, rather Xthan the structure of the software modules. X.br XHints in organizing options: X.RS 6 X.IP * 3 XChronological ordering X.IP * 3 XAscending or descending numerical ordering X.IP * 3 XItems grouped by physical properties, (Increasing volume, weight or temperature) X.IP * 3 XAlphabetic sequence of terms X.IP * 3 XGrouping of related options with spatial demarcation between groups X.IP * 3 XMost frequently used options first X.IP * 3 XMost important options first X.RE X.IP -> 3 XTo facilitate scanning, put blank lines between logical groupings of menu Xoptions and after about every fifth option in a long list. X.IP -> 3 XLimit the number of menu choices of one screen. XThe breadth (number of options per menu) should be no more than eight and the Xdepth (number of levels of menus) should be no more than four. X.IP -> 3 XUse words for your menu options that clearly and specifically describe Xwhat the user is selecting; use simple, active verbs to describe menu options. XUse common, short English words that clearly describe the action that the Xcommand will carry out; choose words that are distinctive from one another. X.IP -> 3 XDisplay the menu options in mixed, upper and lower case letters. X.IP -> 3 XBe sure that any function keys that you use will operate correctly on all of Xthe different types of keyboards the users have. X.IP -> 3 XBe consistent in the use of menu formats, procedures, and wording; the Xmapping of keys to functions; the naming of menu options. X.IP -> 3 XOptions should suggest or entail closure. If a menu option calls another Xmenu (.MENU) the title of the option should be the title of the called menu Xto provide continuity. Likewise, if a menu option calls a program (reports, Xscreens) the title of the option should be the title of the report/screen. X.IP -> 3 XDisplay only information that the user needs to know. X.IP -> 3 XEvery menu should indicate how to exit from the screen. X.IP -> 3 XAvoid hyphenation of words between lines. X.IP -> 3 XUse abbreviation and acronyms only when they are significantly shorter than Xthe full text and when they will be understood by the user. X.IP -> 3 XOptions in a multiple column list should be organized in vertical columns Xwhich are read from left to right on the screen. X.IP -> 3 XPut a least two spaces between the longest item in a column and the beginning Xof the next column. X.IP -> 3 XUse highlighting to emphasize important information only. Do not overuse Xit. X.IP -> 3 XA \fI.POPMENU\fP, if possible, should appear as close to and to the right Xof the option that selected it. Probably a \fI.GETINPUT\fP screen should also. X.PD X X.SS References XHuman Factors Engineering, User Interface Guidelines, Pacific Bell, Sept (1987) X.PP XShore, John, The Sachertorte Algorithm and Other Antidotes to Computer XAnxiety, Viking Penguid Inc. (1985) X.IP * 3 XShore's book for the general public which translates into why designing Xgood user interfaces are necessary. X.PP XBeer, S. and Schoefer, W., Screen Development Guidelines - Draft, XVersion 1.0, Pacific Bell, April (1987) X.PP XRubinstein R., and Hersch H.M., with Ledgard, H.F., The Human Factor: XDesigning Computer Systems for People. Digital Press, Digital Equipment XCorporation, (1984). X.IP * 3 XRubinstein's work is very interesting and original. The text is readable Xand the ideas presented are clear and attractive. This is not a text book. X.PP XFuture Technology Architecture District, Proposed Pacific*Bell Screen XStandards For NonProgrammable Terminals, Pacific Bell, May (1988) X.PP XDumas Joseph S., Designing User Interface for Software, Prentice Hall, 1988 X X.SH CREDITS XPaul J. Condie 8/18/86 original author X.br X{att,bellcore,sun,ames,pyramid}!pacbell!pcbox!pjc X.br X XIrving Griesman GetInput(3X) X.br XSam S. Lok .POPMENU enhancements X X.SH NOTE XIf memory size is important modify LoadKeys.c and remove all references Xto keywords your application does not use then relink. This will reduce Xthe size of menu. X X.SH FILES Xmenu.hlp - menu help file X.br X/usr/local/lib/menus - some menus you might want to use or look at. X.br X/usr/local/lib/menus/sample.m - a sample menu file X.br X/usr/local/lib/menus/printers.m - printers pop-up menu X.br X/usr/local/lib/menus/reportsrn.m - report option input screen X XThe library of menus may vary from machine to machine. X X.SH SEE ALSO XMenuAccess(1), curses(3X), system(3), mail(1), getenv(3), Xlock(1), unlock(1), GetInput(3X), checkpass(1), runrealid(1). X X.SH WARNING XBecause menu uses the environment to pass and save data you are limited on the Xvolume of data you can have based upon the size of your environment. XThis will vary from machine to machine. If you see the Xmessage "Unable to allocate environment memory..." then you have reached Xyour limit. Actually you've surpassed the limit or you wouldn't have Xgotten the message. But lets not squabble. X XMenu has very little intellegence built in to check if you exceed the bounds Xof any fields. If menu core dumps, especially will a bus error, you are Xprobably trying to load too large a value into a field. X X.SH BUGS XCurses bug - When a attribute is the last character on the line (spaces don't Xcount) the attributes do not get turned off until it hits the next character Xon the next line. X X.PP XWhen you use the mail notification $MAIL the alarms get buffered up when Xthe cursor is just sitting there, so, as soon as the user types something Xat the keyboard all the alarms that were buffered take off, which means, you Xget a beep...beep...beep...beep. This doesn't happen on AT&T 3b machines Xbut I've noticed it on SUNS and ARETE machines. XYou should take the -DALARM off the CFLAGS in the makefile which tells Xmenu not to use the alarm(2) to check for mail, but check when a key Xhas been pressed. X X.PP XMenu has not really been tested on terminals/windows that is not 24x80, Xok,ok... it hasn't been tested at all. For the most part it should work Xfine, EXCEPT (you knew that was coming), when you want to create columns Xof options using the .WINDOW keyword. The parameters to .WINDOW are Xabsolute therefore when you line up your columns for a 24x80 terminal and Xyour menu is run on say a 34x132 terminal your columns will not be Xcentered right. Probably a new keyword should be introduced ".COLUMN" Xwhich would have some intelligence built in to try to center columns within Xthe window space. It might have some problems going from a larger window Xto a smaller window if the columns won't fit. X.br XAnyone volunteer to write this one? X X.PP XTerminal attributes sometimes don't work right. Especially when putting Xmultiple attributes on one line. In all cases I've seen it is a restriction Xof the terminal (hardware). X X.bp X.SH PROGRAMMING NOTES XThis section is for those of you who want to or need to add new keywords. X.PP XThe keywords that have been provided should accommodate most Xapplication menus, however, if customization is needed the following Xmay come in handy. If you introduce any neat new keywords (say like X".IF THEN ELSE") I would Xappreciate you sending them to me so I can incorporate them. Send your XParse, Show, and Run functions along with a copy of \fILoadKeys.c\fP. X.PP XMenu is primarily driven from the LoadKeys.c module. This Xmodule describes to menu what keywords it needs to scan for and what Xaction to take when found. XThere are four sections in LoadKeys (see LoadKeys example) each of which Xneed to be Xdefined if you are introducing a new keyword. LoadKkeys provides three areas Xof control (sections 2,3,4), and it is important that you know what you Xwant to accomplish at each control point: X.TP 4 XParse XWhat do you want menu to do with your keyword once it has found it during Xthe parsing routine? Any data you need to store for a later step, etc.. X.TP 4 XShow XHow do you want your keyword displayed to the screen? Define as NULL if Xnot appropriate. X.TP 4 XRun XIf the user selects an option that is your keyword, what do you want done? X X.PP XIf you want to put debugging code in your functions then the following Xformat should be used. X.nf Xextern int debug; Xif (debug) X{ X fprintf (stderr, "\\n[Function] <KeyWord> ...", ...); X} X.fi Xwhere [Function] is the function name and <KeyWord> is the keyword being Xprocessed. X X.SS ADDING A NEW KEYWORD X.TP 8 XStep 1: XDecide on the name of the new keyword. For consistency sake, I suggest, it Xshould begin with a "." and be all in caps. Maximum length of keyword is XMAXKEYLENGTH (15). Then formulate a syntax for the keyword (what the user Xneeds to type in the menufile). X.br XAlso, get clear in your mind what you want done at each of the three control Xpoints. X X.TP 8 XStep 2: Xvi LoadKeys.c X.br XStrcpy your keyword into the next available slot in KeyWord[], under SECTION 1. XMake sure MAXKEYS in menu.h is >= the slot you strcpy'ied your keyword into. XSee KeyWord[] below. X X.TP 8 XStep 3: XIn SECTION 2 of LoadKeys.c assign the Parse function that is going Xto parse your keyword. XIt should be assigned to the same slot as in SECTION 1. First see if one Xof the Parse functions already written will do the job. If so use that one, Xif not you will have to write one. For consistency call it Parse????.c or XPar????.c, and declare it at the beginning of LoadKeys.c. XAll keywords must have a parse function. XThis function is called immediately when your keyword is found while parsing Xthe menufile. XSee ParseKey[]() below. X.br XReturn Values: X.RS 8 X.TP 9 X0 XContinue to parse next keyword. X.TP 9 X-1 XQuit/Exit menu program. X.TP 9 X-2 XReturn to main menu. X.TP 9 X-4 XNOWAYJOSE - Not authorized to run this menu. X.TP Xanything else XAbort this menu and return to previous menu. X.RE X X.TP 8 XStep 4: XIn SECTION 3 of LoadKeys.c assign the Show function (if your keyword is a Xuser selectable option) that will display the Xoption to the screen. XIt should be assigned to the same slot as in SECTION 1. First see if one Xof the Show functions already written will do the job. If so use that one, Xif not you will have to write one. For consistency call it Show????.c, and Xdeclare it at the beginning of LoadKeys.c. XThis function is called when displaying options to the screen. XIf you don't need a Show function for your keyword assign slot to NULL. XSee ShowKey[]() below. X X.TP 8 XStep 5: XIn SECTION 4 of LoadKeys.c assign the Run function (if your keyword is a Xuser selectable option) that will be called when the user selects this option. XIt should be assigned to the same slot as in SECTION 1. First see if one Xof the Run functions already written will do the job. If so use that one, Xif not you will have to write one. For consistency call it Run????.c, and Xdeclare it at the beginning of LoadKeys.c. XIf you don't need a Run function for your keyword assign slot to NULL. X.br XReturn Values: X.RS 8 X.TP 9 X0 XAOK, continue with normal menu processing. X.TP 9 XMAINMENU XGoto main menu. This is as if the user had typed an "M". X.TP XPREVIOUSMENU XGoto previous menu. This is as if the user had typed a "P". X.TP XQUIT XQuit program. This is as if the user had typed an "E". X.TP XSUBMENU XIf you are introducing Xa new submenu keyword (like \fI.MENU\fP) the Run??? function must return X(SUBMENU), a #define. XRefer to \fIRunMenu.c\fP for an example. X.TP XGNAMEOFFSET + gindex XGoto a specific (.GNAME) menu. XWhere gindex = the index into the gnames array (base 0). XThis is as if the user had typed a goto menu. X.RE X X.TP 6 XStep 6: XCompile your new functions, LoadKeys.c and link into menu. XYour KeyWord should work. XThere should be no need to change any of the existing driver routines X(other than LoadKeys.c)? X X X.SS char KeyWord[] XThis array identifies all the keywords to be scanned for in your Xmenufile. Maximum number of keys is "MAXKEYS" defined in menu.h Xfile. Increasing MAXKEYS will allow more keys. X X.SS "int (*ParseKey[]) (keyword, menufile, menu, KeyWord, ParseKey, gnames, gfiles, gindex, opnumber)" X.nf Xchar keyword[]; XFILE *menufile; Xstruct MenuInfo *menu; Xchar KeyWord[][MAXKEYLENGTH]; Xint (*ParseKey[])(); Xchar gnames[][15], gfiles[][15]; Xint *gindex; Xint *opnumber; X.fi XArray of pointers to functions that will be called to parse the Xkeyword when found. Any processing you want done while program Xis parsing your keyword should be placed in this function. XIf you have defined a new keyword you must Xdescribe how that keyword is to be parsed. Unless you are doing Xsomething special ParseOption() should do the job. XYour new function will need to malloc struct OptionInfo if you Xwant to store some information for the option. The following describes Xthe data passed to all parsing functions. X.RS 6 X.TP 6 Xkeyword XThe keyword that was found in menufile. X.TP 6 X*menufile XA pointer to your menufile. When function returns you must leave Xthe pointer set to read in the next keyword. X.TP 6 X*menu XA struct holding information about the menufile. You need to maintain Xthe information for later processing. The Show and Run functions use the Xinformation you store here. See struct MenuInfo and struct OptionInfo. X.TP 6 Xgnames XThe goto menu names (.GNAME) presently defined (base 0). X.TP 6 Xgfiles XThe menufiles associated with the goto names (base 0) (.GNAME). X.TP 6 Xgindex XThe number of goto names (.GNAME) presently defined. X.TP 6 Xopnumber XThe last option number. This is the number that will appear to the left Xof the option, and the number the user will type in to select the option. XYou should increment this for the next option if your keyword will Xcontain a option number. XThe option number should be set to zero for options you don't want a Xnumber to appear to the left of the option. X.nf X.RE X X/* X** Menu structure layout X*/ Xstruct MenuInfo X{ X char name [15]; /* file name */ X int wfrow; /* window first row */ X int wlrow; /* window last row */ X int wfcol; /* window first col */ X int wlcol; /* window last col */ X int row_cursor; /* row for cursor */ X int col_cursor; /* col for cursor */ X unsigned boxtype; /* 0 = no box */ X unsigned linetype; /* same as box */ X int titlecount; X int optioncount; /* base 0 */ X struct OptionInfo *option [MAXOPTION]; X struct ScreenInfo *srn [MAXSCREENS+1]; /* .DEFINE_SCREEN */ X /* NULL = EOL */ X}; X X Xstruct OptionInfo X{ X char keyword [MAXKEYLENGTH+1]; X int opnumber; /* option number */ X char description [200]; X char command [MAXLEN]; X int row; /* row to display */ X int col; /* col to display */ X}; X Xstruct ScreenInfo X{ X char name [30]; /* screen name */ X char title [100]; /* window title */ X int toprow; /* upper left corner */ X int leftcol; X int rows; /* # rows in win */ X int cols; /* # cols in win */ X unsigned boxtype; /* 0 = no box */ X int exitlastfield; /* after last field */ X char helpfile[16]; X char *fielddefaults; /* init field command */ X struct FieldInfo *field [MAXFIELDS+1]; X}; X X Xstruct FieldInfo X{ X char name [30]; /* field name */ X char label [50]; /* field label */ X int row; /* start position */ X int col; X int length; X int min_input; X char mask [100]; X char range [1025]; X char type; X char adjust; X int mustenter; X char prompt [100]; X char terminator[3]; /* field terminators */ X int noinput; X}; X.fi X.RE X X.SS "int (*ShowKey[]) (menu, index)" X.nf Xstruct MenuInfo *menu; Xint index; X X.fi XThe following describes the data passed to all Show functions. XArray of pointers to functions that will be called to display Xthat option to the screen. Unless you are doing something special XShowOption() should do the job. X.RS 6 X.TP 6 X*menu XSee above for description of menu structure. X.br Xmenu.option[index]->description gets displayed to the screen. X.TP 6 Xindex XOption number in menu structure that is to be displayed. X X.SS "int (*RunKey[]) (menu, opnumber, KeyWord, ParseKey, ShowKey, RunKey, gnames, gfiles, gindex)" X.nf Xstruct MenuInfo *menu; Xint opnumber; Xint (*ParseKey[MAXKEYS])(); Xint (*ShowKey[MAXKEYS])(); Xint (*RunKey[MAXKEYS])(); Xchar KeyWord[MAXKEYS][MAXKEYLENGTH]; Xchar gnames[MAXGNAME][15]; Xchar gfiles[MAXGNAME][15]; Xint gindex; X.fi XThe following describes the data passed to all Run functions. XArray of pointers to functions that will be called when the Xuser selects the option on the screen. X.RS 6 X.TP 6 X*option XSee above for description of struct OptionInfo. X.br Xoption->command is what is to be executed for this option. X.RE X X.SS LoadKeys Example: X.nf XLoadKeys (KeyWord, ParseKey, ShowKey, RunKey) X X char KeyWord[][10]; X int (*ParseKey[])(), (*ShowKey[])(), (*RunKey[])(); X{ X int ParseTitle(), ParseOption(); X int ShowOption(); X int RunSystem(); X X /* X ** Section 1: X ** Identify the new keyword here. X */ X strcpy (KeyWord[1], ".TITLE"); X strcpy (KeyWord[2], ".MENU"); X strcpy (KeyWord[3], ".SYSTEM"); X X /* X ** Section 2: X ** Identify the parse function for the new keyword. X ** Every keyword needs a parse function. X */ X ParseKey[1] = ParseTitle; X ParseKey[2] = ParseOption; X ParseKey[3] = ParseOption; X X /* X ** Section 3: X ** Identify the show function for keywords that are options. X ** If ShowKey is set to NULL the option will not be displayed. X */ X ShowKey[1] = NULL; /* Title gets displayed in the parse function */ X ShowKey[2] = ShowOption; X ShowKey[3] = ShowOption; X X /* X ** Section 4: X ** Identify the run function for keywords that are options. X ** If RunKey is set to NULL the cursor will not stop at X ** the option. The user will not be able to select it. X */ X RunKey[1] = NULL; /* You can't select a title */ X RunKey[2] = RunMenu; X RunKey[3] = RunSystem; X} X.fi X X X X X.PP XTHE END (whew) SHAR_EOF echo "File menu.1 is complete" chmod 0644 menu.1 || echo "restore of menu.1 fails" echo "x - extracting Main.c (Text)" sed 's/^X//' << 'SHAR_EOF' > Main.c && Xstatic char Sccsid[] = "@(#)Main.c 1.9 DeltaDate 1/22/90 ExtrDate 1/22/90"; X/* PROGRAM Menu (generic) X** AUTHOR Paul J. Condie X** DATE 8/18/86 X*/ X X#include <curses.h> X#include <signal.h> X#include "menu.h" X Xint MAILCALL = FALSE; Xint mailrow; Xint mailcol; Xint debug = FALSE; /* debug flag */ X X Xmain (argc, argv) X X int argc; X char *argv[]; X{ X FILE *fopen(), *menufile; X char *getenv(); X char *findfile(); X int shutdown(); /* clean up before exit */ X struct MenuInfo menu; X int (*ParseKey[MAXKEYS])(), X (*ShowKey[MAXKEYS])(), X (*RunKey[MAXKEYS])(); X char KeyWord[MAXKEYS][MAXKEYLENGTH]; X/* X** menuname keeps track of nested submenus. X** mptr is the index into menuname 0 = main menu SHAR_EOF echo "End of part 2" echo "File Main.c is continued in part 3" echo "3" > s2_seq_.tmp exit 0