Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / TPHELP.ZIP / TPHELP.DOC < prev next >

Wrap

Text File | 1988-02-07 | 22.3 KB | 510 lines

Help Facility for Turbo Pascal 4.0 ---------------------------------- Kim Kokkonen TurboPower Software Version 1.0 2/7/88 Overview --------------------------------------------------------------------- If you've ever had to develop a help facility for a Turbo Pascal application, you know that it takes some effort to write one that is efficient and easy to use. The help facility here offers a powerful, easy method to incorporate help screens into Turbo Pascal 4.0 programs. The Help Facility for Turbo Pascal 4.0, herein called TPHELP, consists of two parts. A Turbo Pascal unit, TPHELP.TPU, will be compiled into a program that needs to make use of the help facility. A "help file compiler", MAKEHELP.EXE, will convert a text file containing the desired help to an indexed binary file for use by TPHELP itself. The binary help file can be linked into the target program, so that no additional files are required by the end user of the application. Alternately, for large applications or large help files, the file may be left separate and paged automatically into memory by TPHELP. The help system supports up to 16000 help topics in one file, each of which may have up to 20 pages of help information. Help is displayed in a pop-up window through which the user may browse. Various formatting controls allow help to appear in up to four different video attributes. The help compiler word-wraps and paginates the original help text, under the control of directives that you insert. Within the application program, help may be selected by topic name, by index number, or by letting the user choose a topic from a pick window. You may also activate a "context-sensitive help system", which pops help up automatically whenever the user presses a specified key. You must have the commercial product Turbo Professional 4.0 in order to compile and use TPHELP. See the Advertisement section below for more information on obtaining Turbo Professional 4.0. This help facility includes complete source code for TPHELP and MAKEHELP. To enable certain features of TPHELP, you must also have the Turbo Professional "bonus" unit TPPICK. You can obtain the TPPICK source code by downloading TPPICK.ARC from Compuserve (GO BPROGA, DL2). Initializing a Help System --------------------------------------------------------------------- TPHELP exports several data types and routines so that a client program can easily integrate a help system. The main data type is: type HelpPtr = ^HelpDesc; {The user hook to the help system} A variable of this type points to a data structure that lets TPHELP manage the help system. The client program needs only to declare a variable of this type (which uses 4 bytes of space in whatever segment it's declared) and initialize it as described below, in order to access the help system. TPHELP offers the following two functions to initialize a help system. One of these must be called prior to displaying help. function OpenHelpFile(HelpFileName : string; XLow, YLow, YHigh : Byte; var Help : HelpPtr) : Word; {-Find and open help file, returning 0 or error code, and an initialized help descriptor if successful} function OpenHelpMem(HPtr : Pointer; XLow, YLow, YHigh : Byte; var Help : HelpPtr) : Word; {-Initialize help descriptor for a help structure bound into code} procedure SetHelpPos(Help : HelpPtr; XLow, YLow, YHigh : Byte); {-Change the position and height of a help window} OpenHelpFile and OpenHelpMem offer complementary methods of initializing a help system. OpenHelpFile looks for a binary help file on disk. It searches first in the current directory, then in the directory of the main program's EXE file (if DOS 3.x is in use), and finally on the DOS PATH. OpenHelpMem initializes the help system based on binary help information linked into the program. Its first parameter is a pointer to the help structure. More on using this option later. Both OpenHelpMem and OpenHelpFile take XLow, YLow parameters. These specify the screen position of the upper left corner of the help window. YHigh specifies the lower (row) boundary of the help window. The width of the help window is defined within the help file itself. Since it used to word wrap the help text, the width of a help window may not be changed within an application. Since the pop-up help window will typically appear at the same screen location throughout an application, by specifying the position once when the help system is initialized, you can avoid respecifying it every time help is called. If you need to move the help window or change its height from time to time, you can do so by calling the SetHelpPos routine interfaced by TPHELP. Do not call SetHelpPos until the Help variable has been initialized by a call to OpenHelpMem or OpenHelpFile. The colors used for pop-up help are obtained from typed constants HelpColorAttr and HelpMonocAttr defined within TpHelp. You can accept the default values of these typed constants, or modify them prior to calling OpenHelpMem or OpenHelpFile. Each typed constant is an array of six bytes, each one specifying the video attribute of one part of the help display. The attribute values are bytes that combine both the foreground and background colors, just like attributes passed to FastWrite. The attributes are specified in the following order: FrameAttr TextAttr HeaderAttr SpAttr1 SpAttr2 SpAttr3 FrameAttr is used to draw the frame of the pop-up help box. TextAttr is the default attribute for text drawn within the help window. HeaderAttr is the attribute for information on the frame, such as the topic title and help prompts. SpAttr1 through SpAttr3 are alternate attributes that may be used to highlight the help text. More on activating these alternate attributes below. The frame type that surrounds the pop-up help window is determined by the value in TpCrt.FrameChars at the time of the call to OpenHelpMem or OpenHelpFile. Upon successful completion, OpenHelpMem and OpenHelpFile return an initialized HelpPtr and a status word of zero. Otherwise, they return a non-zero error code that corresponds to a Turbo Pascal runtime error. Errors may occur because the help file isn't found, the file is not of the appropriate format, or insufficient heap space is available. (Both routines allocate heap space to hold a header record. If the help is kept on disk, an additional heap buffer is allocated to hold the largest help section.) Displaying Help --------------------------------------------------------------------- TPHELP offers three methods of displaying help. You can call one or more of them at appropriate places in your program. function ShowHelp(Help : HelpPtr; Item : Word) : Boolean; {-Display help screen, returning true if successful} function ShowHelpByName(Help : HelpPtr; Name : string) : Boolean; {-Display help screen for topic with pick name Name} function PickHelp(Help : HelpPtr; XLow, YLow, YHigh, PickCols : byte) : word; {-Display help pick list, returning Item number, or 0 for none} A bit of background: each help topic is referenced by an Item number (which ranges from 1 to the maximum topic number) and optionally by a topic Name. The Item number and Name for each topic are assigned by you in the original text help file. If no Name is assigned to each item, the only method for displaying help is the function ShowHelp. Call it by passing the previously initialized HelpPtr and the Item number. A successful call to ShowHelp will pop a window onto the screen, allow the user to browse through the help, and return when the user presses <Esc>. If ShowHelp succeeds, it will return True, otherwise False. It might return False if the Help variable isn't initialized, if no help exists for the specified Item, if a disk error occurs, or if sufficient heap space is not available to save the screen under the pop-up window. If a Name is assigned to each item, the other two help access methods become available. ShowHelpByName takes a topic Name as its second parameter, and displays help for the topic just like ShowHelp. Matching of the name to the original topic name is case-insensitive. ShowHelpByName returns false if no matching name is found. PickHelp allows the user to choose from a list of help items, and returns the selected Item number. The item number may then be passed to ShowHelp for display. XLow, YLow and YHigh specify the screen coordinates of the pick window, including its frame. PickCols specifies how many columns of pick items to display. The value of XHigh is computed by PickHelp based on the value of PickCols. PickHelp will return 0 (an invalid item number) if the user presses <Esc> to exit the pick list, or if an error occurs within PickHelp. Otherwise it returns a valid item number. See the discussion later about implementing context-sensitive help systems. Using the Help Compiler --------------------------------------------------------------------- The text that will eventually be displayed by the help system starts out as a text file that you must write. You put directives in that text file to tell the help compiler how to format it. You then run the help compiler, MAKEHELP, to create a formatted, indexed file that will be used by the help system. We typically use the extension .TXT to indicate a help text file, and reserve the extension .HLP for the binary help file produced by MAKEHELP. The help system does not require this, however. Directives are denoted by an exclamation point that appears as the first character on a line, immediately followed by the directive name, followed by various options separated by one or more spaces. Here is a list of the directives accepted by the help compiler. !WIDTH Width Specifies the number of columns to be occupied by the help window, including the frame. The help will eventually be displayed with one blank column separating the text from each edge of the frame. Thus, the actual width for text is (Width-4) columns. If no !WIDTH directive is specified, MAKEHELP assumes Width=40. Because MAKEHELP word wraps the text, the width specification for a help system is built into the help file. The width cannot be changed when the help is later displayed. By contrast, MAKEHELP does not automatically paginate the help text, thus allowing help screens that can automatically adjust between 25, 43, and 50 line text modes. The !WIDTH directive must appear before the first !TOPIC directive. Example: !WIDTH 70 !TOPIC Item [Name] Each help topic must begin with a !TOPIC directive. Typically, help topics will be entered in ascending numerical order, starting with number 1. The !TOPIC directive may also specify an optional topic name. The name may contain spaces, and it will later appear on-screen exactly as entered in the !TOPIC directive. (The topic name appears as the title of the help window, and as an entry in the help pick list.) The total space for Names in the help file is limited to 64K bytes. Space used for names is equal to the length of the longest name plus one times the total number of help topics. When topic names are used, this restriction will probably set the limit on the maximum number of topics in a help file. MAKEHELP assures that the 64K limit is not exceeded. Lines (even blank ones) immediately following the !TOPIC directive start the help text for that topic. The topic continues until another !TOPIC directive is found or end of file is reached. Each help file must have at least one help !TOPIC. The item number 0 is reserved by the help system to indicate an error, so you should never specify !TOPIC 0. Examples: !TOPIC 1 First Help Section !TOPIC 22 !LINE This directive forces MAKEHELP to finish the current line of text, inserting a line break. Since MAKEHELP automatically fills and word-wraps the text in your original help file, the line breaks in the final help screens are not necessarily the same as those in the original text file. The !LINE command gives you appropriate control when needed. MAKEHELP also inserts a line break whenever it encounters a blank line or a line that begins with one or more spaces. !PAGE This directive forces MAKEHELP to finish the current page of text, inserting a page break. Normally, TPHELP paginates the help text automatically when the help is displayed. For best appearance, however, you may wish to force page breaks at selected locations in your help file. You may enter comments in the text file that will not appear in the final help. Comments are indicated when a semicolon appears in the first column of the text file. Example: ;ANY TEXT APPEARING AFTER THE SEMICOLON IS IGNORED. To activate the special text attributes, you insert control characters directly into your help text. ^A toggles SpAttr1 on and off, ^B toggles SpAttr2, and ^C toggles SpAttr3. The actual control characters will not appear in the final help screens. To enter such characters using the Turbo Pascal editor, first press <CtrlP>, then hold down the Ctrl key and press the desired character. When the special attributes are used in combination, they are applied in priority order. SpAttr1 takes priority over SpAttr2, which takes priority over SpAttr3. SpAttr1 has a special purpose as well. The selected topic in the help pick menu is displayed in attribute SpAttr1. See DEMOHELP.TXT, supplied here, for a complete example of a help text file. To run the help compiler, enter the following command from the DOS prompt: MAKEHELP HelpTextFile HelpBinaryFile MAKEHELP will read from the text file specified as HelpTextFile and will create a new binary file HelpBinaryFile. MAKEHELP will overwrite any existing HelpBinaryFile without warning. MAKEHELP makes two passes through the input text: one to determine the number of help items and whether any topic names are specified; and a second to actually format the text and write output. If MAKEHELP finds any errors, it will halt and report the error type and line number within your help text file. TPHELP comes with a demonstration program, DEMOHELP.PAS, and a corresponding help file DEMOHELP.TXT. Take a look at these for an example. Binding Help Into a Program --------------------------------------------------------------------- TPHELP will directly read the binary file produced by MAKEHELP. However, if the help file is relatively small (definitely less than 64K), you may want to link the help file directly into the application so that no additional files are required at runtime. You can do this with the aid of the BINOBJ.EXE utility that Borland supplies with Turbo Pascal. BINOBJ converts the binary help file into a linkable OBJ file that can be bound into your program. Let's use an example to show how this works. Assume you have a help text file named MYHELP.TXT. The first step would be to run MAKEHELP.EXE to create the binary help file: MAKEHELP MYHELP.TXT MYHELP.HLP Then run BINOBJ to create the OBJ file: BINOBJ MYHELP.HLP MYHELP.OBJ MYHELP The third parameter to BINOBJ specifies the name of the public identifier by which your program can refer to the contents of the OBJ file. Now, within your application program, insert the following lines of source code: {$L MYHELP.OBJ} procedure MyHelp; external; The $L compiler directive tells Turbo to link in MYHELP.OBJ. The fake procedure MyHelp gives your program a way to refer to the contents of that OBJ file. Finally, to initialize the help system, make a call to OpenHelpMem as follows: Status := OpenHelpMem(@MyHelp, Col, TopRow, BotRow, Help); if Status <> 0 then {Error, help not available}; The notation @MyHelp passes the address of the binary structure to the help system initialization procedure. From then on, simply refer to the Help variable returned by OpenHelpMem. Context Sensitive Help --------------------------------------------------------------------- Context sensitive help means that the user of a program can press a help key at any time during operation, and the help system will respond with information appropriate to the user's current actions. TPHELP implements one method of providing context sensitive help, in a fashion that is quite transparent to your program, by installing an interrupt handler for the keyboard interrupt. When context sensitive help has been activated, TPHELP "sits on" interrupt 16h, watching for a specified help key. When the help key, perhaps <F1>, is detected, TPHELP pops up the help window, displaying the current help topic. TPHELP can detect the help key when entered during any ReadLn, ReadKey, or ReadKeyWord call. When the user finishes looking at help, the interrupt handler returns to the application as if nothing had happened. It is your program's responsibility to maintain an appropriate value for the current help topic at all times. TPHELP interfaces a Word variable named CurrentTopic. Your program must assign the appropriate help topic number to this variable as execution of the program proceeds. Should you enter a region of program operation where no help is available, assign the value 0 to CurrentTopic to temporarily disable context sensitive help. Otherwise, assign one of your previously defined help topic numbers to CurrentTopic. TPHELP provides two procedures that your program can call to activate and deactivate context sensitive help: procedure SetContextHelp(Help : HelpPtr; Key : Word); {-Install a keyboard interrupt handler to pop help when Key is pressed} procedure RemoveHelp; {-Deinstall context sensitive help} You must call SetContextHelp to activate context sensitive help. SetContextHelp takes two parameters: Help is a previously initialized HelpPtr, and Key is the scan word of the help key. For example, the scan word of the <F1> key is $3B00. Another reasonable choice might be <AltH>, whose scan word is $2300. To avoid problems with DOS re-entrancy, context sensitive help is available _only_ when the help file has been converted to an OBJ file and linked into the program. Thus the Help parameter to SetContextHelp must have been initialized by a call to OpenHelpMem. SetContextHelp enforces this requirement, and will not activate context sensitive help otherwise. (If your program never reads the keyboard using DOS services, this precaution is unnecessary. For safety's sake, it is always enforced in TPHELP.) SetContextHelp allocates 2000 bytes of heap space when you call it the first time. This 2000 bytes is used as an alternate stack -- the interrupt 16h handler switches to this stack prior to popping up the help window, just in case it has taken control when little stack space is available. If SetContextHelp cannot allocate 2000 bytes, it will not activate the context sensitive help system. You can call RemoveHelp at any time to remove the keyboard interrupt handler. You probably won't need to though, since RemoveHelp is called automatically when your program halts. The following skeleton program shows how to use the context sensitive help system. ... var Help : HelpPtr; Status : word; ... {$L MYHELP.OBJ} procedure MyHelp; external; ... begin {Initialize help pointer} Status := OpenHelpMem(@MyHelp, XLow, YLow, YHigh, Help); if Status = 0 then {Successful initialization, pop up help with F1 key} SetContextHelp(Help, $3B00); {Set current topic to appropriate value} CurrentTopic := 20; ... {Change topic} CurrentTopic := 3; ... end. Whenever your program is reading the keyboard via ReadLn or ReadKey and the user presses <F1>, the help window will pop up to display information about the current topic. Copyright --------------------------------------------------------------------- TPHELP and MAKEHELP are copyright (c) 1988 by TurboPower Software, all rights reserved. The help facilities may be used and distributed freely by owners of Turbo Professional 4.0. Advertisement --------------------------------------------------------------------- TurboPower Software is in the business of providing powerful tools for the Turbo Pascal programmer. Our line of products for Turbo Pascal 3.0 includes the TurboPower Utilities, Turbo Extender, T-DebugPLUS, and Turbo Optimizer. Our first product for Turbo Pascal 4.0 is Turbo Professional 4.0, a library of 400 routines to solve the most common programming problems. Professional 4.0 includes units to save time and effort in the following ways: o CRT unit emulation, with many added features: cursor manipulation, support for Taskview and Desqview multitaskers, screen save and restore, BufLen control, and more. o Popup windows, virtual screens, and pulldown menu systems. o Easy and reliable ways to make your program memory resident. o Interrupt service routine handlers. o Keyboard macros. o Data entry routines. o Extended and Expanded memory access. o A complete BCD arithmetic unit, including the transcendental functions and the Form routine. o Sorting and searching. o Extensive string manipulation. o Strings longer than 255 characters. o Arrays larger than 64K. o Runtime error recovery. Turbo Professional 4.0 also comes with a dozen powerful demo programs, including a memory resident programmer's calculator, time management system, and keyboard macro utility, as well as a source code generator for menu systems. With complete source code (over 30,000 lines of it) and a 450 page manual, Turbo Professional 4.0 is a bargain at $99. Also available is Overlay Manager 4.0, which adds overlays and chaining back to the Turbo Pascal 4.0 compiler. Just $45. Coming in February '88 is a Turbo 4.0 version of T-DebugPLUS, our acclaimed symbolic debugger for Turbo Pascal. Following soon thereafter will be Turbo Analyst 4.0, the successor to our popular TurboPower Utilities. Call TurboPower Software at 408-438-8608 for more information.