UTILITY:  MENU.bin  Version 2.1                                       Page  1


MENU.BIN is a dBASE III utility.  It was written for use on an IBM compatible 
computer.   MENU.BIN  and the accompanying documentation  are  being  offered 
under the "ShareWare Concept".  If you find this utility of value and plan to 
use it in your programs it is requested that you reward the author's  efforts 
by sending him $5.00.  This money will be used to offset the costs associated 
with  distribution  and  will give the author an idea of  whether  he  should 
pursue in the distribution of this utility and others that he has written.

     The Author of MENU.bin is:
          Keith Roddey
          2823 Corning St.  #2
          Los Angeles, CA.  90034

RELEASE NOTES

This version supports a new switch, the /N (No Shadow) switch.

PURPOSE

This utility was designed to create professional looking menus.  When used in 
your programs it will cut down on the number of lines of code that you  would 
normally have to write.

This utility supports 4 different types of menus.  They are:

Default
     This  menu  uses colors/shades to draw a menu similar to those  used  in 
     several CAD/Graphics programs.
Horizontal (/H)
     This  is  a Horizontal Light Bar menu.  It occupies one line  only  with 
     each  menu  option separated by the previous option or  the  menu  title 
     (optional)  by  2  spaces.   The selected option  is  displayed  in  one 
     color/attribute  while  the  other  options  are  displayed  in  another 
     color/attribute.   If a menu title is passed in the parameter string  it 
     will be displayed in another color/attribute.
Vertical (/V):
     This is a Vertical Light Bar menu.  The menu title and options are drawn 
     within  a rectangle made up of the extended ASCII codes from the  double 
     line  group.   If you prefer, you may use other characters to  draw  the 
     rectangle.   The  menu  title  and  options  are  centered  within   the 
     rectangle.   The  selected option is displayed  in  one  color/attribute 
     while the other options are displayed in another color/attribute.  If  a 
     menu  title  is passed in the parameter string it will be  displayed  in 
     another color/attribute.  In addition,  if the  help flag is passed, the 
     message "<F1> Help" will be displayed below the menu.
Left Justified (/L):
     This  menu is similar to the Vertical menu except the direct  keystrokes 
     are  displayed  (inside brackets < >) to the left of each  of  the  menu 
     options.   The menu title (if given) and the options are displayed  left 
     justified.   The  selected option is displayed  in  one  color/attribute 
     while the other options are displayed in another color/attribute.






Copyright (C) Keith Roddey 1988
UTILITY:  MENU.bin  Version 2.1                                       Page  2


FILES

MENU.doc  - This documentation.
MENU.prg  - A dBASE program that not only illustrates MENU.bin but allows you 
            to try different menu color combinations.  If you are using dBASE 
            III Plus set STATUS OFF.
MENU.bin  - The loadable menu utility.

INSTRUCTIONS

As with any BIN module, you must first load it with the command:
     LOAD MENU
     or
     LOAD drive:\path\MENU

The calling sequence is:
     CALL MENU WITH mem_var
     or  if you are setting the default colors or border characters  you  may 
     use a literal as in
     CALL MENU WITH "/C,R,,,W+"


PARAMETER STRING
   
Before calling MENU with a memory variable you must initialize it, the memory 
variable,  with  a proper parameter string.  The parameter string  is  broken 
down into the following parameters:
     
opt[,?],[top_row],[left_col],[menu_title],option_list[,switches]

opt       This  parameter specifies the menu option that will be  highlighted 
          when MENU is called and this parameter is checked when MENU returns 
          to determine what option was chosen.  It must be 2 characters long.  
          As  an example in it's format, to have the second menu  option   as 
          the  initial   default option,  this parameter  would  be  "02"  or 
          " 2".  If "00" is passed then the first option in the menu will  be 
          highlighted.  When this function returns the two characters in this 
          parameter  will  contain "00" if the <Esc> key was pressed  or  the 
          menu option that the user chose with a direct keystroke, <Enter> or 
          the  Help  key (<F1>).  After MENU returns, the VAL()  function  is 
          probably the easiest way to determine the return value.
?         The  help  parameter and it's comma are optional.   Providing  this 
          parameter  will allow the user to press <F1> as a means of  seeking 
          help  on a particular menu option or on the menu itself.   If  this 
          parameter  is  included, when the user presses <F1> MENU  will  set 
          'opt'  equal to the option that was highlighted and change the  4th 
          position  of  the  parameter  string,  the  question  mark,  to  an 
          uppercase  Y.   This  position can then be checked  to  see  if  it 
          contains a Y, and if it does your program can then branch to a help 
          procedure.   You may also pass a "Y" in the 4th position.   If  the 
          user doesn't press <F1> then the "Y" will be changed to a "?".
top_row   This is an optional parameter.  If supplied, it should be  the  top 
          row  coordinate that you want the menu positioned on.  If the  menu 
          cannot  be drawn vertically using this row then the  menu  function 
          will  return  without being drawn or processed.  If  not  supplied, 


Copyright (C) Keith Roddey 1988
UTILITY:  MENU.bin  Version 2.1                                       Page  3


          then row 0 will be used.
left_col  This is an optional parameter.  If supplied, it should be the  left 
          column  coordinate  that you want the menu positioned on.   If  the 
          menu  cannot fit on the screen with the given column then the  menu 
          function  will return without drawing or processing the  menu.   If 
          not supplied, it will default to column 0.
menu_title
          This is an optional parameter.  If given, it is the title that will 
          be displayed on the beginning of the line for a Horizontal menu  or 
          the top of the menu if other than a Horizontal menu.
option_list
          The  option_list contains a list of menu options that comprise  the 
          menu.    Each  option  is  separated  by  a  comma.  For   example, 
          "Update,Reports,Quit dBASE". 


SWITCHES

Switches are optional.  They give you greater control over how the menus  are 
displayed and control the various ways the user can select, or not select, an 
option.  Each switch is preceded by a backslash.  If more than one switch  is 
included they must be separated by commas.

/O        Overwrite  screen.   Will not save/restore screen  region  menu  is 
          drawn on.
/R        <Return>  Disabled.  This is useful for those cases where you  want 
          the user to choose an option by pressing a direct keystroke and not 
          merely by highlighting an option and pressing <Return>.
/E        <Esc> Disabled.  This is useful for those cases where the user MUST 
          choose an option.
/Kkeystrokes
          Set the direct keystroke list.  Allows you to give a unique  direct 
          keystroke  to  each  menu  option.   Use  a  space  for  no  direct 
          keystroke,  or if you want to change a direct keystroke but not the 
          preceding  keystroke(s) use a comma (ex. /K,,,X).  If no /K  switch 
          is  given,  MENU will use the 1st character of each option  as  the 
          direct  keystroke.  When this switch is used, it must be  the  last 
          switch in the parameter string.
/Sn       Stack menu.  This switch tells the menu function to stack the  menu 
          until it has been terminated by the user pressing <Esc>.   Stacking 
          a menu saves the region of the screen that the menu is drawn on  in 
          a  buffer.  When the menu is terminated with <Esc>, this region  is 
          redrawn.   This  is how the menu function works when  you  are  not 
          using  the  /O  switch, except normally the screen  is  redrawn  no 
          matter how the menu is terminated.  Stacking menus is usually  done 
          when  you  want the user to proceed to a point in the  program  and 
          allow  the user to back track without starting over again.  n is  a 
          number  between  1 and 5 which identifies the level of  the  stack.  
          The total size of the buffer that holds the screen regions is 6,000 
          bytes.  You can have 5 menus on the stack at one time provided  the 
          combined  regions  are less than or equal to 6,000 bytes.   If  you 
          want to call MENU with a new menu and five menus are already on the 
          stack you must use the /O switch.  The first time you buffer a menu 
          you  must start with n equal to 1.  Each additional menu  that  you 
          stack  should  have n equal to the previous n + 1.   As  menus  are 


Copyright (C) Keith Roddey 1988
UTILITY:  MENU.bin  Version 2.1                                       Page  4


          popped (terminated with <Esc>) the value of n for that popped  menu 
          becomes available again.
/V        This  is  the Vertical Menu switch.  Supplying this  switch  causes 
          MENU to draw and process a Vertical menu.
/H        This  is the Horizontal Menu switch.  Supplying this switch  causes 
          MENU to draw and process a Horizontal menu.
/L        This  is the Left Justified switch.  Supplying this  switch  causes 
          MENU to draw and process a Left Justified menu.
/N        This  is  the No Shadow switch.  This switch only operates  on  the 
          Default  menu type.  If this switch is passed then the menu  shadow 
          will not be drawn.
/Bborder_string
          This  is  the  border  switch.  It is used  to  change  the  border 
          characters used to draw the Vertical and Left Justified menus. Once 
          the border characters are set they will remain in effect until MENU 
          is  reLOADed or they are set again.  The border_string is  composed 
          of  11  characters.  The position of the character  in  the  string 
          determines which border character/position is modified.  The  first 
          character  in the string is used to draw the top left  corner,  the 
          2nd  character the top horizontal line, the 3rd character  the  top 
          right   corner,   etc.   Below  is  a  sample   menu   which   used 
          "/B1234567890A" for the border string.  This sample menu shows  the 
          border positions which are altered by each of the characters in the 
          border_string.

               1222222222223
               4 TITLE     5
               6777777777778
               4<A> Add    5
               4<E> Edit   5
               4<D> Delete 5
               900000000000A

          The default border string is "/B"+CHR(201)+CHR(205)+CHR(187)+;
          CHR(186)+CHR(186)+CHR(204)+CHR(205)+CHR(185)+CHR(200)+CHR(205)+;
          CHR(188)
          This  must  be  the last switch passed otherwise the  rest  of  the 
          switches will not be processed.
/Ccolor_string
          Sets  the colors used to draw the menus.  Once the colors  are  set 
          they  will remain in effect until MENU is reLOADed or they are  set 
          again.   This  must be the last switch when passed.   The  standard 
          dBASE  color switches that can be used are W, N, B, G, R, + and  *.  
          If  you want to change the color for a particular feature, say  the 
          Title  Line  (on  the Default menu type),  but  not  the  preceding 
          color(s)  use a comma (ex. /C,,W+).  This switch acts on  the  menu 
          type chosen with either the /V, /L, /H or the default (no menu type 
          switch).   When your menu is other than the Default Menu  type  the 
          /V,  /L,  or /H switch must be given prior to the /C  switch.   The 
          number of parameters in the color_string is specific to the type of 
          menu  in use.  The color string is broken down into  the  following 
          parameters,  each  describes  that part of the menu  that  will  be 
          modified by a given attribute/color:




Copyright (C) Keith Roddey 1988
UTILITY:  MENU.bin  Version 2.1                                       Page  5


          Default Menu Type:
             Title Background*,
             Title Text Foreground,
             Title Line Foreground,
             Options Background*,
             Options Text Selected Foreground,
             Options Text Others Foreground,
             Options Line Top Foreground,
             Options Line Bottom Foreground,
             Direct Keystrokes Foreground/Background,
             Shadow Foreground/Background,
             Help Message Foreground/Background.
          * precede by backslash (/).

          Horizontal Menu Type (/H):
             Title Foreground/Background,
             Options Text Selected Foreground/Background,
             Options Text Others Foreground/Background,

          Vertical & Left Justified (/V or /L):
             Background*,
             Border Foreground,
             Title Text Foreground,
             Options Text Selected Foreground/Background,
             Options Text Others Foreground,
             Help Message Foreground/Background,
             Direct Keystrokes Foreground/Background,
          * precede by backslash (/).

EXAMPLES

CALL MENU WITH "/C/W,R,RG+,,,,,,,W/B"    && Sets the default colors used
&& for the Default menu type. Title background to white, title text to red,
&& title line to yellow, and shadow attributes to white on blue.

CALL MENU WITH "/H,/CW/N,N/W,W+/N"      && Sets the colors used to draw the
&& Horizontal Menus.  (These particular colors are the default)

CALL MENU WITH "/B"+CHR(218)+CHR(196)+CHR(191)+CHR(179)+CHR(179)+CHR(195)+;
CHR(196)+CHR(180)+CHR(192)+CHR(196)+CHR(217)
&& Sets the borders characters used to draw the Vertical and Left Justified
&& Menus to the Single Line Group from the Extended ASCII Set.

mm_str = "01,,,MAIN MENU,Update,Reports,Utilities,/K,,1,/O,/R"
CALL MENU WITH mm_str
&& the preceding example draws a menu on the screen using 0,0 as the left top 
&& corner, the menu title is "MAIN MENU", the direct keystrokes will be U, R, 
&& and 1.  The screen region that this menu covers will be overwritten.  
&& Since <Return> is disabled, the user can only terminate this menu by 
&& pressing <Esc>, U, R, or 1.

main_menu = "01,0,0,OPTIONS,Add,Edit,Delete,Next,Previous,Goto,/H"
&& This statement defines a Horizontal Menu.




Copyright (C) Keith Roddey 1988
UTILITY:  MENU.bin  Version 2.1                                       Page  6


main_menu = "01,10,20,,MON,TUE,WED,THU,FRI,SAT,SUN,/V,/E,/K , , , , , , "
&& This statement defines a Vertical Menu that does not use a title.  In 
&& addition, the user can only take an option by moving the light bar to the 
&& selected option and pressing <Enter>.  Also the user cannot terminate this 
&& menu by pressing <Esc>.

main_menu = "01,0,0,OPTIONS,e(X)it,(A)dd,(E)dit,(D)elete,/H,/KX,A,E,D"
&& This statement defines a Horizontal Menu.  It uses the /K flag to set up a 
&& unique direct keystroke for each of the options.

&& The following procedure can be used as a general purpose report procedure.  
&& It first asks the user if he wants to print the report (using the menu
&& title for asking the question), if the user selects yes, the printer
&& status is then checked (in a procedure not shown).  If the printer is not
&& ready, the procedure loops until the printer becomes ready or the user
&& chooses to cancel the print job.
PROCEDURE PRINTIT
PARAMETERS rpt_name, rpt_proc     
rpt_menu  = "01,10,10,PRINT THE "+rpt_name+"?,NO,YES"
CALL MENU WITH rpt_menu
IF VAL(rpt_menu) <> 2
     RETURN
ENDIF
lpt_error = .F.
DO TESTLPT WITH lpt_error
lpterrmenu = "01,10,10,PRINTER NOT READY,Try Again,Cancel,/E,/C,R+*"
DO WHILE lpt_error .AND. VAL(lpterrmenu) <> 2
     CALL MENU WITH lpterrmenu          && Get user action
     IF VAL(lpterrmenu) = 1             && Try printer again?
          DO TESTLPT WITH lpt_error     && Yes, check printer status
     ENDIF
ENDDO
CALL MENU WITH "/C,R+"                  && Set title color back to default
IF VAL(lpterrmenu) <> 2                 && Print report?
     DO &rpt_proc                       && Yes, print it.
ENDIF
RETURN




















Copyright (C) Keith Roddey 1988
UTILITY:  MENU.bin  Version 2.1                                       Page  7


&& The following code is an example of stacking menus with the /S switch  and 
&& using the Help option.
main_menu = "01,?,0,0,MAIN MENU,Update,Reports,/O"
menu1     = "01,5,10,UPDATE MENU,Add,Edit,Delete,Lookup,/S1"
menu1A    = "01,10,15,LOOKUP MENU,Class Code,Dept. Code,Acctg. Code,/S2"
menu2     = "01,5,10,REPORT MENU,Report 1,Report 2,Report 3,/K1,2,3,/S1"
DO WHILE .T.
     CALL MENU WITH main_menu
     DO CASE
     CASE VAL(main_menu) = 0
          EXIT
     CASE SUBSTR(main_menu,4,1) = "Y"
          DO HELP WITH "MAIN", VAL(main_menu)
     CASE VAL(main_menu) = 1
          DO WHILE .T.
               CALL MENU WITH menu1
               DO CASE
               CASE VAL(menu1) = 0
                    EXIT
               CASE VAL(menu1) = 1
                    DO ADD
               CASE VAL(menu1) = 2
                    DO EDIT
               CASE VAL(menu1) = 3
                    DO DEL
               CASE VAL(menu1) = 4
                    DO WHILE .T.
                         CALL MENU WITH menu1A
                         IF VAL(menu1A) = 0
                              EXIT
                         ENDIF
                         DO LOOKUP WITH VAL(menu1A)
                    ENDDO
               ENDCASE
          ENDDO
     CASE VAL(main_menu) = 2
          DO WHILE .T.
               CALL MENU WITH menu2
               IF VAL(menu2) = 0
                    EXIT
               ENDIF
               DO REPORT WITH VAL(menu2)
          ENDDO
     ENDCASE
ENDDO












Copyright (C) Keith Roddey 1988
