STDBrowse()
 Activate a customizable standard TBrowse
------------------------------------------------------------------------------

 Syntax

     STDBrowse(
        [<nTop>], [<nLeft>], [<nBottom>], [<nRight>],
        [<aColumns>],
        [<cTitle>],
        [<aHotKeys>],
        [<cColorString>],
        [<lLineCursor> | <bHighLight>],
        [<aMenu>],
        [<aColorBlocks> | <bColorBlock>]
        [<bStartUp>],
        [<bEvent>],
        [<lShadow>],
        [<xSeekValue>],
        [<bNoData>]) --> NIL

 Arguments

     <nTop>, <nLeft>, <nBottom> and <nRight> specify coordinates
     for the operation.  They all default to the maximum screen size when
     ommited.

     <cTitle> is the optional title to be displayed in the center of the
     top line of the SDTBrowse.

     When defining a DBF browser <aColumns> is an array filled with the
     column definitions.  Each column definition is an array containing two
     values:  a character string representing the column heading and a
     SET/GET codeblock representing the column contents.  Defaults to all
     fields in the current database.

     When defining an array browser <aColumns> is an array containing either
     a character header and a SINGLE dimension array OR two arrays where the
     first array is a single dimension array containing the the headers for
     the columns and the second is a multi-dimension array containing the data
     to display.  The length of the multi-dimension array would equal to the
     number of rows and each row (element of the primary array) would contain
     another array with a length equal to the number of columns to be
     displayed.

     <aHotKeys> is an optional array containing key stroke handling
     behavior.  Each element contains another two dimensional array which
     has the key scancode number and the corresponding codeblock to be
     evaluated.  When the codeblock is evaluated, it is passed a reference
     to the current STDBrowse object.  Included in here would the remapping
     of the default navigational keys and double-click key of the mouse.

     DEFAULT BEHAVIOUR (listed in priority):

        M_LEFT_BUTTON  if on the data   - go to cell
                       if on a menu     - execute the menu
                       if on status bar - move highlight bar act accordingly
                          - before highlight - page/pan up/previous
                          - after highlight - page/pan down/next
                          - on up arrow - move up
                          - on down arrow - move down
                          - on left arrow - move left
                          - on right arrow - move right

        M_DOUBLE_CLICK
                       if on a menu     - execute the menu
                       if on status bar - move highlight bar act accordingly
                          - before highlight - page/pan up/previous
                          - after highlight - page/pan down/next
                          - on up arrow - goto top of data
                          - on down arrow - goto bottom of data
                          - on left arrow - move to beginning of columns
                          - on right arrow - move to end of columns

        HOT KEY associated with <aMenu> will execute the menu.
        HOT KEY associated with <aHotKeys> will execute its codeblock.

        K_UP           browse:up()
        K_DOWN         browse:down()
        K_RIGHT        browse:right() (default)
                       browse:panRight() (when <lLineCursor> is set to TRUE)
        K_LEFT         browse:left() (default)
                       browse:panLeft() (when <lLineCursor> is set to TRUE)
        K_TAB          move to data or the next menu item when <aMenu> has
                       been provided.
        K_SH_TAB       move to data or the previous menu item when <aMenu>
                       has been provided.
        K_PGDN         browse:pageDown()
        K_PGUP         browse:pageUp()
        K_CTRL_PGDN    browse:goBottom()
        K_CTRL_PGUP    browse:goTop()
        K_HOME         browse:home()
        K_END          browse:end()
        K_CTRL_LEFT    browse:panLeft()
        K_CTRL_RIGHT   browse:panRight()
        K_CTRL_HOME    browse:panHome()
        K_CTRL_END     browse:panEnd()
        OTHER          passed to <bEvent>

     <cColorString> is an optional character string containing the color
     sets to be used by STDBrowse (browse:colorSpec).  At least 4 color
     combinations must be provided.  The color sets are used as follows:

        1     The color for the boarders and status bars.

        2     The color for the title.

        3     The color for the data when the highlight bar is not on it.

        4     The color for the data under the highlight bar.


     The default color string is "W+/B, B/W, W+/B, B+/W, W/B, B/W".

     <lLineCursor> | <bHighLight> is an option parameter which when it is
     <lLineCursor> it is used to signal the turning on of the whole line
     highlight bar rather than just the individual cell.  When <bHighLight>
     is sent the highlight bar is alwways off and <bHighLight> is called to
     do the highlighting.  A reference to the current STDBrowse is passed to it
     when it is evaluated.

     <aMenu> is an optional array containing prompt arrays to be used by
     STDBrowse.  STDBrowse places the prompts (menu items) at the top of the
     browse.  The prompt array needs to contain three elements:

        1     A character string representing the prompt.  By placing a
              tilde (~) before a letter in the prompt will cause the ALT
              value of that character to be the associate hot key for that
              menu item.  The hot key character is highlighted (for colors
              see the section on SetMenuColor()).

        2     An optional codeblock used as the ACTION (see the section on
              MENU TO).  The action codeblock MUST return a logical TRUE
              or False.  A TRUE informs STDBrowse to continue and a FALSE
              tells STDBrowse to abort.  The action codeblock receives a
              reference to the current browse.

        3     An optional codeblock used to determine if the menu item is
              selectable.  It receives a copy of the current STDBrowse and
              it must return a TRUE (accessible) or FALSE (unaccessible).

     <aColorBlocks> | <bColorBlock> is the optional parameter used by the
     columns as their column:colorBlock instance variables.  If
     <aColorBlocks> is used an array the same length as <aColumns> is
     expected.  Each element would contain the column:colorBlock for the
     corresponding column in <aColumns>.  If <bColorBlock> is sent then
     <bColorBlock> is used for each column.  <bColorBlock> is expected to
     return an array containing two numbers, the first is used to point to the
     browse:colorSpec color when the data is not highlighted and the second
     to the color when it is highlighted.  NOTE the <bColorBlock> must take
     into consideration when the highlight bar is on the data or on a menu item
     (if <aMenu> is used).  To determine if focus is on the data or a menu
     item there is a function called TB_OnData() which returns a TRUE when
     data is in focus and FALSE when the menu is.

     <bStartUp> is an optional codeblock which is evaluated at the start up of
     the STDBrowse().  The <bStartUp> codeblock is passed a copy of the
     browse object just before the first stabilize().  This allows the
     programmer an opportunity to modify the browse before commencing.

     <bEvent> is an optional codeblock which will be evaluated receiving the
     current browse and key stroke.  This is evaluated after the STDBrowse
     has looked at the key stroke and was not able to use it.  For example
     if you wanted a standard ASCII key stroke to act as a locator to move to
     another record starting with that letter you would apply the TB_Seek()
     in your custome <bEvent>.  The return value of <bEvent> is ignored.

     <lShadow> is an optional parameter indicating if the STDBrowse is to
     be shadowed or not.  Default is determined by SetShadow().

     <xSeekValue> is an optional parameter which is used as the key to
     restrict the data set.  This is only good on indexed files and it can
     be any expression as long as it matches the index.  This is only
     applicable with a DBF browser.

     <bNoData> is the optional codeblock which is executed when there is
     no data in the data set.  This is a an ERROR situation which <bNoData>
     is used to correct.  It MUST retrun a logical TRUE or FALSE.  TRUE if
     problem has been fixed (data appended, etc.) or FALSE if it was not
     rectified.  A return of TRUE continues and a return of FALSE aborts.
     This is only applicable with a DBF browser.

 Eample:

 FUNCTION TBDemo()

 LOCAL x, aColumns := {}
 LOCAL aMenu := { {"~Next_Key",{|| TB_NextKey()},},;
                  {"~Previous_Key",{|| TB_PreviousKey()},},;
                  {"~Last_Name",{|browse| GetLast( browse )},},;
                  {"~Birthday",{|browse| GetDOB( browse )},},;
                  {"E~xit",{|| FALSE},} }

 // As an example of custom highlight bar send this ss the line indicator
 LOCAL bHiLite := { |browse| browse:colorRect(  { browse:rowPos, ;
                     browse:leftVisible, ;
                     browse:rowPos, browse:rightVisible }, ;
                     IIF( TB_OnData(), { 4, 4 }, { 6, 6} ) ) }

 LOCAL cOldMenuColor := SetMenuColor("W/B,B/W,N+/B,W+/B")
 USE CUSTOMER INDEX CUSTPROV /* indexed by province code and customer */
 FOR X:= 1 TO 10 // first 10 only

    AADD(aColumns,{FIELDNAME(x),FIELDBLOCK(FIELDNAME(x))})

 NEXT x

 STDBrowse( 10, ;
            2, ;
            MAXROW() - 2, ;
            MAXCOL() - 2, ;
            aColumns, ;
            " TOMBSTONE ", ;
            , ;
            "W+/B, B/W, W+/B, B+/W, W/B, B/W, W+/R, R+/W, W/R, R/W", ;
            , ;
            , ;
            , ;
            aMenu, ;
            , ;
            , ;
            "ON", ;
            , )

 USE

 SetMenuColor( cOldMenuColor )

 RETURN NIL


 Files:  Library is CUACLIP.LIB.