home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / pascal / library / dos / t_power / demohelp.txt < prev    next >
Text File  |  1988-02-07  |  8KB  |  205 lines
  1. !WIDTH 66
  2. ;
  3. !TOPIC 1 Initializing
  4. TPHELP exports several data types and routines so that a client
  5. program can easily integrate a help system. The main data type is:
  6.  
  7. type
  8.   HelpPtr = ^HelpDesc; {The user hook to the help system}
  9.  
  10. A variable of this type points to a data structure that lets TPHELP
  11. manage the help system. The client program needs only to declare a
  12. variable of this type (which uses 4 bytes of space in whatever segment
  13. it's declared) and initialize it as described below, in order to
  14. access the help system.
  15. !PAGE
  16. TPHELP offers the following two functions to initialize a help system.
  17. One of these must be called prior to displaying help.
  18.  
  19. function OpenHelpFile(HelpFileName : string;
  20.                       XLow, YLow, YHigh : Byte;
  21.                       var Help : HelpPtr) : Word;
  22.   {-Find and open help file, returning 0 or error code, and
  23.     an initialized help descriptor if successful}
  24.  
  25. function OpenHelpMem(HPtr : Pointer;
  26.                      XLow, YLow, YHigh : Byte;
  27.                      var Help : HelpPtr) : Word;
  28.   {-Initialize help descriptor for a help structure
  29.     bound into code}
  30.  
  31. procedure SetHelpPos(Help : HelpPtr;
  32.                      XLow, YLow, YHigh : Byte);
  33.   {-Change the position of a help window}
  34. ;
  35. ;
  36. ;---------------------------------------------------------------------
  37. !TOPIC 2 Displaying
  38. TPHELP offers three methods of displaying help. You can call one or
  39. more of them at appropriate places in your program.
  40.  
  41. function ShowHelp(Help : HelpPtr; Item : Word) : Boolean;
  42.   {-Display help screen, returning true if successful}
  43.  
  44. function ShowHelpByName(Help : HelpPtr;
  45.                         Name : string) : Boolean;
  46.   {-Display help screen for topic with pick name Name}
  47.  
  48. function PickHelp(Help : HelpPtr;
  49.                   XLow, YLow,
  50.                   YHigh, PickCols : byte) : word;
  51.   {-Display help pick list, returning Item number,
  52.     or 0 for none}
  53. !PAGE
  54. A bit of background: each help topic is referenced by an Item number
  55. (which ranges from 1 to the maximum topic number) and optionally by a
  56. topic Name. The Item number and Name for each topic are assigned by
  57. you in the original text help file.
  58. ;
  59. ;
  60. ;---------------------------------------------------------------------
  61. !TOPIC 3 Help Compiler
  62. The text that will eventually be displayed by the help system starts
  63. out as a text file that you must write. You put directives in that
  64. text file to tell the help compiler how to format it. You then run the
  65. help compiler, MAKEHELP, to create a formatted, indexed file that will
  66. be used by the help system.
  67.  
  68. Directives are denoted by an exclamation point that appears as the
  69. first non-blank character on a line, immediately followed by the
  70. directive name, followed by various options separated by one or more
  71. spaces. Here is a list of the directives accepted by the help
  72. compiler.
  73. ;---------------
  74. !PAGE
  75.  
  76.   !WIDTH Width
  77.  
  78. Specifies the number of columns to be occupied by the
  79. help window, including the frame. The help will eventually be
  80. displayed with one blank column separating the text from each edge
  81. of the frame. Thus, the actual width for text is (Width-4)
  82. columns. If no !WIDTH directive is specified, MAKEHELP assumes
  83. Width=40.
  84.  
  85. Because MAKEHELP word wraps the text, the width specification for
  86. a help system is built into the help file. The width may not be
  87. changed when the text is later displayed. By contrast, MAKEHELP
  88. does not automatically paginate the help text, thus allowing help
  89. screens that can automatically adjust between 25, 43, and 50 line
  90. text modes.
  91.  
  92. The !WIDTH directive must appear before the first !TOPIC directive.
  93.  
  94. Example: !WIDTH 70
  95. ;---------------
  96. !PAGE
  97.  
  98.   !TOPIC Item [Name]
  99.  
  100. Each help topic must begin with a !TOPIC directive. Typically,
  101. help topics will be entered in ascending numerical order, starting
  102. with number 1. The !TOPIC directive may also specify an optional
  103. topic name. The name may contain spaces, and it will later appear
  104. on-screen exactly as entered in the !TOPIC directive. (The topic
  105. name appears as the title of the help window, and as an entry in
  106. the help pick list.)
  107.  
  108. Examples: !TOPIC 1 First Help Section
  109.           !TOPIC 22
  110. ;------------------
  111. !PAGE
  112.  
  113.   !LINE
  114.  
  115. This directive forces MAKEHELP to finish the current line of text,
  116. inserting a line break. Since MAKEHELP automatically fills and
  117. word-wraps the text in your original help file, the line breaks
  118. in the final help screens are not necessarily the same as those in
  119. the your text file. The !LINE command gives you appropriate control when
  120. needed. MAKEHELP also inserts a line break whenever it encounters a
  121. blank line or a line that begins with one or more spaces.
  122. ;---------------------
  123. !PAGE
  124.  
  125.   !PAGE
  126.  
  127. This directive forces MAKEHELP to finish the current page of text,
  128. inserting a page break. Normally, page breaks are inserted when
  129. the help text is displayed, only when the current window has
  130. filled with help.
  131. ;---------------------
  132. !PAGE
  133.  
  134. You may enter comments in the text file that will not appear in the
  135. final help. Comments are indicated when a semicolon appears in the
  136. first column of the text file. Example:
  137.  
  138.   ;ANY TEXT APPEARING AFTER THE SEMICOLON IS IGNORED.
  139. ;---------------------
  140. !PAGE
  141.  
  142. To activate the special text attributes, you insert control characters
  143. directly into your help text. ^A toggles SpAttr1 on and off, ^B
  144. toggles SpAttr2, and ^C toggles SpAttr3. The actual control characters
  145. will not appear in the final help screens. To enter such characters
  146. using the Turbo Pascal editor, first press <CtrlP>, then hold down the
  147. control key and press the desired character.
  148.  
  149. When the special attributes are used in combination, they are applied
  150. in priority order. SpAttr1 takes priority over SpAttr2, which takes
  151. priority over SpAttr3.
  152.  
  153. SpAttr1 has a special purpose as well. The selected topic in the help
  154. pick menu is displayed in attribute SpAttr1.
  155. ;
  156. ;
  157. ;---------------------------------------------------------------------
  158. !TOPIC 4 Binding Help
  159.  
  160. TPHELP will directly read the binary file produced by MAKEHELP.
  161. However, if the help file is relatively small (definitely less than
  162. 64K), you may want to link the help file directly into the application
  163. so that no additional files are required.
  164.  
  165. You can do this with the aid of the BINOBJ.EXE utility that Borland
  166. supplies with Turbo Pascal. BINOBJ converts the binary help file into
  167. a linkable OBJ file that can be bound into your program.
  168.  
  169. Let's use an example to show how this works. Assume you have a help
  170. text file named MYHELP.TXT. The first step would be to run
  171. MAKEHELP.EXE to create the binary help file:
  172.  
  173.   MAKEHELP MYHELP.TXT MYHELP.HLP
  174. !PAGE
  175. Then run BINOBJ to create the OBJ file:
  176.  
  177.   BINOBJ MYHELP.HLP MYHELP.OBJ MYHELP
  178.  
  179. The third parameter to BINOBJ specifies the name of the public
  180. identifier by which your program can refer to the contents of the OBJ
  181. file.
  182.  
  183. Now, within your application program, insert the following lines of
  184. source code:
  185.  
  186.   {$L MYHELP.OBJ}
  187.   procedure MyHelp; external;
  188.  
  189. The $L compiler directive tells Turbo to link in MYHELP.OBJ. The fake
  190. procedure MyHelp gives your program a way to refer to the contents of
  191. that OBJ file.
  192. !PAGE
  193. Finally, to initialize the help system, make a call to OpenHelpMem as
  194. follows:
  195.  
  196.   Status := OpenHelpMem(@MyHelp, XLow, YLow, YHigh, Help);
  197.   if Status <> 0 then
  198.     {Error, help not available};
  199.  
  200. The notation @MyHelp passes the address of the binary structure to the
  201. help system initialization procedure.
  202.  
  203. From then on, simply refer to the Help variable returned by
  204. OpenHelpMem.
  205.