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

GRUMPBROW()

    At first glance, this may appear to be just another generic database
    browser.  But think again, because GRUMPBROW() also includes generic
    add, edit, delete, view, search, and query-by-example routines, and
    is structured so that you can provide any combination of these
    features to the user.  But that's not all... GRUMPBROW() includes a
    screen painter so that you can crank out quick data entry screens
    (working from the generic template it provides).  And if that is not
    enough for you, you can even generate the source code for the
    screens you design with the screen painter!

    Syntax

    GRUMPBROW([<security>, <top>, <left>, <bottom>, <right>, <box>, ;
               <fields>, <heads>, <pictures>, <alternates>, <low range>, ;
               <high range>, <vertical block>, <horizontal block>])

    Parameters shown in bold apply only to the Clipper 5.0 version.
    (See below for the syntax of the APICK user-defined command.)

    Optional Parameters

    <security> is a character string that defines the security level you
    want to give your users.  Case is not significant. You pass the first
    letter of each feature that you wish to activate:

    A    Add
    E    Edit
    D    Delete
    P    Screen Painter (option not displayed)
    Q    Query by example
    S    Search*
    V    View
    N    do Not allow individual field edit (see below)


    Note that even if you include the letter "P" to activate the screen
    painter, that option will not be displayed.  This is because most
    users should not be allowed to know too much!

    If you do not pass this parameter, all the user will be able to do is
    browse vertically and Esc when they are finished (wouldn't it be
    funny if we didn't even let them do THAT?).

    *If no index file is open, or if the index key is not of character
    type, you will not be able to Search, regardless of whether or not
    you pass an "S" in the <security> parameter.

    <top>, <left>, <bottom>, <right> are numerics that delineate the
    screen region to be used for the browse.  The default values are 0,
    0, 23, and 79, respectively.  (Row 24 is used for menu prompts.)

    <box> is a logical value that indicates whether or not you want the
    browse area to be surrounded by a box.  This is purely for aesthetic
    purposes.  The default is yes, so pass .F. if you do not want one.

    <fields> is an array containing the fields to show in the browse. If
    you do not pass this, all fields in the currently active database
    will be displayed.  Use a null string if you do not wish to use this
    parameter.

    <heads> is an array containing column headings to be used for the
    browse.  If you do not pass this, the fieldnames will be used as
    column headings.  Use a null string if you do not wish to use this
    parameter.

    <pictures> is an array containing PICTURE clauses corresponding to
    each field.  You may use this if, for example, you wish to truncate
    certain fields or use "Y" for logicals.  If you do not pass this
    parameter, GRUMPBROW() will establish default PICTURE values for each
    field that conform to the general norm.  Use a null string if you do
    not wish to use this parameter.

    <alternates> is a six element array.  Pass this if you want to
    override the default routines.  This array MUST be six elements long,
    and should contain character strings.  The elements correspond to the
    actions as follows:

    alternate_[1] = alternate ADD function
    alternate_[2] = alternate DELETE function
    alternate_[3] = alternate EDIT function
    alternate_[4] = alternate QUERY function
    alternate_[5] = alternate SEARCH function
    alternate_[6] = alternate VIEW function

    Fill ALTERNATE_ with null strings, and redefine only what you need
    to. If for example, you want to use your own Add and Edit routines,
    you could do the following:

    PRIVATE alternate_[6]       
    AFILL(alternate_, '')       
    alternate_[1] = "SpecAdd()" 
    alternate_[3] = "SpecEdit()"

    Then when the user presses "A" to Add, GRUMPBROW() would make a call
    to the module SpecAdd instead of using its generic routine.

    Additional Optional Parameters (Clipper 5 only)

    <low range> and <high range> allow you to restrict browsing
    operations to a subset of records.  These parameters may be of any
    data type - conversion will be handled internally by GRUMPBROW().
    Note that the subset feature works only if you have an index file
    open!  Further note that if you have two indexes open, and wish to
    switch between them using ALT-I, GRUMPBROW() will maintain a
    different data subset for each index!

    <vertical block> and <horizontal block> allow you to hook into basic
    movement in the browse. <vertical block> is relevant to vertical
    movement, whereas <horizontal block> applies to horizontal movement.
    These blocks will be evaluated after the stabilization loop when you
    are moving in the appropriate direction. For example, if you hit the
    up arrow, the vertical block will be evaluated if it exists. Hitting
    the right arrow would cause the horizontal block to be evaluated if
    you are using it.

    Note that upon evaluation the browse object will be passed as a
    parameter to either the horizontal or vertical block.  This enables
    you to tap into the browse to do interesting things. The following
    simple example is meant as a starting point.  Whenever you hit an
    arrow key, the contents of the current cell will be displayed on the
    bottom row.

      #include "grump.ch"                                         
                                                                  
      function main(dbf_file)                                     
      if dbf_file == NIL                                          
         ? "Please pass me the name of a database file!"          
         quit                                                     
      endif                                                       
      use (dbf_file)                                              
      grumpbrow bottom maxrow() - 1 vblock { | b | showcell(b) } ;
                                    hblock { | b | showcell(b) }  
      return nil                                                  
                                                                  
      function showcell(browse)                                   
      @ maxrow(), 0                                               
      dispout( eval( browse:getColumn( browse:colPos ):block ) )  
      return nil                                                  


    Return Value

    Not a darned thing.

    Memo Support

    When adding, editing, or doing a query by example, you will notice
    that memo support is handled quite neatly.  As you go through the GET
    list, when you hit a memo, a small window will open for you to edit
    the memo.

    Security Levels

    GRUMPBROW() is incredibly flexible.  First, it is a snap to define
    different security levels at different parts of the program.  For
    example, you might want to give your users the ability to add and
    edit records at one part of the program, but only view records
    elsewhere.  This is generally a tedious process, but not with
    GRUMPBROW().  All you need do is change the <security> string that
    you pass to the function.

    Search

    If you press "S" to search, and if the current controlling index is
    of character type, you may jump quickly to records by typing in the
    first few letters of the desired value.  For example, searching for
    the name 'MCALLISTER' could prove quite tedious in a 750-record
    database, but with quick-search you need only type in the letters
    "M", "C", and "A" to narrow the scope down considerably.  As letters
    are added to the search string, it is redisplayed centered along the
    bottom row of the browse box (unless the new letter results in a
    value that is not FOUND() in the database).  You may press backspace
    to erase the rightmost character of the search string.

    Note that the search facility only works with upper-case character
    type index keys!  All characters are automatically converted to
    upper-case upon entry.

    Swapping Indexes (Alt-I)

    If you have two index files open, you may switch between them by
    pressing Alt-I.  This means that you could have one index on company
    name and another on last name, and jump back and forth between them
    for searches.

    Query by Example

    By pressing "Q    you can do a query-by-example to find the next
    record matching their specific criteria.  All you need do is fill in
    the blanks.  Fill in as many fields as you want to narrow the search
    criteria. Note that all query-by-example searches are
    case-insensitive.

    If you want to search for a field that contains a certain value, they
    may enter that value surrounded by two periods ("..") on either side.
    For example, if you wanted to find the next record that contains the
    word "STREET" in the address field, you could enter "..STREET.." for
    that field.

    After you perform a query-by-example, the next time you press "Q" you
    will be given the option to repeat the search using the same criteria
    (which will save you the bother of re-entering it).

    Screen Painter

    GRUMPBROW() also addresses the painfully mundane task of data entry
    screens. Not only does it provide you with handsome generic add/edit/
    view screens, but better yet... it allows you to create your own!

    Press "P" from the browse window to activate the screen painter. You
    will be presented with the generic Add/Edit/View record layout. If
    you have already created a screen with the screen painter, you will
    be given that instead.

    At this point, you have the following options:

    Key         Action

    Alt-B       draw box
    Alt-P       change color with interactive color palette
    Insert      toggle Insert mode on/off
    Backspace   destructive backspace
    Delete      delete from cursor position
    Esc         exit without saving changes
    F10         save screen file (.GFS) and exit
    Shift-F10   generate code for this screen
    LtArrow     move cursor left one column
    RtArrow     move cursor right one column
    Home        move cursor to top left
    End         move cursor to bottom right
    Tab         move cursor right five columns
    Shift-Tab   move cursor left five columns
    PgUp        move cursor to top row
    PgDn        move cursor to bottom row
    Ctrl-Left   move cursor to left column
    Ctrl-Right  move cursor to right column

    Boxes may be filled or unfilled.  If you create a filled box, any
    text underneath it will be pulled in, and will be displayed in the
    color of the box.  You may delete boxes by placing the cursor
    anywhere on its outline and pressing Delete. You may resize boxes by
    placing the cursor anywhere on the outline, pressing Enter, and then
    using the arrow keys to drag the bottom right corner to the desired
    location.

    In similar fashion you can delete and move GET fields.  To delete a
    GET, place the cursor on it and press Delete.  To move a GET, place
    the cursor on it, press Enter, and use the arrow keys to move it to
    the desired location.  You cannot place a GET on top of another GET.
    Also, be warned that if you place a GET over static text, the user
    will never see the static text!

    The following speed keys apply when moving GET fields:

    Home         move field to top left
    End          move field to bottom right
    Tab          move field over right five columns
    Page Up      move field to top row
    Page Down    move field to bottom row
    Ctrl-Left    move field to left column
    Ctrl-Right   move field to right column

    When you are finished designing your screen, press F10 to save the
    screen to a Grumpfish Screen (.GFS) file for future use when adding,
    editing, viewing, or query-by-example.  If you do not want to save
    your work, press Esc instead.

    Generating Code

    Press Shift-F10 to generate the code for a standard data entry
    screen based on the screen you have designed.  The code will:

    - paint the static text in the colors you have specified

    - draw any boxes you have created

    - move field contents to memory variables for editing

    - issue a READ command

    - REPLACE the fields with the contents of said memory variables
      (assuming that Esc was not used to terminate the READ)

    Editing One Field

    When the user highlights a field and press Enter, they can edit it
    directly without going to a vertical view.  (This assumes, of
    course, that you have given them Edit privileges.)  If they wish to
    edit the same field in a series of records, they can terminate the
    READ by pressing the down arrow, which will move them down one
    record and pop them immediately into edit mode.

    However, there may be situations when you do not want the user to be
    able to edit an individual field.  In such situations, you should
    include "N" as part of the security parameter.

    Info for Techies

    If you really want to get technical about things, you may be
    interested in knowing that the screen painter maintains all GET
    fields in an array GETS_.  This array is filled with character
    strings, one for each GET, with each string containing the following
    information:

    Byte     Description

     1       row position
     2       column position
     3       length of GET field
    4-13     name of field (padded with trailing spaces)
    14+      PICTURE clause (variable length)

    In similar fashion, all boxes drawn in the screen painter are
    maintained in an array BOXES_. This array is filled with character
    strings, one for each box, with each string containing the following
    information:

    Byte     Description

     1       top row
     2       left column
     3       bottom row
     4       right column
    5-12     box outline string
     13      color (converted to binary)
     14      fill box? ("Y"=yes "N"=no)

    Sample Usage

    There are many different ways to call GRUMPBROW().  Here are a few
    examples to get you started.

    ** quick and dirty                                        
    USE customer INDEX customer                               
    GRUMPBROW('aev')  && allow Add, Edit, View                

    ** passing an array of PICTURE clauses                    
    USE customer INDEX cust1, cust2                           
    * you can switch between the two indexes                  
    * by pressing Alt-I at the browse window                  
    PRIVATE pics_[14]                                         
    pics_[1] = replicate("X", 10)                             
    pics_[2] = replicate("X", 20)                             
    pics_[3] = replicate("X", 20)                             
    pics_[4] = replicate("X", 20)                             
    pics_[5] = replicate("X", 20)                             
    pics_[6] = replicate("X", 10)                             
    pics_[7] = "###-###-####"                                 
    pics_[8] = replicate("X", 1)                              
    pics_[9] = replicate("X", 10)                             
    pics_[10] = "X"                                           
    pics_[11] = "#####"                                       
    pics_[12] = "@!"                                          
    pics_[13] = "!!"                                          
    pics_[14] = "##"                                          
    GRUMPBROW("aevq", 0, 0, 23, 79, .T., '', '', pics_)       

    ** using alternate search and delete routines             
    USE customer INDEX customer                               
    PRIVATE alternate_[6]                                     
    AFILL(alternate_, '')                                     
    alternate_[2] = "MyDelete()"                              
    alternate_[5] = "MySearch()"                              
    GRUMPBROW("ds", 0, 0, 23, 79, .T., '', '', '', alternate_)

    Clipper 5.0 Notes

    - You can now view a subset of records.  There are two ways to do
      this:

      (a) by passing parameters -- the low range would be the 11th
      parameter, and the high range would be the 12th parameter; or

      (b) by pressing Alt-S within the browse window and typing in the
      ranges.

      Note that you obviously must have an index open for this to
      function.

    - Pressing "L" at the browse window will permit you to lock one
      or more columns.

    - The GRUMP.CH header file includes a GRUMPBROW user-defined
      command.  Note that if you wish to use this, you must #include
      GRUMP.CH at the top of your program.

      Syntax

      GRUMPBROW [SECURITY <cSec>] [TOP <nTop>] [LEFT <nLeft>] ;
                [BOTTOM <nBottom>] [RIGHT <nRight>] [NOBOX]   ;
                [FIELDS <aFields>] [HEADINGS <aHeadings>]     ;
                [PICTURES <aPictures>] [ALTERNATES <aAlts>]   ;
                [LOW <low>] [HIGH <high>]

      These parameters are exactly the same as listed above. The big
      advantage to using the user-defined command is that you can use
      optional clauses in any order that you desire.  This means that you
      no longer have to remember the exact order of all the parameters.

    - If there is data off the screen to the left or right, an arrow
      will appear on the bottom row at the left or right side,
      respectively.  This is made possible through the b:leftvisible
      and b:rightvisible instance variables that were added with 5.01.

    - The GETS_ and BOXES_ arrays are now multi-dimensional.  This makes
      GRUMPBROW() faster and cleaner because it no longer needs to
      concatenate everything into one big sloppy character string.

      The structure of GETS_ is:

      gets_[xx, 1]  => row
      gets_[xx, 2]  => column
      gets_[xx, 3]  => length of GET
      gets_[xx, 4]  => field name
      gets_[xx, 5]  => PICTURE clause

      The structure of BOXES_ is:

      boxes_[xx, 1] => top row
      boxes_[xx, 2] => left column
      boxes_[xx, 3] => bottom row
      boxes_[xx, 4] => right column
      boxes_[xx, 5] => box outline
      boxes_[xx, 6] => box color
      boxes_[xx, 7] => fill? (Y = Yes, N = No)

    - If you want to skip parameters, just pass commas rather
      than null strings.  The 5.0 call for the second example
      shown above would be:

      GRUMPBROW("aevq", 0, 0, 23, 79, .T., , , pics_)