home *** CD-ROM | disk | FTP | other *** search
/ Stars of Shareware: Programmierung / SOURCE.mdf / programm / windows / c / uw260 / enqhelp.doc < prev    next >
Encoding:
Text File  |  1992-11-10  |  13.4 KB  |  244 lines
  1. ------------------------ Using the EnQue Help Engine ----------- 11/10/92 --
  2.  
  3.     This file is divided into two parts.  The first describes how to use the
  4. help engine.  The second describes how to create your own help files.
  5.  
  6.   The help engine is very easy to use due to its employment of EnQue's new
  7. user-interface construction program, the TUICP.  The help may be used with
  8. either the keyboard or mouse.  To make composing your own help easy, the
  9. engine uses simple ASCII files.  These files can contain text commands to
  10. allow for color control, hypertext links, sound, and much more.  If the
  11. files exist in the current directory, those files are accessed, otherwise,
  12. the help engine looks in the path set by the environment variable ENQHELP.
  13. To set this, add a line like "SET ENQHELP=C:\BORLANDC\ENQUE" to your
  14. AUTOEXEC.BAT file.
  15.  
  16.   To invoke the ENQHELP.EXE stand alone help engine, type:
  17.   
  18.   ENQHELP FILENAME.EXT GET_MODE SEARCH_STR SX SY EX EY
  19.   
  20. where FILENAME.EXT is the first file the help engine should access, the
  21. GET_MODE (0 or 1) parameter tells the help engine to read the characters
  22. underneath the cursor and search for that keyword, and SEARCH_STR is an
  23. optional search string.  If you simply wish the help engine to display the
  24. beginning of the file, use 0 for both GET_MODE and SEARCH_STR.  The SX, SY,
  25. EX and EY parameters specify the upper-left and lower-right corners for the
  26. help window.  Default values of 0, 0, 79, and 24 will be used if no
  27. parameters are specified.  The help window must be either wider than 64
  28. characters, or taller than 14. This is to allow for the dialog interface
  29. buttons and sliders.  If the values are out of range or the file does not
  30. exist, the help engine will return.  The help engine can be invoked with no
  31. parameters and will act as if you had typed
  32.                "ENQHELP UW_HELP0.HLP 0 0 0 0 79 24".
  33.  
  34.     If you wish to use ENQHELP.EXE from within Borland's compilers, you may
  35. set it up as a Transfer program.  This allows you to pull up help for all
  36. UltraWin functions.  See "Setting up a transfer program" below.
  37.  
  38.   Once active, you can scroll around the help file much like an editor.
  39. UP, DOWN, LEFT, RIGHT, HOME, END, PgUp, PgDn, Ctrl-PgUp, and Ctrl-PgDn
  40. allow you to move around the file.  If the file is wider than the help
  41. window you can scroll horizontally as well as vertically.
  42. The buttons operate as follows:
  43.  
  44. Search   - [Alt-S] allows you to search for a specific word or phrase.
  45. Repeat   - [Alt-R] finds the next occurrence specified by Search.
  46. <<<      - [Shift-Tab] moves to the previous keyword.
  47. >>>      - [Tab]  moves to the next keyword.
  48. Previous - [Alt-P] moves to the previously active keyword.
  49. Index    - [Alt-I] moves to the original starting place.
  50. Quit     - [Alt-Q] exits the help program.
  51.  
  52.     If you are using a mouse, clicking on the button, sliders, close box,
  53. (upper left corner), or keyword will activate the function.
  54.  
  55.   To move to a keyword, you can use the tab or cursor keys.  The keyword
  56. will change colors.  Pressing [Enter] or double clicking on this word will
  57. take you to additional information on this topic.  Pressing [Alt-P]
  58. (previous) will take you back one level.
  59.  
  60.     To search for a specific word/phrase, press [Alt-S] or click on Search.
  61. This pulls up a dialog box.  To enter the word/phrase, press [Alt-S] again
  62. or click on the string following the word Search.  Type in the word/phrase
  63. and press [Alt-O] or click on OK.  The default search will proceed forward
  64. from the current cursor location.  The direction and scope can be changed by
  65. clicking on the appropriate check box or pressing the desired hot-key.
  66.  
  67. Forward   - [Alt-F] sets the search direction to forwards.
  68. Backward  - [Alt-B] sets the search direction to backwards.
  69. From Csr  - [Alt-R] searches from current cursor position.
  70. Global    - [Alt-G] searches from the start of file.
  71. Case      - [Alt-C] sets the case sensitivity.
  72. Quit      - [Alt-Q] quits from the search dialog.
  73. OK        - [Alt-O] accepts the parameters and finds the first word. 
  74.  
  75.  
  76. SETTING UP A TRANSFER PROGRAM
  77. -----------------------------
  78.   To use the help engine as a transfer program for the Borland Compilers,
  79. edit the transfer parameters as normal (see the Borland documentation) and
  80. for the command line parameters be sure to type $NOSWAP as the first
  81. command.  An example for an EGA 43 row screen would be "$NOSWAP UW_HELP0.HLP
  82. 1 0 1 15 78 40".  If you would like the help engine to "move" directly to
  83. the function underneath the cursor, load the tiny TSR TCKBD.COM before
  84. entering the compiler.  This program keeps a copy of the last cursor column
  85. and row, so when the cursor is hidden on execution of the transfer program
  86. the engine will know the location of the search word.  It is a good idea to
  87. call TCKBD.COM form your AUTOEXEC.BAT file.
  88.  
  89.     Please note that the Borland compilers require you to set up the transfer
  90. program for each project file you create.
  91.   
  92.  
  93. WRITING YOUR OWN HELP FILES
  94. ---------------------------
  95.   The help commands are structured much like a "C" function call with a few
  96. restrictions.  The command must be preceded by a ` character, and no white-
  97. space is allowed within the command.  All commands are stripped from the
  98. help display.  A line within the help text file can contain multiple
  99. commands and can be up to 255 characters in length.  Keep in mind that the
  100. displayed width may be less since commands are stripped.  Also note that no
  101. commands are required, the help may simply consist of ASCII text that is
  102. linefeed or carriage return/linefeed delimited.  These commands are designed
  103. to allow you to enhance your help files and add powerful HyperText
  104. capabilities.  Since the help files are simply ASCII, they can be edited
  105. with virtually any text editor.  The help engine will accept and display the
  106. extended character set if desired and if your editor allows the inclusion of
  107. these characters.  This allows you to create borders, etc., within your help
  108. files.  The drawback to ASCII files is a small sacrifice in speed when
  109. reading/parsing these files.  However, by keeping your help files relatively
  110. small, (which they should be to conserve memory as much as for speed), this
  111. drawback is all but unnoticable.
  112.  
  113.  
  114. SPECIAL HELP COMMANDS
  115. ---------------------
  116.  
  117. KEYWORD:  `keyword(word,search string);
  118.   There are three forms of the keyword command.  The first specifies the 
  119. actual keyword followed by a search string.  Both the keyword and the search
  120. string can consist of several words (up to 80 characters).  In this form, 
  121. the search string must reside in the same file as the keyword command.  It
  122. can be located anywhere in the file and should be unique.  It is good
  123. practice to use a character or sequence of characters in the search string
  124. that will not commonly occur in the text in order to assure this uniqueness.
  125. For example `keyword(File System,/// The DOS File System);  Here we use
  126. three / to insure the uniqueness of the search string.  Note that the keyword
  127. and search string can be different.
  128.   The second form is like the first but includes a modifier in front of the
  129. search string.  This modifier, enclosed in brackets, specifies the file in
  130. which the search string exists.  For example, `keyword(DOS,[dos.hlp]/// DOS);
  131. This works the same as the example above except that the file dos.hlp will
  132. no be loaded into the help engine and the search string "/// DOS" will be
  133. located.
  134.   The third form is similar to the other two in form but different in action.
  135. When the user moves to this keyword and presses <Enter>, the second parameter
  136. is used as a DOS command and executed.  For example, `keyword(DIR,{dir c:});
  137. When selected, this keyword will execute the DOS command "dir c:".  This
  138. is useful for creating menus, shells, etc.
  139.  
  140. COLOR:  `color(foreground string,background string);
  141.   There are a number of color control commands that allow you to personalize
  142. your help files.  Often, only one or two are used.  The first and most common
  143. is the color command.  Two parameters specify the foreground and background
  144. colors.  For example `color(RED,LIGHTGRAY);  Sixteen colors are available
  145. for each.  Knowledge of the PC text attribute structure is recommended but
  146. not required.  The colors are as follows:
  147.  
  148.                     Normal           High Intensity
  149.                     -------          --------------
  150.                     0 BLACK           8 DARKGRAY     
  151.                     1 BLUE            9 LIGHTBLUE    
  152.                     2 GREEN          10 LIGHTGREEN   
  153.                     3 CYAN           11 LIGHTCYAN    
  154.                     4 RED            12 LIGHTRED     
  155.                     5 MAGENTA        13 LIGHTMAGENTA 
  156.                     6 BROWN          14 YELLOW       
  157.                     7 LIGHTGRAY      15 WHITE        
  158.  
  159. The high intensity will cause the text to blink if used as the background 
  160. color unless the blink bit is disabled.  In addition to these 16 colors,
  161. DEFAULT can be specified for either/both foreground or background.  This
  162. will restore the color to its default state. (As specified by color_default
  163. or the program if color_default is not used).  For example if our default
  164. colors are WHITE on BLACK and we specify `color(RED,BLACK);  followed later
  165. by `color(DEFAULT,GREEN); we will then have WHITE on GREEN.
  166.  
  167. CO:  `co(foreground #,background #);
  168.   This command operates identically to color but is a short form version
  169. and is preferable where many color commands are used.  In this form we
  170. specify the colors with their decimal value 0-15 instead of a much longer
  171. text string.  For example, instead of `color(LIGHTGRAY,GREEN); we would
  172. have `co(7,2);  If many commands exists in a file this saves both space
  173. and time when the text is displayed, as the help engine does not have to
  174. search for the color string.  This also accepts default parameters but
  175. in this form you simply use a ? i.e. `co(?,3);  In addition, this form
  176. allows you to completely exclude the parameters and restore the default
  177. foreground and background with the simple call `co();  This is preferable
  178. since it then allows you greater flexibility is changing the default 
  179. colors without having to search and replace all color commands that 
  180. restore the defaults.
  181.  
  182. CK:  `ck(foreground #,background #);
  183.   This command is the same as co except that the first character following
  184. the command is displayed in the attribute specified by the color_first_char
  185. command (or the program if color_first_char is not used).  This is used
  186. internally by the help engine and is not normally needed.
  187.  
  188. COLOR_DEFAULT:  `color_default(foreground string,background string);
  189.   This command specifies the default foreground and background colors.
  190. This command is not required unless the program default is to be overidden.
  191. If it is used, it should be on the first line in the help file.
  192.  
  193. COLOR_FIRST_CHAR:  `color_first_char(foreground string,background string);
  194.   This command specifies the color of the first character of all keywords.
  195. This command is not required unless the program default is to be overidden.
  196. If it is used, it should be on the first line in the help file.
  197.  
  198. COLOR_HILITE:  `color_hilite(foreground string,background string);
  199.   This command specifies the color of the keyword when the cursor selects it.
  200. This command is not required unless the program default is to be overidden.
  201. If it is used, it should be on the first line in the help file.
  202.  
  203. COLOR_KEYWORD:  `color_keyword(foreground string,background string);
  204.   This command specifies the color of the keyword itself.
  205. This command is not required unless the program default is to be overidden.
  206. If it is used, it should be on the first line in the help file.
  207.   
  208. SOUND:  `sound(frequency,duration);
  209.   This routine causes the speaker to sound at the desired frequency for the
  210. specified duration in clock ticks (91/second) when this line is displayed. 
  211. It is useful in specifying the end of file and other important segments
  212. within the help file.
  213.  
  214. DELAY:  `delay(duration);
  215.   This routine causes the program to pause for the specified duration in
  216. clock ticks (91/second) when this line is displayed and is useful for
  217. animation, etc.
  218.  
  219. DOS:  `dos(command line);
  220.   This routine causes the DOS program to be executed when the line containing
  221. this command is displayed.  Note that this is different from the DOS command
  222. within a keyword, as this occurs on display, and the keyword version only
  223. occurs if the user selects the keyword and presses <Enter>.
  224.  
  225. BLINK:  `blink(state);  (EGA/VGA only)
  226.   This routine turns the blink enable bit on or off depending on "state".
  227. To disable blinking, use 0, to enable, use 1.  Turning this bit off
  228. allows all 256 possible color combinations to be used without the high
  229. intensity background colors blinking.  If this function is used, it should
  230. be on the first line in the help file.
  231.  
  232. FONT:  `font(fontname,block);  (EGA/VGA only)
  233.     This routine loads the desired font into the specified "block".  Block
  234. 0 is the primary font, block 1 is the font selected by usig the high
  235. intensisty colors.  (See the UltraWin documentation for more details).
  236. If this function is used, it should be on the first line in the help file.
  237. Once the font command is encountered, it is "disable" so that each time
  238. the line is displayed the font will not be reloaded and the screen reset.
  239.  
  240. TAB:  `tab(value);
  241.     This routine sets the tab size for the given file.  The default value
  242. is 2.  If this function is used, it should be on the first line in the
  243. help file. (Or before any tabs occur).
  244.