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

HELPBROW()

    HELPBROW() is perfect for basic data validation from a lookup file.
    It pops up a scrolling list of all valid entries, along with
    optional descriptions.  You simply point-and-shoot to insert a value
    into the desired memory variable.  Plus, if the variable is
    character-type, HELPBROW() provides an additive quick search
    facility to zoom in on the desired value.

    Syntax (Summer '87)

    HELPBROW(<search area>, <return field>, <heading 1>, [<description>,
             <heading 2>, <box color>, <row coord>, <col coord>]
             [,<top>, <left>, <bottom>, <right>, <message row>])

    See below for the Clipper 5.0 syntax, which is slightly different.

    Required Parameters

    <search area> is a character string representing the work area to
    use for the SEEK.  Obviously, this database should be opened prior
    to calling HELPBROW(), else the heartbreaking "Type Mismatch" will
    ruin someone's day.

    <return field> is a character string representing the name of the
    field to be returned from the search area.  DO NOT include the alias
    when specifying this parameter; for example, use 'CODE' rather than
    'TYPES->CODE'.

    <heading 1> is a character string representing the heading to be
    used for the first column of the browse window.

    Optional Parameters

    <description> is a character string representing the name of a
    secondary field to be displayed in the browse window.  As with the
    return field parameter, do not include the alias.

    <heading 2> is a character string to be used for the heading of the
    second column of the browse window.

    <box color> is a character string representing the color with which
    to draw the browse window.  The default is a pleasant white on blue.

    If you wish to display the secondary field on the screen after
    validation, use parameters <row coord> and <col coord> as the row
    and column coordinates, respectively, at which to display it.

    The coordinates for the browse window will be calculated
    automatically so as to be centered on the screen.  Likewise, the
    user prompt will appear on row 21.  However, you may override this
    feature by explicitly specifying where you would like the box and
    prompt to appear by using the next five optional parameters.

    <top> is an integer representing the top row of the box.

    <left> is an integer representing the leftmost column of the box.

    <bottom> is an integer representing the bottom row of the box.

    <right> is an integer representing the rightmost box column.

    <message row> is an integer numeric representing the row at which to
    display the user prompt (default is 21).

    Return Value

    HELPBROW() returns True (.T.) if the variable in the READ is found
    in the look-up database or if the user selects one of the values
    shown in the browse window.  It returns False (.F.) if the user does
    not enter a value that is found in the look-up database.

    Sample Usage

    Let's suppose that you want to keep track of the gender of everyone
    in your 250,000 record rolodex database (you must be very popular).
    You thoughtfully design the field GENDER as character type with a
    length of one to save space, and create a small look-up database
    entitled GENDERS.dbf, which contains the following four records:

    Type     Description
    M        Male
    F        Female
    N        Neuter
    H        Hermaphrodite

    You want to display the full gender description on the data entry
    screen right next to the field GENDER.  This is how you could write
    the call to HELPBROW():

    @ 16,10 GET mGENDER PICTURE '!' VALID HELPBROW('genders', 'type', ;
                           'TYPE', 'descrip', 'DESCRIPTION', '', 16,13)

    Now, if your user enters 'E' (for Eunuch??), he/she/it will be
    confronted with a window showing the four valid entries and will be
    prompted to select one.  They will not be able to proceed until they
    do so.  Once they select a value, the verbose description will be
    displayed at row 16, column 13 for reference.

    Quick-Search: if the index key in the search area is of character
    type, quick-search will automatically be activated.  This allows the
    user to jump quickly to values by typing in the first few letters of
    the desired value. For example, searching for the code 'RPG' could
    prove quite tedious in a 100-record database, but with quick-search
    the user need only type in the letters 'R' and 'P' to jump directly
    to it.  Your users will love it!

    Please note that for performance considerations, this search will
    only operate with indexed files.

    Clipper 5.0 Notes

    The 5.0 syntax is slightly different:

    HELPBROW(<search area>, <return field>, <heading 1>, [<description>, ;
             <heading 2>, <editable>, <box color>, <row coord>, <col coord>] ;
             [,<top>, <left>, <bottom>, <right>] )

    If the user inputs a code that does not exist in your lookup
    database, they can now press F10 to add it to the lookup database.
    This will only work if you have specified a <description>, because
    HELPBROW() needs to know that field so it can prompt the user to
    enter a value for it.  The function will then append a record to the
    database which will contain the new code and description.  (Can you
    remember sweating bullets trying to write this in Summer '87?  I
    surely can.)

    The sixth parameter, <editable>, is a logical that determines whether
    or not you wish to allow the user to add codes in this fashion. The
    default is True (able to add), so if you do not want to let them add,
    be sure to pass a False (.F.) as this parameter.

    Here is an example demonstrating this new parameter.  The user
    is not permitted to add new codes to the lookup database:

    local mstring := space(3)                           
    @ 20,0 get mstring valid helpbrow('lookup', 'code',;
             'Code', 'descrip', 'description', .F.)     
    read                                                

    Other new functionality: if the lookup database is not already open,
    HELPBROW() will open it and then close it prior to exit.