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

 C_SELECT()

 DESCRIPTION

 The C_SELECT() function scrolls through a database file or an
 array, inside a window, to allow selection of a record or an
 option.  The display can be based on a complete DBF of any size
 (with or without an index), a subset of a DBF of any size (with or
 without an index), an array containing specific record numbers to
 display, or an array containing the actual data to display (like
 Clipper's ACHOICE()).  The window display can scroll up, down,
 left, and right and is completely configurable.  All keyboard and
 display activity is controlled by a specified user-defined function
 (UDF).  However, if a UDF is not specified, C_SELECT() will work
 using built-in defaults for all keyboard activity.

 SYNTAX

 C_SELECT(data_type, st_row, st_col, end_row, end_col, flds [,color]
 [,title] [,header1] [,header2] [,footer1] [,footer2] [,expr] [,forexpr]
 [,firstrec] [,lastrec] [,savescrn] [,udf] [,markarr] [,border] [,refno])

 PARAMETERS

 data_type (N) is the type of data (1 - 4) to display, as follows:

 DATA_TYPE   DESCRIPTION
 ---------   -----------
 1           Direct DBF, complete or subset
 2           Clipper array of specific records in DBF to display
 3           ClipOn array of specific records in DBF to display
 4           Clipper array of character values to display

 st_row (N), st_col (N), end_row (N), and end_col (N) define the
 upper left and lower right screen coordinates of the display window.

 flds (C) is the database field(s) to display in the form of a macro
 expression which must evaluate to a character data type.  Note that
 the C_FTOMACRO() and C_ATOMACRO() functions can be used to
 construct the macro expression.
 Example:  "NAME + ' ' + ADDRESS + ' ' + str(ZIP,5) + space(5) + CODE"

 color (C) is the color of the window.

 title (C) is the title line for the window.  The title is
 automatically centered at the top of the window and remains stationary.

 header1 (C) is the first column header line for field descriptions.
 The header lines are automatically scrolled left and right with the
 window.

 header2 (C) is the second column header line for field
 descriptions.  The header lines are automatically scrolled left and
 right with the window.

 footer1 (C) is the first footer line.  The footer lines are
 automatically centered at the bottom of the window and remain stationary.

 footer2 (C) is the second footer line.  The footer lines are
 automatically centered at the bottom of the window and remain stationary.

 expr (C/N/A) is the expression that defines the scope of the
 display.  See the table below:

 DATA_TYPE                  EXPRESSION TO PASS (expr parameter)
 ---------                  -----------------------------------
 1 (Direct DBF)             Null ("")
 1 (DBF subset)             The WHILE scope ("state = 'VA'")
 2 (Clipper Record Array)   The name of the array, not in quotes
 3 (ClipOn Record Array)    The numeric reference of the array
 4 (Array containing data)  The name of the array, not in quotes

 forexpr (C) is the macro expression that defines the acceptance of
 records to be included in the display.  This parameter only has
 meaning if the data_type parameter is 1 (direct DBF and DBF
 subset).  forexpr is evaluated for every record in the scope of
 records to determine whether the record should be included in the
 display.  forexpr must be in the form of a macro expression that
 evaluates to a logical data type.  If forexpr is not specified, all
 records in the scope are included.
 Examples:  "CITY != 'RICHMOND'"  /  "AMOUNT > 1000"

 firstrec (N) is the record number of the first record in the list,
 for Mode 1, to speed the search when positioning to the top of the
 list.  For Modes 2, 3, and 4, firstrec is the starting position in
 the array to highlight.  If the first record or item is not known,
 pass a zero (0) which is the default.

 lastrec (N) is the record number of the last record in the list
 for, Mode 1, to speed the search when positioning to the end of the
 list.  For Modes 2, 3, and 4, lastrec is the maximum range to
 display in the array.  If the last record or element is not known,
 pass a zero (0) which is the default.

 savescrn (L) indicates whether or not the screen should be saved
 when C_SELECT() is called and restored when exited.  Specify true
 (.T.) to save and restore the screen, or false (.F.) to overwrite
 the previous screen and leave the selection window on the screen
 when C_SELECT() exits.  If savescrn is not specified, the default
 of true (.T.) is used.

 udf (C) is the name of the user-defined function (UDF) to maintain
 a dialog with during the C_SELECT() call.  The UDF is called
 continuously to allow complete access and control of the C_SELECT()
 function.  udf should be passed in quotes and without parenthesis,
 for example, "SELECT_UDF".  If udf is not specified, the default
 key control options are used.  (Refer to file UDF_SEL.PRG on the
 ClipOn diskette for a functional UDF.)

 markarr (C) is the name of the array to use to store record/item
 numbers "marked" for selection when the user toggles record/item
 marking on or off.  The selection of a single record or item is
 always available in C_SELECT(), but this option allows one, many,
 or all record/items to be selected by the user as in a check-off
 type list.  The markarr array name must be undeclared and passed in
 quotes.  The markarr array name will be declared as a public array
 in C_SELECT() for the number of record/items that were selected by
 the user.  The presence or absence of the array name in the
 argument list indicates to C_SELECT() whether record/item marking
 is enabled or disabled.  If a UDF is specified it also controls the
 marking and unmarking of records by controlling the key
 definitions.  If markarr is not specified, the default of no record
 is used.

 border (L) indicates whether or not boxes and lines should be drawn
 around the list window.  This option allows the list window box and
 connecting lines to be customized for a particular application.
 Specify true (.T.) if boxes and lines should be displayed around
 the window, or false (.F.) to not display a box.  If border is not
 specified, boxes and lines will be displayed.

 refno (N) is a reference number that is automatically passed to the
 specified user-defined function (UDF), to identify which C_SELECT()
 function call is current.  This option allows many C_SELECT()
 function calls to use the same UDF, even when the UDF must perform
 special functions for a specific C_SELECT() list.

 DEFAULT KEY DEFINITIONS AND ACTIONS (with no UDF)

 KEY PRESSED     ACTION TAKEN
 -----------     ------------
 ENTER           Exit C_SELECT(), return current record/item number
 ESC             Exit C_SELECT(), return zero
 SPACE           Toggle record/item mark on/off
 HOME            Display first full page, highlight first item
 END             Display last full page, highlight last item
 PGUP            Display previous page, highlight first item
 PGDN            Display next full page, highlight first item
 UP-ARROW        Highlight previous item, scroll window up if at top
 DN-ARROW        Highlight next item, scroll window down if at end
 RT-ARROW        Pan right 10 characters
 LT-ARROW        Pan left 10 characters
 CTRL-RT-ARROW   Pan right, all the way (last column)
 CTRL-LT-ARROW   Pan left, all the way (column 1)
 A-Z, a-z, 0-9   Search for first record/item matching key pressed

 PARAMETERS AND RETURN VALUES FOR THE UDF

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

 Mode - current mode state of C_SELECT(), where:
   0 = Startup
   1 = Request action
   2 = Report previous action (not at top or end)
   3 = Report previous action (at top of list)
   4 = Report previous action (at end of list)
 Prev_action - the previous action taken by C_SELECT()
 Curr_rec - current record number highlighted
 Window_pos - current window position for highlighted item
 Scrn_pos - current screen row for highlighted item
 Bottom_row - the last row of the window display box
 Pan_offset - current offset of position left and right (1 is startup)
 Refno - reference number passed to C_SELECT() function

 The following codes can be returned to C_SELECT() to tell it what
 action to perform:

 -1 = Ignore key, continue
 0  = Exit C_SELECT(), return 0
 1  = Exit C_SELECT(), return current record number or element number
 2  = Perform default action based on last key pressed (automatic mode)
 3  = Request record search on first letter in field
 4  = Redisplay current screen in window (database has not changed)
 5  = Toggle record mark on/off
 6  = Toggle record mark on/off for all
 7  = Reset and redisplay (database has changed)
 10 = Top of list
 11 = Bottom of list
 12 = Page up
 13 = Page down
 14 = Scroll up one
 15 = Scroll down one
 20 = Pan right - all the way
 21 = Pan left - all the way
 22 = Pan right - one full window
 23 = Pan left - one full window
 24 = Pan right - 1 column
 25 = Pan right - 5 columns
 26 = Pan right - 10 columns
 27 = Pan left - 1 column
 28 = Pan left - 5 columns
 29 = Pan left - 10 columns

 C_SELECT() FUNCTIONS CALLED FROM THE UDF (SEEK, MOVE, RESIZE WINDOW)

 FUNCTION: _stseek(firstrec, index_key, seek_string)

 firstrec (N) indicates whether to position to the first record
 matching the seek_string or the next record.  Pass a zero (0) for
 the first record or a one (1) for the next record.
 index_key (C) is the index key expression to match against the
 seek_string.  The index_key parameter will be evaluated as a macro
 expression in the form: if &index_key = seek_string
 seek_string (C) is the character string to find.  The seek_string
 may contain a single character or a string of characters and will
 be used in a SEEK expression.

 Returns: _stseek() returns a true (.T.) if a match was found or a
 false (.F.) if not match was found.

 FUNCTION: _stfind(field_name, find_string)

 field_name (C) is the name of a DBF field or a character macro to
 match with find_string.  The parameter will be evaluated as a macro
 expression in the form: if &field_name = find_string
 find_string (C) is the character string to find.  The find_string
 may contain a single character (which is the same as returning a 3
 from the UDF or a string of characters.

 Returns: _stfind() returns a true (.T.) if a match was found or a
 false (.F.) if no match was found.

 RETURNS

 C_SELECT() returns the currently highlighted record/item number if
 selected, or a zero (0) if C_SELECT() is aborted.

 EXAMPLES

 use test   && (Contains fields Name-C25, Addr-C35, City-C15, State-
            && C2, Zip-C10, Phone-C12, Amount-N8.2)

 && Define field macro (xfld), title, and footer
 xtitle = "CUSTOMER DATABASE LIST"
 xfld = "name + '  ' + addr + '  ' + city + '  ' + state + '  ' +
 zip + '  ' +        phone + '  ' + str(amount,8,2)"
 xfooter = "ENTER-Select Customer     ESC-Cancel"

 && This displays all records in the database in a window 5,10 to 20,70.
 && Recno() indicates that the current record is the record at the top of
 && the list. "SEL_UDF" is the callable UDF and 99 is the reference number
 && to pass to it.
 ret=c_select(1,5,10,20,70,xfld,"W/B,W+/R",xtitle,"","",xfooter,"","","",
              recno(),0,.t.,"sel_udf","",.t.,99)

 use test index test     && Open file with an index

 mstate = space(2)
 @ 0,0 say "Enter State: " get mstate picture "!!"
 read

 seek mstate                && Seek to first mstate record (assume found)
 xexp = "state = mstate"    && Set "WHILE" expression

 && This displays a list using the active index.  The parameter "xexp" will
 && determine the upper and lower range (State must equal the value in mstate)
 ret=c_select(1,5,10,20,70,xfld,"W/B,W+/R",xtitle,"","",xfooter,"",
              xexp,"",recno(),0,.t.,"sel_udf","",.t.,1)

 use test      && Open file

 mzip = space(10)
 @ 0,0 say "Enter Zip Code: " get mzip
 read

 locate for zip = mzip       && Find first mzip record (assume found)
 xfor = "zip = mzip"         && Set "FOR" expression

 && This displays a list using no index file.  The parameter "xfor" will
 && determine the records to include throughout the database
 ret=c_select(1,5,10,20,70,xfld,"W/B,W+/R",xtitle,"","",xfooter,"","",
              xfor,recno(),0,.t.,"sel_udf","",.t.,1)

 private darr[3]                && Declare array for selection
 darr[1] = "Add Record"
 darr[2] = "Update Record"
 darr[3] = "Delete Record"

 t1 = "ENTER SELECTION"
 clr = "W/B,W+/R"
 && This uses an array (darr) containing the data to display
 && Note that a (4) is passed as the mode and DARR is passed as the
 && expression.
 ret=c_select(4,10,10,16,20,"",clr,t1,"","","","",darr,"",0,0,.t.,"sel_udf")


 go top
 carr = c_adeclare(50)          && Declare ClipOn array
 for i = 1 to 50
   c_aput(carr,i,recno())       && Load with record numbers
   skip
 next
 go c_aget(carr,1)              && Position to first record

 && This displays a list using a ClipOn numeric array containing
 && record numbers to display.  Note that a (3) is passed as the mode
 && and CARR is passed as the expression.
 rr=c_select(3,7,0,22,79,xfld,"W/B,W+/B",xtitle,"","","","",carr,"",
             0,0,.t.,"sel_udf","markarr",.t.,1)

 go top
 do while deleted()  && Skip any deleted records
   skip
 enddo

 && This displays the database fields defined by XFLD using all the C_SELECT
 && default options including the default UDF to control keyboard activity.
 rr=c_select(1,10,0,20,79,xfld)

 Note that in the examples above, the code for the callable UDF
 "SEL_UDF" is contained in the file UDF_SEL.PRG on the ClipOn diskette.