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

 browse()            Database browse
------------------------------------------------------------------------------
 Declaration
   database.hdr

 Syntax
   func long browse extern
   param       alias    sBrowseAlias, ;
         value uint     uTop, ;
         value uint     uLeft, ;
         value uint     uBottom, ;
         value uint     uRight, ;
         const char(74) cTitle[3], ;
         const char(74) cFootNote, ;
         const char     cFieldNames, ;
               byte     bColors[3], ;
         value uint     uBeginField, ;
         value ulong    mTopRecord, ;
         value ulong    nBottomRecord, ;
               untyped  xBrowseUDF

 Arguments
   sBrowseAlias is the alias of the open database to browse.
   uTop is the top row of the display.
   uLeft is the leftmost column of the display.
   uBottom is the bottom row of the display.
   uRight is the rightmost column of the display.
   cTitle[3] is an array of three title line strings.
   cFootNote is the footer line string.
   cFieldNames is the column header string.
   bColors[3] is an array of color attributes.
   uBeginField is the field number where display begins.
   mTopRecord is the first record to display.
   nBottomRecord is the last record to display.
   xBrowseUDF is a user-defined callback function.

 Return
   The record number of the selected record if the Enter key was pressed,
   or zero if the browse was exited by pressing the Escape key.

 Description
   The browse() function displays the records of an open database on
   the screen, and allows the operator to navigate between records with
   the keyboard or the mouse. The display accommodates the record order
   specified by the active index if any. The browse() function does not
   open datafiles or indexes.

   The four coordinate parameters identify the four corners of the
   display itself, and not the total screen area required. Because the
   browse automatically draws other related portions of the screen
   outside the browse area, behavior can be unpredictable if
   inappropriate parameters are passed. For instance, specifying a zero
   value for the uLeft parameter will definitely cause problems as the
   browse() internals need to be able to display the left side of the
   perimeter box at column uLeft - 1.

   The browse title array given by the cTitle[] parameter adds four
   total lines to the top of the browse box, except when all three
   elements are initialized to null strings. In this case none of the
   upper title area is displayed. If any of the three title lines is
   initialized as anything other than a null string, then the entire
   title area is painted, including the empty lines.

   The footer line, specified by the cFootNote parameter is automatically
   centered. Displaying the footer can be prevented by initializing the
   parameter to a null string.

   The cFieldNames parameter is a descriptive string containing either
   the names of the fields to be browsed or explanatory descriptions of
   the browse columns. The column header line (and another containing a
   line on top of it) will be drawn even if the parameter is initialized
   to or passed as an empty string.

   The application can query the __browse_colsep variable to apply the
   same character as the column delimiter. Note that __browse_colsep is
   a byte variable that must be converted to a char with the chr()
   function to use within the cFieldNames string.

   The three elements of the bColors array represent the color attributes
   for regular text, highlighted element row, and enclosing box frame
   respectively.

   The callback function passed as the xBrowseUDF parameter
   has a mandated prototype of:

   func uint <funcname>
   param value ulong nDummy, ;
         value uint  uCallType, ;
               char  cString

   where

   uDummy is an unused variable preserved for compatibility with earlier
   Force versions.

   uCallType denotes what action to take. A value of 0 indicates that
   browse() expects the callback function to return a line of record data.
   A value of 1 indicates the function is expected to handle keypress
   exceptions.

   cString is the browse line to display.

   The callback function performs alternately two different types of
   activities depending on the parameters it is passed:

   (1) Either (a) return a line of record data in the cString parameter for
   display, or (b) provide a routine for handling special exception
   keypresses via calls to other functions.

   (2) Return an action code to browse() that instructs it what to do next
   (nothing, refresh, restart, or quit).

 Example
   #define EXAMPLE_DATABASE
   #include example.hdr

   vardef static
      byte bColor1[ 3 ] := CYAN_BLUE, WHITE_WHITE, CYAN_BLUE
   enddef
   
   proc Info1 static
   // Show record information
   savearea( 9, 10, 15, 70 )
   @  9, 10 clear to 15, 70
   @  9, 10 to 15, 70 double
   @ 11, 13 ?? "Record number:", istr( recno() )
   @ 12, 13 ?? "Last name    :", sTest->lastname
   getkey()
   restorearea()
   endproc
   
   func uint BrowseCallback1 static
   param value ulong nAddress, ;
         value uint  uCallType, ;
               char  cRecord
   // Return a record or a key code
   vardef
      uint uRet
   enddef
   uRet := BROWSE_NIL
   do case
   case uCallType == 0                                 // return a record
      arecstring( &cRecord, sTest, arecsize( sTest ) )
   case uCallType == 1                                 // process special keys
      do case
      case lastkey() == K_F5               // info
         Info1()
      case lastkey() == K_DEL              // delete/recall
         if deleted()
            recall
         else
            delete
         endif
         uRet := BROWSE_RESTART
      case lastkey() == K_F10              // quit
         uRet := BROWSE_QUIT
      endcase
   endcase
   return( uRet )
   endfunc
   
   proc Test_browse
   vardef
      char( 74 ) cTitle[ 3 ]
   enddef
   open sTest index sIdxLN
   go top
   cTitle[ 0 ] := "Sample application"
   cTitle[ 1 ] := replicate( "-", 50 )
   cTitle[ 2 ] := center( "Demonstrate using the browse() function", 50 )
   browse( sTest, 8, 17, 18, 63, cTitle[], ;
      center( "F5 Info  Del Delete/Recall  F10, Esc Quit", 50 ), ;
      " First     Last name       A S Balance Due", ;
      bColor1[], 1, 1, reccount() + 1, BrowseCallback1 )
   endproc

   proc main
   Test_browse()
   endproc