ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / APPS / DATABASE / CLHLP110.ZIP / CLIPHELP.DOC < prev next >

Wrap

Text File | 1991-10-24 | 37.1 KB | 1,004 lines

HHHHHHH. HH:^^^^^ HH. HH. (C) 1991 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 1.1 October 24, 1991 S.R. Eddy & Associates 267 Acourt Road CANNING VALE 6155 Western Australia Tel: (09) 455-1004 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 5. Preparing Help Text ......................... 7 6. Creating the on-screen file which your application will use ................... 8 7. Adding color to your on-screen help file .... 8 8. Rewriting HELP.TXT with the codes entered in the color editor ....................... 10 9. Adding context-sensitivity to your HELP.TXT file ................................... 11 10. Printing a User Manual (Registered version) . 12 11. Clipper Summer '87 version - PUBLIC variables to declare in your application ......... 14 12. Clipper 5 version - Declarations in your application .................................14 13. Points to remember when using INKEY(0) ...... 15 14. Linking ClipHelp's .OBJ and .LIB files in your application ....................... 15 15. ClipHelp's command line parameters .......... 16 16. Credits ..................................... 17 17. Copyright, Trademark etc .................... 17 ------------------------------------------------------------------- ClipHelp (C) User Manual Page 2 S.R. Eddy & Assoc DISCLAIMER S.R. Eddy & Associates hereby disclaims all warranties relating to this product, whether express 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 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 30 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 pay for ClipHelp and register by payment with S.R. Eddy & Associates. By virtue of registration and payment for the program, registered users are granted a license to continue to utilize the program on their personal computer for as long as they choose. This license authorizes the user to use the 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 upon request at a reduced fee based upon 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 charge a regular user subscription fee. Computer information services are authorized to post this product for ------------------------------------------------------------------- ClipHelp (C) User Manual Page 3 S.R. Eddy & Assoc subscriber access. The Shareware version of ClipHelp may NOT be distributed on diskette by any disk distributor/vendor that charges more than $12.00 for the diskette upon 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 to be useful enough to incorporate into one or more applications, you are expected to pay for it by registering with S.R. Eddy & Associates. The registration fee is $48.00 and the registered version which will be sent in return, which is NOT distributed as Shareware, will not contain Shareware labels nor the closing message. The registered version also includes the ability to print a paginated User Manual with Table of Contents generated from the on-screen help data which you incorporate in your application. You may register by completing and despatching the form on the following page together with the registration fee stated therein. ------------------------------------------------------------------- ClipHelp (C) User Manual Page 4 S.R. Eddy & Assoc O R D E R F O R M =================== Mail To: S.R. Eddy & Associates Phone:(Intnl) (+61) 9 455-1004 267 Acourt Road CANNING VALE, PERTH WESTERN AUSTRALIA 6155 ____________________________________________________________________ Please tick as appropriate: Mastercard ____ Visa ____ Bankcard ____ (Australia Only) Cheque ____ (Sorry... Aust $, drawn on Australian Banks only.) Card Number: _____________________________ Expiry Date: ________ Name: ________________________________________________________ Signature: ________________________________________________________ Company: __________________________________________________________ Position: __________________________________________________________ Address: __________________________________________________________ City: ________________ State: _______________ Zip/Postcode _____ Country: _____________________ Phone: ___________________________ DESCRIPTION QTY UNIT TOTAL PRICE AMOUNT ____________________________________________________________________ Within Australia: ClipHelp (program and manual on disk) ____ @ Aust$48.00 _______ (Price includes airmail postage & packing) Other than Australia: ClipHelp (program and manual on disk) ____ @ US$48.00 _______ (Price includes airmail postage & packing) ======== TOTAL ORDER VALUE (Aust/US)$ ________ Preference: 5.25" (360k) Disk ____ or 3.5" (720k) Disk ____ ------------------------------------------------------------------- ClipHelp (C) 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 flashing counterparts. * Easily learned color editing facility. * Ability to use text generated with your preferred ASCII text editor, such as QEdit. * Automatic generation of a User Manual based on the on-screen help text file, including a table of contents (Registered users version). 2. Installation Create a sub-directory for ClipHelp (such as c:\ch) and extract all files into it. 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. 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. ------------------------------------------------------------------- ClipHelp (C) User Manual Page 6 S.R. Eddy & Assoc 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 code 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 differing values at points in your program where you wish your on-screen help to be context- sensitive then use the ASCII text editor to write the same values in the appropriate places in your HELP.TXT file (as explained later) and regenerate HELP.DAT through steps b), c) and d). ] f) Copy the HELP.DAT file and the appropriate ClipHelp .OBJ and .LIB files (as explained later) to your application's sub- directory, incorporate the lines of code given later in your application, compile and link. 5. Preparing Help Text Use an ASCII text editor such as QEdit to prepare your help text, 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. ------------------------------------------------------------------- ClipHelp (C) User Manual Page 7 S.R. Eddy & Assoc 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 about editing a HELP.TXT file after color information has been added to it by ClipHelp's color editor. 6. 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 [[[<ExpC1>] <ExpC2> ] ...] <ExpC1> etc are optional parameters listed later in this document. (It is unlikely that you will need to know about these at this stage but if the program should not run satisfactorily on your screen see whether there is anything under 'ClipHelp 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. 7. 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. ------------------------------------------------------------------- ClipHelp (C) User Manual Page 8 S.R. Eddy & Assoc 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>. 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 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- ------------------------------------------------------------------- ClipHelp (C) User Manual Page 9 S.R. Eddy & Assoc 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 section later in this document.) 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> Automatically selects the default help text color and repositions the color code selection rectangle at that code. <F5> Selects the color attribute of the character beneath the flashing arrow. (A quick way of color editing a line which has recently been edited in HELP.TXT.) <F8> Repeats the color attributes of the line at the top of the window in the line beneath it. (A quick way to do something like color a message panel.) <F9> 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 follows with a 'y'. 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. 8. 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. ------------------------------------------------------------------- ClipHelp (C) User Manual Page 10 S.R. Eddy & Assoc 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. 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. If an accident occurs 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. 9. 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: #$$ 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: ------------------------------------------------------------------- ClipHelp (C) User Manual Page 11 S.R. Eddy & Assoc 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 - 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.OBJ 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 ) 10. Printing a User Manual The 'Print User Man' option translates your HELP.DAT file into a paginated user manual complete with a table of contents. 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. ------------------------------------------------------------------- ClipHelp (C) User Manual Page 12 S.R. Eddy & Assoc 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. 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. Prior to printing, you may find it beneficial to use one of the several utilities generally available from bulletin boards which redirects printer output to a disk file. You can then examine the print file with your ASCII text editor to ensure that page breaks are suitable. 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 User Man' option. ------------------------------------------------------------------- ClipHelp (C) User Manual Page 13 S.R. Eddy & Assoc 11. 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 * ----- Declare default values STORE 0 TO no_pages, no_topics, st_rec STORE '' TO hlp_var, head_tag 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. * ----- Call function which gathers important information * from HELP.DAT for later use when <F1> pressed LdHelpMU() IMPORTANT: Don't forget to include the all-important LdHelpMU() function call above in your setup procedure or very early in your main .PRG file. 12. Clipper 5 version - Declarations in your application All variables in the Clipper 5 version .OBJ file (CLHLP501.OBJ) 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 the function SetHV(). See the section headed 'Clipper 5 -' under section 9. above for details of its use. The only line necessary to add to a Clipper 5 application to provide access to ClipHelp is: LdHelpMU() ------------------------------------------------------------------- ClipHelp (C) User Manual Page 14 S.R. Eddy & Assoc 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) 13. 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: FUNCTION Await && (C) S.R. Eddy & Associates 1989 * 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. 14. Linking ClipHelp's .OBJ and .LIB files with your application CLHLPS87.OBJ/CLHLP501.OBJ and HLPCS87.LIB/HLPC501.LIB are all that are needed to be added to your linker instructions. Proceed as follows: Clipper Summer '87: a) Add 'clhlps87' to the list of object files in your linker command or .LNK file. b) Add 'hlpcs87' to the list of libraries in your linker command or .LNK file. ------------------------------------------------------------------- ClipHelp (C) User Manual Page 15 S.R. Eddy & Assoc Clipper 5.01 c) Add 'clhlp501' to the list of object files in your linker command or .LNK file. d) Add 'hlpc501' to the list of libraries in your linker command or .LNK file. IMPORTANT: The library files mentioned above contain functions written in C. If your application includes overlays please be sure to refer to the your linker's user manual to see whether it allows such libraries to be overlaid before attempting to do so. 15. ClipHelp command line parameters ClipHelp will interpret certain command line parameters given in the following format: cliphelp [<topic1>=<on>/<off> [<topic2>=<on>/<off> [...]]] Parameter options: 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) ------------------------------------------------------------------- ClipHelp (C) User Manual Page 16 S.R. Eddy & Assoc 16. Credits My thanks to Gary Louth and John Buxton for helpful suggestions during development and for testing the results. 17. 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) User Manual Page 17 S.R. Eddy & Assoc