/* $DOC$
   $NAME$
      ft_BrwsWhl()
   $CATEGORY$
      Menus/Prompts
   $ONELINER$
      Browse an indexed database limited to a while condition
   $SYNTAX$
      ft_BrwsWhl( <aFields>, <bWhileCond>, <cKey>,                  ;
                  [ <nFreeze> ], [ <lSaveScrn> ], [ <cColorList> ], ;
                  [ <cColorShadow> ], [ <nTop> ], [ <nLeft> ],      ;
                  [ <nBottom> ], [ <nRight> ] -> nRecno
   $ARGUMENTS$
      <aFields> is array of field blocks of fields you want to display.
         Example to set up last name and first name in array:
         aFields := {}
         AAdd( aFields, { "Last Name" , {|| Names->Last }  } )
         AAdd( aFields, { "First Name", {|| Names->First } } )

      <bWhileCond> is the limiting WHILE condition as a block.
         Example 1: {|| Names->Last == "JONES" }
         Example 2: {|| Names->Last == "JONES" .AND. Names->First == "A"  }

      <cKey> is the key to find top condition of WHILE.
         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.

      <cColorShad> is the color of the TBrowse box shadow.  Defaults
      to "N/N" if not passed.

      <nTop>, <nLeft>, <nBottom>, <nRight> are the coordinates of
      the area to display the TBrowse in.  Defaults to 2, 2,
      MaxRow() - 2, MaxCol() - 2 with shadowed box, i.e. full screen.
   $RETURNS$
      nRecno is the number of the record selected by the <Enter> key.
      0 is returned if there are either no records matching the WHILE
      condition or an <Esc> is pressed instead of an <Enter>
   $DESCRIPTION$
      This is a demonstration of TBrowse with a WHILE condition for an
      indexed database.
   $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 cColorShad := "N/N"

      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 ft_BrwsWhl()
      AAdd( aFields, { "Last Name" , {|| TBNames->Last }  } )
      AAdd( aFields, { "First Name", {|| TBNames->First } } )
      AAdd( aFields, { "City"      , {|| TBNames->City }  } )

      IF ft_BrwsWhl( aFields, bWhile, cKey, nFreeze, lSaveScrn, ;
         cColorList, cColorShad, 3, 6, MaxRow() - 2, MaxCol() - 6 ) == 0
         ? "Sorry, No records were selected"
      ELSE
         ? "You Selected:", TBNames->Last, TBNames->First, TBNames->City
      ENDIF
   $END$
 */