Incorporating Help into Your Windows Applications

elp is one of the most overlooked aspects of Windows development. Ask yourself this: for the last application that you finished and rolled out, how much effort did you put in to ensure that the users get all the help they need? No doubt you tried to design a user-friendly user interface, but did you provide any avenue for your users to get help when they are stuck?

This article discusses some ways to incorporate help into your application and make it much more user-friendly

Tooltips
The first (and easiest) way to create a help for your Windows application is to use Tooltips. A tooltip is a little graphical balloon that pops up when you position your cursor over an item, such as a Button or a CheckBox control.

Figure 1. Displaying a Tooltip: This is what it looks like when the mouse cursor hovers over the Button control.

In Windows Forms, you implement the Tooltip by using the Tooltip control (located in the Toolbox). You can also call it programmatically using the ToolTip class. For example, the following code snippet creates a ToolTip object, sets the message to display, and then binds itself to a Button control:

        Dim tooltip1 As New ToolTip        With ToolTip1            .ToolTipTitle = "About Button1"            .SetToolTip(Button1, "Button 1 help string...")        End With

Figure 1 shows how it will look when the mouse cursor hovers over the Button control.

By default, the Tooltip is displayed as a rectangle. However, you can set the IsBalloon property to True to change it into a balloon (see also Figure 2):

        With ToolTip1            .ToolTipTitle = "About Button1"            .SetToolTip(Button1, "Button 1 help string...")            .IsBalloon = True        End With
Figure 2. Balloon Tooltip: Setting the IsBalloon property to True changes it into a balloon.

The ToolTip control also supports additional properties that allow you to control the duration for which it is displayed. For example, you can use the InitialDelay, ReshowDelay, and AutoPopDelay properties to control when the balloon is displayed and for how long:

        With ToolTip1            .ToolTipTitle = "About Button1"            .SetToolTip(Button1, "Button 1 help string...")            '---time to wait before tip is shown for the first time---            .InitialDelay = 500             '---time to wait for subsequent display---            .ReshowDelay = 1000            '---time to show the tip---            .AutoPopDelay = 2000         End With

To ensure that all Tooltip balloons have consistent behaviors, you can set the AutomaticDelay property, which will automatically set the other properties. Simply use the formula shown below:

            .AutomaticDelay = 500 '---N---            '---automatically sets the following---            '.InitialDelay = 500 '---N---            '.ReshowDelay = 100 '---N/5---            '.AutoPopDelay = 5000 '---10N---

Once the AutomaticDelay property is set, you can choose to overwrite the defaults for the other properties by setting their values.

Displaying the “?” Button
Another way to offer your users help is to implement the “?” button. This help button can usually be found on the top-right corner of a window. When users need help with your application, they can click on the “?” button and then click on controls on your form to display the help message for each control (which you will implement).

To display the “?” button on a form, you need to set the form’s HelpButton property to True, like this:

Figure 3. Display Help Messages: Drop the HelpProvider control onto your form to display help messages.

Private Sub Form2_Load( _       ByVal sender As System.Object, _       ByVal e As System.EventArgs) _       Handles MyBase.Load        With Me            .MinimizeBox = False            .MaximizeBox = False            .HelpButton = True        End With    End Sub

Note that you need to set the MinimizeBox and MaximizeBox properties to False. If you don’t, the “?” button will not be shown.

To associate the “?” button with help, use the HelpProvider control (also located in the Toolbox). The HelpProvider control extends the controls on your form with help capabilities.

Once you have dropped a HelpProvider control onto your form, you can set the “HelpString on HelpProvider1” property for the TextBox control with a string (as shown in Figure 3). This will associate a help message for the TextBox control.

When you run the application, you will see that the “?” button is displayed (see Figure 4). Click on the “?” button and then click on the TextBox control. You will notice that a help message is displayed.

Figure 4. Display the “?” Button: This is displayed when you run the application.

Programmatically, you can set the help string for a control using the HelpProvider control through the SetHelpString() method:

        HelpProvider1.SetHelpString( _           TextBox1, "This is a textbox for...")

To disassociate the help string from a control, use the SetShowHelp() method and pass in False for the second parameter:

        HelpProvider1.SetShowHelp(TextBox1, False)

Displaying Microsoft Compiled HTML Help (.chm)
The third way to provide help for your users is to create a professional help application. You can do so using the Microsoft Compiled HTML Help. Microsoft Compiled HTML Help is a proprietary format for online help files, developed by Microsoft and first released in 1997 as a successor to the Microsoft WinHelp format. Microsoft Compiled HTML Help files have the extension .chm and is a standard way of providing help documentation for most Windows applications. Figure 5 shows an example of a help file (Microsoft Device Emulator).


Figure 5. The .chm File: Microsoft Compiled HTML Help files have the extension .chm.
?
Figure 6. Populating the Form: These controls populate your form.

There are many ways to create Microsoft Compiled HTML Help, including the HTML Help Workshop from Microsoft as well as some third party tools that greatly simplify the task. Hence this article will not be covering how to create help files. Instead, you’ll see how to integrate a .chm help file into your Windows application.

Assume you have a form populated with the following controls (see also Figure 6):

Figure 7. Add a .chm File: This example uses the Help file for Microsoft Device Emulator for the project.
  • Label
  • Button
  • CheckBox
  • RichTextBox

And further assume that you have also added a .chm file into your project (see Figure 7). This example uses the Help file for Microsoft Device Emulator for the project.

Set the properties of the controls shown in Table 1.

Control

Property

Value

Button1

HelpKeyword on HelpProvider1

skins

Button1

HelpNavigator on HelpProvider1

Index

Button2

HelpKeyword on HelpProvider1

skins

Button2

HelpNavigator on HelpProvider1

KeywordIndex

Table 1.Setting the Properties for the Controls.

The HelpNavigator property determines the kind of help associated with a particular control. Table 2 shows the list of possible values. The HelpKeyword property indicates the keyword used in association with the HelpNavigator property.

Properties

Description

AssociateIndex

The Help file opens to the index entry for the first letter of a specified topic.?

?

Find

The Help file opens to the search page.?

?

Index

The Help file opens to the index.?

?

KeywordIndex

The Help file opens to the topic with the specified index entry, if one exists; otherwise, the index entry closest to the specified keyword is displayed.?

?

TableOfContents

The Help file opens to the table of contents.?

?

Topic

The Help file opens to a specified topic, if the topic exists.?

?

TopicId

The Help file opens to a topic indicated by a numeric topic identifier.?

?

Table 2. Possible Values for the HelpNavigator Property.

Set the HelpNamespace property of the HelpProvider control to .DeviceEmulator.chm (see Figure 8).


Figure 8. Pointing to the .chm File: Set the HelpNamespace property to point to the .chm file.
?
Figure 9. Searching: Searching using the Index page.

Notice Table 1 sets the help properties for Button1 and Button2 only. This means that when one of these Button controls has the focus, the user can press F1 to launch the .chm Help file.

Figure 9 shows that when the user selects the Button1 control and presses F1, the text “skins” will be used as a key for index search.

When the Button2 control is selected and the user presses F1, the Topics Found dialog opens (see Figure 10).

To manually open the help file, use the ShowHelp() method from the Help class. Code the View Help button as shown below:

    Private Sub btnViewHelp_Click( _       ByVal sender As System.Object, _       ByVal e As System.EventArgs) _       Handles btnViewHelp.Click        Help.ShowHelp(Me, "DeviceEmulator.chm", _           HelpNavigator.TableOfContents)    End Sub

This will display the Table of Contents page of the Help file (see Figure 11) when the button is clicked.


Figure 10. Display: Displaying the Topics Found dialog.
?
Figure 11. Display: Displaying help using the ShowHelp() method.

If you want to display the Index page, simply use the ShowHelpIndex() method:

        Help.ShowHelpIndex(Me, "DeviceEmulator.chm")

Setting the HelpKeyword and HelpNavigator properties is one way of associating help with the controls. Alternatively, you can also handle the HelpRequested event of a control, such as the following:

    Private Sub RichTextBox1_HelpRequested( _       ByVal sender As System.Object, _       ByVal hlpevent As System.Windows.Forms.HelpEventArgs) _       Handles RichTextBox1.HelpRequested        Help.ShowHelp(Me, "DeviceEmulator.chm", _           HelpNavigator.Index, RichTextBox1.SelectedText)    End Sub

Using this approach allows you to dynamically insert the text to search for in the help file.

The above code launches the DeviceEmulator.chm file and use the text stored in the RichTextBox control as the search key. Figure 12 shows an example when a user selects the sentence “Platform Builder” and then presses the F1 key.


Figure 12. The HelpRequested Event: When a user selects the sentence “Platform Builder” and then presses the F1 key.
?
Figure 13. Display: The balloon help when an action occurs.

Finally, when you want to display a little balloon help when the CheckBox control is checked, you can use the ShowPopup() method, like the following:

    Private Sub CheckBox1_CheckedChanged( _       ByVal sender As System.Object, _       ByVal e As System.EventArgs) _       Handles CheckBox1.CheckedChanged        Help.ShowPopup(Me, "Checkbox: " & CheckBox1.Checked, _           Control.MousePosition)    End Sub

Figure 13 shows the balloon help that is displayed every time the user checks/unchecks the CheckBox control.

The Extra Effort Pays Off
You’ve seen three ways to provide help for the users of your application. Remember that if you make your application easy to use, that will reduce your support cost in the long run. Hence, take the extra effort to implement the techniques introduced in this article.

Share the Post:
Share on facebook
Share on twitter
Share on linkedin

Overview

The Latest

homes in the real estate industry

Exploring the Latest Tech Trends Impacting the Real Estate Industry

The real estate industry is changing thanks to the newest technological advancements. These new developments — from blockchain and AI to virtual reality and 3D printing — are poised to change how we buy and sell homes. Real estate brokers, buyers, sellers, wholesale real estate professionals, fix and flippers, and beyond may

man on floor with data

DevX Quick Guide to Data Ingestion

One of the biggest trends of the 21st century is the massive surge in internet usage. With major innovations such as smart technology, social media, and online shopping sites, the internet has become an essential part of everyday life for a large portion of the population. Due to this internet

payment via phone

7 Ways Technology Has Changed Traditional Payments

In today’s digital world, technology has changed how we make payments. From contactless cards to mobile wallets, it’s now easier to pay for goods and services without carrying cash or using a checkbook. This article will look at seven of the most significant ways technology has transformed traditional payment methods.