Recipe 14.28. Adding Pop-up Help to Controls

Problem

Dialog boxes in Windows applications support pop-up help on controls. On such forms, clicking the question-mark button in the upper-right corner of the form and then clicking on a form control displays a tooltip-like message describing the use of the control. (See Figure 14-27 for an example.) You want to add a similar feature to controls on your form.

Figure 14-27. Pop-up help for a control

Solution

Sample code folder: Chapter 14\PopupHelp

Include a HelpProvider control on your form, and use it to enable the pop-up help.

Discussion

Create a new Windows Forms application, and add a Button control to the form. We'll add pop-up help to this button. Next, add a HelpProvider control to the form, which you'll find in the Components part of the Windows Forms Toolbox. This control (HelpProvider1) appears in the off-form area of the designer.

Change the form's HelpButton property to TRue. The button won't appear yet because it only appears when the Minimize and Maximize buttons are hidden. Set both the MinimizeButton and MaximizeButton properties to False to make the help button appear. You'll see the standard Windows question-mark button.

To set the help message for the Button control, select it on the form. One of the control's properties is HelpString on HelpProvider1, which appears indirectly through the HelpProvider1 control. Add some text to this property.

To view the pop-up help, run the program, click on the question-mark button, and then click on the Button control. The pop-up help will appear until you click some-where else.

The HelpProvider control also supports more standard online help methods. It can display help through a web page that appears when the user presses the F1 key from anywhere on the form. It can also display online help through a compiled HTML Help 1.x (.chm) file.

To enable web-page-based help, add a HelpProvider control to your form, and change its HelpNamespace property to any valid web page.

To display help through HTML Help files, set the HelpProvider control's HelpNamespace property to the help-file path. Change the form's HelpKeyword on HelpProvider1 property (the name may vary based on the name you gave to the help provider control) to the name of the page within the compiled file as defined by your HTML Help editing tool. An example may be html/EditorPage.htm. Also change the form's HelpNavigator on HelpProvider1 property to Topic.

The HelpNavigator on HelpProvider1 property includes other methods with which you can access compiled help pages. For instance, the TableOfContents and Index values, when used, bring up the Table of Contents page and the Index page for the online help, respectively.