In a perfect world, you could create an application that would not require any explanation. In this perfect world, your user could simply view any form in your application and instantly know how to use it. No assistance would be required. Unfortunately, the world is not perfect. Even with the elegant graphical user interface that Windows provides, it is necessary that you provide users with guidance in using your application. This can be accomplished relatively easily by including Help files with your application.
Before you venture into the process of creating a custom Help file, it is important that you become familiar with the basics of working with Windows 95 Help. This provides you with a context within which to develop your own Help files. Your own Help files should provide your users with the same look and feel as the Help files included with Access, Word, Excel, and the other standard products with which your users should already be familiar.
Figure 34.1 shows the Access Help dialog. Notice the Contents, Index, Find, and Answer Wizard tabs. These tabs are standard for many Windows applications. Each tab of the Help dialog provides users with a different interface for obtaining the help they need.
Figure 34.1. The Microsoft Access for Windows 95 Help Topics dialog.
The Contents tab of the help dialog provides an expandable/collapsible table of contents for the Help file. Using the contents tab, the user can peruse the available topics, learning about all aspects of your application. After locating a topic that she wants to obtain help on, the user can simply double-click the item and Access provides help on the selected topic (see Figure 34.2).
Figure 34.2. This is a help topic selected from the Contents tab in Access's online help facility.
The Index tab replaces the Search dialog available in previous versions of Windows. It enables users to search for help topics using keywords (see Figure 34.3). When the keyword is found, users can double-click the entry that they want to obtain help on. A Topics Found dialog appears if more than one entry is found on the selected help topic (see Figure 34.4). Otherwise, the user is immediately provided with help on the selected topic. The help provided can appear in the main Help window or, alternatively, in a secondary Help window. Usually, overviews are displayed in the main window and step-by-step instructions for accomplishing specific tasks are provided in a secondary window.
Figure 34.3. Using the Index tab to search for a keyword.
Figure 34.4. The Topics Found dialog.
The Find tab enables users to search for a particular word or phrase. After typing the selected word or phrase, users are provided with a list box that enables them to refine their search. Upon selecting a matching word from the list box, a list of topics associated with the matching word is displayed (see Figure 34.5). Users can then double-click the entry they want to learn about.
Figure 34.5. Using the Find tab.
The Answer Wizard is a special feature that allows users to enter English-like questions and to obtain a list of topics associated with their questions. Notice in Figure 34.6 that the question is "How do I Create a Query?" After the user clicks Search, a list appears of all of the available topics relating to the question.
Figure 34.6. Using the Answer Wizard.
Button bars within the Help window enable the user to easily navigate through Help. The secondary Help window shown in Figure 34.7 enables the user to view Help topics, move back to the previous Help topic, or view available options. Button bars are fully customizable so that you can provide your users with the appropriate options.
Figure 34.7. Online help has button bars for easy navigation. This button bar has buttons for Help Topics, Back, and Options.
The underlined words, phrases, or sentences that appear in green within the Help topic are called hotspots. When the user places the mouse over a hotspot, the mouse pointer turns into a hand. If the user clicks over a hotspot underlined with a dotted line, a popup window appears with specific information about the hotspot item (see Figure 34.8). When the user clicks anywhere else, the popup window disappears. When the user clicks over a hotspot underlined with a solid line, help is displayed about a related topic.
Figure 34.8. A topic popped up from a hotspot.
Help topics can contain pictures (images) set up to operate as hotspots. When the user places the mouse over the picture, the mouse pointer appears as a hand. When the user clicks the hypergraphic, a popup window displays, providing additional information about the picture. The hypergraphic in Figure 34.9 shows the Query Type tool. After the user clicks the picture of the tool, a popup window appears displaying additional information about the Query Type tool.
Figure 34.9. The interlocked table graphic just under the words "query Design view" is a hypergraphic. Clicking on it jumps you to the topic of appending records using a query.
Figure 34.10 shows an example of authorable buttons. These buttons perform an action, such as displaying a secondary window, when they are clicked.
Figure 34.10. Authorable buttons have small double greater than signs (>>) on them. You can see them to the left of the help topic list.
Before you worry about how to build a Help file, you should plan out what it will look like. What you provide in a Help file is determined by the type of users that will be working with your application. For example, if you application will be distributed to a wide range of users, including those new to Windows, your Help file should include the most basic information. On the other hand, if your application is directed toward power users who are extremely adept at Windows and maybe even Access, your Help file should focus on assisting the user with the more complex aspects of your application. In general, your Help file should contain the following:
Depending on the level of the users, you might want to provide additional detail, such as a description of terms, concepts, or Windows 95 or Access skills required for the use of your application.
When you have decided what to include in the Help file that will accompany your application, you are ready to begin the process of creating the actual file. The following is an overview of the tasks required in order to build a custom Help file:
Each of these steps is covered in detail in the sections that follow.
The first step in creating a Help file is to create a Topic file. The Topic file is a Rich Text Format (.RTF) file containing all of the text and formatting codes that will appear in the Help file. A Help project must contain at least one Topic file. It can contain more than one topic file if you choose. Help Topic files can be created in Microsoft Word or using any tool that allows you to build a file in the RTF format. This file format contains special characters and formatting that the Help compiler uses to build the custom Help file.
Several Help authoring tools are available to assist you with the process of building a Topic file. These include RoboHelp, Doc-To-Help, and ForeHelp, just to name a few. These valuable tools (discussed in the "Getting Help With Help: Authoring Tools" section of this chapter) assist you with the process of building the RTF file. Even if you plan to use one of these tools, it is a good idea to understand how the RTF file is built. This section provides you with the knowledge and tools to build and work with an RTF file.
This text covers how to build a Topic file using Microsoft Word for Windows 95. The steps can easily be modified to work with other versions of Microsoft Word or with other tools that allow you to save a file in the RTF format. To begin the process of building the Help Topic file, follow these steps:
Figure 34.11. Selecting Rich Text Format from the Save As dialog.
You are now ready to begin the process of entering the text and formatting codes that dictate the content, appearance, and functionality of your custom Help file. The Help compiler uses various footnotes as codes to designate the role that each portion of the RTF file will serve. In other words, each footnote communicates the function of the text to the Help compiler. For example, the pound sign (#) is used to designate a unique Topic ID for the text that it precedes. You add each help Topic with the appropriate footnote codes. Here's how it works:
Figure 34.12. Inserting a special footnote code.
Before you walk through the step-by-step process of building a Help topic, it is important that you understand the meaning of the more commonly used footnote codes. They are covered in the following sections.
The pound sign (#) footnote is required for every Help topic. It is used to identify a unique Topic ID. This is the name that WINHELP uses to identify the topic. The Topic ID must be unique within the Help project.
The dollar sign ($) footnote is also required for every help topic. It is used to specify the Help Topic's title as it will appear in the Topics Found dialog, the Bookmark dialog, and the History window. This title should match the Topic title that appears in the Help window.
The letter K is used to specify search keywords for the topic. These are the keywords that the user can use when searching for the topic. Remember that users do not always remember the correct terms for the topic that they require help on. It is important that you are creative in designating search keywords so that you supply your users with a variety of terms that will bring them to the correct help topic.
Several other tags exist that enable you to build extremely complex Help files. For example, the asterisk (*) footnote enables you to create build tags. These build tags enable you to create several versions of a Help file using the same Help Topic file. This is an excellent option if you want to provide different Help files to the different levels of users to whom you will distribute your application. Other tags enable you to specify the window in which a Help topic is displayed, designate entry point macros, and so on. These more advanced tags are not covered in this text.
All of this might seem rather confusing to you. The best way to learn how it really works is to build your own Topic file. With a new RTF file open (see the "Creating an RTF File" section of this chapter), follow these steps:
Figure 34.13 illustrates the RTF file as it should appear after following the previous 15 steps. You can continue adding additional topics as desired.
Figure 34.13. An RTF file with a Help topic.
Access Help and the Help provided with many other products contain nonscrolling regions. These regions often include hotspots that read See Also or Example (see Figure 34.14). The nonscrolling region for the help topic pictured in Figure 34.14 includes hotspots for See Also, Example, Applies To, and Specifics. You can only have one nonscrolling region per Help topic. It must include the first paragraph of the Help topic (the one with the footnotes). To create a nonscrolling region, follow these steps:
Figure 34.14. The nonscrolling region of this help screen includes the areas of the title OpenDatabase Method and the link topics See Also, Example, Applies To, and Specifics.
One of the wonderful aspects of Windows Help is the capability to quickly jump from one topic to another related topic or obtain more information about an entry in the text. Hotspots enable you to provide this functionality to the users of your application. There are three types of hotspots:
Follow these steps to create a Jump hotspot:
Figure 34.15 gives an example. The double-underlined word projects jumps to the Topic ID ProjectForm. The word client (marked as hidden) jumps to the Topic ID ClientForm.
Figure 34.15. An example of a Jump hotspot.
To create a popup hotspot, follow these steps:
Figure 34.16 shows a popup hotspot with the word ID that pops up a window with the help text with the associated Topic ID of UniqueIdentifier.
Figure 34.16. An example of a popup hotspot.
The WinHelp engine supports the following four types of graphic files:
Graphics files can be embedded in the Topic file, or they can be referenced. It is almost always best to reference a graphic file rather than embed it in the Topic file. Embedded graphics require a significant amount of memory and are generally not practical. To reference a graphic file, insert the following statement where you want the graphic to appear:
The bm is hardcoded text. The x is a variable that can be set to c, l, or r. The letter c indicates that the graphic is like a character and will flow with the text. The letter l indicates that the graphic will appear as if it were in a left-justified frame; text will flow around the picture. The letter r indicates that the graphic will appear as if it were in a right-justified frame and, again, the text will flow around the picture. The t parameter is optional. If it is used, the background color of the graphic is replaced with the background color of the help topic containing the graphic.
Figure 34.17 shows the bitmap called contacts.bmp as it flows with the paragraph within which it is inserted.
Figure 34.17. Inserting a graphic.
A hypergraphic is a picture that functions like a hotspot. When the user places the mouse over the hypergraphic, a hand appears. If the user clicks the graphic, a popup window appears. Here is how to add a hypergraphic:
Figure 34.18 shows an example in which the Contacts.Bmp bitmap is used as a hotspot to pop up a window containing Help with the Topic ID of ClientForm. The name of the graphic is underlined and the Topic ID is hidden.
Figure 34.18. Inserting a hypergraphic.
A map file is an optional ASCII text file that contains a context number for each Topic ID. These context IDs will ultimately be used to associate a particular Help topic with a specific form, report, or control. Associating a Help topic with a specific form, report, or control is covered in the "Adding Custom Help to Your Applications" section of this chapter.
Although the map file is optional, it is highly recommended. You can map Help topics to context numbers directly in the Help Project file, but this can become unwieldy even with the smallest of Help files. A map file is very easy to create, so there is really no reason to refrain from creating one.
To create a map file, follow these steps:
Figure 34.19 shows a map file containing context numbers associated with four different Topic IDs. For example, the ClientForm Topic ID has been associated with a context number of 150. The UniqueIdentifier Topic ID has been associated with a context number of 450.
Figure 34.19. Building a map file.
A context number must be created for each Topic ID in the Help file. When assigning context numbers, you should leave extra room between each topic number. This enables you to easily insert additional related items at any time. The idea is that you want your topic numbers to be logically sequenced and you do not want to change a topic number after it has been associated with an Access object.
Figure 34.19. Creating a map file.
A Contents file is an ASCII text file that is used to determine the table of contents that appears in the Contents tab of the Help Topics dialog. The Contents file must be distributed along with your application and the compiled Help file (.HLP). Here is how to create a Contents file:
Figure 34.20. Creating a contents file.
Figure 34.21. Viewing the table of contents.
The Help Project file brings everything about the Help file together, including the following:
The easiest way to build the Help project file is to use the Help Workshop. You can obtain the Help Workshop in one of the following ways:
You can launch the Help Workshop using the Start menu or with a desktop shortcut. Figure 34.22 shows the Help Workshop window when the Help Workshop is launched.
Figure 34.22. The Help Workshop window.
To create a new Project file, follow these steps:
Figure 34.23. Selecting the type of file you are creating.
Figure 34.24. The Project File Name dialog.
Figure 34.25. The Help Workshop window after creating a project.
Now that you have created a new Help file, you must perform several tasks to prepare the Help Project for compilation. You must specify the Help Topic file, the Map file, and the location of any graphics files. You probably also should customize the Help window and specify other optional settings. The steps involved in performing each of these tasks are covered in the sections that follow.
The first step is to locate the Help Topic file. This is the .RTF file that you created in the "Creating a Topic File" section of this chapter.
Figure 34.26. The Topic Files dialog.
The next step in the process is to designate the location of the Map file, which is accomplished with the following steps:
Figure 34.27. The Map dialog.
You do not need to specify a Bitmaps folder if the bitmaps are in the same folder as the Help Project. If the bitmaps are in a different location than the Help Project, you must follow these steps.
The Help Workshop gives you the opportunity to create secondary Help windows. Secondary Help windows are often used to provide the user with step by step guidance in completing a process. To add new Help windows, click the Windows button. The Window Properties dialog appears, as shown in Figure 34.28.
Figure 34.28. The Window Properties Dialog.
From the Windows Properties dialog, you can add and customize new Help windows. To add a new Help window, follow these steps:
Figure 34.29. The Add a New Window dialog.
Figure 34.30. The Buttons tab of the New Window dialog.
The new window can be used in the following ways:
To have the new Help window appear when the user selects the Help topic from the Index tab or Find tab, you must use the Greater Than (>) footnote when adding the Help topic. Figure 34.31 gives an example. Notice the >AddProj footnote for the AddNewProject topic. The >AddProj indicates that the AddNewProject topic should be opened in a window named AddProj.
Figure 34.31. Instructing a Help topic to appear in another window.
To have the new Help window appear when the user clicks a Jump hotspot, you must follow the Topic ID with a Greater Than (>) symbol and then the name of the window (see Figure 34.32). The Hotspot New Projects jumps to a topic called AddNewProject, opening it up in the AddProj window.
Figure 34.32. Instructing a Jump topic to appear in another window.
The Help Workshop offers some final options. To access these additional features, click the Options button. The Options dialog appears (see Figure 34.33). This dialog has several tabs. Each tab enables you to define different aspects of your Help project. For example, the General tab enables you to specify a default Help topic and define a title for the Help window. The Compression tab enables you to select a level of compression for the compiled Help file. The higher the level of compression, the longer the Help file takes to compile, but the less space the Help files require. Also, if you use Maximum compression, the Help file loads more quickly and operates better on the user's machine.
Figure 34.33. The Options dialog.
After you select a Help Topic file, specify the Map file, define the location of your graphics files, add and customize any additional Help windows, and indicate any special options for the Help project, you are ready to compile the project into a .HLP file. This is the file that will be used by your Access application. Figure 34.34 shows what the Help Workshop Project window looks like when you are ready to compile. Notice the Options, Files, Maps, and windows defined as part of the Help project. To save all changes to the Help file and then compile it, click the Save and Compile button. If the project is successfully compiled and saved, the Help Workshop window should appear as in Figure 34.35. Notice that in the example, five topics, five jumps, 15 keywords, and one bitmap have been defined. The Help file compiled with no errors or warnings. The file MyHelp.hlp is now compiled and ready to be attached to an Access database.
Figure 34.34. The Help Workshop Project window before compilation.
Figure 34.35. The Help Workshop Project window after compilation.
After you have created a compiled Help file, you need to let your application know that it is available. You must also associate different objects within your application with different help topics within the Help file. Each form and report has a Help File property and a Help Context ID property (see Figure 34.36). The Help File property must be filled in with the name of a compiled Help file. The Help Context ID is the number that you defined within the Map file. Each control on a form contains a Help Context ID property. If you fill in this property with a Context ID as specified in the Map file, the Help topic that has the Topic ID associated with the specified Context ID appears whenever that control has focus and the user presses F1. For example, the number 150, found in the Help Context ID of the frmClients form shown in Figure 34.36, is associated via the Map file with the Help Topic ID ClientForm.
Figure 34.36. Associating a form, report, or control with a specific Help topic.
Many people feel that the process of creating the RTF Topic file in Microsoft Word (or using another word processor) is tedious and difficult. Fortunately, several third-party tools are on the market to assist you with this process.
RoboHELP is one of the more popular help-authoring tools. Available from Blue Sky Software, this excellent tool adds user-friendly toolbars, menu commands, and dialog boxes to Microsoft Word, significantly easing the process of creating the RTF file. Creating the footnotes and jumps as well as adding graphics to the RTF file becomes a matter of pointing and clicking. RoboHELP also facilitates the process of building help into your application by automatically creating and maintaining the Help Project and Map files for you!
Another popular help authoring tool is Doc-To-Help. This product, offered by WexTech Systems, enables you to create a printed manual and online help at the same time. Like RoboHELP, Doc-To-Help provides templates that add buttons and menu commands to Microsoft Word, making the process of developing the RTF file a matter of pointing and clicking.
The MyHelp.Rtf file, included on the sample code CD-ROM, contains Help Topics that assist with the following tasks:
The MyHelp.rtf Topic file has been compiled along with the MyHelp.map Map file to build the MyHelp.hlp Help file. The MyHelp.cnt Contents file is also included on the sample code CD. The resulting Help file has been associated with the CHAP34.MDB database. The ClientForm Topic ID has been associated with the frmClients form. The ProjectForm Topic ID has been associated with the frmProjects form. The ViewProjectsButton Topic ID has been associated with the cmdViewOtherProjects command button on the frmProjects form. The AddNewProject Topic ID and the UniqueIdentifier TopicID can both be accessed using hotspots included in the ProjectForm topic (see Figure 34.37). The Help project is complete with Windows standard Help Context, Index, and built-in printing capabilities.
Figure 34.37. Help within the Time and Billing Application.
Most Windows products today ship with extremely elegant and effective help systems. Windows users are accustomed to pressing their F1 keys to obtain the assistance they need even to accomplish the most complex of tasks. To provide the professional polish that your users expect in an application and to assist them with getting the most out of the product you provide, it is necessary that you include a custom help system as part of your application. Using the tools that ship with Microsoft Access and the Access Developer's Toolkit, or employing the assistance of third party tools, you can provide your users with very elegant (and often expected) online help documentation at their fingertips.