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

 twBRBrowse( wT, wL, wB, wR, aColumns, cTitle,;
             cTopKey, bScopeBlock, lEditFlag,;
             aActionKeys, wColor, wSType, wFType,;
             wFColor, lScBar, lMsgs, lAlite, nFreeze,;
             lStabilize, bPreRun, bPostRun, nExitKey,;
             aSeparators, lOKAppend, lSound, lWindow,;
             bBarColor, aSrch )
 ----------------------------------------------------------------------------

     twBRBrowse() is a very flexible, completely configurable, mouse
     driven database handler. It and twRABrowse() are the central
     functions in the TSDWIN browse system. The programmer has complete
     control over column definitions and keystroke handling, as with
     other TSDWIN browses.

     There is built in mouse support, scoping and the ability to pass
     executable code to the function through the use of actionkeys. You
     may also obtain  a reference to the browse and its full cargo
     structure, and modify its behaviour on the fly.

     The default keystroke handling in twBRBrowse() can be overridden by
     assigning ActionKey blocks to replace the defaults. ActionKeys are
     processed BEFORE the default keystroke handler. This method was
     deemed easier for programmers than the method of passing an entire
     ApplyKey function.  Both methods will be made available in a
     future release. The defaults vary according to the Autolite
     setting:

       Keystroke Handling:

                Up Arrow ---------+
                Down Arrow        |
                Left Arrow        |
                Right Arrow       |
                Page Down         |- Scroll the Highlight Bar in
                Page Up           |  the normal way.
                Ctrl Page Down    |
                Ctrl Page Up      |
                Ctrl Left Arrow   |
                Ctrl Right Arrow  |
                Ctrl Home         |
                Ctrl End ---------+

                Escape         - Exit with no choice.
                Enter          - If EditFlag is .T., allow editing of
                                 the current field in the current
                                 record, otherwise, exit the browse.
                Alpha Keys     - Speed Search (See aSrch).
                Back Space     - Reset Search String to empty. Any
                                 cursor key movement which moves the
                                 record pointer will also reset the
                                 search string.
                F1             - Display default keystroke handling.
                F8             - Swap current column with the one on
                                 the left.
                F7             - Delete the current column from the
                                 display.
                F9             - Subtract one to the count of columns
                                 on the left which are frozen. The
                                 freeze value defaults to 0.
                F10            - Add one to the count of columns
                                 on the left which are frozen. The
                                 freeze value defaults to 0.

        If lAlite is False, the right and left arrow keys pan the
        browse. If it is true, the cursor is moved one column.

     The built in Get System allows the user to perform gets on the
     entire browse or only on selected columns. The ability to define a
     reader makes the browse totally configurable to your needs.

     An append mode is included, but editing and appending to databases
     is best performed by executing the task through ActionKeys.

     Both vertical and horizontal scrollbars are available. If you
     allow scrollbars, the horizontal one is displayed only if the
     entire browse will not fit within the window.

       Mouse Support:

     The default mouse support varies according to the value of
     lEditFlag.

     When the browse is internally configured, two mouse hot spots may
     be defined. The hot spots will cover the area occupied by the
     scrollbars. If scrollbars are allowed, the mouse actions are:

     Vertical Scroll Bar:

       Direction Arrows:

           Left Button: Up or Down one record.
          Right Button: Page Up or Down.
          Both Buttons: Top or Bottom of File.

       Shaded Area: Move to Relative File
                    Position.

     Horizontal Scroll Bar: Left Button

       Shaded Area: Move to Relative Column
                    Position.

        lEditFlag is TRUE:

           Direction Arrows: Right or Left One
                             Column.

        lEditFlag is FALSE:

           Direction Arrows: Pan Right or Left.

     Browse Table:

     Right Button: Escape with no choice.

      Left Button:

         lEditFlag is TRUE:

           Single Click: Move to Field.
           Double Click: Edit Field.

         lEditFlag is FALSE:

           Single Click: Move to field.
           Double Click: Select Record and
                         EXIT.

     You may add your own mouse actions to the browse with
     twBRHotSpot().

       Arguments:

     wT,wL
     wB,wR       - 'N' Screen coordinates at which to display the
                       browse. The defaults are:

                         0, 0, MAXROW(), MAXCOL()

     aColumns    - 'A' An array of column definitions to browse.

                       Each element in the column array passed to
                       twBRBrowse() MUST have at least TWO elements.
                       One is for the column header and the other for
                       the block used to display the data. Six other
                       elements are possible, but are not necessary.
                       One is the column width and the others define
                       and modify the get system in the browse.

                       The following is the array structure used to
                       pass columns to the browse:

                       Column Structure to Pass in aColumns:

                       AADD( aColumns, { cHead, bBlk, nWid, cFoot, ;
                                         lEdit, cPic, bWhn, bVld, ;
                                         bRdr, aClr, bClr, cCsep, ;
                                         cHsep, cFsep })
                       Where:

                       1 - cHead - Browse Column Header
                       2 - bBlk  - Browse Column Block for Data
                       3 - nWid  - Optional Column Width
                       4 - cFoot - Browse Column Footer
                       5 - lEdit - Optional Logical to Allow Edits
                       6 - cPic  - Optional Picture for Gets
                       7 - bWhn  - Optional When Block for Gets
                       8 - bVld  - Optional Valid Block for Gets
                       9 - bRdr  - Optional Reader Block for Gets
                      10 - aClr  - Browse Column DeFColor
                      11 - bClr  - Browse Column Colorblock
                      12 - cCsep - Browse Column Separator to left
                      13 - cHsep - Browse Column Head Separator
                      14 - cFsep - Browse Column Foot Separator


                      The block definition should take the form of a
                      get-set block  to allow the database field to be
                      updated, IF you allow editing.  Such a block is
                      of the form:

                      {|x| IIF( x == NIL, cField, cField := x ) }

                      NOTE: If you are allowing direct edits on the
                      database in a network situation, the column block
                      MUST include the necessary record locking checks
                      to allow updating, eg.,

                      {|x| IIF( x == NIL, cField, ;
                           IIF( yLock( n ), cField := x, ;
                                dbUnlock() ), .F. )}

                      The Get Reader may be configured to allow cursor
                      movements after editing columns or to keep the
                      cursor out of columns.

                      NOTE: The get system will operate only if the
                      lEditFlag is set to true in the function call. If
                      it is, individual columns may be excluded from
                      editing by setting the fourth element, lEdit in
                      the column definition to False.

                      NOTE: If you use the append mode, all False
                      column definitions of lEdit become True.
                      Therefore, if appends are allowed, pictures,
                      whens, valids and readers may have to be assigned
                      to columns which are normally NOT editable. They
                      will be editable during appends.

                      NOTE: Append should be allowed only if there is
                      no scope imposed on the database with cTopKey and
                      bScopeBlock.

                      It is recommended that the edit, and especially
                      the append mode be reserved for 'down and dirty'
                      situations. The use of ActionKeys will allow you
                      to process database edits and appends much more
                      satisfactorily.

     cTitle      - 'C' Optional Title for the browse. See also bPreRun.

     cTopKey     - 'C' First index key for scoped browses. The default
                       is the first record in the key.

     bScopeBlock - 'B' Code block to evaluate in order to determine if
                       a record is within the scope, eg.,

                       bScopeBlock := {|x| IIF( x=NIL,
                                LEFT( Windemo->CodeShort:, 1 ) == cTopKey,
                                LEFT( x, 1 ) == cTopKey )}

                       The bScopeBlock is best set up  as a get/set
                       block with exact matching.

                       The default scope is all records.

     lEditFlag   - 'L' Logical to allow editing of fields. If you are
                       working in a network environment it is best to
                       edit records through the use of ActionKey
                       procedures, but you may include your network
                       file or record locking functions in the
                       individual column definitions or by replacing
                       the default keystroke handling where necessary
                       by passing ActionKeys to override the defaults.
                       The default is .F.

     aActionKeys - 'A' An array of keys and code blocks to be executed
                       during the browse.

                       ActionKeys provide a means to pass executable
                       code to a browse. The information is passed in
                       an array where each element is a two element
                       array:

                        AADD( aActionKeys, { nKey, bBlock } )

                        Where: nKey   - key number to assign
                               bBlock - code block to execute

                       If you are using SET Keys, you should save any
                       of them which might  conflict with your
                       actionkeys before calling the browse, then
                       restore them on return.

     wColor      - 'C' Clipper colour string with which to configure
                       the browse. In order to be consistent with other
                       functions in TSDWIN, wColor must be passed as a
                       Clipper colour string. The minimum acceptable is
                       NIL, in which case the colour defaults to the
                       current SETCOLOR(). You must ensure that
                       SETCOLOR() is a full length colour string if you
                       do this.

                       The basic format for passing a colour is:

                            "x,x,,x,x"

                       TSDWIN uses the first two elements in the list
                       as the standard and enhanced colours for the
                       browse, and ALWAYS the last one for the
                       unselected colour, no matter how long your
                       colour string is. In a future release of TSDWIN,
                       all colours will be passed to all functions as
                       colorspecs.

                       You may want to pass more complicated colorspecs
                       if you choose to enhance your browse through the
                       column definitions.

     wSType      - 'N' TSDWIN Shadow type. The default is 0.

     wFType      - 'N' TSDWIN Frame type. The default is 1.

     wFColor     - 'C or A' If a character value is passed, it becomes
                            the frame colour for active and inactive
                            windows.  If an array is passed, the first
                            element is used for active windows and the
                            second for inactive. If you are opening
                            other windows through ActionKeys, it is
                            recommended you use an array for this
                            parameter. wFColor defaults to the current
                            window colour.

     lScBar      - 'L' Logical for Scroll bar display. If this is set
                       to .T., a vertical bar is always displayed but a
                       horizontal bar is displayed only when the
                       columns in the browse will not fit into the
                       window. The default is .F.

     lMsgs       - 'L' Logical to display 'Wait' messages if the browse
                       is performing some type of time consuming
                       action. The default is .F.

     lAlite      - 'L' Logical to allow individual field highlighting.
                       If .T. the normal Clipper field highlighting is
                       followed. If .F., the highlight bar extends
                       across the entire window, including the column
                       separators. The default  is .F., ie., NO field
                       highlighting.

     nFreeze     - 'N' The initial number of columns to freeze. The
                       default is 0.

     lStabilize  - 'L' The TBrowse Stabilize() method allows users to
                       break out of the stabilization process if a key
                       is pressed, thereby allowing the user faster
                       response on key presses. However, not all users
                       like the results when this is allowed. The
                       display will go blank in the browse window as
                       long as the user holds down a navigation key for
                       up or down movement. The lStabilize parameter
                       indicates whether or not carry out stabilization
                       to completion before processing the next key
                       press. The default is .F., indicating NOT TO
                       FINISH STABILIZING the browse as keys are
                       pressed. For large databases, the difference in
                       speed is very noticeable. The default is .F.

     bPreRun     - 'B' You may pass in a code block to execute before
                       the browse begins. For instance, the default
                       title colour in the browse is the standard text
                       colour. bPreRun allows you to change this by
                       leaving cTitle as NIL and creating:

                         bPreRun := {|| twTitle( "Title", YourColor" )}

     bPostRun    - 'B' This parameter acts like the PreRun block but is
                       executed after leaving the browse before the
                       browse window is popped if there is one.

     nExitKey    - 'N' The default exit keys are ESC and ENTER ( if
                       editing is disallowed ). You may wish to change
                       the behaviour of a browse with an ActionKey,
                       Therefore provision is made here to allow a
                       different key to provide an escape sequence.
                       Many users choose K_ALT_X to exit as it is used
                       in most CUA systems.

     lBarOn      - 'L' lBarOn defaults to .T. and indicates whether or
                       not the highlight bar is to be displayed when
                       AutoLite is set to off. If you set it to .F.,
                       you can use this browse to scan text files which
                       you have stored in an array.

     aSeparators - 'A' An optional three element array of browse
                       separators. If this parameter is passed, it must
                       take the form:

                         { HeadSep, ColSep, FootSep }

                       Column definitions may be used to override this
                       parameter.

     lOKAppend   - 'L' Logical to allow appends to the database. This
                       parameter, if TRUE, allows appending similar to
                       DBU. You must do the append at the end of the
                       browse. It is suggested that you use an
                       ActionKey for editing and appending to a
                       database. You have much better control that way.

     lSound      - 'L' Logical to allow a tone at HitBottom and HitTop.

     lWindow     - 'L' lWindow indicates whether you want the function
                       to open a window in which to display the browse.
                       You may wish to create a browse in part of a
                       window. lWindow allows you to do this. If
                       lWindow is set to .F., no window is displayed
                       and the browse fills the entire coordinate area.

     bBarColor   - 'B' Optional code block for the highlight bar color.
                       This parameter allows you to define a highlight
                       bar colour dependent on a logical condition,
                       eg.,

                       LOCAL nBar1 := twVAttr( aBarColor[ 2 ] )
                       LOCAL nBar2 := twVAttr( aBarColor[ 5 ] )

                       bBarColor  := ;
                       {|| IIF( Members->Active, nBar1, nBar2 ) })

     aSrch       - 'A' Five element array which defines the search key
                       handling. aSrch must have the structure:

                       aSrch := { Column number on which to search, ;
                                  Optional colour for the highlight
                                      bar search string display,;
                                  Optional code block for search the
                                      database,;
                                  Optional mask for the search
                                      display,;
                                  Optional prefix to apply to the
                                      search string for scoped browses. }

                       The element descriptions are:

                       1 - The column number is simply the member of
                           aColumns which contains your index key.

                       2 - The current search string will be
                           highlighted within the highlight bar for the
                           browse. You may specify a colour or use the
                           default.

                       3 - The code block uses the current search
                           string as a parameter. Therefore it must be
                           of a form to properly locate keys in the
                           index. The default is to apply UPPER() to
                           the search string. You may make adjustments
                           for the method you used to create  your
                           index.

                       4 - A mask for the display to compensate for
                           differences in the index key and the
                           displayed values. For instance, if you store
                           phone numbers as:

                                4166285086 in the file.

                           Then you use:

                                TRANSFORM( cPhone, ;
                                           "@R (999) 999-9999" )

                           to display them. The mask would be:

                                "X   XX   X    "
                                 (999) 999-9999

                           X's or any character can be used in
                           positions where displayed data is not the
                           actual information if the database.

                       5 - If you are operating a scoped browse, all
                           the displayed records have keys starting
                           with the same character sequence. You may
                           pass this sequence to the search mechanism
                           so the highlighting will match the display.
                           For instance, if you are indexed on phone
                           number and scope to all records in the 416
                           exchange, your search prefix would be:

                                "416"

                       If aSrch is not passed, the default search
                       mechanism is:

                           1 - Search on column 1 of the browse.
                           2 - Clipper unselected colour.
                           3 - {|c| UPPER( c ) }
                           4 - SPACE( LEN( &(INDEXKEY())))
                           5 - Empty string.

                       You can turn off searching by passing .F. in place
                       of aSrch.

       Return:

     RECNO() or Zero for no choice. If you require another type of
     return, you can get it with bPostRun.