Visual CSharp .NET Developer's Handbook (2002) [eng]

Topic Each file contains one help file topic. For example, you might have a file on data entry methods. Users who want to find information about a specific topic will get fast access since all of the information arrives in one download. Unfortunately, remote users who require information about menu-related items will end up waiting for each item to download. In addition, the information is difficult to update, since you'll need to look through several files for one menu change.

Large Menu/Dialog Control All dialog controls or menu tree entries appear in one file. Anchors help the user move from topic to topic. Users rely on a table of contents to go directly to a topic, making it easy for first-time users to explore the application. In addition, the layout makes the help file read more like the manual it's designed to replace. The use of a table of contents makes information easy to find. The negative aspect is that the large file size will cause some users to think twice before downloading the file.

Small Menu/Dialog Control Each menu item or dialog box control appears in a separate file. Users will benefit from the short download times, which will enable users to use help even when connected through a dial-up line. Users will find information fast since they see only one screen. Updates are faster and more reliable since the information only appears in one file. The drawback is that first-time users will find the constant download of information for each menu item or dialog control frustrating, especially when a dial-up connection is used. A table of contents won't be an automatic feature and will require separate maintenance time.

Large Task Each file contains a complete description and procedure for performing a specific task. For example, a file might show how to create a new document. New users will find that they can learn to perform tasks more easily. You can test each task separately, reducing the possibility of mistakes. Large task files allow the writer to include specific screen shots and enhanced graphics. This is the only layout that works for tutorials. This technique is generally unacceptable for advanced users who won't want to wade through entire procedures to find one piece of information. In addition, the help files are harder to update and will require more space on the server. Remote downloads will take a long time.

Small Task A hierarchical table of contents and a list of tasks organizes the information. Each task is broken into a series of common subtasks. A task overview page covers any special events. The table of contents makes information easy to find. The hierarchical format allows users to drill down to the information they need. Short download time encourages everyone to use help rather than call the help desk for information. Updates consist of changing the information in a single subtask folder. On the down side, there's a possibility of introducing subtle errors into the task procedures. For example, a menu entry may change in one part of the application but not in another.

Connection Type

It's interesting to note that some vendors who use HTML-based help assume that everyone has a T1 connection to the Internet. The truth is that many users rely on a dial-up connection to download their files. Help files are an essential application, unlike many sites that users surf on the Internet. This means you need to keep HTML help fast or the support desk will hear about it. The following list will help you optimize your help file for dial-up connections.

•Use graphics, sounds, and multimedia sparingly. Keep file sizes small by reducing resolution, color depth, or other features.

•Allow users to choose a text-only presentation.

•Reduce content whenever possible, but allow the user to click links that provide additional information.

•Use the right HTML file layout.

Search Capability

Searching a help file for valuable information is what most users do once they get past the novice level. They'll look for some tidbit of knowledge that they need to accomplish a task or an explanation for some control on a dialog box. You can't completely duplicate the search features of Windows Help using HTML help. However, there are ways you can mimic the search capability of Windows help. The following list provides a few ideas you can use.

•Create an index.

•Define additional links.

•Add a table of contents.

•Produce a hot topics list.

•Add a Search page that relies on the search capabilities of your server.

It's unlikely that you'll create a word-for-word index like the one provided with Windows Help. This means the user will always have some question that you didn't anticipate and the search features of your HTML-based help file won't be able to answer. It always pays to provide a comment page so users can request additional links.

Standard Windows Help

If you choose the standard Windows help file, the Microsoft Help Workshop will aid you in creating help project files and compiling them from within Windows. Standard Windows help files rely on Rich Text Format (RTF) files formatted with special footnotes. For example, the $ footnote represents a topic title, # is a topic identifier (like an anchor on a web page), K is a keyword used for searching, and @ is used for comments. Formatting includes using the outlining suggestions found in the "Multiple or Single-Page Files?" section earlier in the chapter.

We'll use the RTF files found in the \Chapter 10\Help folder on the CD in this section. Use these files as examples of the types of formatting you can use in a help file.

Tip RTF files have a standardized format. You can find a complete breakdown of all the tags in an RTF file by looking at the Rich Text Format (RTF) Specification, version 1.6 help topic (ms-help://MS.VSCC/MS.MSDNVS/Dnrtfspec/html/rtfspec_16.htm). Windows Help doesn't support the full RTF specification. The Rich Text Format Subset Supported by Windows (mshelp://MS.VSCC/MS.MSDNVS/kbwin32/Source/win16sdk/q75010.htm) provides additional information on which RTF features you can use.

Once you create the RTF help files, the first step in creating the new help file is to create a new project. Use the File → New command to display the New dialog. Select Help Project and click on OK to complete the action. The project starts out as a blank page that you fill in with the characteristics of your help file.

Adding Special Effects to a Help File

You can add many enhancements to a help file. For example, you can grab a screen shot of your application and then define hotspots on it with the Hotspot Editor utility (SHED.EXE). You can use BMP, DIB, WMF, and SHG graphics formats with the Hotspot Editor. Files containing hotspots always use the .SHG extension. (Note that you might not find SHED.EXE installed with Visual Studio .NET, but this utility always comes with the Platform SDK.)

Figure 10.1 shows a typical view of the Hotspot Editor. I've opened a screen shot of the Resource example program (from Chapter 5) that we'll use as a topic for the help file. In this case, we're looking at a picture of the main form. I'll add hotspots for each control to make it easy for the user to learn about the application. You can't use the Hotspot Editor to create a new drawing—you'll need a graphics application to do that. The purpose of using the Hotspot Editor is to add places where the user can point and expect something to happen. Every time you see the cursor change from a pointer to a pointing hand in a help file, you're seeing the effect of using the Hotspot Editor.

Figure 10.1: The Hotspot Editor won't allow you to create a new drawing, but it does add hotspots to existing ones.

Creating a new hotspot is as easy as dragging the mouse. All you need to do is create a box, and the area within that box becomes the hotspot. Once you create a hotspot, you need to define it. Just double-click on the hotspot and you'll see the Attributes dialog shown in Figure 10.2. Notice that the Hotspot Editor automatically fills some entries in for you, but you can change them as needed.

Figure 10.2: Use the Attributes dialog box to define special characteristics for a hotspot.

There are three mandatory entries in this dialog: Context String, Type, and Attribute. A context string acts as the second half of a hyperlink. When the user clicks on the hotspot, Windows Help will set the focus to the place in the help file that you've defined. You can choose to make the box surrounding the hotspot visible or invisible. There are three types of hotspots as described in the following list.

Jump A jump moves the user from one area of the help file to another. Windows Help replaces the contents of the current window with the help topic pointed at by the context string. This hotspot type works well for icons that tell users about other information they can find on a given topic. You could use it to create a "See Also" icon. I also use this type of jump when creating links between a multi-page hierarchical chart. Hotspots allow the user to jump from one place to another without using the Browse buttons. I also use this jump to control pictures used to simulate the display the user will find in an application.

Pop-up A pop-up displays the help topic associated with the hotspot in a dialog/message box window. You'll find that this kind of a jump is used most often with control descriptions or other pictorial-type hotspots. Since the user doesn't leave the picture, they can easily select other controls. I also use this hotspot in tutorial-type help files in the question-and-answer section. An Answer button displays a pop-up window containing the answer to a question, which remains visible for reference in the original window.

Macro The macro hotspot allows you to play back a predefined macro. You'll find that macros are a powerful (and underused) feature of Windows Help. You can even use macros to call programs or reprogram the way that Windows Help works.

Tip The Microsoft Help Compiler provides many predefined macros. For example, you can use the SetPopupColor macro to change the color of a pop-up window. Attaching macros to a button or menu will give users control over the help window and enhance their ability to use it. One way to combine a macro with a bitmap is to create a bitmap of colored squares. When a user clicks on a colored square, the color of the help windows changes.

The Attribute dialog contains a few optional entries. One is the Hotspot ID field. It tells the Hotspot Editor how to identify this particular hotspot. The other four entries define the bounding box for the hotspot. You can use these entries to fine-tune a box's position or size. However, the user won't notice if the hotspot is a pixel or two off, as long as the hotspot is available for use.

You may need to redefine a hotspot. Hotspots are easy to find if you make them visible, but most people don't. So how do you find a hidden hotspot on a complex drawing? The Edit → Select command provides the answer. It displays the Select dialog.

The Select dialog lists the hotspots in the current drawing by hotspot identifier, not by context string. Selecting a particular hotspot will display its context string so that you can be sure you have the right one without going to that location on the drawing. The Select dialog also displays the jump type and attribute information.

After you define the hotspots, you may be tempted to save your graphic using the File → Save command; however, you should always save it with an .SHG extension using File → Save As command. The Hotspot Editor doesn't insist you do this, but if you don't, you'll find that you've overwritten your drawing with information that some drawing programs can't read. Since you can't modify your drawing within the Hotspot Editor, you're stuck with an image that you can't change.

Once you have a drawing (or other multimedia element), you can add it to your help file using Microsoft-defined commands that enable you to add graphics or other elements to your help file. The same commands provide control over the placement of these graphics, but I find the positioning mechanism is crude at best. Table 10.1 shows a complete list of the commands you'll use to add multimedia elements to your help file. Note that you can add a T (for transparent) to the three graphics commands listed in Table 10.1. Adding a T changes the background color of the image to match that of the help window.

Table 10.1: Multimedia Element Help Commands

Defining a Project's Options

By the time you begin a help project, you should have all of the data files created and the graphics files edited using the Hotspot Editor. You'll start a project by defining some of the project options. For example, you should give your help file a name and add copyright information. I always use "Contents" as my main topic, so adding that entry at the beginning is a good idea as well. Click Options and you'll see the Options dialog shown in Figure 10.3.

Figure 10.3: The Options dialog enables you to define the help file project options.

The General tab contains the default topic for the help file. This is an essential entry because the help file might not work properly otherwise. You can also give the help file a title, add copyright and trademark information, and determine what level of output you want to receive from the compiler. In most cases, you'll want to check both Notes and Progress to ensure that you receive complete information about the help file compilation process.

The Compression tab contains options for compressing the content of the help file into a manageable size. In most cases, you'll want to set the compression level to None as you build the help file for testing. Leaving compression off reduces compile time. Once you're satisfied with your help file, you'll want to set compression on. Using the Maximum option ensures that the help file is as small as possible. However, you might want to choose one of the lesser compression options to ensure good help file performance.

The Sorting tab of the Options dialog contains several options that determine how to sort entries. The Non-spacing marks option allows you to ignore non-spacing characters. For example, the circumflex (^) that appears in ê would affect the sort order if you didn't select this option. Another option tells the help compiler to ignore any symbols in the help file when sorting. This is handy if you want to create a non-specialized index for a data entry program or other general application. On the other hand, it would actually get in the way when creating an index for a reference help file. Many C functions begin with an underscore. Ignoring those underscores would make the function difficult to find. Finally, you can choose something other than commas and colons to separate index entries. The only time you'd need this feature is if you wanted to create a help file based on the output of another application that doesn't support the standard separators.

The Files tab of the Options dialog, shown in Figure 10.4, determines which files you use for a given task. You can change the name of the help file by changing the contents of the Help File field. The help compiler uses the name of the project file as a basis for naming the help file. The Log File field contains the name of a log file. This option isn't required with the help compiler since it also displays errors on screen.

Figure 10.4: Use the Files tab to list the files used in your project.

One of the most important fields on the Files tab is the Rich Text Format (RTF) Files list box. You'll find a list of the files for the current help project here. Clicking the Change button next to the field displays the Topic Files dialog. This is where you add and remove topic files from the list in the FILES section of the project file. The two check boxes at the bottom of this dialog control how the help compiler reacts to your RTF files. The first option tells the help compiler to automatically implement any changes you make to the RTF files during the next compile. If you leave this box unchecked, the help compiler will ignore any changes. The second option is important if you use a double-byte character set (DBCS) within your help file. This option changes the way the help compiler works with your file and allows it to preserve the special characters.

Windows Help offers full text search (FTS)—a database created when you select the Find page of the Help Topics dialog. FTS allows you to search an entire help file word-by-word. The FTS tab of the Options dialog contains an option to generate this file at the time you compile the help file. Since Windows automatically generates the GID file, most developers leave this option blank. The GID file that the help compiler creates takes up a lot of room on the distribution disks and increases compile time considerably.

You'll want to spend some time learning to use the Macros tab. It helps you to define keyword macros to use on a file-wide basis. These macros also appear on the Index page of the Help Topics dialog when the user searches for a particular topic.

Clicking Add displays a Keyword Macros dialog containing three fields. The first field contains the name of the macro. The second field contains the macro itself. The third field contains a string that tells Help Workshop how to display the macro on the Index page. Use this entry when you have more than one help file and want to display a particular keyword file-wide. For example, I often place the glossary and list of acronyms in a separate file and then use the JI macro to create a file-wide jump to them. The keyword macro is the method I use to do this. The user never even realizes that he or she has loaded another file—it's that transparent.

The Build Tags tab of the Options dialog helps you use build (*) tags found within the RTF files. The main idea is to provide Help Workshop with a list of build tags that you want to include in a help file. Even if an RTF file contains other topics, it won't include them in the help file if you don't include the build tag. If you leave this page blank, Help Workshop assumes you want to include all RTF file topics as part of the final help file.

The Fonts tab of the Options dialog customizes the fonts used for the help file. The Character Set field selects a character set for your help file; the default is ANSI. You can also choose from language types such as Arabic. The Font in WinHelp Dialog Boxes field defines a default font type. Click Change and you'll see a Font dialog containing three fields. The first defines the font name, the second the font point size. The third field defines the character set. The list box below the Font in WinHelp Dialog Boxes field changes the general fonts used within the Windows help file—substituting one font for another. The Add button displays an Add/Edit Font Mapping dialog that contains two groups of three fields. The three fields are the same as the ones used in the Font dialog. The settings on this tab won't work if your word processor overrides the settings—something that generally happens if you use a product like Word for Windows.

Defining Windows

Defining options is only the first phase of creating a project file—you need to define some windows to display your data. The example uses one window called Main. Ancillary windows may include a Glossary window to display terms. To create a window, click Windows in the Main window to display the Window Properties dialog shown in Figure 10.5.

Figure 10.5: The Window Properties dialog enables you to define new windows for your project.

The General window is where you'll start. Click Add and you'll see an Add a New Window dialog with two fields. One field contains the name of the window; the other field contains the window type. Help Workshop creates three window types: procedural, reference, and error message. There's little difference between the procedural and reference windows. Both autosize and contain the three system buttons. The big difference between the two is their placement on screen. The error message window differs from the other two in that it doesn't include the three system buttons. It looks somewhat like a dialog.

The Title Bar Text field on the General tab determines what Windows Help places on the title bar. This entry doesn't affect the appearance of the topic title area of the Help window. The Comment field places a comment next to the entry in the project file. There are also three attribute check boxes. Help Workshop may disable one or more of these checkboxes, depending on the situation. For example, you can't make the main help window auto-sizing. If you make an ancillary window auto-sizing, you can't maximize it when it opens. Most procedural windows default to staying on top.

You'll usually want to spend some time working with the Position tab of the Window Properties dialog. There are four fields on the Position tab: Left, Top, Width, and Height. These control the size and position of your window. I normally position my first help window in the upper-left corner and use a size of either 640 X 480 or 800 X 600, depending on the capabilities of the target machine for my application. This may seem a bit small, but the user can always resize the window as needed. Trying to find a help window on an older display when the programmer positions it near one of the edges is frustrating, to say the least. I really like the Adjust for User's Screen Resolution option on this page, because it prevents the help window from becoming totally hidden when the user has a low-resolution display.

There's one special feature on the Position tab that you may not notice at first. Look at the Auto-Sizer button. Clicking on this button displays an example window. If you change the window's position, the Left and Top field values also change. Resizing the window changes