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

 twRABrowse( wT, wL, wB, wR, aArray, aColumns, cTitle,;
             lEditFlag, aActionKeys, wColor,;
             wSType, wFType, wFColor, lScBar, lAlite,;
             nFreeze, lStabilize, bPreRun, bPostRun,;
             nExitKey, lBarOn, aSeparators,;
             aAppend, lSound, lWindow )
 ----------------------------------------------------------------------------

     twRABrowse() is a powerful function allowing the programmer
     practically unlimited choice in defining its mode of operation. It
     arose out of the need for an all-purpose array browser for
     construction of various order entry and invoicing systems.

     There is built in mouse support, 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 twRABrowse() 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 element in the current
                                 array, otherwise, exit the browse.
                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. The
     ability to edit and append in an array browser allow you to, for
     instance, create invoices without reference to a database and
     throw them away if they are not used. Naturally, inventory
     management must still be done. Ahhrghh!

     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 line.
          Right Button: Page Up or Down.
          Both Buttons: Top or Bottom of array.

       Shaded Area: Move to Relative array 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 element.
           Double Click: Edit element.

         lEditFlag is FALSE:

           Single Click: Move to element.
           Double Click: Select element and
                         EXIT.

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

       Arguments:

     aArray      - 'A' The array to browse: single or multi dimensional.

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

                       Each element in the column array passed to
                       twRABrowse() 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, nClm, nWid, cFoot, ;
                                         lEdit, cPic, bWhn, bVld, ;
                                         bRdr, aClr, bClr, cCsep, ;
                                         cHsep, cFsep })
                          Where:

                          1 - cHead - Browse Column Header
                          2 - nClm  - Browse Array Column for
                                        Multi Dimensional Arrays
                          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

                      NOTE: For arrays of single dimension, nClm
                            becomes zero automatically. For Multi-
                            Dimensional arrays, nClm is found from the
                            structure:

                            aArray := { "xxxxx", "xxxxx", "xxxxx",... }
                              nClm :=      1        2        3    etc.

                      The Get Reader may be configured to allow cursor
                      movements after editing columns or to keep the
                      cursor out of columns. twRABrowse() can therefore
                      be configured to behave as a spreadsheet by
                      adding suitable auxiliary functions.

                      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.

                      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. However, when appending or
                      deleting from arrays, other concerns must be
                      taken into account. The internals of twRABrowse()
                      depend on an up to date knowledge of the length
                      of the array and the current element. There are
                      associated functions to allow you to perform
                      these additional housekeeping chores:

                        twRAGetBrowse()
                        twRAGetElement()
                        twRAGetCurrent()
                        twRAGetArray()
                        twRASetArray()

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

     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.

     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.

     aAppend     - 'A/C' If you wish to allow appends to the array
                         being browsed, you must pass an empty element
                         with which to do the append. In th case of a
                         one dimensional array, the element will be a
                         string. For multi-dimensional arrays, it will
                         be one element.

     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.

       Return:

     Selected array element or zero for no selection. If you require a
     different return, use twRAGetArray() with bPostRun.

       Example:

     This example is taken from an actual application.

     FUNCTION ShowEdit( aShowCol, aGetSpots, aShowSpots )
     LOCAL f, bK_F2 := SETKEY( K_F2, NIL ), g
     LOCAL bK_F3 := SETKEY( K_F3, NIL )
     LOCAL bK_F10 := SETKEY( K_F10, NIL )
     LOCAL aActionKeys := {}
     aShowSpots := {}

     // Disable the hot spots from the caller.
     FOR F = 1 TO LEN( aGetSpots )
         twRESpotOff( aGetSpots[ F ] )
     NEXT

     IF twOKMouse()
          // hide the mouse
          // TSDWIN functions with mouse support
          // assume the mouse is off on entry
         _twM2()
     ENDIF

     // add the hot spots
     AADD( aShowSpots, twRAHotSpot( 24, 00, 24, 24,;
            {|| ShowSelect( aShowSpots ), ;
                    twRABarDisp() }, 1,, .T. ))
     AADD( aShowSpots, twRAHotSpot( 24, 28, 24, 43, ;
            {|| RowDel( 1 ) }, 1,, .T. ))
     AADD( aShowSpots, twRAHotSpot( 24, 46, 24, 67, ;
            {|| __keyboard( CHR( K_ENTER )) }, 1,, .T. ))
     AADD( aShowSpots, twRAHotSpot( 24, 70, 24, 77, ;
            {|| __keyboard( CHR( K_ESC )) }, 1,, .T. ))

     // add the actionkeys
     AADD( aActionKeys, { K_F10, {|| ShowSelect( aShowSpots ),;
                            twRABarDisp() } })
     AADD( aActionKeys, { K_DEL, {|| RowDel( 1 ) }})

     // add actionkeys to stop cursor right
     AADD( aActionKeys, { K_RIGHT, {|| NIL }})
     AADD( aActionKeys, { K_CTRL_RIGHT, {|| NIL }})
     AADD( aActionKeys, { K_END, {|| NIL }})

     // display selection list and hot spots
     twInfoLine( -2, ".F10..List and Select Shows " +;
                 .DEL.. Delete Show  " +;
                 .ENTER/ALPHA..Enter Show  .ESC..Done",  "P" )

     // browse the array. Appends allowed.
     twRABrowse( 11, 0, 23, 40, aShow, aShowCol,, ;
                 .T., aActionKeys, MCOLORN, 0, YFRAME, ;
                 MCOLORFN, .T., .T., 2, .T. ;
                 ,,,,, { "---", " | ", "" }, ;
                 { "  ", SPACE( 30 ) } )
     twAMPop()

     // release  hot spot handles
     FOR F = 1 TO LEN( aShowSpots )
         twRARemHotSpot( aShowSpots[ F ] )
     NEXT

     ASORT( aShow,,, {|x,y| x[ 1 ] < y[ 1 ] } )

     FOR F = 1 TO LEN( aShow )
         @ 13 + F, 2 SAY aShow[ f, 1 ] + ;
                 "   | " + aShow[ f, 2 ]
         IF f = 9
             EXIT
         ENDIF
     NEXT
     IF f < 9
         FOR g = f to 9
             @ 13 + g, 2 SAY SPACE( 5 ) + "|" +  SPACE( 30 )
         NEXT
     ENDIF
     SETKEY( K_F10, bK_F10 )
     SETKEY( K_F3, bK_F3 )
     SETKEY( K_F2, bK_F2 )
     IF twOKMouse()
         // show the mouse
         _twM1()
     ENDIF

     // Enable the hot spots
     FOR F = 1 TO LEN( aGetSpots )
         twRESpotOn( aGetSpots[ F ] )
     NEXT

     RETURN NIL