BUNGEE()                             *new*

  Short:
  ------
  BUNGEE() Mouseable, multi-level dropdown menu with triggers

  Returns:
  --------
  NIL

  Syntax:
  -------

  BUNGEE(<nTop>,<nLeft>,<nRight>,<aMenu>,[aColumns],;
         [aColors],[aHotMice],[aHotKeys],[bExitCheck],;
         [lImmediate],[lDropped],[nHideLevel],[nShadowPos],;
         [nShadowAtt],[lHandleAlt] )

  Description:
  ------------
  Creates and activates a dropdown menu (bungee style)

  <nTop>          Row of menu bar
  <nLeft>         Left side of menu bar
  <nRight>        Right side of menu bar
  <aMenu>         A menu definition array of arrays

                  You  use the BUNGEE() menu array definition functions:
                  BUNGSTART(), BUNGEND(), BUNGOPTION(),BUNGDROP(),
                  BUNGUNDROP() together to create a menu definition array
                  for BUNGEE( ). This basically defines the menu options,
                  boxes and actions

  [aColumns]      An array of columns to determine the column
                  positions for the top bar options. Optional, as
                  this is automatically determined otherwise.

  [aColors]       An array of seven elements describing 6 colors
                  and the box drawing frame string

                  BACKGROUND COLOR         1
                  SELECTED OPTION COLOR    2
                  UNSELECTED OPTION COLOR  3
                  INACTIVE OPTION COLOR    4
                  SELECTED TRIGGER COLOR   5
                  UNSELECTED TRIGGER COLOR 6
                  BOX FRAME STRING         7   (as in "+-+|+-+| ")

                  Defaults are extracted from the current
                  values in SETCOLOR(), and adjusted to
                  account for trigger letters and inactive
                  colors.

  [aHotMice]      An array of hot areas where, should the
                  mouse click, a codeblock will be evaluated.
                  The array is an array of arrays, where each
                  sub-array is in the form:
                      {nTop,nLeft,nBottom,nRight,bCodeblock}
                  Where nTop..nRight refer to the screen
                  coordinates of the hot area.
                  i.e.
                  @24,0 say "<Help>"
                  aHotMice := { {24,0,24,5,{||dohelp}}  }

  [aHotKeys]      An array of hotkey values, which, if one of
                  the keys is pressed, a codeblock will be
                  evaluated on the spot.
                  The array is an array of arrays, where each
                  sub-array is of the form:
                      {nASCIIValue,bCodeblock}

                  @24,0 say "<Help>"
                  aHotKeys := { {K_F1,{||dohelp()}  }  }

  [bExitBlock]    This is a codeblock which returns a LOGICAL
                  which is evaluated before a menu exit is
                  allowed. If it returns .f., a menu exit will
                  not be allowed.
                  i.e. {||MESSYN("Really exit?")}

  [lImmediate]    Do mouse clicks or hot keys on options other
                  than current option cause an immediate action
                  request? Default = True

  [lDropped]      Should the menu start up in dropped mode (boxes
                  are already dropped from top bar) Default is
                  True.

  [nHideLevel]    This indicates the level to which the menu hides
                  itself when executing an option action, a mouse
                  hot button or a hot key.
                  0 - does not hide itself at all
                  1 - hides everything except the top bar  (default)
                  2 - hides everything

  [nShadowPos]    Optional shadow position for menu dropdown boxes.
                  Valid options are:
                       1. Lower left
                       3. Lower right
                       0. None
                  Upper left and upper right shadow positions are not
                  allowed. (they can overwrite parts of the menu bar)
                  Default is SLS_SHADPOS(), unless SLS_SHADPOS() is
                  upper left or upper right (7,9), in which case it
                  is set to 0 (none).

                  To force no shadows for the menu, pass 0.

                  Boxes may not always have shadows, if the shadow would
                  be drawn offscreen.

  [nShadowAtt]   Numeric shadow attribute. Default is SLS_SHADATT(), whose
                 default is 8. (grey on black)

  [lHandleAlt]   Allow ALT+trigger letter combinations (ALT-A through ALT-Z)
                 to select menu options

  Examples:
  ---------

  (Also see S3META2.PRG in the sample files for a good example)

  bungstart()
  bungoption("Files")
  bungdrop()
          bungoption("Open" ,{} ,{||!lFileIsOpen} )
          bungoption("Close",{||nil},{||lFileIsOpen } )
  bungundrop()
  bungoption("Edit")
  bungdrop()
          bungoption("DBF"  ,{||nil},nil )
          bungoption("Ascii",{||nil},nil )
  bungundrop()
  bungoption("Quit",{||bungeequit()},nil)

  aMenu := bungend()

  @24,0 say "[ALT-X=exit]"   // set up Alt-X as a hotkey exit also
  aHotKeys := { {K_ALT_X,{||bungeequit()}           }
  aHotMice := {  {24,0,24,11,{||bungeequit()}     }  }

  bungee(0,0,79,aMenu,nil,nil,aHotMice,aHotKeys, { ||messyn("Exit now?") }   )

  Example 2
  ---------

  bungstart()
  bungoption("Next",{||dbskip(1)})
  bungoption("Prev",{||dbskip(-1)})
  bungoption("Edit",{||doedit()})
  bungoption("Add ",{||doadd()})
  bungoption("Delete",{||dodelete()})
  bungoption("Table",{||editdb(.t.)})
  bungoption("Search")
       bungdrop()
       bungoption("Field Search",{||searchme()} )
       bungoption("Key Search",{||SPOPSEEK()} )
       bungoption("Query ",{||query()} )
       bungundrop()
  bungoption("Memo")
       bungdrop()
       bungoption("View",{||viewmemo()} )
       bungoption("Edit",{||editmemo()} )
       bungundrop()
  bungoption("Hardcopy")
       bungdrop()
       bungoption("Record",{||hcrecord()})
       bungoption("Memo",{||hcmemo()})
       bungundrop()
  bungoption("Quit",{||bungeequit()},nil)

  aMenu := bungend()
  bungee(0,0,79,aMenu)

  Notes:
  ------
  Notes: Dropdown boxes will adjust for 'too far right' or 'too far down',
  but there is no adjustment for 'too many options in the box to fit on
  screen'

---------------------------------------------------------------------
  Source:
  -------
  S_BUNGEE.PRG, S_BUNGDE.PRG