How to: Display User Help

Article
06/18/2009

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

The .NET Compact Framework provides access to the Windows CE Help program, peghelp.exe, to display Help topics for Pocket PC applications. You can display a Help topic with the ShowHelp method of the Windows Forms Help class responding to the HelpRequested event and use HelpEventArgs. The .NET Compact Framework does not support the HelpNavigator enumeration or HelpProvider class.

Help topics can be located in one or more .htm files. Compiled HTML, or .chm files, are not supported on the Pocket PC. The HelpRequested event is received by the currently active form when the user navigates to the Start menu and chooses Help. The event is not raised by controls on the form.

Help is not integrated into the Smartphone operating system because Smartphone applications should be simple.

The following table lists the system Help features displayed for each topic.

Menu item	Function
View	Provides access to the Contents command that displays the first level of contents for the current Help file, and the All Installed Help command that displays a list of all installed Help files.
Back	Displays the previously viewed topic in the current session.
Forward	Displays the next topic in the history list.
Find	Opens the Find dialog box for searching Help topics by keywords. You can specify keywords in the .htm files.

The following procedures show how to do the following:

Create an .htm file of Help topics
Display Help for your application
Install your Help file on the device

To create an .htm file of Help topics

Create a text file named for your Help with an .htm extension. This procedure creates Help for a game, called Critters, as an example. The file must have the META tag in the header as follows:
```
<HTML>
<HEAD>
<META HTTP-EQUIV="Htm-Help" Content="Critters.htm#main_contents">
```
The first topic in each Help file must be named "main_contents".

Add keywords for the Find program. Separate keywords with semicolons. Add additional keyword tags to link to specific topics as needed.

<KEYWORD VALUE="Critters;Games" TITLE="Critters Help" 
  HREF="Critters.htm#main_contents">
<KEYWORD VALUE="Critters overview" TITLE="Critters Help" 
  HREF="Critters.htm#overview">
<KEYWORD VALUE="Critters options" TITLE="Critters Help" 
  HREF="Critters.htm#options">

There is no maximum keyword limit for a topic.

Create the main_contents topic. Each topic, including main_contents, must preceded by the following comment tag:
```

```
The main_contents topic typically contains links to subtopics. Note that links require the file name in addition to the anchor name.
```
</head>
<body>

<a name="Main_Contents"></a>
Critters Help

<a href="critters.htm#overview">Game Overview</a> 
<a href="critters.htm#options">Options</a> 
```
You can add graphics, but only bitmaps that must be renamed to have a "2pb" extension.
```
<img src="critter.2bp">
```

Create additional topics.

Following is an example of the HTML between two topics:

</p>
<!-- PegHelp -->
<!-- ******* TOPIC BREAK ******* -->
<hr>
<a name="overview">

Save the file and copy it into the Windows directory of the Pocket PC.

The complete HTML for this example is as follows:

<html>
<head>
<META HTTP-EQUIV="Htm-Help" Content="critters.htm#Main_Contents">
<KEYWORD VALUE="Critters;Games" TITLE="Critters Help" 
  HREF="Critters.htm#main_contents">
<KEYWORD VALUE="Critters overview" TITLE="Critters Help" 
  HREF="Critters.htm#overview">
<KEYWORD VALUE="Critters options" TITLE="Critters Help" 
  HREF="Critters.htm#options">
</head>
<body>
<!-- PegHelp -->
<p>
<a name="Main_Contents"></a>
</p>
<b>Critters Help</b>
</p>
<p>
<a href="critters.htm#overview">Game Overview</a><br>
<a href="critters.htm#options">Game Options</a><br>
<img src="critter.2bp">
</p>
<!-- PegHelp -->
<!-- ******* TOPIC BREAK ******* -->
<hr>
<a name="overview"></a>
<p><b>Game Overview</b></p>
<p>Critters are small round creatures that you can adopt and raise.  
  They have various moods and characteristics and each one has its own 
  personality and appearance that will change over time.</p>
<!-- PegHelp -->
<!-- ******* TOPIC BREAK ******* -->
<hr>
<a name="options"></a>
<p><b>Options</b></p>
<ul>
<li><i>Sound</i> – Turn sound on / off</li>
<li><i>Sub-Games</i> – Turn sub-games on / off.  When a caretaker 
  attempts to play with a critter or teach a critter, sub-games are 
  presented such as ‘Guess my number’ and ‘Trivia’ if this option is 
  checked.</li>
<li><i>Animation</i> – Turn animation on / off.  Turning this off will 
  cause the critter to remain still.</li>
<li><i>Notifications</i> – Choose icon / text / none.  Notifications 
  appear to inform you when your critter is in danger of dying due to 
  a particular need not being met.</li>
<li><i>Speed</i> – This is the rate at which the game engine operates.
  It affects how fast feelings develop and statistics are 
  modified.</li>
</ul>
</p>
</body>
</html>

Note

When working with Help files, a previous version of your Help could be in the cache preventing you from seeing the latest updates. To refresh, display a Help topic other than what you are working on, and then display your Help again.

To display Help for your application

To display Help on the Pocket PC, tap the Help command on the Start menu. Windows CE displays the Help topic for the currently displayed application, provided that you have called the ShowHelp method in response to the HelpRequested event.

You can also use ShowHelp to call Help from within your application, such as from a button click. The following code example shows how to call Help for both cases. Note that the first parameter for the ShowHelp method is the parent control. This parameter is not relevant for the Pocket PC but is provided for compatibility with the full .NET Framework.

Protected Overrides Sub OnHelpRequested(ByVal hlpevent As HelpEventArgs) 
    ' The HelpRequested event occurs when
    ' the user taps Help on the Start menu.
    Help.ShowHelp(Me, "\windows\myAppHelp.htm#Main_Contents")
    MyBase.OnHelpRequested(hlpevent)

End Sub
Private Sub button1_Click(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles button1.Click
    ' You can also show Help
    ' for a subtopic
    ' by clicking a button.
    Try
        Help.ShowHelp(Me, "\windows\myappHelp.htm#overview")
    Catch ex As Exception
        MessageBox.Show(ex.Message)
    End Try
End Sub

protected override void OnHelpRequested(HelpEventArgs hlpevent)
{
    // The HelpRequested event occurs when
    // the user taps Help on the Start menu.
    Help.ShowHelp(this,@"\windows\myAppHelp.htm#Main_Contents");
    base.OnHelpRequested(hlpevent);
}

private void button1_Click(object sender, System.EventArgs e)
{
    // You can also show Help
    // for a subtopic
    // by clicking a button.
    try
    {
        Help.ShowHelp(this,@"\windows\myappHelp.htm#overview");
    }
    catch (Exception ex)
    {
        MessageBox.Show(ex.Message);
    }
}

To install your Help file on the device

Create a shortcut file for the Help system to list your Help with the other installed Help in the system. In a text editor, create a file with a path to your Help using the following syntax:
```
14#\windows\critters.htm
```
The path is preceded by the number of characters in the path and the number sign (#). This should be the only line in the file. In this example, the Help for the Critters game is displayed.
Save the file using the same name as your Help but with a .lnk extension in the \Windows\Help folder.
Tap Help from the Start menu. If your Help is not already displayed, choose All Installed Help from the View menu. Your Help should be included alphabetically in the list.

How to: Display User Help

To create an .htm file of Help topics

To display Help for your application

To install your Help file on the device

See Also

Concepts

Other Resources

Additional resources