Yesterday I provided a tip about using the context sensitive help feature within Windows Mobile. I finished the post with a gotcha, mentioning that it worked in few third party applications. This was due to the feature needing to be explicitly handled by the application developer. This blog entry is designed to discuss how .NET Compact Framework developers can implement integrated help within their own applications.
Integrating help into your application
Help within Windows Mobile is implemented by an application called peghelp.exe. This application is essentially a host for a web browser control which renders an HTML based help file.
There is typically one HTML help file per application. A special structure is used within the HTML file to determine where to split topics.
As a demonstration of how this works you may like to use the run dialog tip mentioned yesterday to run “peghelp \windows\calc.htm#Main_Contents”. This will view the help file associated with the built in calculator application.
Within the .NET Compact Framework the System.Windows.Forms.Help class helps wrap up this functionality and hide the specifics of launching peghelp.exe.
The ShowHelp method will display a specified topic within a help file. It can be invoked from within a button click event handler reasonably easily, as the following example demonstrates:
private void button1_Click(object sender, EventArgs e)
Notice the ‘#’ character which seperates the path of the HTML help file and the name of the topic.
The first code sample is ideal for launching help from a button or menu item within our application. To launch your help by using the context sensitive help feature within the Windows Start Menu you need to listen to the form’s HelpRequested event as shown below.
private void Form1_HelpRequested(object sender, HelpEventArgs hlpevent)
By using unique topic names within the event handler associated with each form, you can obtain context sensitive help. In an advanced application you may even place conditional logic within your HelpRequested event handler. This enables you to display different help topics, depending upon the state of your user interface.
Creating your own help file
The help file for your application is a simple HTML file. However there are a couple of special tags you must utilise, in order for the help application to be able to split up your single file into multiple topics.
To create your first topic within an HTML help file, insert the following elements within the <body> element of the file.
<!-- PegHelp -->
<a name="SomeTopic" title="SomeTopic" />
.... HTML contents of topic goes here ....
The value of the name attribute (in this case set to “SomeTopic”) is the unique name for the topic, and is the value you should use to link to this topic.
The only special topic name that you should use is “Main_Contents” which should point to a topic which is suitable for use as a table of contents. Other than this topic name, you are free to use what ever names suit you.
To create additional topics, simply repeat this structure as many times as required. After the last topic it is very important to place another <!– PegHelp –> comment to mark the end of the help file. It is a common mistake for this comment to be missed and this has the effect of hiding the last topic.
Links between topics
Typically you will want to refer to other topics from within a topic. For example, at the bottom of each topic you may want to have a “see also” section, which lists other relevant topics.
To refer to another topic within your help file you use standard HTML anchor functionality, referring to the anchor name of the topic you want to jump to. This syntax is shown below, and is basically the path of your help file and the desired topic name seperated by a ‘#’ character.
<a href="MyHelpFile.htm#main_contents">Table Of Contents</a>
The parser used to break up a single file into multiple topics is not case sensitive, however it is sensitive to whitespace and changes in the format of the HTML elements. My recommendation is to utilise the same formatting of the <A NAME=”…”> and <!– PegHelp –> elements as shown in the examples in this blog entry. If you find that a topic is missing, or the content of more than one topic have become merged, double check that you have not accidently inserted additional whitespace between attributes etc.
When creating your help file you are most likely going to be using a desktop web browser which will show all your topics in one large page. When doing this it can become tricky to determine where one topic ends and another begins.
There is a special trick which will help resolve this issue. If you place an <hr> element immediately after each <!– PegHelp –> comment you will get nice divider lines separating each topic when you view your HTML help file within a desktop web-browser. However when you view the help file from within the Windows Mobile Help application they will have been removed.
Adding Keyword Search
Within the <head> element of your help file it can be handy to list a series of help topics and their matching keywords by using the <keyword> element. These keyword definitions are utilised by the Windows Mobile Find application when the user searches for help on a given topic (i.e. the find application does not search through your entire help file, it relies upon your explicitly listing all relevant keywords).
Some example keyword enteries may look like the following two example entries.
<keyword value="Puzzle;Games" title="Tetris 2000" href="tetris.htm#main_contents" />
<keyword value="High Score;Internet" title="Tetris 2000 High Score" href="tetris.htm#highscore" />
The value element contains a list of keywords separated by semi colons, while the title element contains the title which will be displayed within the Find application when a match is found. Finally the href element contains the topic reference of the topic which should be displayed when a matching keyword is found.
Images are displayed within the HTML help file using standard <img> HTML elements. However there are a couple of limitations to be aware of. The documentation on MSDN states that all images must be bitmaps with the *.2bp file extension. I believe that this document is purely a historical reference. I have had no problem using standard bitmaps with the *.bmp file extension, and I notice some of the included system help files do the same. You can not however utilise other image file formats, such as JPEGs or PNGs from within your help file.
URLs used to reference images are also relative to the \Windows directory, not the folder your HTML help file is located within.
Deploying your custom help file
Realistically your HTML help file must be located within the \windows directory. The help application can have problems if you place your help file in other locations, due to the need to use hardcoded file paths to refer to additional topics and images. These hard coded references will break if the user chooses to install your application in a different location, or your application is installed on a localised version of Windows Mobile (which will have different names for folders such as “My Documents”).
If you want the help file to show up in the main list of help files you should also place a shortcut link to your help file within the \windows\help folder. On a Windows Mobile 5.0 device this means that the help file will be accessable by selecting the “Help for Added Programs” entry within the help application’s table of contents.
If you are using a Smart Device CAB Project within Visual Studio 2005 to build your application cab you can include your help file within the CAB file by using the following procedure:
- Right click on your deployment project within the Solution Explorer and select “File System” from the “View” submenu.
- On the “File System on Target Machine” entry on the left hand side of the window, right click and select “Windows Folder” from the “Add Special Folder” submenu.
- Right click on the newly created “Windows Folder” directory and select “Folder” from the “Add” submenu.
- Type in “Help” and press enter
- Click on “Windows Folder” to select it
- On the right side of the window right click and select “File…” from the “Add” submenu
- Browse to your HTML help file and click “Open”
- Right click on the help file and select “Create Shortcut to ….”
- Rename the shortcut to remove the “shortcut to…” prefix
- Drag the shortcut to the “Help” subdirectory created above
An example application which demonstrates how to create a properly formatted HTML help file, and launch it from a .NET Compact Framework application is available for download.
I have included the source code for the application, as well as a pre-built cab file. I would suggest you install the CAB file onto your device and have a play around with how it integrates the application’s help within the help application.
As a starter, try searching for “transport” or “chris” within the Find utility (you can find this within the “Programs” start menu option) and see how this produces links to the help file installed along with the application.
26 July 2007 – updated the example application to include examples of using images within help topics in response to a recent forum thread.