Lesson 4: Context-Sensitive Help | Desktop Applications with Microsoft Visual C++ 6.0 MCSD Training Kit

Windows applications usually provide context-sensitive Help, allowing the user to get help on a particular feature of an application, such as a dialog box, a command, or a toolbar button.

Currently, Windows provides two distinct Help authoring environments: the traditional Windows Help system WinHelp, based on rich text format (RTF) documents; and the newer HTML Help system, based on compiled HTML documents.

In this chapter, you will learn how to provide context-sensitive Help for your applications using application framework features provided by the MFC AppWizard. You will also learn the basic steps required to implement HTML Help for an application.

After this lesson, you will be able to:

Describe how a Windows application implements context-sensitive Help.

Describe how to add context-sensitive Help to an MFC AppWizard application.

Describe the components of WinHelp development.

Describe how to display HTML-based Help for an application.

Estimated lesson time: 40 minutes

WinHelp

Applications that use the Windows Help system respond to user requests for Help by loading the WinHelp application (Winhlp32.exe) located in the system folder.

WinHelp displays pages from the application Help file. The application Help file resides in the same directory as the application executable file and has the same file name but with an .hlp extension. The page that is displayed is determined by the help context, a parameter passed to WinHelp by the application.

The user can access the application Help in the following ways:

Pressing the F1 key The user can press the F1 key from an active window, dialog box, or message box, or with a command or toolbar button selected, to invoke a Help topic relevant to the selected item. For commands, Help is summoned for the item currently selected.

Note that although you can define any key as a Help key, the F1 key is the accepted standard.

Entering Help mode From within an active application, the user can press SHIFT+F1 or click the Help button to activate "Help mode."

In Help mode, the mouse pointer changes to an arrow with a question mark. While the application is in this mode, the user can click any window, dialog box, message box, command, or toolbar button to summon Help specific to the item. Help mode ends when Help is displayed. Pressing ESC or switching away from the application and then back to the application ends Help mode.

Using the Help menu Most applications provide Help support through one or more commands. For instance, most Windows applications include a Help command that invokes the application's Help file when chosen. Additional commands on the Help menu might display a Search dialog box or provide a link to a Web site for more information.

AppWizard Support for Context-Sensitive Help

The MFC application framework provides extensive support for the implementation of WinHelp. Selecting the context-sensitive Help option when using the MFC AppWizard will set up your project with everything you need to create WinHelp for your application with minimal effort.

The following exercises show you how to use the AppWizard to create a project that provides support for context-sensitive Help, and they demonstrate how application Help pages are displayed.

To create the MyHelpApp project

Use the New command on the File menu to create a new MFC AppWizard (exe) project named MyHelpApp.

On the Step 1 screen of the MFC AppWizard, select Single document.

Select the default options for Steps 2 and 3. For Step 4, select the Context-sensitive Help check box as shown in Figure 5.9.

click to view at full size.

Figure 5.9 The AppWizard context-sensitive Help option

Select the default options for the remaining AppWizard steps and create the MyHelpApp project.

In the following exercises, you will view the default Help application that is created for your application.

To view MyHelpApp Help

Press F7 to build the MyHelpApp application.

Press CTRL+F5 to run the application.

On the Help menu, click Help Topics. The MyHelpApp application Help appears.

Click the Contents tab. Double-click Menus so that the Help screen appears as shown in Figure 5.10.

click to view at full size.

Figure 5.10 The MyHelpApp application Help window

Select the File menu Help topic. The Close button changes to the Display button.

Click Display to view the Help topic about the File menu. The File menu Help page appears as shown in Figure 5.11.

click to view at full size.

Figure 5.11 The File menu Help page

Take some time to explore the Help system. Try selecting some of the hyperlinks and experiment with some of the toolbar and menu options. When you have finished, close the Help application.

To invoke context-sensitive Help

Click File in the MyHelpApp application to open the File menu. Highlight the Print command with the mouse, but do not select it.

Press the F1 key. The Help application will open and display the Print command topic.

Close the Help application. Click in the application window client area to close the File menu. Position the pointer over the Context Help button so that the button appears raised and the ToolTip text is displayed. The Context Help button, which is on the far right of the toolbar, depicts a black cursor arrow next to a blue question mark.

Press the F1 key. The Help application will open and display the Context Help command topic.

Close the Help application.

To view Help-mode Help

Click the Context Help button. Notice how the pointer changes to inform you that you are in Help mode.

Click any command or toolbar button to view its Help information.

Close the Help application.

Help Development Components

When you choose the context-sensitive Help option for your application, AppWizard creates an extra subfolder named hlp beneath your main project folder. This subfolder contains files that are used in the development of your application's Help file. Figure 5.12 shows Windows Explorer displaying the contents of the hlp folder for the MyHelpApp project (after the project has been built).

click to view at full size.

Figure 5.12 The MyHelpApp\hlp folder

The following sections explain how these files are used in the Help file development process.

.hpj Files

A .hpj file is a Help project file that provides the information the Windows Help compiler needs to build a Help file for your application. Help project files are maintained by the Microsoft Help Workshop, which is an application that allows you to visually develop application Help—.hpj files are to Help Workshop what .dsw files are to Visual Studio. Like Visual Studio, Help Workshop is capable of hosting several different types of files.

The Microsoft Help Workshop (hcw.exe) is installed in the \Program Files\ Microsoft Visual Studio\Common\Tools folder as part of a standard installation of Visual Studio. You can launch Help Workshop by double-clicking a Help project file. Figure 5.13 shows the MyHelpApp.hpj file open in Help Workshop.

click to view at full size.

Figure 5.13 Help Workshop displaying MyHelpApp.hpj

The .hpj file contains several sections that can be modified by using the buttons on the right side of the pane. Options used by the Help compiler are specified in the Options section displayed in Figure 5.13. Other sections contain references to other types of files that can be included in the Help project build.

.rtf Files

An .rtf file is a rich text format file that forms the pages in the Help file. The .rtf files that are to be included in a Help file are listed in the [FILES] section of the project's .hpj file.

AppWizard supplies skeleton .rtf files that contain Help topics for common elements of the Windows user interface, such as the File and Edit menus. You can edit these files to revise the supplied text and add your own application-specific Help information. To edit .rtf files, you will need to install a word processor, such as Microsoft Word, that is capable of editing the rich text format.

.bmp Files

The .rtf files can contain references to .bmp files to be used as illustrations.

.hm Files

An .hm file is created by the MakeHm tool. MakeHm reads your Resource.h file and creates Help context IDs to correspond to the application resource IDs so that each dialog box, command, or other resource has a Help context ID associated with it. Be aware that MakeHm is not guaranteed to generate unique IDs and that this can sometimes result in name collisions.

Your project's .hpj file contains a statement in its [MAP] section that includes the project's .hm file, as well as the standard .hm file included with MFC. The Help compiler uses the Help context IDs in these .hm files to determine which Help topic is associated with each dialog box, command, or other resource.

When adding new resource IDs, you should be careful to use the standard prefixes for resource IDs so that MakeHm can create the mappings correctly. The names suggested for your resources by the Visual C++ resource editor use the correct prefixes. For more information, search for "Preferred Resource ID Prefixes" in the Visual C++ Help file.

Whenever you add new resources to your project, you must add new Help topics for those resources to your .rtf files. AppWizard creates custom build rules for your project to so that your Help file is rebuilt when its source files are changed. This includes a call to MakeHm.exe when the Resource.h file is changed.

.cnt Files

A .cnt file contains the information needed to create the Help file's Contents screen. You use Help Workshop to visually edit a .cnt file, as shown in Figure 5.14.

click to view at full size.

Figure 5.14 Help Workshop displaying MyHelpApp.cnt

.ph Files

A .ph file is a key-phrase table file created by the Help compiler when the compression option is specified.

.hlp Files

As mentioned earlier, .hlp files are the application Help files, the output of the Windows Help compiler. The Help compiler creates the .hlp file in your application's main source code folder. If an output folder (i.e. a Debug or Release folder) exists, the .hlp file is copied there so that an up-to-date copy of the application Help is always available when you run the application.

.log Files

A .log file contains messages generated by the Help compiler. They can be viewed with Help Workshop.

Source Code Components

In addition to creating the files required to build a Help file for your application, AppWizard adds features to your application source code to implement context-sensitive Help. The Help Topics option (resource ID_HELP_FINDER) is added to the Help menu, and the Context Help button (help-mode help, which has the resource ID_CONTEXT_HELP) is added to the application toolbar. The ap-plication's accelerator table defines F1 as the context-sensitive help key (resource ID_HELP), and SHIFT+F1 as the help-mode help key.

These resource IDs are mapped to base class handler functions in the main frame window's message map, as illustrated by the following code:

BEGIN_MESSAGE_MAP(CMainFrame, CFrameWnd)      //{{AFX_MSG_MAP(CMainFrame)      ON_WM_CREATE()      //}}AFX_MSG_MAP      // Global Help commands      ON_COMMAND(ID_HELP_FINDER, CFrameWnd::OnHelpFinder)      ON_COMMAND(ID_HELP, CFrameWnd::OnHelp)      ON_COMMAND(ID_CONTEXT_HELP, CFrameWnd::OnContextHelp)      ON_COMMAND(ID_DEFAULT_HELP, CFrameWnd::OnHelpFinder) END_MESSAGE_MAP()

The handler functions all eventually call the CWnd::WinHelp() function, which starts the WinHelp application. OnContextHelp() generates a Help context ID from the resource ID, which it passes to WinHelp as a parameter to the WinHelp() function. If the framework fails to generate a valid Help context ID, an ID_DEFAULT_HELP command message is sent to the application.

Creating Help Topics

In the following exercises, you will add a new menu to the MyHelpApp application menu and add Help topics for the menu and its item. You will learn how to add Help context information so that the context-sensitive Help features function correctly.

To complete these exercises, you will need to install a word processor that is capable of editing rich text format files. In our examples, we have used Microsoft Word.

To add the ID_IMPORT_TEXTFILE command

From the ResourceView of the MyHelpApp project, open the IDR_MAINFRAME menu in the menu editor. Add a new menu title with the caption &Import. Under this title, create a command with the caption &Text File. Close and re-open the Menu Item Properties to ensure that the editor has created the ID ID_IMPORT_TEXTFILE for the command.

Build the MyHelpApp application. Note that the following messages appear in the output window:

Making Help include file... Making Help file...

Locate the MyHelpApp.hm file in the hlp subfolder. Use Notepad to view this file, and confirm that the MakeHm utility has added the Help context ID HID_IMPORT_TEXTFILE. Close the MyHelpApp.hm file.

In the next exercise, you will add topics to the application's .rtf file. To help you understand the file format, open AfxCore.rtf in your rich text editor. If the editor contains an option that allows you view hidden text, make that option available. In Word, this is achieved by choosing Options from the Tools menu and selecting the Hidden text check box on the View tab. Also, make footnote editing available—in Word, choose Footnotes from the View menu.

Figure 5.15 shows how AfxCore.rtf looks in Word's Normal view.

click to view at full size.

Figure 5.15 Microsoft Word displaying AfxCore.rtf

Each Help topic in the .rtf file begins with a hard page break. Each topic might contain hypertext links to other Help topics. Links are formatted as double-underlined text and are followed immediately by the link destinations formatted as hidden text. The link destinations are signified by a pound (#) footnote mark. The footnote text contains the context name, which can either be a name internal to the Help file or one of the context IDs specified in the Help project's .hm file. Help uses embedded context IDs to locate the correct Help topic for context-sensitive Help.

The other special footnote marks identify keywords for searching (K) and for topic names ($).

The text in double angle-brackets (for example, <<YourApp>> in Figure 5.15) is generic placeholder text generated by the AppWizard, which you replace with text specific to your application.

In the following exercise, you will create a Help topic for the Import menu that you added to the MyHelpApp application.

To create the Import menu Help topic

In the AfxCore.rtf file, replace all instances of <<YourApp>> with MyHelpApp.

In the Help Index topic (the first in the file), change the hypertext link item Record menu to Import menu. (The Record menu is not implemented by MyHelpApp, so there is no Help topic for it.)

Change the associated link destination text (the hidden text immediately after the link text) to menu_import.

At an appropriate location, add a new topic titled Import Menu Commands. Ensure that the topic is on its own page. The title should be marked with a # footnote that points to the text menu_import. The topic page should contain a hypertext link named Text File, followed by a reference to the jump location HID_IMPORT_TEXTFILE. The hyperlink should be followed by a brief explanation formatted as plain text, as shown in Figure 5.16.

click to view at full size.

Figure 5.16 The Import menu Help topic

At an appropriate location, add another topic titled Text Files command (Import menu). The title should be marked with a # footnote that points to the text HID_IMPORT_TEXTFILE. Add a K footnote that points to the text Text Files, and a $ footnote that points to the text Importing Text Files. Add a brief explanation of the topic. Use Figure 5.17 as a guide.

click to view at full size.

Figure 5.17 The Importing Text Files Help topic

Save and close the AfxCore.rtf file.

NOTE
In a real-world development situation, you would probably want to rename the AfxCore.rtf and AfxPrint.rtf files once they become specific to your application. You'd then need to alter the file references in the Visual Studio and the Microsoft Help Workshop projects. We have omitted this step from the exercises for the sake of brevity.

Rebuild and run the MyHelpApp application. Press F1 to view your modified MyHelpApp index page. Search for "Import menu", and then "Text files" to locate the Importing Text Files topic. Close the MyHelpApp application Help file.

Check that the context-sensitive Help feature works properly for the Text Files option on the Import menu.

Open the Help Topics dialog box and search for the "Text files" topic on the Index tab, and perform a keyword search for the topic on the Find tab.

NOTE
You are able to do this because of the K and $ footnotes you added to the AfxCore.rtf file.

HTML Help

HTML Help, Microsoft's next-generation Help development platform, uses the underlying components of Microsoft Internet Explorer to display Help content. You can use HTML, ActiveX, Java, scripting (JavaScript and Microsoft Visual Basic Scripting Edition), and HTML image formats (.jpeg, .gif) to give your application Help system the power and appearance of a fully featured Web site. Your Help system can provide your customers with links to external resources such as your company's technical support Web site.

The viewer used by HTML Help contains a toolbar and a contents/index control to help the user navigate through the Help pages. You should be very familiar with the HTML Help interface by now, as it is used by the Visual C++ 6.0 Help system.

At some point, Microsoft will likely provide the same kind of support in the MFC application framework for HTML Help as it has already provided for WinHelp. In the meantime, if you require an HTML Help system for your application, you will need to implement it manually. However, your task is made easier because the HTML Help Workshop, the development environment used to develop HTML Help files, bears a strong resemblance to WinHelp's Help Workshop. Best of all, the HTML Help Workshop allows you to convert a WinHelp project (a .hpj file) into an HTML Help project (a .hhp file). The WinHelp project's rich text files are converted to HTML files, .bmp files are converted to .gif files, and the WinHelp contents files (.cnt files) are converted to the HTML Help equivalent .hhc files. The output of the HTML Help compiler is a .chm file—a compressed HTML file format.

It is not our intention for this book to cover HTML Help development in depth. However, we have provided a couple of exercises to get you started. The first exercise shows you how to use the HTML Help Workshop to convert the WinHelp project that you created for MyHelpApp into an HTML Help project named MyHHelp.hhp. You will then build the MyHHelp Help file and add code to the MyApp application to display it.

Before you can complete these exercises, you will need to install HTML Help on your computer.

To install HTML Help

Run Htmlhelp.exe, which is located in the \HtmlHelp subfolder on Disc 1 of your Visual C++ or Visual Studio CDs.

Follow the setup instructions to install HTML Help to this default location: c:\Program Files\HTML Help Workshop.

To convert the MyHelpApp WinHelp project

Close any Visual Studio projects that you have open. Using Windows Explorer, create a subfolder named hlp inside your MyApp development folder.

On the Start menu, point to Programs, point to HTML Help Workshop, and click HTML Help Workshop.

On the File menu of HTML Help Workshop, click New.

Specify that you want to create a new project by clicking OK.

On the first screen of the New Project Wizard, select the Convert WinHelp Project check box and click Next.

On the second screen of the New Project Wizard, type the full path to the MyHelpApp.hpj WinHelp project file into the first edit box (for example, c:\Program Files\Microsoft Visual Studio\MyProjects\MyHelpApp\hlp\ MyHelpApp.hpj).

In the second edit box, type the full path of the new hlp folder that you created in Step 1. Use MyHHelp as the name of the HTML Help project file that you want to create (for example, c:\Program Files\Microsoft Visual Studio\MyProjects\MyApp\hlp\MyHHelp).

Click Next to continue and then click Finish. The MyHHelp.hhp file is created and opened in HTML Help Workshop, as shown in Figure 5.18.

click to view at full size.

Figure 5.18 HTML Help Workshop

Click the Save all project files and compile button to create the Help file. This is the bottom button on the vertical toolbar to the left of the project information window.

When the Help compiler has finished, close the HTML Help Workshop. Using Windows Explorer, locate the MyHHelp.chm file from the ..\MyApp\hlp folder. Double click the MyHHelp.chm file to run it inside the HTML Help application. You will see how the WinHelp file that you created for MyHelpApp has been nicely converted into the HTML Help format, as shown in Figure 5.19.

click to view at full size.

Figure 5.19 The MyHHelp.chm file

In the next exercise, you will learn how to use the HTML Help API to call the MyHHelp.chm Help file from within the MyApp application. To be able to do this, you will need to link the HTML Help library to your application.

To invoke HTML Help from the MyApp application

In Visual C++, open the MyApp project. On the Project menu, click Settings.

Click the Link tab. In the Category box, click Input.

In the Object/library modules box, type htmlhelp.lib.

In the Additional library path box, type the path to the directory where the htmlhelp.lib file is installed (for example, c:\Program Files\HTML Help Workshop\lib).

Click the C/C++ tab. In the Category box, click Preprocessor.

In the Additional include directories box, type the path to the directory where the htmlhelp.h file is installed (for example, c:\Program Files\HTML Help Workshop\include).

Click OK to save the settings.

In FileView, locate and open the StdAfx.h file. Add the following line of code after the other #include statements:

#include <htmlhelp.h>

Open the IDR_MAINFRAME menu in the menu editor. Add a new item with the caption &Help Topics to the Help menu. Close and re-open the Menu Item Properties dialog box to ensure that the command has been created with the ID ID_HELP_HELPTOPICS.

Use ClassWizard to create an OnHelpHelptopics() handler function for the ID_HELP_HELPTOPICS command message in the CMainFrame class.

Add the following line of code to the function implementation:

::HtmlHelp(NULL,       C:\\Program Files\\Microsoft Visual                 Studio\\MyProjects\\MyApp\\hlp\\MyHHelp.chm",      HH_DISPLAY_TOPIC, 0);

Your code will differ slightly if the path to the .chm file is not the same. Notice that backslash characters embedded in strings need to be represented by the escape character sequence \\. If you break the string across a line, make sure that you add a \ continuation character.

The HtmlHelp() function is the core of the HTML API. You can use it to display .chm files, HTML files, URL destinations, or plain text inside a pop-up window. There are many parameters to the HtmlHelp() function that specify the features of the display window and what should be displayed, For more information, see "HTML Help API reference" in the Visual C++ Help files.

Build the MyApp application. Don't worry if you get a linker warning message about library conflicts—this is a side effect of linking to the htmlhelp.lib library and will not affect your application. Run the application and choose Help Topics from the Help menu. The HTML Help application should appear, displaying the MyHHelp.chm Help file.

Lesson Summary

Applications written in Windows usually provide context-sensitive Help, which you can use to get help on features of the application user interface.

Windows applications are now moving from the WinHelp traditional Windows Help system, which is based on RTF documents, to the newer HTML Help, which is based on compiled HTML documents. Although Visual C++ ships with a development environment for producing HTML Help files, the automatic features of the MFC AppWizard, which provide Help systems for your programs, still employ the WinHelp system.

By convention, users access context-sensitive Help by pressing the F1 key. If a feature of the user interface, such as a command, toolbar button, or dialog box control, is currently selected when F1 is pressed, the application should display context-sensitive Help for the selected feature. An application should also implement Help mode Help. An application is put into Help mode when the user presses SHIFT+F1 or selects Help from the toolbar. When in Help mode, the user can gain information about a user interface element simply by clicking it with the mouse.

The MFC application framework provides extensive support for the implementation of WinHelp. Selecting Context-sensitive Help in Step 4 of the MFC AppWizard will set up your project with everything you need to create WinHelp for your application with a minimum of effort. The AppWizard creates a folder named hlp beneath your project folder and generates a Help project file and source files for your application Help file. These source files include .rtf files that contain Help topics for the common elements of the Windows user interface, such as the File and Edit menus. You can edit these files to revise the supplied text and add your own application-specific Help information.

Help project files are managed by the Microsoft Help Workshop, which is installed in the \Program Files\Microsoft Visual Studio\Common\Tools folder as part of a standard installation of Visual Studio. AppWizard creates custom build rules for your project to so that your Help file is rebuilt when its source files are changed.

User interface features are linked to topics in the application's Help file by Help context IDs. These are created from the application resource IDs by the MakeHm tool and stored in files with the .hm extension as part of the Help project.

An application's Help file is distributed with an .hlp extension. Help is invoked from within an application source code with a call to the CWnd::WinHelp() function. The application framework generates an appropriate Help context ID that it passes to the Help system as a parameter to the WinHelp() function.

HTML Help is Microsoft's next-generation Help development platform, which uses the underlying components of Microsoft Internet Explorer to display Help content. You can use the power of HTML, ActiveX, Java, scripting, and HTML image formats to implement your application's Help system, which can include links to intranet and Internet-based resources.

Currently, the AppWizard cannot automatically generate an HTML Help system for your application. You can manually create a system using the HTML Help development environment that ships with Visual C++ 6.0. This includes the HTML Help Workshop, which bears a strong resemblance to the Microsoft Help Workshop, and which allows you to convert a WinHelp project into an HTML Help project. The WinHelp project's rich text files are converted to HTML files. An application's HTML Help is contained in a .chm file—a compressed HTML file format. HTML Help is invoked from within the application source code with a call to the HTML Help API function HTMLHelp().