##S0 \R fPlib_MENU Brian K. White - linut@squonk.net \R - MENU EDITOR - MAIN SCREEN - From here you can create/modify/delete menus. The main screen has 2 basic sections. The header, and the line-items. ---------------------------- Header section ---------------------------------- The header consists of the three fields at the top labeled Name, Title, & Description. NAME is the name that you will need to use in processing tables to ask for this particular menu to be displayed. TITLE will be displayed in a box above this menu when it is run. DESCRIPTION is an optional, longer, more descriptive message that will be shown at the bottom of the screen while this menu is being displayed. If you press \KE while you are "in" any of the header fields shown above, this will pop-up a small dialog where you can view/edit some developers notes for this menu. (like a brief description of what the return-values are used for, or what format the return-values should adhere to) This text is never displayed to users. --------------------------- Line-Items section ------------------------------- The rest of the screen constists of menu-position entires. There is currently a maximum of 30 possible entries in any one menu, and they are all visible from this one screen. Each of the 30 menu position lines consist of a KEYPRESS field, and a DISPLAY-TEXT field which are visible on the main screen, and RETURN-VALUE and HELP-TEXT fields which are only visible from the detailed line-item configuration dialog. Pressing \KE while "in" any line-item field on the main screen will bring up the dialog where you can define optional, extra information for the line of the menu from which you pressed \KE . KEYPRESS this is the single keystroke the user may enter to select this line from the menu instantly, instead of moving the highlight bar. this field is available both from the main screen and the detailed pop-up. If you attempt to define a keypress that is already being used in another menu position, a descriptive error message will pop up, the keypress field will be cleared and you will be left ready to enter a new one. (todo: add a few default behaviour toggle fields to the menu file and use one of them to toggle this behaviour on or off, on a per-menu basis) DISPLAY-TEXT this is the text that will be displayed on a menu line next to the keypress character. this field is available from both main screen and the detailed pop-up. RETURN-VALUE whatever this field contains is what will be given to the calling process if the user selects this menu item. this field is only available from the detailed configuration pop-up. Note: although this is a required field (must always contain something, except for un-used menu positions) it is still not strictly necessary to go through the extra work of calling up the detailed config popup for each menu position when creating menus. If the return-value field is left empty (or deliberately cleared) it will automatically be set to equal the keypress. This means you can quickly create fully valid menus without ever having to leave the main screen. (todo: use one of the previously mentioned behaviour toggle fields to toggle the default return value between keypress / display-text / empty, on a per-menu basis) HELP-TEXT this field (displayed as 4 50-character lines) is only available from the detailed item configuration pop-up. This text (if any) will be displayed to the user if they press \K4 while the highlight bar is on this menu position. ------------------------------------------------------------------------------ \R How to install fPlib_MENU \R 1) Unpack fpl_menu.tar.gz in the /usr/appl/filepro directory. This will create a new sub directory named fpl_meu, which is actually a new "filepro file" named fpl_menu. 2) As root, go into the filepro utilities menu and run the "reset permissions" script. 3) As anybody, go into the filepro configuration editor, and add this line: FPL_MENU /usr/appl/filepro/fpl_menu/m ------------------------------------------------------------------------------ \R How to use fPlib_MENU \R 1) create one or more menus as described above. refer to the top of this help text for details on that. a few sample menus are included with the distribution. feel free to erase or modify them. later in this document I may refer to these sample menus in sample lines of code for displaying a menu, in case you happen to be reading this after the samples have been deleted. note: there is no real reason or advantage to removing the sample menus, they merely take up a little hard drive space and otherwise have no effect when not used. 2) in the processing table where you want to use the menu, put this line at or near the top, or anywhere that is outside of any and all processing loops and outside of any @W*** sections. Then: DECLARE GLOBAL fpl_menu(32,*) 3) now, anywhere else in the processing, as many times as you want, calling as many different menus as you want, put this one line any place where you want to present the user with a menu. Then: fpl_menu="menuname" ;CALL getenv("FPL_MENU") This will display menu "menuname" to the user. when the user makes a selection and exits the menu, the menu will go away, and the variable "fpl_menu", which used to hold the name of the menu you wanted, will now contain the "return-value" from the menu-position that the user chose. If the user hit \KY to cancel out of the menu, then fpl_menu will equal "" (empty). To display a menu with a default action already highlighted, use pushkey just before the call command, as in this example, which pre-selects the "P - Print" option from the included sample menu "oraction". The user then just hits \KZ to select the default, or they can still select any other action. Then: fpl_menu="oraction" ;pushkey "p" ;call getenv("FPL_MENU") That's it. Enjoy! :) ------------------------------------------------------------------------------ \R Notes / ToDo / Ideas / Future Enhancements \R o improve the way help is implemented. because of a limitation with listbox(), the help-key \KJ, is not available while displaying a menu, so as a temporary work-around, the save-key \K4, is used to display line-item help. o re-write the library such that it stores menu data in a form where each record in the database holds a line-item of a menu, instead of the current format where each record holds an entire menu. this will remove the current 30-item per menu limit, as well as eliminate the wasted space of unused menu entries. o try to devise a better method of "short hand" for the path to the actual library routine than the current use of a new environment (config-file) variable and getenv(). o allow the developer to pop up a test view of the menu he is working on, as it would appear to the user. Or possibly just: o re-write the menu-editor such that you are always looking at the menu as it would appear to the user, except that you have the ability to modify the contents and the same as now, pop-up expanded views of items for configuration. o increase the available size of "return-value" from 32 characters up to perhaps $MAXPATH (256, 512, 1024 bytes or more?). o maybe add a help-text for the whole menu. (in addition to the help-text for each position) The menu description field more or less serves this purpose now. o optional ability for a user to be able to edit the menu being displayed. settable on a per-menu basis, or maybe available to all menus on a per-call basis. Perhaps put a password on this feature. Perhaps allow each menu to have it's own password (or lack of same) hmm: this suggests: o passwords for menus, to *view* the menus. each menu would have it's own password (or maybe 2 passwords if the previous feature should be passworded seperately). if the password field is not empty for a menu, then the user would first be presented with a password prompt. the menu would only display if the got it right. ... Then again perhaps this overflows what should be the design limits of a simple menu library. IE: maybe this is best left for the programmer to do in processing before calling a menu if he wants. Actually, this is probably an excellent candidate for a whole seperate fPlib library routine. fPlib_PASS anyone? o pop-up time-out default? settable per-menu, per-call, either/both? o anything else ? cappuccino ? with nutmeg ? "42" ?? ______________________________________________________________________________ Brian K. White http://www.squonk.net/users/linut +++++[>+++[>+++++>+++++++<<-]<-]>>+.>.+++++.+++++++.-.[>+<---]>++. filePro BBx Linux SCO Prosper/FACTS AutoCAD #callahans Satriani