Click above to get retro games delivered to your door ever month!

 C_MENU()

 DESCRIPTION

 C_MENU() displays a two level, pull-down menu at the top of the
 screen.  Each main menu item can have pull-down, sub-menu items
 associated with it.  A callable UDF can be used to control certain
 keys and to display messages for each menu.  Additionally, the box
 style, colors, shadow, space between menu items, and menu title can
 be specified.

 SYNTAX

 C_MENU(main_items [,sub_items] [,first_main] [,first_sub] [,main_box]
 [,sub_box] [,color] [,shadow] [,draw_opt] [,space] [,title] [,udf])

 PARAMETERS

 main_items (A) is an array of character strings to be displayed as
 main menu items.  The array must be declared the same size as the
 number of items.

 sub_items (A) is an optional array of character strings to be
 displayed as sub-menu (pull-down) items.  There can be as many sub-
 menu items as desired for each main menu item, provided they can be
 placed on the screen, and a main menu item does not have to have a
 sub-menu associated with it.  Each sub-menu is represented by
 assigning the main menu item number to the sub-menu array element.
 (See the example below for more information.)

 first_main (N) is the number of the first main menu item to
 highlight when C_MENU() first begins.  first_main can be any main
 menu item specified in the main_items array.

 first_sub (N) is the number of the first sub-menu item to highlight
 when C_MENU() first begins.  first_sub can be any sub-menu item
 associated with a main menu item.

 main_box (N) is the box type (0 - 5) to draw for the main menu.  If
 main_box is not specified, box type 0 (no box) is used.  The box
 types are as follows:

 BOX TYPE     DESCRIPTION
 --------     -----------
 0            No box
 1            Single top/bottom, single sides
 2            Double top/bottom, double sides
 3            Double top/bottom, single sides
 4            Single top/bottom, double sides
 5            Solid graphics characters

 sub_box (N) is the box type (0 - 5) to draw for each pull-down
 menu.  If sub_box is not specified, box type 1 (single box) is
 used.  Refer to parameter main_box for box types.

 color (C) is the color to display the menu.  The color parameter
 consists of four parts:  menu/border, highlight bar, first letter,
 and title each separated by a comma  (i.e. "W/B,W+/R,W+/B,BG+/B").
 If color is not specified, the current Clipper color is used.

 shadow (N) is the type of shadow to display around the box.  The
 shadow types are as follows:  0 = no shadow, 1 = left side/bottom
 shadow, 2 = right side/bottom shadow.  If shadow is not specified,
 no shadow is displayed.

 draw_opt (L) indicates whether or not the menu should be drawn on
 the screen upon entry into the function.  This provides the ability
 to transparently exit and re-enter the function.  Specify true
 (.T.) to draw the menu or false (.F.) to suppress drawing.  If
 draw_opt is not specified, the default of true (.T.) is used.

 space (N) is the number of spaces that should appear between each
 main menu item.  If space is not specified, the default of 2 is used.

 title (C) is the optional menu title to display on the screen in
 the far right corner.  The title is drawn using the third color
 part of the color parameter, if specified.

 udf (C) is the name of the user-defined function (UDF) to maintain
 a dialog during the C_MENU() call.  udf should be passed in quotes
 and without parenthesis, for example, "MENU_UDF".  If udf is not
 specified, the default options are used.  (Refer to file
 UDF_MENU.PRG on the ClipOn diskette for a functional UDF.)

 DEFAULT KEY DEFINITIONS AND ACTIONS (with no UDF)

 KEY PRESSED     ACTION TAKEN FOR MAIN MENU ITEMS
 -----------     --------------------------------
 ESC             Exit
 ENTER           Display pull-down or Exit if none
 HOME            Highlight first menu item
 END             Highlight last menu item
 RT-ARROW        Highlight next menu item, if last item highlight first
 LT-ARROW        Highlight previous item, if first item highlight last
 A-Z, a-z, 0-9   Highlight item and display pull-down or Exit if none

 KEY PRESSED     ACTION TAKEN FOR PULL-DOWN MENU ITEMS
 -----------     -------------------------------------
 ESC             Return to main menu item
 ENTER           Exit
 HOME            Highlight first menu item
 END             Highlight last menu item
 DN-ARROW        Highlight next menu item, if last item highlight first
 UP-ARROW        Highlight previous item, if first item highlight last
 RT-ARROW        Display next pull-down and main menu item
 LT-ARROW        Display previous pull-down and main menu item
 A-Z, a-z, 0-9   Highlight item and Exit

 PARAMETERS AND RETURN VALUES FOR THE UDF

 The user-defined function for C_MENU() receives the following
 parameters when called:

 Mode - current mode state of C_MENU(), where:
   0 = Startup
   1 = Request action
   2 = Report previous action
 Prev_action - the previous action taken by C_MENU()
 Key_pressed - the INKEY() value of the last key pressed
 Main_no - the currently highlighted main-menu number (starting at 1)
 Main_total - the total number of main-menu items
 Sub_no - the highlighted sub-menu number (starting at 1, 0 if no pull-down)
 Sub_total - the total number of sub-menu items
 Offset - current offset of both main and sub arrays (for messages)

 The following action codes can be returned to C_MENU() to tell it
 what action to take:
 -1 = Ignore key, continue
 0  = Exit C_MENU(), return null ("")
 1  = Exit C_MENU(), return current main-menu and sub-menu number
 2  = Perform default action based on last key pressed (automatic mode)

 RETURNS

 C_MENU() returns the current main menu and sub-menu item number
 when the function exits as a character string.  The first and
 second characters are the main menu item number and the third and
 fourth characters are the sub-menu item number (Example: " 3 2"
 would be the 3rd main menu and the 2nd sub-menu).  Use Clipper's
 LASTKEY() to determine the keystroke used to exit.

 EXAMPLES

 declare xmenu[3], xsub[6]
 xmenu[1] = "Update"             && define 3 main menu items
 xmenu[2] = "Setup"
 xmenu[3] = "Quit"

 xsub[1] = "1"                   && define 2 pull-down items for menu 1
 xsub[2] = "Add New Record"      && ("Update" main menu)
 xsub[3] = "Update Record"
 xsub[4] = "2"                   && define 2 pull-down items for menu 2
 xsub[5] = "Colors"              && ("Setup" main menu)
 xsub[6] = "Printer"

 c_menu(xmenu,xsub,1,0,3,1,"W/B,W+/R,W+/B,BG+/B",1,.t.,2,"MAIN","MENU_UDF")
 m_main = val(substr(ans,1,2))     && get main-menu choice
 m_sub  = val(substr(ans,3,2))     && get sub-menu choice


 Note that UDF "MENU_UDF" is contained in the file UDF_MENU.PRG on
 the ClipOn diskette.