Visual Basic Expert SolutionsChapter 18Developing Online HelpBy Jon Oelschlaeger |
One very visible quality measure of a professionally developed Visual Basic application is advertised by the scope and usability of its Help system. Oftentimes this is an overlooked aspect of an otherwise well crafted program. An application with no Help system, or one that's amateurish, is frequently the result of not understanding how to effectively develop and control a Help system. In this chapter, we'll cover the following:
Achieving an understanding of the Windows Help environment begins with a clear-cut definition of the components involved. In this regard there are both runtime components of your Visual Basic program supporting the Help system, and components used during the design phase to develop the Help system.
First, let's look at the relationship between your Visual Basic program, the Windows Help engine, and your application's Help system files (*.HLP files). As shown in figure 18.1, your Visual Basic application will typically have several interfaces to the Windows Help system.
Fig. 18.1 Your Visual Basic application's Help system interfaces can be used to make Help easily accessible from within your application.
Next, let's look at the software components that are used during the design of your Visual Basic application's Help system. The files involved and the Help compiler are shown in figure 18.2. The subsequent sections survey various tools that are designed to create and manage these files.
Fig. 18.2 The components of a designtime Help system are compiled into a user-friendly Help system.
The remainder of this chapter incorporates some very specific terminology regarding development and use of a Help system. The following is a list of terms and their relationships:
Note: As of the writing of this book, the Version of the Help Compiler for HCP or HC is Version 3.10.505. The most current version of the Help Compiler is available from CompuServe on the Windows Development forum. If in doubt, check to see if you have the most current version of the Help compiler.
The central concept in a Help system is the topic. A topic is a sort of modular unit of explanation in the Help system that can stand alone and convey essential information. Physically, topics are delimited from each other in the source text of your Help system by hard page breaks. Topics are identified uniquely throughout the Help system by means of an associated context string.
A context string is an arbitrary string that acts as an address or location within the completed and compiled Help system of a Help topic. Context strings therefore are used to reference topics.
Context strings are used by pop-ups, jumps, and jump or pop-up hotspots to identify the topics to be displayed in the pop-up window, or the location to which to jump.
And finally, keywords are words that are associated with one or more topics (or actually the topic's context string). Keywords are displayed in the upper list portion of the Window's Help Search dialog box, and the associated topics are displayed in the lower list of the dialog box. Thus, keywords act much like the index section of a book.
There are two fundamental mechanisms that you can use to invoke your application's Help system. One mechanism is to control the Help system by means of Visual Basic code. The other mechanism is to control the Help system using Visual Basic's built-in context-sensitive jumps into the Help system by using the F1 function key. Both approaches can, and should, be used together within the same application, and are generally complementary to each other.
Note: The Windows Help engine (WINHELP.EXE) can be invoked directly because it is an ordinary Windows executable program. Many people have not had the experience of just starting WINHELP, and should try it at least once. In the startup screen, you should notice some characteristics of WINHELP all by itself. First, if you don't specify Windows Help resources file (*.HLP) when starting WINHELP, Windows Help to initializes with only a logo screen and menu bar. In addition, there are only four standard menu bar items—File, Edit, Bookmark and Help. In the section "Setting Up Added Menus" (later in this chapter), you learn how to customize the standard menu bar and drop-down menus associated with each menu bar item to suit your own special purposes.
The next section examines techniques for controlling your Help system using Visual Basic coding techniques.
Usually you invoke WINHELP indirectly by using the Windows Common Dialogs capabilities, Windows API calls, or by using context-sensitive Help and Help Context IDs that are associated with objects in your Visual Basic application user interface.
When you invoke the Windows Help engine from your Visual Basic code, you can start it in one of several operating modes. These modes are generally known as:
Starting the Help engine in one or the other of these modes is typically accomplished by having the menu items as part of your Visual Basic application's menu system, and then using either the Common Dialogs or Windows API calls to invoke the corresponding mode based on the menu items Click event procedure.
The simplest and most direct way to invoke the Windows Help engine in code is to make use of the Common Dialog Control (CMDIALOG.VBX) provided with Visual Basic. The Common Dialog control enables you to invoke one of six standard Windows dialog boxes. Each of the six dialog boxes has its own unique properties that are set before execution of the dialog box.
To invoke the Help engine, you set some properties of the Common Dialog control, and then invoke the dialog box by setting the Action property to DLG_HELP (for example, integer value = 6).
Let's look a little more closely at how you can get the Windows Help engine started with a particular *.HLP file loaded, and in a specific mode by setting the properties of the Common Dialog control. When invoking the Windows Help system, the Common Dialog uses the properties in Table 18.1.
Table 18.1
Table 18.1 The Common Dialog Properties
Property |
Purpose and Effect |
HelpFile |
Sets the *.HLP Help resource file to use in Help engine when it is started. |
HelpCommand |
Sets the Mode of the Help engine, according to: context displayed. |
HELP_CONTEXT—starts with particular Help |
|
HELP_HELPONHELP—displays Help on Help the Help engine itself. |
|
HELP_INDEX—displays the Index of the Help file. |
|
HELP_KEY—displays Help for a specified keyword. |
|
HELP_QUIT—terminates use of a Help file and the Help engine. |
|
HELP_SETINDEX 7Ästarts Help with a specific index key set. |
|
HelpContext |
Specifies the Context ID of the desired Help topic; used to invoke a specific Context ID. |
HelpKey |
Specifies a keyword that identifies the Help topic; sets the index key. |
Action |
Set to DLG_HELP, invokes the Help engine. |
In the section "Understanding the Help Project File" (later in the chapter), we'll discuss how you can control other aspects of the way that the Windows Help engine initializes, by choosing various options at the time you run the Help compiler to produce your Help resources file (*.HLP).
Using the Common Dialog to invoke the Help system appears to limit the modes and options that you can control. This might be inferred if you just refer to the Visual Basic Help topics associated with the search topic WinHelp. However, this impression is misleading.
The principle use of the Common Dialog is to invoke the Windows Help engine. You can, in fact, invoke the Windows Help engine using the Common Dialog control in any way that you can by making direct Windows API WinHelp function calls. For other modes of the Help engine, we'll next investigate using Windows API calls.
You can use calls to functions in the Windows API to invoke the Help engine and to select its operating modes. The Windows API function that you need to call is the WinHelp function.
The WinHelp function as defined in a Visual Basic formatted external DLL library function declaration is as follows:
Declare Function WinHelp Lib "User" (ByVal hWnd As Integer,_
ByVal lpHelpFile As String,
ByVal wCommand As Integer, dwData As Any) As Integer
The purpose and use of each of the function's calling arguments is shown in Table 18.2.
Table 18.2
Table 18.2 The Arguments for the WinHelp Function
Argument Values and Effects
hWnd Window handle of window requesting Help.
lpHelpFile String specifying file name of Help file.
wCommand Integer specifying the operation of the Help
system as:
HELP_CONTEXT—displays Help for a particular topic
specified by dwData context ID.
HELP_CONTENTS—dwData ignored; displays Help
Contents topic.
HELP_SETCONTENTS—dwData ignored; sets Help Content
topic.
HELP_CONTEXTPOPUP—dwData is a pointer to a
HelpContextID; displays PopUp with ID number.
HELP_KEY—dwData is a pointer to string containing a specific keyword; puts
Help in Search mode.
HELP_PARTIALKEY—dwData is a pointer to string for
partial keyword; puts Help in Search mode.
HELP_MULTIKEY—dwData is a pointer to MULTIKEY data
structure.
HELP_COMMAND—dwData is a pointer to string
containing a Help macro; executes macro.
HELP_SETWINPOS—dwData is a pointer to a HELPWININFO structure; sets Help
window position and other attributes.
HELP_FORCEFILE—dwData ignored; changes Windows Help file to a different
file.
HELP_HELPONHELP—dwData ignored; displays Help's
Help file.
HELP_QUIT—dwData ignored; Windows closes WinHelp
engine.
dwData Long specifying additional data depending on wCommand as presented in the list above. Ignored means dwData can be set to 0& (long null pointer).
As mentioned in the previous section, any of the symbolic constants that can be used with the WinHelp API function call can also be used to accomplish the same objectives with the Help Common Dialog control. Any of these symbolic constant values can be set as the HelpCommand property of the Common Dialog. Corresponding values for the HelpKey and HelpContext property also must be set prior to setting the Common Dialog Action property to DLG_HELP.
For example, to invoke the Windows Help engine in the general search mode, you would set the HelpKey property to a NULL string, and set the HelpCommand property to HELP_PARTIALKEY. Invoking the Help Common dialog box by setting the Action property to Dlg_Help would start the Windows Help engine in the Search mode.
Setting the HelpKey property to a partial search string (for example, HelpKey = "s") and then setting the HelpCommand property to HELP_PARTIALKEY starts the Windows Help engine in the Search mode with the letter "s" as the preset default search key and so forth. The results of using this setting of the HELP_PARTIALKEY, and using the CALC.HLP Help file, are shown in figure 18.3.
Fig. 18.3 Use the HELP_PARTIALKEY property—set to "s" to start the Help engine with a specific value.
The Visual Basic code for invoking the Windows Help engine in the PARTIALKEY mode is in Listing 18.1.
Listing 18.1 HELPSRC1.BAS Using the PARTIALKEY Property
Alternatively, the WinHelp function call can be eliminated by using the Visual Basic Common Dialog VBX, as shown in the following code:
Either of the above techniques will give you the same results.
Another method to invoke your Visual Basic application's Help system is to use the Help Context IDs of the objects that make up your application's user interface, along with the F1 Key. This is called context-sensitive help. Support for it is a built-in feature of Visual Basic.
Context-sensitive help is very valuable to the user. When your application is running, the user merely moves the focus to a particular object in any user interface window and presses the F1 key. This causes the Windows Help engine to be loaded and initialized at a specific topic within the Help resources file—the topic assigned to the object that has the focus. Setting up this object-to-topic relationship, and specifying the correct Help resource file are discussed in this section.
In order to establish the Help file that is used with context-sensitive Help, you need only set the HelpFile by choosing Options, Project in Visual Basic. Executing these menu commands invokes the dialog box shown in figure 18.4. Setting the Help File item in this dialog box creates the association between your Visual Basic application and the context-sensitive Help file.
Fig. 18.4 You can set your application's Help File in the Options dialog box.
Each visible screen object in your Visual Basic application includes the property HelpContextID. The value setting of this property determines which Help topic is presented when the user is focused on the object, and then presses F1. The relationship between these values of HelpContextID and the corresponding topic is established in the [MAP] section of your Help Project file (MYAPP.HPJ).
As an example, assume that the following is part of the [MAP] section of your Visual Basic application's MYAPP.HPJ Help Project file:
The string on the left-hand side of each line in the [MAP] section is called a context string, which corresponds to some Help topic in your MYAPP.RTF text. The number on the right-hand side of each line is the HelpContextID property value you would assign to the control or menu object. During program execution, when the focus was set to the object and the F1 key was pressed, your application's Help file would be loaded along with the Windows Help engine, and the topic referenced by the context string would be displayed automatically.
Invoking your application's Help file is in some ways the simplest aspect of adding a Help system to your Visual Basic application. Most of the really hard work involves developing the Help files in the first place.
The central concept in developing your Help files revolves around authoring one or more technical manuals that comprise the raw material from which your Help files are created. This authoring process is quite similar to the process involved in writing any type of technical documentation.
Without a doubt, the most important step in authoring your Help system is planning. This is true of writing any type of technical documentation, but it is even more important when working on a Help system. Planning is important because at each step you will make decisions that are time consuming to edit or rework later.
Your best time investment is to develop a fairly detailed schematic of the way you anticipate your Help system needs to work after it is completed. With this detailed schematic, you can then proceed to actually develop the Help topics that comprise the body of your Help system. Even with this advance planning, there will always be the inevitable modifications and changes that crop up during writing of your Help system documentation. However, with a clearly defined plan, incorporating these changes or additions is much easier to manage, because you will have a well-defined frame of reference.
Therefore, suggested planning steps are as follows:
A typical topic hierarchy for a simple application might look something like that shown in figure 18.5.
Fig. 18.5 The topic hierarchy of a Help system determines the navigation path through the information.
Once you have a detailed plan for your Help system, you are ready to begin writing the materials used for each of the Help topics. The process involved in this writing step is like writing any other documentation.
At a minimum, you'll need to use a word processor that supports writing documents in RTF (Rich Text Format), and incorporate the specialized codes that provide information for the Windows Help compiler. There are a number of high-end Windows and DOS-based word processors that can be used to accomplish this task. However, throughout the remainder of this chapter we'll be restricting our attention to Microsoft Word for Windows, because many of the tools to assist you in this process are centered around Word for Windows.
In addition to the ordinary text that comprises the written materials of your RTF formatted Help materials, you need to embed special codes within your RTF files. These codes are processed by the Help Compiler while it creates the HLP Help resource files used by the Windows Help engine. These special codes are formatted as footnotes, or embedded in-line with the rest of the text in your RTF files. These special codes are listed in Table 18.3.
Table 18.3
Table 18.3 The RTF File Codes
Special Code |
Name |
Purpose |
Number Sign (#) |
Context String |
String that uniquely |
Footnote |
identifies a topic. Used for links. Topics without context strings can only be displayed with keywords in a browse sequence. |
|
Dollar Sign ($) |
Title |
Defines topic title. |
Footnote |
Titles appear in list box in Search mode. Titles are optional. |
|
Letter K (K) |
Keyword |
Defines keyword for topic |
Footnote |
using the standard keyword table search. Keywords are optional. Other Letters can be used as such footnotes to provide other alternative keyword search tables. |
|
Plus Sign (+) |
Browse Sequence |
Defines a sequence |
Footnote |
number determining user browse order. Browse sequence numbers are optional. |
|
Asterisk (*) |
Build Tag |
Help compiler conditional |
Footnote |
inclusion tags. |
|
Strikethrough or Double-Underline |
Jump Text |
Specifies jump to another topic. Jump text is followed by Context String of topic for jump |
Underlined Text |
Definition |
Specifies that a pop-up window is to appear. Underlined text is followed by context string for topic of the pop-up content. |
Hidden Text |
Context String |
Specifies context string for topic to be displayed when user selected text immediately preceding. Embedded jump to a topic. |
{command fn.ext} |
Graphics |
Reference to graphics command —file name and extension, and graphic positioning. |
The methodology for coding and using these special Help compiler codes is fairly involved if you just use a word processor to create your RTF files. Using a Help authoring tool can automate the correct insertion of these specialized compiler codes.
Design of the indexing scheme for your Help system is very important. After designing the general topic hierarchy and relationships for your Help system, the indexing scheme is the next highest priority.
The Windows Help engine uses keywords as the mechanism for implementing index searches. The process of selecting keywords, therefore, is identical to the process of developing the index section of any book. Keywords are often the most efficient and direct way for a user to find the Help topic information they need.
There are numerous ways to orient an indexing scheme for Help information. Oftentimes, combinations of one or more orientations proves to be the most effective for the Help system user. Possible orientations are:
Designing an effective index (or, in this case, keyword system) is usually not simple. It deserves a great deal of thought and planning, since the usability of the index scheme will more than anything else determine the effectiveness of the Help system to the end user.
The basic idea of keywords is that a particular keyword is associated with one or more Help system topics. The keywords themselves appear in the upper list box in the Help system Search dialog box. See figure 18.6 for the Search dialog box.
Fig. 18.6 The Help system Search dialog box shows keywords and topics (using Visual Basic Help file).
For each keyword in the upper list box, there are one or more Help topics presented in the lower list box of the dialog box. Selecting one of the topics causes a jump to the selected topic within the Help system.
Next in importance after a well designed keyword scheme is a well developed browse sequence. The browse sequence defines the order in which Help system topics are presented to the user when she clicks the Browse Forward (>>) and Browse Back (<<) buttons on the Help engine's Toolbar. To the user, these browse buttons present Help system topics in an apparent linear subject order that is similar to reading successive topics in a book. Although the user isn't really browsing in this fashion, she is lead through a succession of related topics determined by the Help system developer. This ordering is called a browse sequence.
A browse sequence design should arrange topics in an order that would make sense to the user. Typically, browse sequences are constructed along the following organizational lines:
Browse sequences consist of a browse sequence group and an order number within the group. For plus-sign (+) footnotes that define browse sequences, the group name string is separated from the order number by a colon, as follows:
Browse sequences can also be organized into a hierarchy, using a major topic and minor topic type of structure, like the following:
In the above example, Topic_1_Main and Topic_2_Main are members of the MajorTopics group, with the order being Topic_1_Main first in the browse order, and Topic_2_Main second.
Within Topic_1_Main, the sub-topics are in the browse order Topic_1:005, then Topic_1:010, and finally Topic_1:015.
Build tags are strings that control conditional compilation of a particular set of topics. Each topic in the Help source text (*.RTF files) can have one or more associated build tags. These can be used to produce different versions, and therefore different content Help resource files during compilation.
Build tags are associated with the asterisk (*) footnote compiler codes. If more than one build tag is assigned to a topic, the successive build tag strings are separated by a semi-colon (;).
At compilation time, all of the topics with the build tag specified in the [BUILD] section of the Help Project file (*.HPJ) are included in the compilation. In addition, all topics for which no build tags are specified are also included in the compilation. Therefore, the use of build tags can be considered to operate in an exclusionary fashion. That is, any topic with a build tag defined for which no corresponding build tag inclusion is specified in the Help Project file's [BUILD] section will be excluded from compilation.
The context strings that you define for your Help system topic information provides the mechanism for navigating through your completed Help system. In addition to the keyword and browse navigation previously discussed, the context strings provide the addressing information for the following types of Help system navigation:
These facilities provide the fundamental navigational features of the Windows Help system. More sophisticated types of jumps can also be implemented in your Help system.
Oftentimes all of the Help topics you might want to use may not be present in a single Help file. There are several circumstances where you might encounter this, for example:
To jump to a topic in another Help file, just follow the jump's context string with the "@" symbol, and then the path and file name of the Help file that contains the desired topic. An example might be the following:
Don't forget that once you have jumped out of a Help file, the only way for the user to get back to the original Help file is to use the "Back" button, the "History" list, or through another explicit jump that refers to the original Help file.
In addition to the basic navigational techniques outlined in the previous section, it is possible to achieve more complex and more sophisticated types of jumps.
Up to this point, we have assumed that any of the jumps that we specify will cause the topic to which you jumped to be presented in the main Help window. It is possible, however, to specify jumps that display the topic in a secondary window. To accomplish this, follow the jump's context string reference with the ">" symbol, and specify a named secondary window within which to display the topic identified by the context string. For example:
The section entitled "Setting Other Compiler Options" (later in this chapter) examines how to define named secondary windows that can be used for this purpose.
Thus far, you have looked at the basic terms and steps in planning a Help system, as well as the navigational techniques for maneuvering through the Help system topics. Now that you have some idea what the terminology means, and what can be done within a Help system, you can focus on the Help compiler and the all-important Help Project file that gives the Help compiler its marching orders.
The components of your Help project consist of one or more RTF (Rich Text Formatted) files, along with the embedded special codes outlined in the previous section. All of the text in an RTF file contains special formatting codes. These codes are what makes an RTF file self-describing, and an exchangeable file format between word processors supporting this format. So just by using an RTF-capable word processor you automatically accomplish much of the work of preparing your Help text for the Help compiler.
Additionally, any of the bitmaps and other graphics that you've produced, along with any 'hot spots' you've embedded will become components of your Help file. These bitmaps, graphics, and hotspots can be part of the user topic selection interface, as well as decoration to add visual interest.
09r.gif">Finally, instructions to the Help compiler, contained in your Help Project file, round out the components of your Help project. The section "Creating the Help Project File" has more information about the Help Project file sections that provide information to the Help compiler.
Using bitmaps and graphics as active user interface elements involves embedding "hotspots" within the bitmaps and graphics. Embedded hotspots can be associated with context strings to control jumps, pop-ups, or can be used to invoke macros, thereby making them a mechanism for user interaction. The process of embedding one or more hotspots within a bitmap or graphic involves the use of the Hotspot Editor.
The Hotspot Editor is a software tool that is provided with Visual Basic. It is a Windows application named SHED.EXE. The Hotspot Editor enables you to load a bitmap or graphic and add one or more hotspots to the files before using them in your Help system. Figure 18.7 shows the Hotspot Editor with a bitmap loaded into it, and incorporating a hotspot.
Fig. 18.7 The Hotspot Editor shows a bitmap with a hotspot and the hotspot Attributes dialog box.
As you can see in figure 18.7, the bitmap graphic (SCREEN01.BMP) has one hotspot assigned within it—notice the rectangular box with the sizing handles near the top left corner of the bitmap image. You will also notice, in the Attributes dialog box near the center of the screen that the selected hotspot can be defined as a jump, pop-up, or macro hotspot. If it's a jump or pop-up, it can be assigned to a specific context string.
Multiple hotspots can be incorporated into a bitmap or graphic, each with its own set of attributes. Once the hotspots have been added, the bitmap or graphic is saved as an *.SHG file (Segmented Hypergraphics file).
Including these SHG files into your Help system project, and locating them within topic files, enables you to accomplish jumps, pop-ups, and macro execution when the user clicks on the corresponding hotspots in the graphic.
The Help Project file is at the crossroads of pulling together all of many pieces of your Help system. It is the road map that identifies to the Windows Help compiler what files and other resources it's supposed to use to generate your Help resource file (*.HLP).
A Help Project file (*.HPJ) is an ordinary ASCII file without formatting. You produce it with any word processor or editor that can edit ASCII files.
The Help Project file contains the following sections that provide information to the Help compiler and tell it what it's to do. Section are identified by section names enclosed in square brackets (for example, [and]). These sections are listed in Table 18.4.
Table 18.4
Table 18.4 The Help Project File Sections
Section |
Purpose and Description |
[OPTIONS] |
Specifies options that control the compilation process. If it is used, it must be the first section. |
[FILES] |
This section lists all of the RTF text topic files to include in the compilation. This section must be present. |
[BUILDTAGS] |
Specifies the build tags to be used in the compilation. Build tags selectively specify what topics to include. Topics without build tags are automatically included. This section is optional, and needed only if you intend to use the build tag capability. A maximum of 30 build tags can be specified. |
[CONFIG] |
Specifies author-defined menus and buttons to be included in the Help file. It is also used to register custom dynamic link libraries (DLLs) and functions in these DLLs that are used as custom macros within the Help file. This section is required if any such customization is desired. |
[BITMAPS] |
Specifies bitmap files to be included in the compilation. This section is not required if the Help Project file lists a path for bitmap files in the [OPTIONS] section using the BMROOT or ROOT options. More on this later. |
[MAP] |
This section associates context strings with HelpContextID integers. This section is optional, but is highly important for Visual Basic programs, since it is these associations that provide the HelpContextID property values for context-sensitive Help system invocation. |
[ALIAS] |
Assigns one or more context strings to the same Help topic. This section is optional. |
[WINDOWS] |
Defines the characteristics of the primary Help window, and the types and characteristics of any secondary windows that may be used in the Help system. This section is required if secondary windows are used. |
[BAGGAGE] |
Lists files that are to be placed within the Help file (*.HLP). The Help file contains its own stand-alone file system that can be used during execution of the Help system. These additional files can be more efficiently accessed from within the Windows Help engine. This section is optional. |
The [OPTIONS] section includes settings that controls how the Help file is built by the compiler, and what types of information the compiler produces while it is executing. The options that can be specified in this section are listed in Table 18.5.
Table 18.5
Table 18.5 The [OPTIONS] Specifiers
Option |
Purpose and Description |
BMROOT |
Specifies the directory where the Help Compiler can find the bitmaps used in the Help topics. The format of this option line is: BMROOT = pathname1, pathname2, and so on. |
BUILD |
Determines which topics to include or exclude in the compilation. The
format of this option is a logical expression using the following operators
and operands: |
COMPRESS |
Specifies the type of compression used during compilation of the Help files. There are three levels of compression that can be specified: COMPRESS = NO No compression |
CONTENTS |
Specifies the context string for the Help Contents topic of the Help file. An example would be: CONTENTS = context_string |
COPYRIGHT |
Adds a copyright message to the Help About dialog box: a string of 35 to 75 characters. |
ERRORLOG |
Places compiler error messages into a file during the compilation process. These can be reviewed after compilation. A file name. |
FORCEFONT |
Forces fonts used in the RTF files to be remapped into some other font during compilation. A font name. |
ICON |
Specifies the icon to be displayed when the Help file and Help engine application are minimized. An icon file name (*.ICO). |
LANGUAGE |
Specifies a different sort ordering for Help file authored in a Scandinavian language. |
MAPFONTSIZE |
Maps a font size used in the RTF topic files into a different font size in the compiled Help files. An example might be: MAPFONTSIZE = 12-24:16 which would map all fonts in the size range of 12 to 24 points into 16 point font. The specification can include a single size or a range of sizes. |
MULTIKEY |
Specifies an alternate keyword table for mapping topics. The standard keyword footnote table character is "K". Other keyword footnotes using other letters can be used to create additional keyword tables. |
OLDKEYPHRASE |
Designates whether the Help compiler should use the existing key phrase table or create a new one during compilation. |
REPORT |
Control message display during compilation. To turn on message display; REPORT = ON. |
ROOT |
Designates the root directories used to locate topic and data files listed in the Help Project file. An example would be: ROOT = pathname1, pathname2, and so on. |
TITLE |
Specifies the text caption that appears in the Help engine's title bar. String of up to about 50 characters. |
WARNING |
Indicates the desired level of compiler error level reporting to be
used during compilation. Warning levels are: |
The [MAP] section also merits some additional attention, because it is used to map context strings to HelpContextID that are used to set the properties of Visual Basic objects to link them to context-sensitive Help invocation.
When you create the [MAP] section of the Help Project file, it is usually a good idea to create and maintain a context string to HelpContextID number catalog when you begin to author the Help topic (*.RTF) files. The assignment of HelpContextID integers is completely arbitrary and up to your discretion.
This section examines a typical Help Project file, and analyzes the purpose of the specifications in each section. For this analysis we will start with a Help Project file shipped with the Visual Basic product—the Help Project file for IconWorks.
The sample Visual Basic program IconWorks is a browser and editor for Windows Icons. It is a complete Visual Basic application, all the way through to including a Help system. The Help Project file that we are going to investigate is in the HC directory of the installed Visual Basic product.
We will investigate each section, and then correlate the effects of the specifications in each section with the behavior and appearance of the completed Help system for the IconWorks application.
The following listing is the Help Project file for the IconWorks sample Visual Basic program. Most of the lines in the [MAP] section have been eliminated in the interests of brevity, because a few sample lines indicate the concept involved.
The initial section of the Help Project file is the [OPTIONS] section. From this section you can see that an error log file has been specified, the title of the completed Help system is to be "IconWorks Help", the contents topics is to correspond to the context string CONTENTS, compression has been turned off, any old key phrase dictionary is not to be used, and the compiler warning level has been set to 3 (that is, show all errors and warnings).
Of course, it would have been possible to specify specialized directory roots for bitmaps and RTF files (using the BMROOT or ROOT parameters), but in this case all bitmap and RTF files are going to be located in the same root directory as the project file, so these optional specifications are not used.
Build tags are also not used, because all of the contents of the topics file are to be compiled in this version of the Help system. Likewise no copyright notice is specified, nor are any font mappings specified.
Notice the [FILES] section of the Help Project file. It contains only one RTF topic file. If additional topic files were needed they could be added as lines in this section.
The next section of the ICONWRKS.HPJ Help Project file is the [MAP] section. This section correlates context strings (on the left-hand side of each line) with the HelpContextID integer (on the right-hand side of each line). You should notice in particular that the choice of context strings has been done in such a way that the chosen string is evocative of the topic being referenced. This is good practice, and can make your work much easier; choose good context strings.
You can have as many lines as you need to completely specify the context string to HelpContextID relationships. It should also be noted that a given context string can be correlated to more than one HelpContextID. The effect is that a number of different HelpContextID integers will all invoke the same Help topic.
Other sections of our IconWorks sample Help Project file are used to specify other options to be incorporated into the Help resources file (ICONWRKS.HLP) that will be produced by the Help compiler.
The [WINDOWS] section characterizes two windows that can be used in the completed Help system. It specifies the "main" window, and a secondary window called "glossary". Remember that any Help topic can be displayed in any named window. If no named window is specified, the default (or main) window is used to display the topic.
The parameters specifying the "main" and "glossary" windows attributes consist of the following information:
In the case of the "main" window, the attributes specified are that the caption is to be "IconWorks Help," the window is to be positioned at 0,0 (upper-left corner of the screen), and is to be 1023 units wide and 1023 units high. The specification then skips over the sizing and clientRGB fields, and specifies the RGB colors for the non-scrolling area of the main window (192,192,192—or medium gray).
For the "glossary" window, the attributes specified are that the caption is also to be "IconWorks Help," that the window is to be positioned with its upper-left corner at 222 units right of the left-screen edges, and 206 units from the top of the screen. Additionally, this window is to be 725 units wide and 486 units high. The specification then skips over the sizing and clientRGB fields, and finally specifies the non-scrolling area of the window as medium gray (i.e., 192,192,192). The last field of the specification for this window sets the attributes of this window to topmost (for example, on top of other windows).
It should be noted here that the Windows Help engine uses an internal screen coordinate system that is 1024 x 1024 units in size. This 1coordinate system is proportionally mapped to the actual screen resolution of the display device being used.
If desired, additional named secondary windows can be specified for other specialized purposes, using the same type of specifications.
Next let's turn our attention to the [CONFIG] section of the Help Project file. The first line in this section (CreateButton, and so on) creates a custom button that is added to the standard buttons at the top of the Help system window. The form of this line, which is a Window Help engine macro, is as follows:
The buttonid field is used to specify the internal symbol name used by the Windows Help engine. You may later want to refer to this symbol to invoke the DisableButton, DestroyButton, or ChangeButtonBinding macros to manipulate this resource. In our example, this symbol name is glossary.
The name field is used to specify the caption used on the additional button. In this example, the caption is &Glossary with the usual convention that the character of any caption that is preceded with an "&" character becomes the access key (Alt+G in this case).
Finally, the macro field identifies the macro to be invoked when the added custom button is chosen by the user. In this example, the macro invoked is the JI macro (short for JumpId. The JumpId macro causes a jump to another Help file, and topic within that Help file identified by a context string. In our example, the form used causes a jump to the context string GLOSSARY, and the Help file is the ICONWRKS.HLP Help file. Note, however, the use of the ">" character and the reference to the glossary window. This JI macro then would display the topic referenced by the GLOSSARY context string, of the ICONWRKS.HLP Help file, and display the referenced topic in the secondary window named glossary.
The second line of the [CONFIG] section specifies that the macro BrowseButtons be invoked. This adds the two browse buttons (Browse Forward ">>" and Browse Back "<<") to the standard default set of command buttons at the top of the Help window.
Finally, the order in which these additional buttons are appended to the default Help window is the same as the order in which they are specified in the [CONFIG] section. Furthermore, it is possible to invoke other macros in the [CONFIG] section to accomplish such things as registering custom DLLs for use with the Help system, insert custom menu bar items, append menu items to menus, and so on.
Using the Microsoft Help compiler is pretty straightforward. The Help compiler is a DOS command-line compiler that accepts just the Help Project file as a command-line argument.
For any contemporary application Help system you will typically use the Windows 3.1 (Windows for Workgroups 3.11 and Windows NT 3.1 and 3.5 compatible) Help compiler. This compiler incorporates all of the latest Help system capabilities, and is called HCP.EXE or HC31.EXE. The most current version of the HCP compiler as of this writing is version 3.10.505.
Using our example of the IconWorks Help project from the previous section's example, you would invoke the compiler from a DOS prompt as follows:
This would create a file Windows Help resource file, ICONWRKS.HLP in the same directory path that you used for the Project file. It would also create an error log file in the file specified in the [OPTIONS] section of the project file.
Note: The HCP or HC31 Help compiler requires quite a bit or extended memory (XMS) to successfully execute. Alternatively, you can use expanded (EMS) memory using EMM386 from within DOS. Estimates of the memory required range from a low of about 1 MB to more than 2MB, depending on the complexity of your Help project. The easiest way to assure that this memory will be available is to execute the Help compiler from a Windows DOS session. This will provide the needed XMS memory automatically.
If you encounter errors during compilation of your Help project, you will need to review the error log, and interpret the error messages that you find so that you can take corrective action.
To interpret the error log messages you should refer to the Help Compiler Reference, which is contained in the Help file HELPREF.HLP. In this Help system is a comprehensive listing and interpretation of all of the Help compiler error messages.
Whenever possible, the Help compiler error log identifies the topic that caused the error by outputting the topic string, as well as a sequential topic number. The topic number given with an error message refers to the sequential position of that topic in the topic file (first topic, second topic, and so on). Topics within your Help topic RTF files are separated by hard page breaks, even though there is no such thing as a "page" within the Help system itself. By locating the sequential "page" in the appropriate RTF file you can find the topic referenced by the error message.
Error messages beginning with "Error" may indicate fatal errors. Fatal errors are always reported, since no usable Help file results from the compilation. Messages beginning with the word "Warning" are less serious in nature. A compilation with warnings produces a valid Help file that the WinHelp engine can open, but the file may contain operational errors that render it unusable. Remember you can specify the amount of warning information that you want to be reported by the Help Compiler using the WARNING parameter in the [OPTIONS] section of your Help Project file.
During processing of the .HPJ file, the Help Compiler ignores lines that contain errors and attempts to continue with the compilation. This can have the effect that errors found near the beginning of the compilation may result in a error cascade later as additional errors are reported during the remainder of the compilation process.
Similarly, errors encountered during the processing of the RTF topic files are reported, but if the errors are not serious, the Help Compiler continues with the build.
Once you have successfully corrected the errors and completed a Help resources file (*.HLP) in the Help compiler, you need to test it to make sure that it operates as you intended.
To test your Help file, start up WINHELP.EXE, and choose File, Open. A standard File Browser dialog box opens, and you can select your HLP file to load into the Help engine.
Once loaded, you can try out the topic jumps, pop-ups, hotspot graphics, and search mode keywords to make sure that what you intended when you designed your Help system works correctly. As an example refer to figure 18.8 showing the IconWorks Help system that we looked at in previous sections after it has been compiled and loaded into the Windows Help engine.
Fig. 18.8 The IconWorks Help system shows a main window Contents topic and a secondary window used for the Glossary.
You also need to set the HelpContextID property of all of your Visual Basic applications forms and controls to correspond to the topic you want to display when you press the F1 key in your application. Remember to also set the Help File name in the Visual Basic editor under Tools, Options, and the Project tab.
You should test the link between your Visual Basic application and the completed Help system by setting the focus to each and every control in your application and pressing the F1 key to make sure that the correct context-sensitive Help is displayed.
Make note of any operational errors that you notice, and go back and correct your Help Project file, topic RTF files, hotspot graphics, and HelpContextID maps to get the desired changes effected.
Although we looked at some of the added capabilities of the Windows Help engine briefly in an earlier section "Creating the Help Project File," we did not get a chance at that point to focus on the details of using these optional features of the Help engine.
The sections that follow are aimed at giving additional attention to such features as customized menus, extra buttons, the use of macros, and Help engine initialization techniques. Using these feature enables you to get a custom look and feel for your Help system, and to add extensions to its basic capabilities.
In addition to the default Help engine menus of File, Edit, Bookmark, and Help, you can create your own customized menus and menu items. You can also manipulate such menus and menu items in response to user interactions with your Help system.
Customizing your Help system's menus and menu items can be accomplished at the time the Windows Help engine is initialized, or at any time during user interaction with the elements of your Help system. Menu and menu-item customization is accomplished using the Help engine macros listed in Table 18.6.
Table 18.6
Table 18.6 The Help Engine Macros
Menu Macros |
Features and Arguments |
InsertMenu |
Adds a new menu to the Help engine menu bar. The arguments allow specification of the menuid, menuname, and menuposition. |
InsertItem |
Adds a new menu item to one of the standard menus or to a custom menu. The arguments allow specification of the menuid where the item is to be inserted, itemid, itemname, macro to execute when the menu item is selected, and position in list of menu items. |
AppendItem |
Appends a new menu item to the bottom of a menu created with the InsertMenu macro. The arguments allow specification of the menuid, itemid, itemname, and macro. |
DeleteItem |
Deletes a new menu item that was added with the AppendItem macro. The argument allows specification of the itemid. |
DisableItem |
Disables a menu item that was added with the AppendItem macro. The argument allows specification of the itemid. |
EnableItem |
Enables a menu item that was added with the AppendItem macro. The argument allows specification of the itemid. |
Any of these menu macros can be executed by placing them in the [CONFIG] section of the Help Project file. This causes the menus and menu items to be initialized when the Windows Help engine is initialized.
The menu items can also be executed from text or graphics hotspots during user interaction with your Help system. The techniques used depend on what you are trying to accomplish with the menu modifications.
You can also incorporate additional command buttons in the Windows Help engine to customize its look and feel. In a manner that is quite parallel to adding menus and menu items, you can invoke Windows Help macros to manipulate command buttons.
Command button customization is accomplished using the Help engine macros listed in Table 18.7.
Table 18.7
Table 18.7 Additional Help Engine Macros
Button Macros |
Features and Arguments |
BrowseButtons |
Adds the Browse Back (<<) and Browse Forward (>>) buttons to the standard Toolbar button set of the Windows Help engine. |
CreateButton |
Adds a new button to the Help engine Toolbar. The arguments allows specification of the buttonid, name, and macro. |
DestroyButton |
Deletes a new button that was added with the CreateButton macro. The argument allows specification of the buttonid. |
DisableButton |
Disables a button that was added with the CreateButton macro. The argument allows specification of the buttonid. |
EnableButton |
Enables a button that was added with the CreateButton macro. The argument allows specification of the buttonid. |
Any of these button macros can be executed by placing them in the [CONFIG] section of the Help Project file. This will cause the buttons to be initialized when the Windows Help engine is initialized. It should be noted here that if the BrowseButtons macro is used and also other button macros, the Browse Buttons themselves will appear in the order of the macros in the [CONFIG] section.
As with the menu macros, they can also be executed from text or graphics hotspots during user interaction with your Help system.
The capabilities of the built-in macros within the Windows Help engine can easily be extended to include your own custom functions. Your external DLL functions can be incorporated by using the RegisterRoutine macro described earlier in this section. The RegisterRoutine macro has the following calling arguments:
RegisterRoutine("DLLname", "functionname", "formatspec")
Of these the formatspec argument requires a bit of explanation. The formatspec argument uses single character abbreviations for standard C data types to identify the type of the return value and the calling arguments. These are as follows:
Character |
C Data Type |
u |
Unsigned short |
U |
Unsigned long |
i |
Short integer (short int) |
I |
Long integer (long int) |
s |
String (or near char *) pointer |
S |
String (or far char *) pointer |
v |
Void |
A typical formatspec might be something like the following:
This example formatspec indicates that the Registered Routine returns a S or String (far char *) pointer, and accepts two s or String (near char *) arguments and a single U or unsigned long argument.
We have looked closely at invoking and creating Help systems and we've discussed some of the tools that can be used to develop a Help system. You can use this material to improve your applications.
| Previous Chapter | Next Chapter | Search | Table of Contents | Book Home Page |
| Buy This Book | Que Home Page | Digital Bookshelf | Disclaimer |
To order books from QUE, call us at 800-716-0044 or 317-361-5400.
For comments or technical support for our books and software, select Talk to Us.
© 1996, QUE Corporation, an imprint of Macmillan Publishing USA, a Simon and Schuster Company.