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

Function:    PDOWNINIT()

Purpose:     Initialize the PDOWNMENU() function for use.

Syntax:      PDOWNINIT( row, columns, menus, items, starts ;
                        [, menu_msgs [, msg_row [, colors ;
                        [, altkeys [, canexit [, restscrn ]]]]]] )

Arguments:   row         - Numeric value indicating the row on which the
                           top of the Pull Down Menu is to appear.  Value
                           may be between 0 and 24 (MAXROW() in the 5.0
                           version).  However, in practice the value will
                           usually be row number 0 or 1.

             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.

             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.

             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.

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

             msg_row     - Optional numeric value which indicates the row
                           on which the messages contained in the
                           <menu_msgs> array are to appear.  If omitted or
                           a non-numeric value is supplied, the default
                           row is row 24.  (In the Clipper 5.0 version,
                           the default row is MAXROW()).

             colors      - Optional array of character strings indicating
                           the colors to use for the top bar and pull down
                           box menus.  Each element in the color array
                           table represents and controls the color for a
                           separate part of the pull down menu system.

                           color[1] - Menu choices (item options)
                           color[2] - Menu selection bar
                           color[3] - Pull-down ACTIVE menu box
                           color[4] - Pull-down IN_ACTIVE menu box
                           color[5] - Menu choice item upon selection
                           color[6] - Messages displayed on <msg_row>
                           color[7] - Un-selectable option
                           color[8] - Top menu bar option upon selection

             altkeys     - Optional array of character strings which
                           indicate the set of characters to use as
                           alternate select keys for each of the pull-down
                           menu choices.  There should be one element for
                           each corresponding menu.  If omitted, the
                           default direct select keys are the first letter
                           of each menu item.

             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.

             restscrn    - Optional logical value which indicates if the
                           screen area displaced by PDOWNMENU() is to be
                           used as the screen to restore on each "pull
                           down" side step.  The default is false.  See
                           the notes below for a more in-depth explanation
                           of this option.

Returns:     True if initialization successful, false if parameters error.

Description: PDOWNINIT() initializes PDOWNMENU() for operation and is
             required to set up the variables used to control PDOWNMENU().
             Since PDOWNMENU() has a lot of work to do, it is inefficient
             to repeat many of the processes and parameter passing every
             time the function is called.  Therefore, the pull down menu
             function is split into an initialization routine and the main
             menu routine.

             A call to PDOWNINIT() establishes the working environment for
             PDOWNMENU().  This working environment consists of such items
             as the menu column coordinates, the underlying screen, menu
             colors, and alternate select keys.  If this information had
             to be passed to PDOWNMENU() on each call, which is many times
             in a menu control loop, then the parameter passing and
             parameter parsing overhead would slow PDOWNMENU() down
             unnecessarily.

Notes:       Upon initialization, a PUBLIC array is established to hold
             various environment information.  This array is named
             RL_PD[], so check that this name does not conflict with any
             others in your program.  To release this public array, and
             clear the PDOWNMENU environment, issue the PDOWNINIT()
             function with no parameters.  Although not absolutely
             necessary, it is probably a good idea to release variables
             and arrays that are not being used.

             Optional parameters are not required but if you wish to skip
             an optional parameter you must pass a dummy value.  The best
             dummy value to use is a null string "".

             The example that follows shows a basic menu and how simple it
             is to construct a full featured pull down menu system.  For
             an extensive example of the ultimate in menu options and
             control, see the menu initialization routine in the Message
             Reader demo program source code.

             Changes from Version 2.0

             All changes from version 2.0 are upward compatible.  You will
             not need to modify any existing code.  However, you may want
             to modify existing code to take advantage of the new
             features.  The following sections list the changes that are
             specific to some of the parameters, listing the parameter
             name, an indicator of the change, and a description of the
             change.

             <starts> - Expanded from v2.0

             If a zero is provided as the starting element number in the
             <items> array for the associated menu number, then no pull
             down menu will show for that top menu option.  This is useful
             when you want a top menu option to be a single command all by
             itself.

             <menu_msgs> - Ignored in v2.0

             Although specified in the documentation as the array of menu
             ITEM messages, it was not used by PDOWNINIT().   This array
             is now used by PDOWNMENU() as the list of messages for each
             top (bar) menu option (not the pull-down menu items).  This
             now gives you the capability of attaching a single line
             message to each of the top menu choices as well as the
             individual menu items in the sub-menus.

             <menu_msgs> - Ignored in v2.0

             The <msg_row> parameter was being ignored in version 2.0.
             This has now been corrected and is being used as the row on
             which messages are display.  In version 2.0 messages were
             always displayed on row 24.

             <colors> - Expanded

             The colors array may now contain eight elements.  The sixth
             element is now used as the color for displaying the optional
             messages on <msg_row>.  These messages used to be displayed
             in the same color as the menu options which was not always,
             and rarely, desirable.  To maintain upward compatibility, the
             color array table may remain at 6 elements however the 6th
             element has changed from the top menu bar color on exit.
             (See my apology note below).  The 7th and 8th elements are
             optional.  If the 7th element for un-selectable options color
             is not given, then the Option color (element #1) is used.  If
             the 8th element for the top menu bar on selection is not
             provided, BRIGHT() is used.  The defaults for the menu colors
             are as follows:

             colors[1] - Current color
             colors[2] - Enhanced color
             colors[3] - BRIGHT() of current color
             colors[4] - Current color
             colors[5] - BRIGHT() of current color
             colors[6] - Current color
             colors[7] - Current color
             colors[8] - BRIGHT() of current color


             <restscrn> - New parameter

             RLIB version 2.0 PDOWNINIT() saved the area of the screen
             that was displaced by the menu boxes upon initialization and
             restored this original screen upon each entry and side
             movement in PDOWNMENU().  This is fine if you don't care if
             your screen underneath the PDOWNMENU() is disrupted.  In the
             case of a pull-down menu that is to overlay an area of the
             screen, this is un-desirable.  The <restscrn> parameter lets
             you control this action.  Althought the default value is True
             to maintain upward compatibility with RLIB version 2.0, the
             better desired default value is False.  See the demo.


             Separator Lines

             If an menu item in a pull-down menu consists of a separator
             line composed of ASCII CHR(196) characters, then such lines
             will be treated as separator lines and skipped as menu item
             selections.  The requirements are that a separator line must
             not be a pull down menu's first or last option (that doesn't
             make any sense anyway) and the line must begin at position #1
             in the option string.

             Apology Note

             At a slight cost of upward compatibility, the <colors> array
             has been ordered to be the same as the colors used by
             BOXMENU().  Many times you may want to have a BOXMENU() that
             cascades below a PDOWNMENU().  By making the color array
             tables consistent, you can now pass the same color array to
             both PDOWNINIT() and BOXMENU().  Sorry for possibly changing
             your menu colors, but it's worth it!

Example:     *-- arrays to hold top menu, columns, and starting elements
             DECLARE menus[5], columns[5], starts[5]

             *-- array to hold each pull down menu items
             DECLARE items[12]

             menus[1] = "File"
             menus[2] = "Edit"
             menus[3] = "View"
             menus[4] = "Utility"
             menus[5] = "Quit"

             columns[1] =  0
             columns[2] = 24
             columns[3] = 41
             columns[4] = 58
             columns[5] = 76

             starts[1] = 1
             items[ 1] = "Retrieve "
             items[ 2] = "Save     "
             items[ 3] = "Erase    "

             starts[2] = 4
             items[ 4] = "Record "
             items[ 5] = "File   "
             items[ 6] = "Memo   "

             starts[3] = 7
             items[ 7] = "Record "
             items[ 8] = "File   "
             items[ 9] = "Memo   "

             starts[4] = 10
             items[10] = "Directory "
             items[11] = "Reccount  "
             items[12] = "Index     "

             starts[5] = 0

             *-- initialize menu on row 1 using default colors & keys
             CLEAR
             PDOWNINIT( 1, columns, menus, items, starts )

Source:      RL_PDINI.PRG (RL_PDOWN.PRG in 5.0 Library)

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