************************* Using the EnQue Help Engine ************01/15/92***

This file is divided into two parts. The first describes how to use the
help engine. The second describes how to create your own help files.

The help engine is very easy to use due to its employment of EnQue's new
user-interface construction program, the TUICP. The help may be used with
either the keyboard or mouse. To make composing your own help easy, the
engine uses simple ASCII files. These files can contain text commands to
allow for color control, hypertext links, sound, and much more. If the
files exist in the current directory, those files are accessed, otherwise,
the help engine looks in the path set by the environment variable ENQHELP.
To set this, add a line like "SET ENQHELP=C:\BORLANDC\ENQUE" to your
AUTOEXEC.BAT file.

To invoke the ENQHELP.EXE stand alone help engine, type:

ENQHELP FILENAME.EXT GET_MODE SEARCH_STR SX SY EX EY

where FILENAME.EXT is the first file the help engine should access, the
GET_MODE (0 or 1) parameter tells the help engine to read the characters
underneath the cursor and search for that keyword, and SEARCH_STR is an
optional search string. If you simply wish the help engine to display the
beginning of the file, use 0 for both GET_MODE and SEARCH_STR. The SX, SY,
EX and EY parameters specify the upper-left and lower-right corners for the
help window. Default values of 0, 0, 79, and 24 will be used if no
parameters are specified. The help window must be either wider than 64
characters, or taller than 14. This is to allow for the dialog interface
buttons and sliders. If the values are out of range or the file does not
exist, the help engine will return. The help engine can be invoked with no
parameters and will act as if you had typed
"ENQHELP UW_HELP0.HLP 0 0 0 0 79 24".

If you wish to use ENQHELP.EXE from within Borland's compilers, you may
set it up as a Transfer program. This allows you to pull up help for all
UltraWin functions. See "Setting up a transfer program" below.

Once active, you can scroll around the help file much like an editor.
UP, DOWN, LEFT, RIGHT, HOME, END, PgUp, PgDn, Ctrl-PgUp, and Ctrl-PgDn
allow you to move around the file. If the file is wider than the help
window you can scroll horizontally as well as vertically.
The buttons operate as follows:

Search - [Alt-S] allows you to search for a specific word or phrase.
Repeat - [Alt-R] finds the next occurrence specified by Search.
<<< - [Shift-Tab] moves to the previous keyword.
>>> - [Tab] moves to the next keyword.
Previous - [Alt-P] moves to the previously active keyword.
Index - [Alt-I] moves to the original starting place.
Quit - [Alt-Q] exits the help program.

If you are using a mouse, clicking on the button, sliders, close box,
(upper left corner), or keyword will activate the function.

To move to a keyword, you can use the tab or cursor keys. The keyword
will change colors. Pressing [Enter] or double clicking on this word will
take you to additional information on this topic. Pressing [Alt-P]
(previous) will take you back one level.

To search for a specific word/phrase, press [Alt-S] or click on Search.
This pulls up a dialog box. To enter the word/phrase, press [Alt-S] again
or click on the string following the word Search. Type in the word/phrase
and press [Alt-O] or click on OK. The default search will proceed forward
from the current cursor location. The direction and scope can be changed by
clicking on the appropriate check box or pressing the desired hot-key.

Forward - [Alt-F] sets the search direction to forwards.
Backward - [Alt-B] sets the search direction to backwards.
From Csr - [Alt-R] searches from current cursor position.
Global - [Alt-G] searches from the start of file.
Case - [Alt-C] sets the case sensitivity.
Quit - [Alt-Q] quits from the search dialog.
OK - [Alt-O] accepts the parameters and finds the first word.


SETTING UP A TRANSFER PROGRAM
-----------------------------
To use the help engine as a transfer program for the Borland Compilers,
edit the transfer parameters as normal (see the Borland documentation) and
for the command line parameters be sure to type $NOSWAP as the first
command. An example for an EGA 43 row screen would be "$NOSWAP UW_HELP0.HLP
1 0 1 15 78 40". If you would like the help engine to "move" directly to
the function underneath the cursor, load the tiny TSR TCKBD.COM before
entering the compiler. This program keeps a copy of the last cursor column
and row, so when the cursor is hidden on execution of the transfer program
the engine will know the location of the search word. It is a good idea to
call TCKBD.COM form your AUTOEXEC.BAT file.

Please note that the Borland compilers require you to set up the transfer
program for each project file you create.


WRITING YOUR OWN HELP FILES
---------------------------
The help commands are structured much like a "C" function call with a few
restrictions. The command must be preceded by a ` character, and no white-
space is allowed within the command. All commands are stripped from the
help display. A line within the help text file can contain multiple
commands and can be up to 255 characters in length. Keep in mind that the
displayed width may be less since commands are stripped. Also note that no
commands are required, the help may simply consist of ASCII text that is
linefeed or carriage return/linefeed delimited. These commands are designed
to allow you to enhance your help files and add powerful HyperText
capabilities. Since the help files are simply ASCII, they can be edited
with virtually any text editor. The help engine will accept and display the
extended character set if desired and if your editor allows the inclusion of
these characters. This allows you to create borders, etc., within your help
files. The drawback to ASCII files is a small sacrifice in speed when
reading/parsing these files. However, by keeping your help files relatively
small, (which they should be to conserve memory as much as for speed), this
drawback is all but unnoticable.


SPECIAL HELP COMMANDS
---------------------

KEYWORD: `keyword(word,search string);
There are three forms of the keyword command. The first specifies the
actual keyword followed by a search string. Both the keyword and the search
string can consist of several words (up to 80 characters). In this form,
the search string must reside in the same file as the keyword command. It
can be located anywhere in the file and should be unique. It is good
practice to use a character or sequence of characters in the search string
that will not commonly occur in the text in order to assure this uniqueness.
For example `keyword(File System,/// The DOS File System); Here we use
three / to insure the uniqueness of the search string. Note that the keyword
and search string can be different.
The second form is like the first but includes a modifier in front of the
search string. This modifier, enclosed in brackets, specifies the file in
which the search string exists. For example, `keyword(DOS,[dos.hlp]/// DOS);
This works the same as the example above except that the file dos.hlp will
no be loaded into the help engine and the search string "/// DOS" will be
located.
The third form is similar to the other two in form but different in action.
When the user moves to this keyword and presses , the second parameter
is used as a DOS command and executed. For example, `keyword(DIR,{dir c:});
When selected, this keyword will execute the DOS command "dir c:". This
is useful for creating menus, shells, etc.

COLOR: `color(foreground string,background string);
There are a number of color control commands that allow you to personalize
your help files. Often, only one or two are used. The first and most common
is the color command. Two parameters specify the foreground and background
colors. For example `color(RED,LIGHTGRAY); Sixteen colors are available
for each. Knowledge of the PC text attribute structure is recommended but
not required. The colors are as follows:

Normal High Intensity
------- --------------
0 BLACK 8 DARKGRAY
1 BLUE 9 LIGHTBLUE
2 GREEN 10 LIGHTGREEN
3 CYAN 11 LIGHTCYAN
4 RED 12 LIGHTRED
5 MAGENTA 13 LIGHTMAGENTA
6 BROWN 14 YELLOW
7 LIGHTGRAY 15 WHITE

The high intensity will cause the text to blink if used as the background
color unless the blink bit is disabled. In addition to these 16 colors,
DEFAULT can be specified for either/both foreground or background. This
will restore the color to its default state. (As specified by color_default
or the program if color_default is not used). For example if our default
colors are WHITE on BLACK and we specify `color(RED,BLACK); followed later
by `color(DEFAULT,GREEN); we will then have WHITE on GREEN.

CO: `co(foreground #,background #);
This command operates identically to color but is a short form version
and is preferable where many color commands are used. In this form we
specify the colors with their decimal value 0-15 instead of a much longer
text string. For example, instead of `color(LIGHTGRAY,GREEN); we would
have `co(7,2); If many commands exists in a file this saves both space
and time when the text is displayed, as the help engine does not have to
search for the color string. This also accepts default parameters but
in this form you simply use a ? i.e. `co(?,3); In addition, this form
allows you to completely exclude the parameters and restore the default
foreground and background with the simple call `co(); This is preferable
since it then allows you greater flexibility is changing the default

colors without having to search and replace all color commands that
restore the defaults.

CK: `ck(foreground #,background #);
This command is the same as co except that the first character following
the command is displayed in the attribute specified by the color_first_char
command (or the program if color_first_char is not used). This is used
internally by the help engine and is not normally needed.

COLOR_DEFAULT: `color_default(foreground string,background string);
This command specifies the default foreground and background colors.
This command is not required unless the program default is to be overidden.
If it is used, it should be on the first line in the help file.

COLOR_FIRST_CHAR: `color_first_char(foreground string,background string);
This command specifies the color of the first character of all keywords.
This command is not required unless the program default is to be overidden.
If it is used, it should be on the first line in the help file.

COLOR_HILITE: `color_hilite(foreground string,background string);
This command specifies the color of the keyword when the cursor selects it.
This command is not required unless the program default is to be overidden.
If it is used, it should be on the first line in the help file.

COLOR_KEYWORD: `color_keyword(foreground string,background string);
This command specifies the color of the keyword itself.
This command is not required unless the program default is to be overidden.
If it is used, it should be on the first line in the help file.

SOUND: `sound(frequency,duration);
This routine causes the speaker to sound at the desired frequency for the
specified duration in clock ticks (91/second) when this line is displayed.
It is useful in specifying the end of file and other important segments
within the help file.

DELAY: `delay(duration);
This routine causes the program to pause for the specified duration in
clock ticks (91/second) when this line is displayed and is useful for
animation, etc.


DOS: `dos(command line);
This routine causes the DOS program to be executed when the line containing
this command is displayed. Note that this is different from the DOS command
within a keyword, as this occurs on display, and the keyword version only
occurs if the user selects the keyword and presses .

BLINK: `blink(state); (EGA/VGA only)
This routine turns the blink enable bit on or off depending on "state".
To disable blinking, use 0, to enable, use 1. Turning this bit off
allows all 256 possible color combinations to be used without the high
intensity background colors blinking. If this function is used, it should
be on the first line in the help file.

FONT: `font(fontname,block); (EGA/VGA only)
This routine loads the desired font into the specified "block". Block
0 is the primary font, block 1 is the font selected by usig the high
intensisty colors. (See the UltraWin documentation for more details).
If this function is used, it should be on the first line in the help file.
Once the font command is encountered, it is "disable" so that each time
the line is displayed the font will not be reloaded and the screen reset.

TAB: `tab(value);
This routine sets the tab size for the given file. The default value
is 2. If this function is used, it should be on the first line in the
help file. (Or before any tabs occur).