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

 C_BROWSE()

 DESCRIPTION

 The C_BROWSE() function scrolls through a database file to allow
 records to be viewed, added, changed, and/or deleted.  The display
 can be based on a complete database of any size or a subset of the
 database with or without an index.  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_BROWSE() will work using built-in defaults for all keyboard activity.

 SYNTAX

 C_BROWSE(st_row, st_col, length [,a_fld] [,color] [,title] [,header]
 [,footer] [,expr] [,forexpr] [,a_view] [,a_picture] [,a_valid] [,firstrec]
 [,savescrn] [,udf] [,border] [,refno])

 PARAMETERS

 st_row (N), st_col (N) are the starting row and column of the window.

 length (N) is the length of the display window.

 a_fld (A) is a Clipper array containing the names of the fields in
 the database to display.  If a_fld is not specified, all fields in
 the current database will be displayed.

 color (C) is the color to display for the window, the highlight
 bar, and the GET/READ variables.

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

 header (A/C) is a Clipper array containing the names of the field
 headers to display above each field name.  There must be one header
 element for every field element.  To display custom column headers,
 pass a Clipper array containing the field header names.  To display
 the database field names, pass a character string containing the
 letter 'F'.  To suppress column headers, pass a null ("") string.
 If C_BROWSE() is called using default options, the database field
 names are displayed.

 footer (C) is the footer line to display information or commands to
 the user.  The footer line is automatically centered at the bottom
 of the window and remains stationary.

 expr (C) is the macro expression defining the WHILE condition.  The
 WHILE condition specifies the records to be included in the display
 until the condition fails.  expr is usually used for an indexed
 database to include only a contiguous subset of the database.  expr
 must be in the form of a macro expression that evaluates to a
 logical data type.  If expr is not specified, all records in the
 database are included in the display.  Example:  "STATE = 'VA'"

 forexpr (C) is the macro expression that defines the acceptance of
 records to be included in the display.  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"

 a_view (A) is a Clipper array containing logical values to indicate
 whether or not a field should be "view-only" during a GET/READ
 update.  There must be one logical element for every field element.
 Specifying true (.T.) indicates that the field is for viewing only
 and can not be modified during a GET/READ.  Specifying false (.F.)
 indicates that the field can be updated.  The default if a_view is
 not specified, is false (.F.).

 a_picture (A) is a Clipper array containing PICTURE clauses to be
 used during a GET/READ update.  There must be one PICTURE clause
 element for every field element, however, a null value ("") can be
 used to skip a PICTURE element.  If a_picture is not specified, no
 PICTURE clauses are used.  C_BROWSE() will handle any size
 character field for displaying and updating.  C_BROWSE() will sub-
 string the field in display mode so that it does not wrap on the
 screen and in update mode will allow horizontal scrolling within
 the field.  In order to accomplish this, however, you must pass a
 picture clause of "@s76" (or anything less than 76) as an element
 in the picture array parameter for that particular field.  If the
 field is longer than 76 characters and a picture clause is not
 specified, the field will not be displayed on the screen.

 a_valid (A) is a Clipper array containing VALID expressions or
 functions to be used during a GET/READ update.  There must be one
 VALID expression for every field element, however, a null value
 ("") can be used to skip a VALID expression.  If a_valid is not
 specified, no VALID expressions are used.

 firstrec (L) indicates whether the current record, when C_BROWSE()
 is called, is the first record in the scope of records to display,
 which helps speed the search when positioning to the top of the
 list.  Specify true (.T.) if the current record is the first
 record, or false (.F.) if it is not or the first record is not
 known.  If firstrec is not specified, the default of false (.F.) is used.

 savescrn (L) indicates whether or not the screen should be saved
 when C_BROWSE() is called and restored when exited.  Specify true
 (.T.) to save and restore the screen, or false (.F.) to overwrite
 the previous screen and keep the browse display window on the
 screen when C_BROWSE() 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 during the C_BROWSE() call.  The UDF is called
 continuously to allow complete access and control of the C_BROWSE()
 function.  udf should be passed in quotes and without parenthesis,
 for example "BROWSE_UDF".  If udf is not specified, the default key
 control options are used.  (Refer to file UDF_BR.PRG on the ClipOn
 diskette for a functional UDF.)

 border (L) indicates whether or not boxes and lines should be drawn
 around the display window.  This option allows the 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.) not to 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_BROWSE()
 function call is current.  This option allows many C_BROWSE()
 function calls to use the same UDF, even when the UDF must perform
 special functions for a specific C_BROWSE() display.

 DEFAULT KEY DEFINITIONS AND ACTIONS (with no UDF)

 KEY PRESSED    ACTION TAKEN
 -----------    ------------
 ESC            Exit C_BROWSE(), return zero
 A, a           Perform GET/READ - Add new record to DBF if record accepted
 C, c           Perform GET/READ - Update current record if record accepted
 D, d           Delete record from DBF
 HOME           Display first full page, highlight first record in window
 END            Display last full page, highlight last record in window
 PGUP           Display previous page, highlight first record in window
 PGDN           Display next full page, highlight first record in window
 UP-ARROW       Highlight previous record, scroll window up if at top
 DN-ARROW       Highlight next record, scroll window down if at bottom
 RT-ARROW       Pan right 1 field
 LT-ARROW       Pan left 1 field
 CTRL-RT-ARROW  Pan right, all the way (last field)
 CTRL-LT-ARROW  Pan left, all the way (first field)
 CTRL-ENTER     During update, scroll window right one field
 CTRL-PGUP      During update, scroll window up one record
 CTRL-PGDN      During update, scroll window down one record

 PARAMETERS AND RETURN VALUES FOR THE UDF

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

 Mode - current mode state of C_BROWSE(), where:
   0 = Startup
   1 = Request action
   2 = Reply after action (not at top or end)
   3 = Reply after action (at top-of-list)
   4 = Reply after action (at end-of-list)
   5 = After update
 Prev_action - the previous action taken by C_BROWSE()
 Curr_rec - current record number highlighted
 Window_pos - current window position for highlighted item
 Scrn_pos - current screen row for highlighted item
 Pan_offset - current offset of position left and right (1 is startup)
 No_recs - .F. if records to display is greater than 0, else .T.
 Bottom_row - the last row in the window display
 Refno - reference number passed to C_BROWSE() function

 The following action codes can be returned to C_BROWSE() to tell it
 what action to take:

 -1 = Ignore key, continue
 0  = Exit C_BROWSE(), return 0
 1  = Exit C_BROWSE(), return current record number
 2  = Perform default action based on last key pressed (automatic mode)
 4  = Redisplay current screen in window
 5  = Request Add
 6  = Request Change
 7  = Request Delete
 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 - 1 field
 23 = Pan left - 1 field

 RETURNS

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

 EXAMPLES

 && Open DBF (Fields:  Code C 2, Name C 100, City C 35, State C 2, Zip N 5)
 select 0
 use vendor index vendor

 && Declare arrays for C_BROWSE() function
 private fld[5],hd[5],pict[5],valid[5]

 && Load field array
 fld[1] = "code"
 fld[2] = "name"
 fld[3] = "city"
 fld[4] = "state"
 fld[5] = "zip"

 && Load field header array
 hd[1] = "Code"
 hd[2] = "Name"
 hd[3] = "City"
 hd[4] = "State"
 hd[5] = "Zip Code"

 && Load picture clause array
 && (fill all elements with default ("") first)
 afill(pict,"")
 pict[1] = "@!"
 pict[2] = "@s76"
 pict[4] = "@!"
 pict[5] = "99999"

 && Load valid expression array
 && (fill all elements with default ("") first)
 afill(valid,"")
 valid[1]  = "!c_readempty()"
 valid[4] = "ck_state()"    && (See function below)
 valid[5] = "!c_readempty()"

 && Window title and footer (command line)
 title1 = "VENDOR MASTER DATABASE"
 footer1 = "Press:  A-Add    C-Change   D-Delete   ESC-Exit"

 && Call C_BROWSE() to display at 4,0 for a length of 18
 c_browse(4,0,18,fld,"w/b,w+/r,,,bg/n",title1,"",footer1,"","","",
          pict,valid,.t.,.t.,"BR_UDF",.t.,1)

 **---------------------**
 FUNCTION ck_state

 if !c_isstate(c_getvar())
   c_msg(10,1,3,2,"w+/r","Error: Invalid State Code")
   return .f.
 endif
 return .t.

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