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

 C_XBROWSE()

 DESCRIPTION

 The C_XBROWSE() 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) or by default actions if a UDF is not
 specified.  Additional options such as search, and moving and
 resizing the display window are also controlled by the UDF.

 SYNTAX

 C_XBROWSE(st_row, st_col, end_row, end_col [,a_flds] [,box] [,color]
 [,shadow] [,title] [,a_header] [,footer] [,expr] [,forexpr] [,a_view]
 [,a_picture] [,a_valid] [,firstrec] [,savescrn] [,udf] [,dir_arrows]
 [,space] [,a_when])

 PARAMETERS

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

 a_flds (A) is a Clipper array containing the names of the fields in
 the database to display.  Fields from the current database or a
 database in another work area may be specified.  Additionally, a
 user-defined function (UDF) may also be specified to display
 information.  The UDF must return character data to display and
 should be set for view-only using the a_view array.  To display
 fields in another work area, use the alias operator (alias->field_name).
 Field names without an alias operator are assumed to
 be in the current database.  Note that C_XBROWSE() does not handle
 positioning or adding records to a secondary database but will
 update it.  The record positioning should be controlled by
 Clipper's SET RELATION command and the record appending should be
 handled by the UDF.  If a_flds is not specified, all fields in the
 current database will be displayed.

 box (N) is the box type (0 - 5) to draw for the window.  If box is
 not specified, box type 2 (double box) is used.  The box types are
 as follows:

 BOX TYPE     DESCRIPTION
 --------     -----------
 0            No box
 1            Single top/bottom, single sides
 2            Double top/bottom, double sides
 3            Double top/bottom, single sides
 4            Single top/bottom, double sides
 5            Solid graphics characters

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

 shadow (N) is the type of shadow to display around the window.  The
 shadow types are as follows:  0 = no shadow, 1 = left side/bottom
 shadow, 2 = right side/bottom shadow.  If shadow is not specified,
 no shadow is displayed.

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

 a_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 a_header is not specified, the database field names are displayed.

 footer (C) is the footer line to display information or commands to
 the user.

 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'" or
 "STATE = MSTATE"

 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_XBROWSE() will handle any size
 character field for displaying and updating.  C_XBROWSE() 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_XBROWSE()
 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_XBROWSE() 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_XBROWSE() 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_XBROWSE() call.  The UDF is called
 continuously to allow complete access and control of the
 C_XBROWSE() function.  udf should be passed in quotes and without
 parenthesis, for example "XBROWSE_UDF".  If udf is not specified,
 the default key control options are used.  (Refer to file
 UDF_XBR.PRG on the ClipOn diskette for a functional UDF.)

 dir_arrows (L) indicates whether or not directional arrows should
 be used in the C_XBROWSE() display.  Specify true (.T.) if
 directional arrows should be displayed or false (.F.) not to
 display arrows.  If dir_arrows is not specified, arrows will be
 displayed.

 space (C) is the space character(s) or other divider to draw
 between each field in the display.  This can be spaces (" ") or any
 character (" | ").  The value of the space parameter will be drawn
 between each field in the display.  If space is not specified, the
 default of two (2) spaces is used.

 a_when (A) is a Clipper array containing WHEN expressions or
 functions to be used during a GET/READ update.  The WHEN expression
 is used the same as a Clipper @ GET WHEN command to perform pre-
 validation on a GET.  There must be one WHEN expression for every
 field element, however, a null value ("") can be used to skip a
 WHEN expression.  If a_when is not specified, no WHEN expressions
 are used.  Note that the a_when parameter is not available in
 Clipper Summer 87.

 DEFAULT KEY DEFINITIONS AND ACTIONS (with no UDF)

 KEY PRESSED     ACTION TAKEN
 -----------     ------------
 ESC             Exit C_XBROWSE(), 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)

 PARAMETERS AND RETURN VALUES FOR THE UDF

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

 Mode - current mode state of C_XBROWSE(), 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 = Before update (add or change)
   6 = After update (add or change)
 Prev_action - the previous action taken by C_XBROWSE()
 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.

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

 -1 = Ignore key, continue
 0  = Exit C_XBROWSE(), return 0
 1  = Exit C_XBROWSE(), return current record number
 2  = Perform default action based on last key pressed (automatic mode)
 4  = Redisplay current screen in window (database has not changed)
 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

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

 FUNCTION: _xbseek(seek_first, field, string)

 seek_first (N) indicates whether the search should begin at the top
 or continue from the current position.  Specify zero (0) to begin
 at the top or one (1) to continue from the current position.
 field (C) is the name of the database field in the index key to search.
 string (C) is the character string or single character to search
 for in the active index.

 Returns: _xbseek() returns true (.T.) if the text was found or
 false (.F.) if not found.

 FUNCTION: _xbmove(dir, count)

 dir (C) is the direction to move the window (U=Up, D=Down, R=Right, L=Left)
 count (N) is the number of rows or columns to move the window in
 the direction specified by dir.

 Returns: _xbmove() returns true (.T.) if the window was
 successfully moved or false (.F.) if the window could not be moved.

 FUNCTION: _xbsize(dir, count, min_width)

 dir (C) is the direction to resize the window starting from the
 bottom going up and down or from the right going left and right.
 (U=Up, D=Down, R=Right, L=Left)
 count (N) is the number of rows or columns to resize the window in
 the direction specified by dir.
 min_width (N) is the minimum width the window should be shrunk when
 sizing down the width.  The value entered for min_width should be
 slightly larger than the longest field (including picture clause)
 being displayed in the C_XBROWSE() window.  This will prevent the
 window from becoming too small to display and update the fields in
 the window.

 Returns: _xbsize() returns true (.T.) if the window was successfully
 resized or false (.F.) if the window could not be resized.

 RETURNS

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

 EXAMPLES

 use test
 private fld[6],hd[6],pt[6],va[6]   && Declare arrays

 fld[1] = "acct_no"      && Load field names
 fld[2] = "name"
 fld[3] = "city"
 fld[4] = "state"
 fld[5] = "zip"
 fld[6] = "phone"

 hd[1] = "Account No"    && Load field headers
 hd[2] = "Name"
 hd[3] = "City"
 hd[4] = "State"
 hd[5] = "Zip Code"
 hd[6] = "Phone No"

 afill(pt,"")    && Load picture array (use null "" to skip fields)
 pt[1] = "99999999"
 pt[2] = "@!"
 pt[4] = "!!"

 afill(va,"")    && Load valid array (use null "" to skip fields)
 va[1] = "!c_readempty()"
 va[4] = "ck_state()"

 t1 = "Customer Database"
 f1 = "(A)dd   (C)hange   (D)elete   ESC"
 clr = "w/b,w+/r,,,bg/n"

 go top
 c_xbrowse(10,5,20,74,fld,3,clr,2,t1,hd,f1,"","","",pt,va,.t.,.t.,"XBR_UDF")


 **---------------------**
 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
 "XBR_UDF" is contained in the file UDF_XBR.PRG on the ClipOn diskette.