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

Function:    PDOWNMENU()

Purpose:     Activate the pull-down menu initialized with PDOWNINIT().

Syntax:      PDOWNMENU( @menu, @item, menus, items, columns, starts;
                        [, item_msgs [, canexit [, itemflags ]]] )

Arguments:   @menu       - Numeric variable which indicates the starting
                           top menu option.  This variable must be PASSED
                           BY REFERENCE by preceding the variable name
                           with the @ operator.  Passing this variable by
                           reference allows PDOWNMENU() to change its
                           value.

             @item       - Numeric variable which indicates the starting
                           menu item for the starting menu option
                           indicated by <@menu>.  This variable must be
                           PASSED BY REFERENCE by preceding the variable
                           name with the @ operator.  Passing this
                           variable by reference allows PDOWNMENU() to
                           change its value.  A value of zero indicates
                           that the pull-down menu should not be "dropped"
                           and the menu bar should remain on the top menu
                           option.  The <item> number is relative to the
                           menu.

             menus       - Array of character strings which will be used
                           as the top menu options displayed across the
                           top of the pull down menu.  Each <menu> element
                           will display at its corresponding <columns>
                           element number.  For example, Menu #2 will
                           display at coordinate position row,columns[2].

             items       - Array of character strings which will be used
                           as the elements, or items, of each of the
                           pulled down menus.  This is a linear array with
                           each group of pull down menu items being
                           defined by a starting element number in the
                           <starts> array.

             columns     - Array of numeric values indicating the column
                           number on which each top level menu option will
                           be displayed.  These column numbers control how
                           the options and their pull down menus are
                           spaced across the screen.

             starts      - Array of starting element numbers.  Each
                           element in this array is a number which
                           indicates the starting position in the <items>
                           array at which each group of menu items begin.
                           There should be one element for each
                           corresponding menu in the <menus> array.

             item_msgs   - Optional array of messages which correspond to
                           each of the pull-down menu items in the <items>
                           array.  There should be one element for each
                           menu item.  If a pull-down menu item message is
                           to be blank (omitted), insert a null string
                           ("") as the element value.  If omitted then no
                           messages will display.

             canexit     - Optional logical value which indicates if
                           pressing the escape key will cause an exit of
                           the top level menu.  If omitted the default
                           value is false.

             itemflags   - Optional array of logical flags which parallel
                           each menu item in the <items> array.  Each
                           element value is a logical True or False which
                           indicates whether or not the corresponding
                           pull-down menu item is selectable.  Un-
                           selectable menu items are displayed in the un-
                           selectable color initialized in the color array
                           in PDOWNINIT().  If this parameter is omitted
                           or a non-array value is passed, the default is
                           that all menu items are selectable.

Returns:     Since the <menu> and <item> parameters are passed by
             reference with the @ operator, the menu and item number
             selected is changed for the calling procedure.  However,
             PDOWNMENU() also returns a single value which is the element
             number of the item array element chosen.  If only a top menu
             option is selected, then the menu array element number is
             returned as a negative value.  If escape was pressed, and no
             selection was made, zero is returned.

Description: The pull down menu consists of two parts: the "top" level
             menu which looks and acts like BARMENU(), and the "pulled
             down" menus, which look and act like BOXMENU()s.  When the
             menu starts, the left and right arrow keys move the highlight
             bar across the top menu options.  When either the ENTER key
             or the first letter of one of the menu options is pressed,
             the menu drops down to the pull down menu.  At this point the
             up and down arrow keys highlight the different menu item
             options and the ENTER key or first letter will selects each
             one.  The left and right arrow keys at this point cause
             PDOWNMENU() to skip left and right from pull down menu to
             pull down menu.

Notes:       Make sure that the numeric values referenced by <menu> and
             <item> are integer in nature, that is, do not have any
             decimal parts.  Since Clipper stores numeric values in
             internal binary format and not ASCII, numeric comparisons can
             sometimes lead to un-predictable and undesired results.
             Consider this situation:

             x = (1.10 - 1.00) * 10       && will = 1.00
             ? x = 1                      && Clipper will return .F.

             Since PDOWNMENU() makes only integer comparisons, make sure
             the MENU and ITEM numeric values have no decimal parts.

             PDOWNMENU(), like all RLIB functions, uses the RLIB GETKEY()
             function to retrieve keystrokes during the menu process.  If
             you create your own customized version of GETKEY() (see the
             function notes for GETKEY()), you can perform various actions
             while the pull down menu is in action.  Since the <menu> and
             <item> parameters are passed by reference, you can examine
             their values, as they change, while the menu is active.  This
             opens up enormous capabilities of things you can do while a
             menu is in progress!  Consider a demo program that, while the
             user is cursoring through a pull-down menu, a box on the
             bottom right side of the screen is changing with descriptions
             of each menu option.

             See the notes for the preceding PDOWNINIT() function.

Example:     *-- after having been initialized (see above), do the menu
             menu   = 1                   && start on menu number 1
             choice = 0                   && do not "pull down" on entry

             DO WHILE menu < 5            && menu #5 = Quit
                PDOWNMENU( @menu, @choice, menus, items, columns, starts )

                DO CASE
                   CASE menu == 1                 && File
                      FileOp(choice)
                   CASE menu == 2                 && Edit
                      EditOp(choice)
                   CASE menu == 3                 && View
                      ViewOp(choice)
                   CASE menu == 4                 && Utility
                      UtilOp(choice)
                ENDCASE
             ENDDO
             RETURN

             *------------------------------------------------------
             * Function: FileOp()
             * Purpose:  Specific file operations based on the value
             *           of the <choice> parameter.
             * Notes:    You would have a similar function for
             *           EditOp(), ViewOp(), and UtilOp()
             *------------------------------------------------------
             FUNCTION fileop
             PARAMETER choice

             DO CASE
                CASE choice = 1
                   DO retrieve
                CASE choice = 2
                   DO save
                CASE choice = 3
                   DO erase
             ENDCASE
             RETURN

Source:      RL_PDOWN.PRG

See also:    BARMENU(), BOXMENU(), MULTIMENU(), PDOWNINIT()