Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / CLPHLP22.ZIP / CLIPHELP.DOC < prev next >

Wrap

Text File | 1992-04-03 | 59.4 KB | 1,356 lines

HHHHHHH. HH:^^^^^ HH. HH. (C) 1991, 1992 S.R. Eddy & Associates HH: HH: ^^ HH: HH: HH. HHHHHHH. HH. HH. HH: HH: HH: HH:^^HH: HH: HH: HH. HH: HH: HH: HH: HH: HH: HH: HH: HH: HH: HH: HH: HH: HHHHHHHH: HHHHHHH. HH: HHHHHHH. HHHHHHH. HH: HH: HHHHHHH: HH:^^^HH: HH:^^HH: HH: HH:^^HH: ^^^^^^^ ^^ ^^ HH:^^^^^ HH: HH: HHHHHHH: HH: HH: HH: HH: HH: HH: HH:^^^^^ HH: HH: HH: ^^ HH: HH: HHHHHHH. HH: HHHHHHH: ^^ ^^ ^^^^^^^ ^^ HH:^^^^^ Perth, Western Australia HH: ^^ An easy way to add F U L L C O L O R C O N T E X T - S E N S I T I V E H E L P to your Clipper (Summer '87 and 5.01) applications Version 2.2 April 3, 1992 S.R. Eddy & Associates 267 Acourt Road CANNING VALE 6155 Western Australia Tel: 61 9 455-1004 CompuServe ID: 100033,3272 CONTENTS DISCLAIMER . . . . . . . . . . . . . . . . . . . . . . . . . 3 LICENSE . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 REGISTRATION . . . . . . . . . . . . . . . . . . . . . . . . 3 ORDER FORM . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Installation . . . . . . . . . . . . . . . . . . . . . . 6 3. ClipHelp Demonstration . . . . . . . . . . . . . . . . . 6 4. Steps involved in creating and incorporating Help in your Application . . . . . . . . . . . . . . . . . . . . 7 6. Preparing Help Text . . . . . . . . . . . . . . . . . . 8 7. Creating the on-screen file which your application will use . . . . . . . . . . . . . . . . . . . . . . . . . . 8 8. Adding color to your on-screen help file . . . . . . . . 9 9. Importing captured panels . . . . . . . . . . . . . . 11 10. Rewriting HELP.TXT with the codes entered in the color editor . . . . . . . . . . . . . . . . . . . . . . . . 14 11. Adding context sensitivity to your HELP.TXT file . . . 14 12. Printing User Manuals for your Applications . . . . . 15 13. Clipper Summer '87 version - PUBLIC variables to declare in your application . . . . . . . . . . . . . 17 14. Clipper 5 version - Function call . . . . . . . . . . 18 15. Optional UDFs on entering and leaving Help . . . . . . 19 16. Points to remember when using INKEY(0) . . . . . . . . 20 17. Linking ClipHelp's .LIB files with your application . 21 18. ClipHelp command line parameters . . . . . . . . . . . 21 19. The 'Set Defaults' option . . . . . . . . . . . . . . 22 20. Credits . . . . . . . . . . . . . . . . . . . . . . . 23 21. Copyright, Trademark etc . . . . . . . . . . . . . . . 23 DISCLAIMER S.R. Eddy & Associates hereby disclaims all warranties relating to this product, whether expressed or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. S.R. Eddy & Associates cannot and will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if S.R. Eddy & Associates or an authorized S.R. Eddy & Associates agent has been advised of the possibility of such damages. In no event shall the liability for any damages ever exceed the price paid for the license to use the software, regardless of the form and/or extent of the claim. The user of this program bears all risk as to the quality and performance of the software. LICENSE ClipHelp is a Shareware product and is made available to the general computing public as such for evaluation. Users are licensed to operate ClipHelp on their personal computers for the purpose of test and evaluation on a trial basis for a period of 21 days. If the user decides the program is not of sufficient merit to warrant purchase through registration with S.R. Eddy & Associates, the program should be removed from the user's personal computer. Otherwise, if the program is deemed useful and the user has used or intends to use it in any of his or her programs, registration with S.R. Eddy & Associates is required. Registered users are those users that elect to register their use of ClipHelp with S.R. Eddy & Associates and pay the registration fee mentioned elsewhere in this documentation. By virtue of registration and payment for the program, registered users are granted a license to continue to utilize the ClipHelp color editing program on their personal computer and to incorporate ClipHelp's libraries in their applications for as long as they choose. This license authorizes the registered user to use the ClipHelp color editing program on any personal computer system he or she may own so long as the program is operated on only one computer system at a time. Site licenses for use of ClipHelp on multiple computers are available on request at a reduced unit fee based on the number of single machines licensed for use. REGISTRATION ClipHelp is the sole property of S.R. Eddy & Associates. The Shareware version, and ONLY that version, may be freely copied and transferred to individual parties for evaluation purposes. The Shareware version, and ONLY that version, may be posted on Bulletin Board Systems (BBS) for electronic access as long as NO FEE is charged for its distribution except for private BBS operations that ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 3 S.R. Eddy & Assoc charge a regular user subscription fee. Computer information services are authorized to post this product for subscriber access. The Shareware version of ClipHelp may NOT be distributed on diskette by any disk distributor/vendor that charges more than US $12.00 or equivalent for the diskette on which the program and attendant files are recorded without written consent from S.R.Eddy & Associates. ClipHelp is a fully functional Shareware product. Shareware is a computer program distribution/marketing method that permits potential buyers to thoroughly try the program prior to purchase. It is NOT free and it is not in the Public Domain. If, after evaluating the program, you find it useful and wish to incorporate it into one or more applications, you are expected to pay for it by registering with S.R. Eddy & Associates. The registration fee is Australian $48.00 (US $38.00) and may be paid by Mastercard or Visa internationally, by United States Postal Money Order or within Australia by Bankcard or cheque drawn on an Australian bank. The registered version accessed through the use of a serial number and personal code supplied by your choice of CISMail, FAX, phone or airmail is NOT distributed as Shareware, will not contain Shareware labels nor the closing message and does NOT have the inbuilt restriction on the size of help files of the Shareware version. The registered version of the ClipHelp color editor also includes an option to generate paginated user manuals for your applications directly from the files which ClipHelp builds, automatically generating tables of contents. These manuals can be sent directly to your printer or to a disk file for further embellishment with your word processor. You may register by completing and despatching the form on the following page by CISMail or airmail, including credit card details or some other form of payment of the registration fee as described thereon. ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 4 S.R. Eddy & Assoc ORDER FORM ========== From vs 2.2 onwards, persons registering their use of ClipHelp will be supplied by their choice of CISMail, FAX, phone or airmail with a serial number and code which they can use to personalise copies downloaded from Nanforum or a local BBS. Such personalising will fully access all ClipHelp facilities including unlimited help file size and applications' user manual printing - features that have previously only been available through the supply of a floppy disk. We both stand to benefit by this - me by avoiding preparation of floppy disks and you by securing your registration virtually immediately by return CISMail, FAX, phone or Airmail. Moreover, your serial number and code will also work with future versions of ClipHelp immediately you download them. REGISTRATION ALSO ENTITLES YOU TO TELEPHONE/MAIL SUPPORT SHOULD YOU HAVE ANY QUERIES OR DIFFICULTIES. Phone:(Intnl) 61 9 455-1004 Mail To: S.R. Eddy & Associates 267 Acourt Road CompuServe ID: 100033,3272 CANNING VALE, PERTH WESTERN AUSTRALIA 6155 Please tick as appropriate:- -------------------------------------- Mastercard ____ Visa ____ (International) U.S. Post Office Money Order ____ Bankcard ____ (Australia Only) Cheque ____ (Sorry... Australian $, drawn on Australian Banks only.) Card Number: _____________________________ Expiry Date: ________ Name: ________________________________________________________ Signature: ________________________________________________________ Company: __________________________________________________________ Position: __________________________________________________________ Address: __________________________________________________________ City: ________________ State: _______________ Zip/Postcode _____ Country: _____________________ Phone: ___________________________ Please send my Serial No/Code by CISMail / FAX / Phone / Airmail to: ____________________________________________________________________ SINGLE USER REGISTRATION FEES: ----------------------------- Within Australia: Aust $48.00 Other than Australia: US $38.00 Corporate & Multi-User registration fees available on request. ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 5 S.R. Eddy & Assoc 1. Purpose ClipHelp is intended to help you incorporate attractive and effective on-screen help in your applications, providing: * An almost unlimited number of help topics. * Topics size of from just a few lines to a virtually unlimited length. * Easily incorporated context-sensitivity. * Single and multi-user applications suitability. * Full color potential - almost all of the 128 basic combinations and their 128 flashing counterparts. * Easily learned color editing facility. * Ability to use text generated with your preferred ASCII text editor, such as QEdit. * Facility for capturing parts of your application's screen presentations at run time and later inclusion in full color in the help file using ClipHelp's color editor. * Automatic generation of user manuals for your applications built from ClipHelp's files, including automatically generated tables of contents (Registered users version). Please note that in the Shareware version the size of help files is limited to about 250 lines, or about 20 screen displays, which it is hoped will be large enough for you to be able to thoroughly test ClipHelp and decide whether you wish to become a Registered User. 2. Installation Create a sub-directory for ClipHelp (such as c:\ch) and extract all files into it. ClipHelp should always be called from within this sub-directory. Command line parameters allow direct access to and support of multiple application help files (see 'ClipHelp command line parameters' on page 21). 3. ClipHelp Demonstration After installation give the command 'cliphelp' from within the sub- directory into which the ClipHelp files have been extracted and select the first option of the ClipHelp menu - 'About ClipHelp'. This will use ClipHelp's on-screen help facility to present an illustrated description of itself, in browsing which please note the following: ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 6 S.R. Eddy & Assoc * Individual topics may be longer than the screen panel in which they appear. Use <cursor down> and <cursor up> to scroll through a topic's text beyond the screen's limits, and <PgDn> or <PgUp> to summon the next or previous topic to the screen. * <Alt-F1> causes an index of help topics to appear. Using this, it is possible to jump directly to a required topic. 'About ClipHelp' may be summoned at any time to remind you of some of the facilities available and techniques to achieve them. 4. Steps involved in creating and incorporating Help in your Application (a) Create your HELP.TXT file with an ASCII text editor following the guidelines given in the next section. (b) Run ClipHelp and use its 'Make Help File' option to generate a HELP.DAT file from your HELP.TXT file. (c) Use ClipHelp's 'Edit Colors' option to add color to HELP.DAT. (d) Use ClipHelp's 'Rewrite Text' option to generate a replacement HELP.TXT file incorporating color information. [ Optionally use the ASCII text editor to revise the color- coded HELP.TXT file and proceed through b), c) and d) again as many times as necessary.] [ (e) Optionally set PUBLIC (STATIC in the Clipper 5 version) variable 'hlp_var' to help topic titles at points in your program where you wish your on-screen help to be context- sensitive. ] (f) Include a call to ClipHelp's LDHELPMU() function early in your application's source code. If you are using the Summer 87 version of Clipper you will also need to include some public variable declarations. (g) Include the appropriate ClipHelp library files, depending on your version of Clipper, in your application's link command. (h) Compile and link. 5. Setting up Always call ClipHelp from the sub-directory in which you installed it using a command line parameter to tell it where to find the ASCII text file HELP.TXT and write the resultant HELP.DAT file, eg: ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 7 S.R. Eddy & Assoc cliphelp path=c:\myapp\ In this way ClipHelp lets you develop and maintain help files for multiple applications concurrently, with minimal risk of mutual interference. You will find more about command line parameters on page 21. 6. Preparing Help Text Use an ASCII text editor such as QEdit to prepare your help text in your application's own sub-directory, observing the following rules: (a) The file should have the name HELP.TXT. (b) The maximum width of your help text should be 72, so set your editor's right margin to that value. (c) Precede topic titles with the characters '#$$' in the first three columns followed by a space and then the title in up to 35 characters, eg: #$$ Entering sales slip details (d) Of the extended ASCII values 0 to 255 there are very few that have to be avoided: 009 (tab) Use spaces instead. 219 (solid box) This will not matter if you are preparing a color help facility as you can use color to simulate this character. (e) Do NOT prepare your text file with a word processor which inserts codes for line wrap, bold, underlining etc. Remember to take note of the comments later in this document on page 14 about editing a HELP.TXT file after color information has been added to it by ClipHelp's color editor. 7. Creating the on-screen file which your application will use You must of course have created a HELP.TXT file as described in the preceding section before proceeding with the following. At the command prompt enter the command: cliphelp [<param1> [<param2> ]]... <param1> etc are optional parameters listed on page 21. Except for the parameter specifying the path to your application's sub- ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 8 S.R. Eddy & Assoc directory referred to previously it is unlikely that you will need to know about other parameters at this stage but if the program should not run satisfactorily on your screen see whether there is anything under 'ClipHelp command line parameters' which could help you. When ClipHelp's opening screen appears press <cursor down> until the highlight rests on 'Make Help File' then press <Enter>. The message line towards the bottom of the screen will ask you to confirm your intentions with the message 'Create HELP.DAT (Y/-)?'. If you have prepared your HELP.TXT file, tap a 'y' to proceed or any other character to cancel the command. The message 'Creating HELP.DAT' will flash in the message line while the file is being created followed by confirmation that the file has been created. During the creation of HELP.DAT information is written at the beginning of the file about the whereabouts of topic titles and their associated text. 8. Adding color to your on-screen help file Select the option 'Edit Colors' from the ClipHelp menu. The ClipHelp color editor screen will be displayed with the beginning of your HELP.DAT file in the edit window. At the top of the screen is a color code panel with a rectangle superimposed on the default help text color code. The word 'Activity:' appears on the line immediately below the color code panel. As you use the editor one of the following descriptions will appear: Description Meaning ----------- ------- Scrolling The content of HELP.DAT can be scrolled through the window by pressing <cursor down> or <cursor up>, <PgDn>, <PgUp>, <^PgDn>, <^PgUp>. Selecting Appears when <F3> is first pressed accompanied by flashing of the rectangle on the currently selected color code. In this mode the flashing rectangle will move in the direction of any cursor key pressed, allowing selection of another color. Moving Appears when <F3> is pressed while in the Selecting mode together with a flashing arrow as ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 9 S.R. Eddy & Assoc a pointer above the first column of the first line of the edit window. You can then use <cursor right> or <cursor left> to move the pointer until it is at the beginning of the block which you wish to paint with the color you selected. Painting Appears when <F6> is pressed while in the Moving mode. In this mode the right and left cursor keys behave as follows: <cursor right> Colors the character position beneath the flashing arrow with the selected color and causes the arrow to advance one column. <cursor left> Moves the flashing arrow back a column but does not affect the color. Moving Appears when <F6> is pressed while in Painting mode. Behaves exactly as described previously against 'Moving'. Editing Appears when <F10> is pressed while in Scrolling mode and allows the text of the line at the top of the window to be edited. Topic title lines, however, are not allowed to be edited because that might affect entries off-screen at the top of the file which were entered when HELP.DAT was created. (Topic titles can be edited later in the HELP.TXT file which you recreate with ClipHelp's 'Rewrite Text' - see page 14.) At the bottom of the screen is a list of function keys which are used to enter and edit color attributes. Function keys which toggle conditions on and off are indicated in bright red, the remainder in bright white. At any given moment only the function keys available for use will be easily legible; others will be displayed in low intensity to remind you of their existence but indicate their unavailability at that time. The top line of the screen is used to describe what is happening and the significance of particular keys. Some function keys offer useful short cuts: <F4> (Selecting Mode) - Automatically selects the default help text color and repositions the color code selection rectangle at that code. <F5> (Selecting Mode) - Selects the color attribute of the ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 10 S.R. Eddy & Assoc character beneath the flashing arrow. (A quick way of color editing a line which has recently been edited in HELP.TXT.) <F8> (Scrolling Mode) - Repeats the color attributes of the line at the top of the window in the line beneath it and scrolls the panel one line upwards. (A quick way to do something like color a message panel.) <F9> (Scrolling Mode) - Deletes the color attributes of the line at the top of the window and replaces them with the default help text attribute. To avoid accidents through inadvertent use this will only be done if you answer the confirmatory question which appears with a 'y'. <F1> (Both Scrolling and Selecting Modes) - Displays the HELP.DAT file which you are editing exactly as it will appear when <F1> is pressed in your application, allowing you to monitor the results of your editing in their final format. Press <F2> to save your selections when you have finished editing the color attributes of a line, or <Esc> to cancel them and revert to the original attributes. 9. Importing captured panels GrabScreen() function in CLHLPS87.LIB and CLHLP501.LIB ------------------------------------------------------ ClipHelp vs 2.0 library files CLHLPS87 and CLHLP501 include a function called GrabScreen() which can be used during application development to define and capture parts of screen layouts while the application is running for later inclusion in the HELP.DAT file. Include the temporary line "SET KEY ### TO GrabScreen" early in the application so that GrabScreen() can be 'hotkeyed' during wait states. You may also need to add temporary CASE statements such as "CASE <inkeyvar> = ###" to trap the hotkey in places where INKEY() is being used to process keyboard entries. (For "###" substitute the INKEY() value of the selected hotkey.) When the function is hotkeyed it checks if a database called CAPTURES.DBF exists in the location defined by the optional sixth parameter to function LDHELPMU() if you are using Clipper 5 or in public variable HPATH if you are using Clipper Summer '87, or else in the application's default sub-directory and creates it if necessary. GrabScreen() then asks whether you wish to capture all or part of the screen, defaulting to part. Note that if you capture the complete screen you will need to chop out some columns when you ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 11 S.R. Eddy & Assoc summon it from within the 'Edit Color' option of ClipHelp later so that it will fit in the on-screen help panel which has a maximum width of 72 characters. If you select the part screen option, panel framing lines will appear at the extremities of the screen. Use the numeric keypad cursor keys to move the framing lines towards the centre of the screen and the same keys while <Shift> is held down to move them back towards the screen extremities. When you are satisfied that the panel you wish to capture is directly within the framing lines tap <Enter> to save it. You will be asked to enter a description of the panel which will later appear in pick lists of such saved panels. Don't forget to remove the GrabScreen() hotkey assignments in your finished application! Please note that you can access the GrabScreen() function from within the 'Edit Colors' option of the ClipHelp editor, assigned to <Alt-0>, to enable you to capture existing areas of your HELP.DAT file. To use it, first tap <F1> to see the results of your work so far on the screen, move to the page and section you wish to capture then tap <Alt-0> and proceed as described above. You may find this facility useful to change the layout of a complicated section of your file - capturing, importing, adjusting the position horizontally, inserting and later deleting the superceded lines in your rewritten HELP.TXT file. It's not as complicated as it sounds and can save a lot of manually re-coloring. <^F10> Import facility in ClipHelp's 'Edit Colors' option --------------------------------------------------------- Use this option to incorporate a captured panel directly into the HELP.DAT file complete with its color attributes. A pick list of captured panel descriptions appears. Tapping <Enter> overlays the selected panel with an upper left co-ordinate of 0,0 from whence it can be pushed around the screen with the cursor keys. Its left edge relative to the left of the scrolling help text panel when <Enter> is eventually tapped to insert the panel determines its horizontal position within the help text. While the panel is on the screen the following options are accessible: <Alt-H> / Enable row/column editing. A row or column indicator <Alt-V> appears near the centre of the panel temporarily overlaying the row or column beneath it. Use the cursor keys to move the indicator about the panel. Tap <Insert> to insert a row or column above or to the left of the indicator's position; or <Delete> to delete the row or column under the indicator. ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 12 S.R. Eddy & Assoc <Alt-E> Enable character editing. A single character frame appears near the centre of the panel. Use the numeric keypad cursor keys to move it to the required position. The following options are accessible: A-Z etc Replaces the character previously within the frame, retaining its displayed attribute, and advances the frame one column. Shifted Left and Right decrement and increment Numeric background color attribute, Up and Down Keypad decrement and increment foreground color cursor attributes. Any such changes affect only the keys character at the frame position (unless painting has been toggled with <F6> - see below). <Alt-F> Toggles flashing on or off at the character frame position. <F6> Toggles painting on/off. When first tapped, the Paint color attribute of the character at the frame position becomes the attribute wherever the frame traverses, affecting all characters entered or previous characters if the frame is moved by cursor action. Changing the attribute as described in the previous two paragraphs will cause the new attribute to affect all subsequent frame positions until <F6> is tapped again. <Escape> Done. Return to panel movement mode. <Enter> Finished panel manipulation, insert into HELP.DAT. A dialogue box will appear asking you to specify: the number of blank lines you would like to be inserted above the panel (ie between the line currently at the top of the help text screen and the first line of the panel); and the number of blank lines you would like to be inserted between the bottom of the panel and the second line currently displayed in the help text screen. When finished, tap <PgDn> to proceed or <Escape> to abort. <Escape> Abort panel manipulation and return to help text editing. While this facility is designed to considerably simplify the task of including full color reproductions of your application's screens in your help file compared with earlier versions of ClipHelp, it can also be used to insert one or more lines of text. To do this, select '<dummy panel>' from the Captured Panels pick list and then use the panel editing facilities described in recent paragraphs to ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 13 S.R. Eddy & Assoc adapt the dummy panel to the number of lines of text you wish to insert. You can then either use the panel editing facilities to insert both text and color attributes or insert the panel and use ClipHelp's normal text and color editing facilities at that stage. 10. Rewriting HELP.TXT with the codes entered in the color editor It is most important that this be done following any use of the 'Edit Colors' option during which changes were made, otherwise such changes will be lost should you need to recreate the HELP.DAT file to reflect changes in HELP.TXT. Select the 'Rewrite Text' option of the ClipHelp menu. You will be asked to confirm your intentions with the message 'Rewrite HELP.TXT from HELP.DAT (Y/-)?'. Tap a 'y' to confirm. Your HELP.TXT file will be rewritten together with information about the colors which have been entered in HELP.DAT. If a previous HELP.TXT is found it will be safely renamed HELP.BAK before HELP.TXT is rewritten as a backup which you could retrieve in an emergency. When you next look at HELP.TXT in your ASCII text editor you will notice that on the lines where color has been introduced color information will appear starting at column 79. Try not to disturb this information if you need to edit such lines. Make sure it always starts at column 79. Save your text file frequently during editing so that you will not have lost much if something untoward happens. However, if an accident does occur you will be able, in most circumstances, to repair the damage when you next use ClipHelp's 'Edit Colors' option. In particular, try not to accidentally 'wrap' the color information with your text! Keeping a backup copy of HELP.TXT is a good idea. 11. Adding context sensitivity to your HELP.TXT file When <F1> is pressed in your application ClipHelp searches topic entries at the top of HELP.DAT to see whether the character string currently assigned to PUBLIC variable 'hlp_var' (STATIC variable 'hlp_var' in the Clipper 5 version) is there somewhere. If a match is found ClipHelp displays that topic; if not it displays the Help Topic Index. There are (at least) two techniques you can use to introduce context sensitivity: Clipper Summer '87 - (a) At appropriate spots in your source code assign PUBLIC variable 'hlp_var' all - or a unique part of - the applicable help topic. For example, using the sample help topic given earlier in this document: ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 14 S.R. Eddy & Assoc #$$ Entering sales slip details you might, in the interests of brevity, use the unique part: hlp_var = "sales slip" Please note that case IS important. (b) In lieu of all or part of help topics text use a unique code such as "h1v", "h2v" etc. Be sure to maintain a record of the codes you have used to avoid double usage. (If you have Turbo GREP or a similar program you can readily get a list of such lines from all source code files.) Using this technique you would put in your source code entries such as: hlp_var = "h1v" then, with your ASCII text editor, put "h1v" on the appropriate help topic title line of your HELP.TXT file starting at column 45, ie #$$ Entering sales slip details h1v Clipper 5 - (c) The technique of referring to a portion of the help topic or alternatively using unique codes such as "h1v", "h2v" etc is the same as that described above. However, hlp_var is a file-wide static variable in CLHLP501.LIB and values are passed to it with a call to function SetHV(). The equivalents to the examples above would be: SetHV( "sales slip" ) and SetHV( "h1v" ) SetHV() returns the current hlp_var value, so that you may save it on calling a routine requiring a new value and restore it on return from it, eg: LOCAL cur_hv := SetHV( "h21v" ) . SetHV( cur_hv ) 12. Printing User Manuals for your Applications The 'Print Appl Man' option translates your HELP.DAT file into a paginated user manual complete with a table of contents. ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 15 S.R. Eddy & Assoc When you select this option you will be asked to enter the following pieces of information to be incorporated in your manual: Program Title This is the full title to appear on the first page. Abbreviated Title This is the shortened title which will appear at the bottom left of each page. Your Business Name This is your full business name, to appear on the first page. Abbreviated Name The shortened business name to appear at the bottom center of each page. Your address Full address - street, city, state, zip. Your Telephone, Fax & Data Numbers Self-explanatory. You may overtype the reminders that appear in each field as you enter your own text or tap <^Y> as you move to each field to clear its contents in advance. When <Enter> is tapped on the last field you will be asked to confirm that the file should be sent direct to your printer. If you do not respond 'y' you will be asked to enter the name of a disk file to which the manual should be written. Enter the file name only - it will automatically be given a .PRN extension and be written to the sub-directory specified in your 'path' command line parameter or to ClipHelp's own sub-directory if none was specified. One reason you might wish to use the disk file option could be to add embellishments to the manual with your word processor before printing. ClipHelp's default printer output should suit most industry- compatible laser and dot matrix printers. The program endeavors to filter out the ASCII characters < 32 likely to feature in your help text in case they interfere with your printer's operation. You will find that the cover and table of contents will be the last two pages printed. To avoid taking liberties with your printer the cover is a very plain affair which you may wish to replace with something more exciting. ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 16 S.R. Eddy & Assoc Should you find it desirable to force a page break at a place prior to that selected by the program, note the line or lines, then edit the HELP.TXT file and place a slash ('/') in column 73 on those lines, being careful not to displace any color codes from their start column of 79. Next, run ClipHelp's 'Make Help File' option to remake HELP.DAT from the edited HELP.TXT file and then re-run the 'Print Appl Man' option. You can repeat this process as often as necessary until you are satisfied with the results, writing the printer output to a disk file each time for scrutiny with your ASCII editor. 13. Clipper Summer '87 version - PUBLIC variables to declare in your application Include the following statements and function call in the main .PRG module of your application (or in your setup procedure if you use one): * ----- Declare ClipHelp PUBLIC variables PUBLIC no_pages,; && (N) ) Used no_topics,; && (N) ) within st_rec,; && (N) ) ClipHelp head_tag,; && (C)) hlp_var,; && (C) Context-sensitivity variable explode,; && (L) .T. - explode boxes, else .F. expl_in,; && (N) Box expansion increment 1-2. expl_dl,; && (N) 0=fastest. Increase to slow. shadow,; && (L) .T. - shadow boxes, else .F. mono,; && (L) .T. - force mono, .F. - color prehelpfn,; && (C) Procname to call when F1 tapped posthelpfn,; && (C) Procname to call before return hpath && (C) Location of HELP.DAT specified && as "<disk>:\<sub-dirirectory>\" * ----- Declare default values STORE 0 TO no_pages, no_topics, st_rec STORE "" TO hlp_var, head_tag, hpath STORE .T. TO explode && Change these to suit your STORE .T. TO shadow && preferences. You could use STORE .F. TO mono && command line parameters in expl_in = 1 && your application expl_dl = 5 && if you wish. prehelpfn = "" && ) See 'Optional UDFs on entering posthelpfn = "" && ) and leaving Help' on page 19. * ----- Call function which gathers important information * from HELP.DAT for later use when <F1> pressed LdHelpMU() IMPORTANT: 1) Don't forget to include the all-important LdHelpMU() function call above in your setup procedure or very early in your main .PRG file. ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 17 S.R. Eddy & Assoc 2) Replace the default "" assignment for hpath with the location of HELP.DAT and PALETTE.HLP if they reside elsewhere than in your application's default sub- directory. SUGGESTION: To avoid 'typos', use your ASCII editor's facilities ---------- to cut and paste everything above from '* ----- Declare ClipHelp...' to 'LdHelpMU()' into your application's source code, then edit judiciously. Note that LdHelpMU() returns .T. if file HELP.DAT has been located and .F. if not. In the latter case it also displays a message to that effect briefly. You may wish to test this in your code with something like: IF !LdHelpMU() ... [whatever action you wish to take] ENDIF 14. Clipper 5 version - Function call All variables in the Clipper 5 version library (CLHLP501.LIB) are LOCAL or file-wide STATIC. There is no need to declare any variables elsewhere in your application. At the points in your application where you wish to change its context sensitivity, pass the character string or code with a call to function SetHV(). See the section headed 'Clipper 5 -' on page 15 for details of its use. The only line necessary to add to a Clipper 5 application to provide access to ClipHelp is: LdHelpMU() Optionally, the Clipper 5 LdHelpMU() function can have one or more of the following parameters: Parameter 1 .T. = force monochrome performance (default .F.) Parameter 2 .F. = inhibit panel shadows (default .T.) Parameter 3 .F. = inhibit panel explosion (default .T.) Parameter 4 <N> explosion expansion increment 1|2 (default 2) Parameter 5 <N> explosion expansion delay - the lower the value the faster the explosion (default 5) Parameter 6 <C> (optional) path for HELP.DAT and HELP.TXT ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 18 S.R. Eddy & Assoc expressed as "<drive>:\<sub-directory>\" (note the obligatory trailing "\") Parameter 7 <B> (optional) a code block to execute on tapping <F1> and prior to displaying any Help screens. See 'Optional UDFs on entering and leaving Help' on page 19. Parameter 8 <B> (optional) a code block to execute on exiting Help. See 'Optional UDFs on entering and leaving Help' on page 19. The optional sixth parameter allows you to store your application's HELP.DAT and PALETTE.HLP files in a sub-directory other than your application's default sub-directory if you so wish. Note that LdHelpMU() returns .T. if file HELP.DAT has been located and .F. if not. In the latter case it also displays a message to that effect briefly. You may wish to test this in your code with something like: IF !LdHelpMU() ... [whatever action you wish to take] ENDIF 15. Optional UDFs on entering and leaving Help ClipHelp vs 2.2 optionally allows user defined functions to be called: (a) immediately following the tapping of <F1> and before the display of help screens; and (b) immediately following the removal of help screens and prior to return to the point in an application at which <F1> was tapped. in case you wish to have some special routine performed at either or both of these points. In the Summer 87 version this is achieved by assigning the names of UDFs to public variables PREHELPFN and POSTHELPFN, respectively, eg prehelpfn = "MyPreHlpFn" posthelpfn = "MyPstHlpFn" for pre-help function MyPreHlpFn(), while in the Clipper 5 version it is achieved by passing code blocks containing them as optional parameters 7 and 8 when initially calling LdHelpMU(), eg LdHelpMU( <par1>..<par6>,{||MyPreHlpFn()},{||MyPstHlpFn()} ) Note that any functions called at these points should save current color and cursor conditions (and blink conditions in Clipper 5) on entry and restore them on exit, if appropriate. If you so wish, you ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 19 S.R. Eddy & Assoc can have your pre-help function cause a return to your application without displaying help by: Summer 87 - keyboarding a CHR(255) prior to returning, ie KEYBOARD CHR(255) This enables you to let the user use <Esc> if you wish. ClipHelp automatically follows this with a CLEAR TYPEAHEAD command so that nothing untoward will happen on return to your application. Clipper 5 - returning (.F.). Be sure to return (.T.) to proceed with the display of help screens. Any value returned by a post-help function is ignored. How can these function calls be used? Here are a couple of suggestions: (c) Some users of earlier versions of ClipHelp complained that while their mouse was being turned off on summoning Help it was not being restored afterwards. Whether or not this happens seems to be related to the mouse driver in use moreso than to mouse functions. If you experience such a problem you could write a pre-help function to save the current mouse condition and post-help one which calls your own library's mouse restore function prior to returning from Help. (d) A post-help function could be used in the latter stages of development to call a function opening with a dialogue box by means of which a user could opt to append notes to a disk file for later scrutiny by the programmer with suggestions about help screens. I would welcome responses from users about the uses they have found for these functions. 16. Points to remember when using INKEY(0) If your program uses INKEY(0) and you press <F1> you will not get on-screen help in the ordinary course because INKEY() is not a 'wait state' like WAIT, ACCEPT, READ, INPUT or MENU TO. To overcome this, use a function such as: ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 20 S.R. Eddy & Assoc FUNCTION Await && (C) S.R. Eddy & Associates 1989 && and placed in the Public Domain * Syntax : Await() * Purpose : Allow HELP to be accessed during an INKEY(0) * Dependencies: None * Returns : INKEY() value DO WHILE .T. IF INKEY(0) = 28 * ----- <F1> pressed. Essential to pass dummy * parameters so that ClipHelp can avoid recursion. DO HELP WITH "",0,"" && In Clipper 5 you can put Help() ELSE EXIT ENDIF ENDDO RETURN ( LASTKEY() ) and replace 'INKEY(0)' with 'Await()' throughout your program. 17. Linking ClipHelp's .LIB files with your application Libraries CLHLPS87.LIB/CLHLP501.LIB and HLPCS87.LIB/HLPC501.LIB are all that are needed to be added to your linker instructions. Proceed as follows: (a) Clipper Summer '87: Add "clhlps87" and "hlpcs87" to the list of library files in your linker command or .LNK file. (b) Clipper 5.01 Add "clhlp501" and "hlpcs87 to the list of library files in your linker command or .LNK file. IMPORTANT: Library files HLPCS87 and HLPC501 mentioned above contain functions written in C. If your application includes overlays please be sure to refer to your linker's user manual to see whether it allows such libraries to be overlaid before attempting to do so. 18. ClipHelp command line parameters ClipHelp will interpret certain command line parameters given in the following format: cliphelp [<param1>=<on>/<off> [<param2>=<on>/<off> [...]]] Parameter options: ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 21 S.R. Eddy & Assoc (a) If ClipHelp thinks you have a color monitor but in fact you don't, force mono with: mono=on (default is off) (b) If you find assembly of ClipHelp's opening screen irritating you can turn it off with: frag=off (default is on) (c) Turn off box shadows with: shadow=off (default is on) (d) Turn off exploding boxes with: explode=off (default is on) (e) Adjust exploding speed by some value between 1 (fast) and 20 (slow): explspeed=10 (default is 5) (f) Adjust exploding box increment value between 1 and 2: explincr=2 (default is 1) (g) Specify the path to your application's HELP.DAT and HELP.TXT files with: path=<drive>:\<sub-directory>\ (default is "") 19. The 'Set Defaults' option Use this option to specify the seven basic colors in ClipHelp's on- screen panels - borders, index title, index body, selected index item, help topic title, help body text and application background attribute. If you already have a HELP.DAT file be sure to make a copy of it and store it in some safe place in case you are not pleased with the results of your experiments and wish to revert to the original settings. This is especially important if you change the 'Help Body' color, because the attribute of every character in HELP.DAT with the old help text background color will be replaced with the new one. ClipHelp won't be able to tell whether such characters are body text or part of some carefully colored representation - they'll all be changed. A screen reminiscent of the 'Edit Colors' screen will appear with a color palette in the upper half and a sample of what the current ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 22 S.R. Eddy & Assoc selections will produce in the lower half. Changes are made by picking the desired basic color option from the panel at the right of the screen then tapping <F3> to select a color. <F3> switches between basic color option and color code selection. <F2> is used to save the chosen color and display a sample of the results. You can experiment as much as you like without risking permanent damage to present settings. Only when <^F2> is tapped will any changes you have made be written to disk and then only after you have responded in the affirmative to the cautionary message which appears. 20. Credits My thanks to Gary Louth for his time and assistance in testing the several versions of ClipHelp and to John Buxton for helpful suggestions during development of the first version. 21. Copyright, Trademark etc Nantucket(R) and Clipper(R) are registered trademarks of Nantucket Corporation. QEdit is a registered trademark of Applied Systems Technologies, Inc. Turbo GREP is a registered trademark of Borland International. ------------------------------------------------------------------- ClipHelp (C) vs. 2.2 User Manual Page 23 S.R. Eddy & Assoc