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

HELP() / HELPDEV()

    Context-specific pop-up help screens add enormous user-friendliness
    to any program. With the Grumpfish Library, it is easy and even FUN
    to create your own colorful custom help screens.

    There are two stages to the help screen process: development, and
    post-development (release).  The fundamental difference between the
    two stages is that the help screens can only be created during the
    development stage.

    HELPDEV utilizes three files, HELP.DBF, HELP.DBT, and HELP.NTX.
    These files will automatically be created if it cannot find them.
    The structure for HELP.DBF is:

    Field name   Type      Width
    THEPROC      Character    10
    VAR          Character    10
    TEXT         Memo         10
    TOPROW       Numeric       2   0
    BOTROW       Numeric       2   0
    LT_COL       Numeric       2   0
    RT_COL       Numeric       2   0
    BOXCOLOR     Numeric       3   0
    TITCOLOR     Numeric       3   0
    TXTCOLOR     Numeric       3   0
    BOXNO        Numeric       1   0
    TITLE        Character    30
    FTCOLOR      Numeric       3   0 (new for version 3.0)
    FOOTER       Character    30     (new for version 3.0)

    The index key for HELP.NTX is "theproc + var".  (NOTE: previous
    versions of Grumpfish Library used the field PROC.  This has been
    renamed to avoid conflicts with Clipper 5.0, which establishes PROC
    as a reserved word.)

    Development Stage

    To develop the help screens, add these two lines at the top of your
    program:

    EXTERNAL helpdev        && NOTE: required for Summer '87 only!
    SET KEY 28 TO helpdev   && redefine F1 key

    Next, recompile and link your program, because the actual creation
    of the help screens takes place interactively from within your
    program. Then run your program as usual.

    You may create a help screen for any wait state.  Wait state
    commands include ACCEPT, INPUT, MENU TO, MEMOEDIT(), READ, and WAIT.
    Note that although INKEY(0) is not a wait state, the Clipper 5.0
    version of Grumpfish Library includes a function, GINKEY() to help you
    overcome this limitation.  When you are at a wait state where you
    wish to have a help screen, press F1.  If this is the first time you
    have called the HELP function, the program will take a few seconds
    to initialize the HELP database. Three files will be created in the
    default directory: HELP.dbf, HELP.dbt, and HELP.ntx. These files
    should not be deleted!  If you do delete them, any previously-
    created help screens will have to be recreated.

    Assuming that you have not already created a help screen for this
    particular wait state, you will get a help screen with the message:

                           No help text defined...
                 Press F2 to create, any other key to return

    Press F2 to create the help screen text, then type it in exactly as
    you wish it to appear.  Once you are satisfied with the text, press
    Ctrl-W to save it.  Then use the arrow keys to drag the top left
    corner of the box to where you want it on the screen and press
    Enter.  Repeat this process for the bottom right corner of the box.
    You may then drag the entire box using the cursor keys.  Once you
    are satisfied with the placement, you will be asked to select one of
    six available box outlines.

    The next two items are the box title and footer, which may be up to
    30 characters long.  Last, but far from least, is the color palette
    allowing you to interactively select colors for the box outline, box
    title, and help text.  As you use the arrow keys to navigate the
    cursor through the palette, the colors will change instantly,
    allowing you to survey the combinations as you go.  The current
    color will blink so that you don't get lost!

    When you have defined your help screen, it will be painted upon the
    original screen with your desired characteristics.  You will then be
    asked for confirmation.  If you aren't satisfied, it is fairly
    simple to go back and change it until you are satisfied.  All values
    that you enter will be retained, which means that you could go back
    and change the text color, for example, without having to re-enter
    all of the other items.

    You will be pleased to know that you only have to configure your color
    scheme, box position, etc., once per session. The settings that you
    select for the box position, outline, title, footer, and colors will
    be stored as PUBLIC variables (or STATICs if you are using 5.0) and
    re-used when you make additional help screens.

    The next time that you (or an end user) presses F1 at this point in
    the program, your fully-customized help screen will appear to guide
    them through the magnetic wilderness.  The cursor keys can be used
    to scroll through it, or you may print the entire help text by
    pressing Alt-P.

    There is also a hidden function that enables you to edit the text
    and attributes of any help screen.  Press F1 to pop up the help
    screen, then press Alt-E (for Edit).  You are then free to edit it
    as you see fit. Press Ctrl-W to save your text edits.  You will then
    be prompted to enter the values for the various box attributes
    similarly to when you created the help screen.  This function is
    "hidden" because of the strong probability that most of your
    programs will be used by other people.

    Post-Development (Release) Stage

    When you are fairly certain that all the necessary help screens have
    been created, you will probably want to 'lock' the program in such a
    manner that your users cannot run amuck creating their own help
    screens.  To create this lock, replace the two lines you added
    previously:

    EXTERNAL helpdev           && make symbol for linker (S'87 only)
    SET KEY 28 TO helpdev      && redefine F1 key

    with the following line:

    EXTERNAL help              && make symbol for linker

    Then recompile and link your program. Everything will be the same,
    except that your users will be powerless to create their own help
    screens.  You will also notice that the .EXE file will be smaller.
    This is because the routines for customizing the help screens'
    appearance are no longer necessary and are thus not linked into
    the program.

    If F1 is pressed and no help screen has been defined for that wait
    state, an index of all defined help screens will appear for
    selection and viewing.  You can also access this help index by
    pressing F1 from within another help screen.

    If you or your end users decide that creation of further help
    screens is necessary, you can always switch back to HELPDEV.

    Different Help Screens for Same Wait State

    Each of these modules is sensitive to the presence of a variable
    named HELPCODE.  This can allow you to have different help screens
    for the same wait state.  Particular examples include wait states
    such as DBEDIT(), MEMOEDIT(), and ACHOICE().

    You should declare and initialize HELPCODE to a different value
    for each place where you call the function in question. If
    HELPCODE is detected, instead of simply SEEKing on the name of the
    procedure and variable, HELP/HELPDEV will SEEK on its value.

    Here is an example of how you would set up HELPCODE:

    set key 28 to helpdev
    external helpdev     
                         
    procedure proc1      
    private helpcode     
    helpcode = 'DBEDIT1' 
    use customer         
    dbedit(0, 0, 24, 79) 
    return               
                         
    procedure proc2      
    private helpcode     
    helpcode = 'DBEDIT2' 
    use vendors          
    dbedit(0, 0, 24, 79) 
    return               

    HELPCODE can be up to twenty characters long.  Make sure that each
    HELPCODE has a unique value (unless of course you want to get the
    same help screen at two different locations, which I believe is
    what we were trying to avoid).  One last note, make sure that
    HELPCODE is declared PRIVATE to each procedure where you are using
    it.  Otherwise, its value may linger on (like a bad aroma), which
    would then cause the program to seek on its value whether you
    liked it or not.

    Changing Default Settings (Clipper 5.0 only)

    You can change all of the default settings for the help screen
    window attributes by using the HELPDEVSET() function.  This function
    also allows you to specify the name of the help file to use.  For
    more information, please refer to the HELPDEVSET() discussion.