.TOPIC: Contents The Visual Basic for MS-DOS Help Toolkit makes it easy to add hypertext Help to your applications. The text you are reading now is a Helpfile. The Help Toolkit is written entirely in Visual Basic and can be modified. Help files are standard ASCII files that can be edited with most text editors and even by Visual Basic itself. Click the mouse over one of the topics below for more information. Or press TAB to select a topic then press ENTER to jump to it. Creating and Editing Help files Adding Help to Your Applications Using Help Customizing the Help Toolkit .TOPIC: Creating and Editing Help Files To create a new Help file: 1. Determine which topics a user might want Help with. 2. Start any text editor that reads and writes ASCII files. 3. Create a topic named Contents and type a table of contents below. See Creating and Editing Topics. Note that the Contents command button will not work correctly unless you include a topic named Contents. 4. Every entry in the table of contents should be a link to a Help topic. See Creating Links 5. Create a Help topic for every link in the table of contents. See Creating and Editing Topics 6. Every Help topic can contain links to other Help topics. 7. Help topics do not need to be listed in the table of contents. To edit an existing Help file: NOTE: The Help Toolkit cannot access Microsoft .HLP files. 1. Open the Help file in a text editor that reads and writes ASCII files. 2. Modify Links and Topics as described above. See Example Help File .TOPIC: Creating and Editing Topics The Help Toolkit distinguishes Help topics from ordinary text by requiring that all topics are formatted in a specific way. 1. The word TOPIC must be on a line by itself, preceeded by a period (.) and followed by a colon (:). TOPIC must be in uppercase. 2. The period must be the first character on the line. 3. Only spaces are allowed after the colon. 4. The name of the topic itself must be on the line immediately below the .TOPIC: statement. 5. The topic text should begin on the line after the name of the topic. 6. The Help Toolkit will not word wrap text. Use the ENTER key to break text into reasonable length lines. 64 character lines work well because the Help window defaults to 66 characters wide. 7. The next topic should begin immediately after the last line of the current topic. For example, the following would be a valid topic except that the period is the second character on the line not the first. .TOPIC: This is a help topic name This is the first line a Help topic. . . . . This is the last line of a Help topic. See Creating Links Example Help File .TOPIC: Creating Links Links are hot spots that a Help user clicks on to jump to a Help topic. Links are ordinary text surrounded by special triangle characters (ASCII codes 16 and 17). Links and Topics must have exactly the same name or the Help Toolkit will not be able to find a Topic when a Link is clicked. For example, click on Valid Help Topic to see how Links jump to new Topics. And click on Invalid Help Topic to see what happens if you create a Link without a matching Topic. See Creating and Editing Topics .TOPIC: Adding Help to Your Applications Necessary Files --------------- You must add the following files to your project to use the Help Toolkit: 1. HELP.BAS 2. HELPF.FRM 3. HELPUTIL.FRM All files that call Help Toolkit routines must also have the following statement at the module level: '$INCLUDE: 'HELP.BI' Calling Help Toolkit Routines ----------------------------- Required Steps: 1. Initialize the Help system by calling the HelpRegister procedure. You should do this when your application starts. 2. Display Help topics or the table of contents by calling HelpShowTopic . HelpTopicName$ should be "Contents" to show the table of contents. 3. Call HelpClose just before your application ends. NOTE: You must call HelpClose during a Form_Unload event if your application ends when the last form is closed rather than by executing an END statement. Your application will not end if you fail to do this because frmHelpMain is still LOADED although invisible. Optional: 1. Call HelpSetOptions to set Help colors and show/hide specific Help command buttons after you call HelpRegister. See Help Toolkit Procedures for details. 2. Call HelpSearch to open Help's Search dialog. Many applications have a Search item under their Help menu. See Example Help Toolkit Application and Help Toolkit Procedures for detailed information. .TOPIC: Valid Help Topic You jumped to this topic by clicking the Valid Help Topic link. Click ---> Creating Links or choose the Back command button to return. .TOPIC: Customizing the Help Toolkit You can add or remove functionality from the Help Toolkit by changing the code in the following files: 1. HELP.BAS 2. HELPF.FRM 3. HELPUTIL.FRM HELP.BAS contains all the application callable procedures such as HelpShowTopic and HelpRegister. HELPF.FRM is the main Help form. It contains the code required to display and scroll through Help topics. It also has the code used to detect mouse clicks (to jump Links) and keyboard support. HELPUTIL.FRM is a form that serves as the Search dialog, the History dialog, and the Copy dialog. It is called from HELPF.FRM and HELP.BAS. The look of the form is controlled entirely from the cmdButtonBar_Click routine in HELPF.FRM and the HelpSearch routine in HELP.BAS. HELPF.FRM and HELP.BAS use the HELP.BI INCLUDE file. See Adding Help to Your Applications .TOPIC: Example Help File The following is an example of a small Help file. Note that real Help files must be flush left. This example is indented one character to stop the Help Toolkit from processing .TOPIC: statements. A real Help file would also have ASCII 16 and 17 characters in place of the > and < symbols used below. .TOPIC: Contents Welcome to Bob's Accounting System version 7.1 .TOPIC: Introduction Bob's Accounting System is specificially designed for small business accounting. It includes modules for and . Other modules may be purchased seperately. See .TOPIC: Adding New Accounts Choose New from the Accounts menu. You can also press F8. Note that Bob's Accounting System can store as many accounts as disk space allows. .TOPIC: Accounts Payable Access the A/P module through the Payables menu. Note that A/P entries are automatially added to the general ledger when you exit Bob's Accounting System. See .TOPIC: Accounts Receivable Access the A/P module through the Receievables menu. Note that A/R entries are automatially added to the general ledger when you exit Bob's Accounting System. See .TOPIC: Ordering Additional Modules You can call (123) 555-5555 between 9 am and 5 pm to inquire about new modules. New modules such as tax, benefits, and inventory are scheduled to be ready later this year. See Creating and Editing Help files .TOPIC: Example Help Toolkit Application The following shows how the Help Toolkit procedures should be added to an application. Assume the application is one form with menu controls for Help|Contents, Help|Search, and Help|Using Help. It also has a Text control named txtFileName and a check box named ckReadOnly. ' Module-level '$INCLUDE: 'HELP.BI' DIM SHARED HelpLoaded% SUB Form_Load () HelpRegister "MYHELP.TXT" , HelpLoaded% ' HelpLoaded% is set to TRUE (-1) if HelpRegister ' was successful or to FALSE (0) if it failed. IF HelpLoaded% = FALSE THEN ' Ensure that Help menu choices cannot ' be selected. mnuHelpContents.Enabled = 0 mnuHelpSearch.Enabled = 0 mnuHelpUsingHelp.Enabled = 0 END IF END SUB SUB Form_Unload () HelpClose END SUB SUB mnuHelpContents_Click () HelpShowTopic "Contents" END SUB SUB mnuHelpSearch_Click () HelpSearch END SUB SUB mnuHelpUsingHelp_Click () HelpShowTopic "Using Help" END SUB SUB txtFileName_KeyUp (KeyCode AS INTEGER, Shift AS INTEGER) IF KeyCode = 112 AND HelpLoaded% THEN 'F1 Key HelpShowTopic "File Name" END IF END SUB SUB ckReadOnly_KeyUp (KeyCode AS INTEGER, Shift AS INTEGER) IF KeyCode = 112 AND HelpLoaded% THEN 'F1 Key HelpShowTopic "Read Only" END IF END SUB See Adding Help to Your Applications .TOPIC: Using Help Note that the following text is appropriate for adding to your own Help files. A user should be able to access Using Help from the Help menu in your application. See Example Help Toolkit Application ============================================================ Selecting a Help link: ---------------------- With a mouse - click on phrases outlined by two triangles. With the keyboard - Press TAB or Shift-TAB to select a link. Press ENTER to jump to that topic. Scrolling the Help window: -------------------------- With a mouse - click on the horizontal or vertical scroll bars. With the keyboard - press the cursor navigation keys. Closing the Help window: ------------------------ With a mouse - double click on the window's control box icon. With the keyboard - press Ctrl-F4. Command Buttons: ---------------- Applications may use one or more of the following command buttons. Use a mouse to click a button or press the letter mentioned below. Contents - displays a table of contents for the application's Help. Press C to select Contents. Search - opens a dialog box that lists all available Help topics. Select a topic from the list box and press ENTER. Press S to select Search. Back - jumps to the last Help topic viewed. Press B to select Back. History - lists the last 20 Help topics viewed. Jump to a topic by selecting from the list box and pressing ENTER. Press T to select History. Copy - Copies the contents of the current Help topic into an edit area. Select the text you want copied to the Clipboard and choose Copy. Choosing Copy without selecting any text in the edit area copies the entire Help topic to the Clipboard. Press P to select Copy. .TOPIC: Help Toolkit Procedures Five procedures in HELP.BAS give you access to all of Help Toolkit functions. HelpRegister , Success% ----------------------------------------- HelpRegister opens the requested Help file and searches for all Help topics. The Help topics and their file positions are stored in an array for later use. The file itself remains open until you call the HelpClose routine (below). HelpRegister is normally called at application initialization (e.g. Form_Load). You must call HelpRegister before showing any Help topics. HelpFileName$ is the name of the help file required by your application. It can be any valid MS-DOS file name. You must include the appropriate extension (.HLP or .TXT for example). Note that the Help Toolkit will NOT search your path for the file so it may be necessary to supply a fully qualified file name (e.g. "C:\MYAPP\MYHELP.TXT"). Success% will be set to TRUE if the Help file was successfully registered and to FALSE otherwise. The Success% flag should be checked before making subsequent Help Toolkit calls to prevent run-time errors. HelpShowTopic TopicName$ ------------------------ Calling HelpShowTopic with a valid TopicName$ causes the Help Toolkit to display the text for TopicName$. The Help form will be restored to its former size and location if it is minimized when HelpShowTopic is called. TopicName$ must be the name of a Help topic. An error will occur if the Help Toolkit cannot find the TopicName$. HelpRegister must be called before calling HelpShowTopic but it is not necessary to call HelpRegister before every HelpShowTopic. HelpSearch ---------- HelpSearch opens the Help Toolkit topic search dialog box. The Help form will display the selected topic unless the user chooses the Cancel button. HelpRegister must be called before calling HelpSearch but it is not necessary to call HelpRegister before every HelpSearch. HelpClose --------- HelpClose closes the Help file and UNLOADs the Help form. Call HelpClose before you end your application. HelpClose should always be called when your application's last form is being unloaded. HelpSetOptions BackColor%,ForeColor%,DialogBackColor%,DialogForeColor%,ButtonColor%,SelectColor%,Flags% ------------------------------------------------------------------------------------ This is an optional routine that makes it easy to customize the look of the Help form. You cannot call this procedure before you call HelpRegister. The Help Tookit will use the default values listed below if you do not call this procedure. BackColor% is a value between 0 and 15 that specifies the text background color on the Help form. Default is 7 (gray). ForeColor% is a value between 0 and 15 that specifies the text foreground color on the Help form. Default is 0 (black). DialogBackColor% is a value between 0 and 15 that specifies the background color of the Help dialog boxes (Search, History, and Copy). Default is 7 (gray). DialogForeColor% is a value between 0 and 15 that specifies the foreground color of the Help dialog boxes (Search, History, and Copy). Default is 0 (black). ButtonColor% is a value between 0 and 15 that specifies the command button background color on the Help form. Default is 7 (gray). SelectColor% is a value between 0 and 15 that specifies the foreground color of Help links selected using the TAB key. Default is SCREEN.CONTROLPANEL(0) (AccessKey Color). Flags% is a bit field that sets the VISIBLE status of the five command buttons and enables other Help Toolit options. Add the values below to show buttons and enable functions. Function Value Default --------------------- ----- ------- ESC Closes Help 1 0 UNLOAD Help at Form Close 2 0 No Contents Button 4 0 No Search Button 8 0 No Back Button 16 0 No History Button 32 0 No Copy Button 64 0 For example, Flags = 65 would allow ESC to close Help and hide the Copy button. Space is only reserved at the top frmHelpMain if at least one button is visible. Buttons normally to the right of missing buttons will shift to the left to fill gaps. The Help Toolkit will automatically call HelpRegister to re-open the Help file if HelpShowTopic or HelpSearch is called after the Help form has been unloaded. This can only happen if: 1. Unload on Form Close is TRUE and the user closed the Help form. Or 2. An error such as "Insufficient Memory to Display Help" caused Help to close itself. Registering a Help file can take some time so Unload at Form Close should be set to FALSE unless: 1. The Help Toolkit is running standalone (as it is now). Setting Unload at Form Close to TRUE allows the application to end when the Help form is closed. 2. Memory is extremely constrained. See Adding Help to Your Applications and Example Help Toolkit Application