home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
High Voltage Shareware
/
high1.zip
/
high1
/
DIR10
/
AHP141.ZIP
/
AHP141.INS
/
AHELP.DOC
next >
Wrap
Text File
|
1994-01-01
|
19KB
|
428 lines
AHELP.LIB - ADVANCED HELP SYSTEM FOR CLIPPER (SUMMER '87) APPLICATIONS
Version 1.4 Copyright (C) 1990-1993, Capella Inc.
For a printed copy of this user guide, copy this file to your printer.
Introduction
------------
Welcome to AHELP! This help system, for use with your Clipper applications
(Summer '87), provides both context-sensitive and generalized help windows.
Features of AHELP version 1 (be sure to see version 3, p.7):
* You control whether help windows have no border, a single-line border, or
a double-line border.
* You control whether the cross-bars drawn inside the help windows have no
line, a single line, or a double line.
* AHELP automatically determines the appropriate intersections.
* You control what colors AHELP will use for the help window border, title,
content, and highlight bar in the help index window.
* You control whether or not the end user has the ability to create or
modify help windows.
* You control whether or not the help windows have drop shadows.
* AHELP automatically positions the help window immediately below the screen
position of the input variable (e.g., a GET variable) if the window will fit
there; otherwise, the window appears immediately above the input variable.
* AHELP provides a help index; whenever any help window is on the screen,
the user may press F1 to see the help index. The help index is another
window with a scrolling alphabetic listing of help subjects. The user
uses the cursor control keys to highlight the subject of interest, and
presses Enter to see the corresponding help window. The user may also
type the first letter of the subject to move the highlight bar immediately
to the first occurrence of that letter.
* AHELP is sensitive to the Clipper environment. If the cursor is off when
help is invoked, it will be off when control returns to your application.
Conversely, if the cursor is on when help is invoked, it will be on when
control returns to your application. The same principle applies to colors,
function keys, insert status, work area, and the status of SET CONSOLE,
DELETED, ESCAPE, and SCOREBOARD.
* AHELP does not use any "wait state" commands (READ, WAIT, ACCEPT, INPUT,
MENU TO), to avoid conflicts with any pending GETs. It uses the INKEY()
function for all keyboard input, with two exceptions: it calls DBEDIT() for
the help index window and MEMOEDIT() for displaying/editing help text.
What do you have to do in order to use AHELP? Three things:
1. Insert a call to AHELP in your application with the setup parameters you
want to use as described in the next section.
2. Insert the command SET KEY XX TO AHELP in your application.
3. Compile your application and link, specifying AHELP.LIB as one of the
LIB files (AHELP requires both CLIPPER.LIB and EXTEND.LIB).
That's all. The rest is transparent to your application.
Setup
-----
The application must call AHELP with four parameters before starting the user
interface, in order to initialize the help system. During initialization,
AHELP declares four PUBLIC memory variables:
HELPFILE - the name of the application's help file
HELPOPTN - a character string of application options
HELPCODE - a character string for use by the application when no input
variable is waiting -- AHELP uses the content of `HELPCODE' as
its third parameter if the Clipper-passed third parameter is
empty
and
HELPACTIVE - a logical variable set to true when AHELP is executing, and
false otherwise.
Also during initialization, AHELP checks for the existence of the help file
(and creates it if it is missing), and for the existence of the two index
files needed (and creates them if they are missing).
Setup Syntax:
DO AHELP WITH <expC1>, <expN>, <expC2>, <expA>
where
<expC1> is the name of the application's Help File (one to eight characters)
<expN> is any value (ignored by AHELP)
<expC2> is a string of switch values: /Bn/Cn/Dn/En
/Bn defines the help window Border: n=0 means no lines
n=1 means single line
n=2 means double line
/Cn defines the window crossbar: n=0 means no lines
n=1 means single line
n=2 means double line
/Dn defines drop shadows: n=0 means shadows are off
n=1 means shadows are on
/En defines Edit capability: n=0 means edit is off
n=1 means edit is on
These switches may appear in any order. No other switches are defined
in version 1.x. If any switch is missing, default values are:
B = 2 (double line border)
C = 1 (single line crossbar)
D = 0 (drop shadows off)
E = 1 (edit on)
<expA> is the name of a four-element character array containing screen
color values:
element 1 = foreground/background colors, help window content
element 2 = foreground/background colors, help index highlight bar
element 3 = foreground/background colors, help window title and
bottom-row message
element 4 = foreground/background colors, help window border
This array is not needed after AHELP returns.
Example 1:
DECLARE HCOLOR[4]
HCOLOR[1] = "N/W" && content
HCOLOR[2] = "W+/B" && highlight
HCOLOR[3] = "B/W" && title
HCOLOR[4] = "W+/W" && border
DO AHELP WITH "MYAPHELP",0,"/B2/C1/D1/E0",HCOLOR
| | | | | |
filename | | | | color
double | | | array
border | | | name
| | |
single | |
crossbar | |
| |
drop |
shadows |
on |
|
edit
off
Example 2:
<declare color array and values as above>
DO AHELP WITH "MYAPHELP",0,"",HCOLOR && use default switch options
After making this setup call, activate the "hotkey" that will invoke AHELP
with the SET KEY command. Examples:
SET KEY 28 TO AHELP && F1 is the help key
SET KEY 291 TO AHELP && Alt-H is the help key
SET KEY -9 TO AHELP && F10 is the help key
Execution
---------
When the user presses the help key while your application is in any wait
state, Clipper automatically calls AHELP with three parameters: the name of
the procedure in control when the key was pressed, the line number that was
executing, and the name of the wait state input variable. AHELP uses the
first and third parameters only (not all applications are compiled with line
numbers) to construct a "seek key". It opens the help file and performs a
seek for that key.
If the key is found, AHELP opens a help window and displays the help text; the
window is opened as close as possible to the input variable screen position.
If the key is not found, AHELP opens a smaller help window in the center of
the screen and notifies the user that no help is available.
Either window will show available options at the bottom of the window: Escape
to cancel help, F1 to call up the help index, and F4 to edit or create the
help display (if editing is enabled).
Cancel: If the user presses Escape, AHELP closes the help window and returns
to your application.
Help Index: If the user presses F1, AHELP closes the help window, opens a
help index window, and displays a scrolling list of help subjects. The user
may press Escape again (AHELP will close the window and return), or move the
highlight bar to the desired subject and press Enter to select that subject.
AHELP will close the window and use the subject as the new seek key.
Edit: If the user presses F4, AHELP turns on the cursor and allows the user
to modify or add text until F2 is pressed (to save any changes). The user
may press Escape to abort this process, which restores the original help text
(if any) and cancels the edit process. If the user chooses to save changes,
AHELP prompts for a new title for the help text, and for a new index subject;
both are optional. Any title is converted to upper case and centered when the
help window is recalled, prefixed with the words "Help on". If there is no
title, AHELP provides the word "Help" centered at the top of the window. If
the user specifies an index subject, AHELP adds it to the help index (below).
Editing keys available during creation or modification of help text are those
provided by MEMOEDIT: Ctrl-Y (delete line), Ctrl-T (delete word right), Ctrl-
left arrow (cursor left one word), Ctrl-right arrow (cursor right one word),
Ctrl-B (reform paragraph), Ctrl-W (save - same as F2).
AHELP is not intended for recursion; if the public variable HELPACTIVE is true
when AHELP is invoked, AHELP immediately returns. Otherwise, it sets variable
HELPACTIVE to true and continues. When AHELP is done, it resets HELPACTIVE
to false.
Help Index
----------
The help index is basically an alphabetized table of contents for generalized
help (although context-sensitive subjects may also be listed). The scrolling
highlight bar is used to point to the subject desired; the cursor keys move
the highlight bar, and typing a character moves the highlight bar to the first
occurrence of that character, if any. Pressing the Enter key selects the
highlighted entry, and the Escape key cancels the help index.
If edit is enabled, the user may press F4 to edit the highlighted entry,
Delete to delete the highlighted entry, or Insert to add a new entry.
Edit: If the user presses F4, AHELP opens a small window containing the index
entry, turns on the cursor, and prompts for any changes. Pressing Enter saves
the entry; pressing Escape cancels the edit operation.
Delete: If the user presses Delete, AHELP opens a dialog box to confirm that
deletion is desired. The dialog box contains two choices: "Cancel" and
"Delete". The cursor keys switch between these choices and Enter selects the
choice that is highlighted; alternatively, typing the first letter of either
choice selects that choice.
Insert: If the user presses Insert, AHELP opens a small window containing a
blank index entry, turns on the cursor, and prompts for the new index entry.
Pressing Enter saves the new entry; pressing Escape cancels the add operation.
Structure of Help File
----------------------
AHELP uses a .DBF (and associated .DBT) for help displays. The name of the
help file is determined by the application and passed to AHELP as a parameter
in the setup call. If AHELP is unable to find the help file in the current
directory, it creates both the .DBF and .DBT files.
The record layout is:
Field Field Name Type Width Dec Usage
1 HELPKEY Character 20 Seek Key (see below)
2 HELPTITL Character 30 Title for help display
3 HELPTEXT Memo 10 Content of help display
4 HELPSUBJ Character 30 Subject for help index
5 HELPTROW Numeric 2 Window top row [reserved]
6 HELPLCOL Numeric 2 Window left column [reserved]
7 HELPNROW Numeric 2 No. of window rows [reserved]
8 HELPNCOL Numeric 2 No. of window columns [reserved]
** Total ** 99
The Seek Key (field HELPKEY) consists of two concatenated ten-character
fields: the first ten characters are the name of the calling procedure,
AHELP's first parameter; and the second ten characters are the name of the
input variable, AHELP's third parameter.
There are two index files created and maintained by AHELP: HELPKEY.N*X and
HELPSUBJ.N*X. The filename extension, .NDX or .NTX, is determined by
whether you link your application with Nantucket's NDX.OBJ or not.
Since AHELP adds four to the number of file handles in use, you may need to
increase FILES= in CONFIG.SYS and SET CLIPPER=Fnn in AUTOEXEC.BAT. This will
be determined by how many files your application needs to have open at one
time.
Reserved Names
--------------
All function and procedure names in AHELP.LIB begin with the four letters
"HELP" followed by at least four more characters, except for the "AHELP"
procedure itself. Your application should avoid naming any functions or
procedures in a similar fashion, to eliminate any potential conflict at link
time. All variables used internally by AHELP are declared PRIVATE, with the
exception of the four PUBLIC variables HELPACTIVE, HELPCODE, HELPFILE, and
HELPOPTN (all of which also begin with the four letters "HELP").
Version 3
---------
You may order Version 3 of AHELP (next page) for ten additional features:
* Optional path in setup call allows AHELP to use a help file and its index
files in a different drive or directory.
* Network capability. AHELP opens the help file for shared use only unless
an update is required. Then it locks the record long enough for the
update, and immediately unlocks the record.
* Drop shadows in any direction, with a vertical width of one or two columns.
* Help index options: disabled, one level, or two levels; the two-level index
allows creation of categories of help subjects, for a "super" index.
* Import help displays from ASCII text files. During creation of a new help
display, the user may press F7 to tell AHELP to import one or more lines of
text from a user-specified file.
* Copy or refer to an existing help display. During creation of a new help
display, the user may press F1 to tell AHELP to open the help index window,
"point" to the desired entry, and use that help display.
* Key word capability. One or two key words may be specified for each help
display, and a key word search routine allows lookup by matching against a
key word prompt.
* Change the default screen coordinates of either the edit window or the help
window in the setup call.
* "Drag" or move any window around the screen and save its new position.
* Expand or reduce the size of any window and save its new shape.
Registration
------------
There are no royalty fees for including AHELP in your applications. Each
license includes full source code. The registration fee for AHELP is $95.00
for a single-PC license. A site license is $400.00, and a corporate license
is $1000.00. Versions for Clipper S'87 and Clipper 5.x are available; order
both versions and get a 50% discount on the second license! The last page of
this user guide is a ready-to-mail registration form.
Send your check, money order, or MasterCard/Visa number for the appropriate
license to:
MicroFox
P.O. Box 447
Richfield, OH 44286-0447
U.S.A.
We will send you version 3 of AHELP (with full source code), and add your
name(s) to our list of users for future upgrade notices and other offers.
<End of AHELP.DOC>
AHELP REGISTRATION AND ORDER FORM
Send to: MicroFox Co. P.O. # _________________
P.O. Box 447
Richfield, OH DATE _________________
44286-0447 U.S.A.
________________________________________________________________________
Order both S'87 AND 5.x and take 50% off second license at same level!
Single-User License ..................................... $95 U.S.
Quantity: Summer '87 ____ 5.x ____ SUBTOTAL $_________
Site License (unlimited use per site) ............... $400.00 U.S.
Quantity: Summer '87 ____ 5.x ____ SUBTOTAL $_________
Corporate License (unlimited use within enterprise): $1000.00 U.S.
Quantity: Summer '87 ____ 5.x ____ SUBTOTAL $_________
Each License includes source code. LICENSES TOTAL $_________
________________________________________________________________________
Ohio residents add 6.25% sales tax SALES TAX $_________
Shipping and handling charges:
U.S.A. ...... $2 each SHIPPING $_________
Canada ...... $3 each
All others .. $5 each
TOTAL $_________
________________________________________________________________________
Payment: P.O. __ Check __ Money Order __ Visa __ M/C __
MasterCard/Visa # ________________________ Exp. Date _____________
Signature __________________________ (if credit card order)
________________________________________________________________________
Ship To: Name ___________________________________________________
Company ___________________________________________________
Address ___________________________________________________
___________________________________________________
___________________________________________________
Phone ___________________________________________________
Diskette media: 5.25" acceptable ____ 3.5" required ____