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

Function:    PICKREC()

Purpose:     Pop up a scrollable pick list of database records.

Syntax:      PICKREC( t, l, b, r, fieldlist [, procname [, condition ;
                      [, pickrow [, exitkeys [, pickmode ;
                      [, markkey [, markfield [, colors [, boxchars ;
                      [, boxheader [, restore ]]]]]]]]]]] )

Arguments:   t,l,b,r     - Numeric values specifying the Top, Left, Bottom
                           and Right screen coordinates of the display
                           box.  The top and bottom row values must be
                           between 0 and 24 (MAXROW() in 5.0), and the
                           left and right column values must be between 0
                           and 79.

             fieldlist   - Character string that evaluates to a valid
                           character expression.  This character
                           expression is evaluated via macro expansion to
                           produce the text that is displayed in the
                           PICKREC() display box and the scrolling
                           highlight bar.  Since it is macro expanded, it
                           must evaluate correctly to a character string.
                           Any valid expression may be used.  Normally the
                           expression contains a database field list such
                           as "Lastname + ' ' + Firstname", hence the name
                           <fieldlist>.

             procname    - Optional character string indicating the name
                           of the procedure to call after each keypress.
                           Since the call to this procedure is named at
                           runtime via macro substitution, the procedure
                           name must be identified to the compiler/linker
                           by using the EXTERNAL declaration unless it is
                           included in or is a module that will be linked.
                           If omitted or an invalid or empty character
                           parameter is provided, the default is no
                           procedure will be called.

             condition   - Optional character string indicating the
                           condition that records must meet to be included
                           in the list.  This character string is
                           evaluated at runtime via macro substitution,
                           therefore it MUST evaluate to a logical
                           expression!  If omitted or an invalid or empty
                           character parameter is provided, the default
                           condition is ".T.", i.e.  all records in the
                           database will be included.

             pickrow     - Numeric value indicating the current row number
                           of the 'selection bar'.  This parameter is
                           required to allow PICKREC() to 'remember' where
                           the bar was upon return from a previous
                           selection.  Additionally, this parameter allows
                           display refresh control by optionally passing
                           the following values:

                            0 -  Clear display box, GO to the TOP of the
                                 selected database or to the first record
                                 meeting the <condition> if specified, and
                                 display records until box filled, End Of
                                 File, or <condition> is false.  Zero is
                                 the value passed at startup.

                           -1 -  Clear display box, display records
                                 starting at the current record until box
                                 filled, EOF() .OR. (.NOT. &condition).

             exitkeys    - Optional character string which consists of a
                           set of characters which, when pressed, will
                           cause PICKREC() to exit.  If omitted or an
                           invalid parameter is passed, the default is
                           CHR(22) + CHR(7) which are the character values
                           of the Insert and Delete keys.

             pickmode    - Optional numeric value indicating the action
                           mode for PICKREC().  If omitted or an invalid
                           parameter is passed, the default mode is zero.
                           See the detailed notes section for more
                           information.  The allowed values are:

                            0 -  No refresh, pick up at current
                                 record/row.

                            1 -  Refresh record display at current
                                 record/row.

                            2 -  Same as mode 1 above but tell PICKREC()
                                 to not wait for or process any keys but
                                 to immediately exit.

             markkey     - Optional mark/unmark key ASCII value which,
                           when pressed, toggles the current record being
                           included in a "marked" list.  If omitted or a
                           non-numeric value is passed then mark toggling
                           will not be activated.  If numeric with a value
                           of zero, the default ASCII key value is -8, for
                           the F9 key.

             markfield   - Optional field name or expression evaluated and
                           used to add an item to the marked list.  If the
                           mark option is not activated (<markkey> not
                           defined), then <markfield> is ignored.  If
                           marking is on and <markfield> is either omitted
                           or is non-character in type or empty, then the
                           default expression used to add items to the
                           marked list is "STR(RECNO(),8,0)"

             colors      - Optional array of color settings used to govern
                           the colors of various parts of the PICKREC()
                           display.  See the table listed below for
                           options and default values if the array is not
                           provided.

             boxchars    - Optional character string to use in drawing a
                           box around the PICKREC() border using the
                           @..BOX command.  The boxing character string
                           must be in a form acceptable to BORDERBOX()
                           since BORDERBOX() is used to draw the box and
                           header (if specified).  If omitted, empty, or a
                           non-character type parameter is passed, no box
                           will be drawn.

             boxheader   - Optional character string to use as a header to
                           display in a header area of a BORDERBOX() style
                           box.  The string must be in a form acceptable
                           to BORDERBOX().  If omitted or a non-character
                           type parameter is passed (or boxchars) was not
                           specified, no box header will be drawn.

             restore     - Optional logical value indicating whether or
                           not to restore the screen area displaced with
                           the PICKREC() to its contents prior to
                           PICKREC() being called.  If omitted or a
                           non-logical value is passed, the default is
                           False.

Returns:     The row number of the selected record, or zero if the Escape
             Key was pressed to exit.  If either the insert or delete keys
             are pressed, the routine exits to the calling procedure which
             can test for Insert or Delete with the LASTKEY() function.

Description: PICKREC() is a database interface function which permits
             scrolling through a picklist of records from the currently
             selected database.  It provides an easy method to PICK a
             RECord from a database.  Pressing the ENTER key selects a
             record for further processing.  Views are also supported in
             that the fieldlist data which is displayed can be any valid
             expression including field data from related databases.

Notes:       PICKREC() skips forward and backward through the database
             records as the up and down arrow keys are pressed.  The PgUp
             and PgDn scroll one window full of records.  When the Enter
             key is pressed, PICKREC() exits with the record pointer
             positioned at the selected record.  If the Escape Key is
             pressed, the record pointer is at the last displayed record,
             but PICKREC() returns zero.

Example:     See the See Also reference.

Source:      RL_PICKR.PRG

See also:    MARKREC()