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

 MBROWSE()
 Browse database limited by a while condition with mouse
------------------------------------------------------------------------------
 Syntax
      MBROWSE( <aFields>, <bWhileCond>, <cKey>,
                  [<nFreeze>], [<lSaveScrn>], [<cColorList>],
                  [<nTop>], [<nLeft>],
                  [<nBottom>], [<nRight>], [<bScreenInit>], [<nReadInit>],
                  [<bAltReader>], [<nExitKey>], [<lAppendMode>],
                  [<AppendReader>], [<bRecordNum>], [bRecordTotal>] ) ;
            -> <nRecno>
 Arguments
     <aFields> is multidimensional array of field blocks of fields you
        want to display. Each row contains up to six members containing:

        Index 1: Column heading
        Index 2: Code block for displaying information. Note: if you are
                 going to do an a read, this must code block must be written
                 so that if a parameter is passed, it will set the GET
                 variable. For example: {|x| IIF(x=NIL,Last,Last:=x) }
                 can be used by both browse and the GET system.
        Index 3: Optional logical indicating if field can be edited if you
                 are allowing edits. By default, if you are allowing edits
                 (see below) it is .T., and, obviously, if you are not .F.
        Index 4: Optional Picture function for get on this column.
        Index 5: Optional Code block to be executed as a WHEN clause.
        Index 6: Optional Code block to be executed as a VALID clause.
        Index 7: Optional TBColumn:ColorBlock code block for this column

        Example to set up last name and first name in array:
        aFields := {}
        AADD(aFields,{"Last Name",{||Names->Last},.T.,"!XXXXXXXXXXXXXX" })
        AADD(aFields,{"First Name",{||Names->First} } )

     <bWhileCond> is the limiting WHILE condition as a block.
        If cKey (below) is NIL. This is automatically set to {|| .T.}.
        If you will be allowing appends you will want to allow arguments to
        be passed so that you can use this while block on data entered by the
        user prior to adding it to the database. The third example below
        shows such a block (as does the example program above).

        Example 1: { ||Names->Last == "JONES" }
        Example 2: { ||Names->Last == "JONES" .AND. Names->First == "A"  }
        Example 3: { |x| IIF(x=NIL, Names->Last = cKey, x = cKey)}

     <cKey> is the key to find top condition of WHILE.
        If NIL the entire database is browsed.
        cLast  := "JONES     "
        cFirst := "A"
        Example 1: cKey := cLast
        Example 2: cKey := cLast + cFirst

     <nFreeze> is number of fields to freeze in TBrowse.  Defaults
        to 0 if not passed.

     <lSaveScrn> is a logical indicating whether or not you want to
        save the screen from the calling program.  Defaults to .T. if
        not passed.

     <cColorList> is a list of colors for the TBrowse columns.
        The 1st color is used as SAY/TBrowse Background and the
        3rd and 4th colors are used as part of column:defColor := {3, 4}

        Thus if you pass a cColorList, you MUST pass at least 4 colors.
        Defaults to "N/W, N/BG, B/W, B/BG, B/W, B/BG, R/W, B/R" if not
        passed.

     <nTop>, <nLeft>, <nBottom>, <nRight> are the coordinates of
        the area to display the TBrowse in.  Defaults to 2, 2,
        MaxRow(), MaxCol() i.e. full screen.

     <bScreenInit> is a code block which calls a routine to initialize the
        screen after it has been cleared. You could place help or mouse hot
        spots on the screen with this routine. If NIL then nothing happens.

     <nReadInit> indicates how a read is initiated. The constants
        GET_ON_RETURN and DOUBLE_CLICK_GET are defined in MBROWSE.CH.
        GET_ON_RETURN indicates that a return will initiate a GET on the
        current field. DOUBLE_CLICK_GET indicates that a mouse double click
        will initiate a GET on the current field. Either one or the sum of
        the two can be used to indicate how to initiate a GET. Passing
        NO_GET or NIL will prevent any editing.
       Example:
            GET_ON_RETURN+DOUBLE_CLICK_GET   will allow both the mouse and
                                             return initiated gets

     <bAltReader> is a code block which is called in place of the internal
        reader when the user requests an edit. If NIL then the internal one
        is called. This gives more flexibility in doing reads and actually
        can be used for functions other than reads (especially with the
        mouse). See the function DoGet for details of what must be passed.

     <nExitKey> is a InKey code of a key which will exit the browse other
        than the escape key which is always active. By default is is set
        to K_RETURN if GETS are not allowed and nothing if they are
        allowed.

     <lAppendMode> indicates if appends to the database are allowed.

     <bAppendReader> is a code block which will perform a read and append
        when the user requests an append. The routine receives no arguments
        but must return the number of records meeting the current while
        condition that were appended to the database. NOTE: if you are
        appending records under a while condition, do not include records
        which you may have added but which do not meet the criteria.

     <bRecordNum> Is an optional code block which will return the
           sequence number of the current record within the current scope
           including the influence of any WHILE clause given to the browse.
           The value is used in presenting the scroll bar. It returns
           the record number of the current record. Unless you are using
           the natural order of the database, this value is NOT equal to
           RECNO(). If the argument is not given, then the default routine
           is used. One might use this routine if one knows, for example,
           that only 1% of a very large database will be used for the
           browse and you have a faster way of counting than the default
           method.

     <bRecordTotal> is an optional code block which returns the total number
           of records which fall under the scope of the browse. Note: if the
           database contains deleted records the value of LASTREC() is
           incorrect if set deleted is on. If no value is given then the
           the default method is used when scroll bars are in use.
 Returns
     <nRecno> is the number of the record selected by the <nExitKey> key.
        0 is returned if there are either no records matching the WHILE
        condition or an <Esc> is pressed instead of an <Enter> or the
        defined exit key.
 Description
     This is a full database browse which implements scoping using an indexed
     database and a WHILE condition. It also supplies mouse support and
     active scroll bars which can be used with the mouse. Additionally, the
     browse will support editing of current records and appending new
     records.
 Examples
     * This example will only show those people with last name of "JONES"
     * in the TBNames.dbf which contains at least the fields:
     * Last, First, City AND is indexed on Last + First.
     LOCAL nRecSel    := 0
     LOCAL aFields    := {}
     LOCAL bWhile     := {||TBNames->Last = "JONES"}
     LOCAL cKey       := "JONES"
     LOCAL nFreeze    := 1
     LOCAL lSaveScrn  := .t.
     LOCAL cColorList := "N/W, N/BG, B/W, B/BG, B/W, B/BG, R/W, B/R"
     LOCAL bInitScreen:= {|| FancyScreen()}
     LOCAL nReadInit := GET_ON_RETURN+DOUBLE_CLICK_GET  // return and dbl clk
     LOCAL bAltReader := NIL  // no alternate reader
     LOCAL nExitKey := K_ALT_E // alt-E will get you out
     LOCAL lAppendMode := .T. // we will be daring and allow appends
     LOCAL bAppendReader := {|| MybrowseReader()} // The reader

     USE TBNames INDEX TBNames NEW // indexed on Last + First

     * Pass Heading as character and Field as Block including Alias
     * To eliminate the need to use FIELDWBLOCK() function in BROWSE()
     AADD(aFields, {"Last Name" , ;
          {|x| IIF(x=NIL,TBNames->Last, TBNames->Last:=x) },.T.  } )
     AADD(aFields, {"First Name", ;
          {|x| IIF(x=NIL, TBNames->First, TBNames->First:=x) },.T. } )
     AADD(aFields, {"City"      , ;
          {|x| IIF(x=NIL, TBNames->City, TBNames->City:=x},.T. } )
     AADD(aFields, {"Zip Code"  , ;
          {|x| IIF(x=NIL, TBNames->City, TBNames->City:=x},.T.,;
          "@R 99999-9999"})

     IF MBROWSE( aFields, bWhile, cKey, nFreeze, lSaveScrn, ;
       cColorList, 3, 6, MaxRow() - 2, MaxCol() - 6, bInitScreen,;
       nReadInit, bAltReader, nExitKey, lAppendMode, bAppendReader) == 0
       ? "Sorry, NO Records Were Selected"
     ELSE
        ? "You Selected: " + TBNames->Last +" "+ ;
           TBNames->First +" "+ TBNames->City
     ENDIF

 Notes: This browse supplies scroll bars with active arrows for both columns
     and rows by default. See BRSetScroll() for how to turn them off.
     Mouse functions: left button on arrow moves one item.
                      Right button on arrow pages up/down or pans left/right.
                      Both buttons on arrow moves to top/bottom
                      Click on data area moves to that item.
                      Double click on item allows edit if programmer desires.
     This system was written with reentrancy in mind but it has not been
          tested for such.

     This browse system will handle calling functions set by SET KEY in the
     normal way. Two return values (defined in mbrowse.ch) are significant.
     REFRESH_CURRENT will cause browse:RefreshCurrent() to be called while
     REFRESH_ALL will cause browse:RefreshAll() to be called after your
     function is complete.

     The information stored about the browse is stored in browse:cargo as an
     array. The file mbrowse.ch contains the defines which allow access to
     this information including the while code block.


 Source: MOUSBROW.PRG

 Author: Leo Letendre