Provide Help for an application

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) 
  { 
  Help.ShowHelp(this, @"\windows\calc.htm#Main_Contents"); 
  }

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) 
{ 
  Help.ShowHelp(this, @"\windows\calc.htm#pptskusecalculator"); 
}

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>

Development Tips
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
Screen-shot showing search results including topics within the HTML help fileWithin 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.

Including Images
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:

  1. Right click on your deployment project within the Solution Explorer and select “File System” from the “View” submenu.
  2. 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.
  3. Right click on the newly created “Windows Folder” directory and select “Folder” from the “Add” submenu.
  4. Type in “Help” and press enter
  5. Click on “Windows Folder” to select it
  6. On the right side of the window right click and select “File…” from the “Add” submenu
  7. Browse to your HTML help file and click “Open”
  8. Right click on the help file and select “Create Shortcut to ….”
  9. Rename the shortcut to remove the “shortcut to…” prefix
  10. Drag the shortcut to the “Help” subdirectory created above

Example Application
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.

Revision History
26 July 2007 – updated the example application to include examples of using images within help topics in response to a recent forum thread.

7 Responses to “Provide Help for an application”

  1. Aneesh says:

    Hi , I found your blog extremely help full as am developing application with same feature.
    I have downloaded your source code also.
    However , when I tried to run the application – when I clicked the button for help i got an error: Cannot open File.The file cannot be found.This happens in spite of the fact that I have set the properties of HelpExample.htm file as Build Action:Content, Copy Always.
    I had an initial trouble with platform ID.The platform not found error.So I changed that to 3C41C503-53EF-4c2a-8DD4-A8217CAD115E (Pocket PC) so that I could open the project in VS2005.
    Again I tried to run in Windows Mobile 6 with platform ID:
    b2c48bd2-963d-4549-9169-1fa021dce484

    But it is not just working.

    What do u think the issue be?

  2. Hi Aneesh,

    The code sample provided requires the HTML Help file to be installed within the \Windows directory of your device. This is the reason why it’s build action is not set to Content etc. If you look at the contents of Form1.cs you will even see that this path has been hardcoded.

    The easiest way to install the file into the correct location is to utilise the CAB file provided. During development I manually transfered the help file into the \Windows directory whenever I updated it. Once the help file has been deployed to the correct location you should be able to press F5 to debug the main application and have the help functionality opperate correctly.

    With respect to your question on MSDN forums I have never really found a good solution to not placing the help file within the \windows directory.

    Within the sample help file you will see numerious hyperlinks to jump around the various topics within the help file. These links look like the following within the HTML source code:

    <a href="HelpExample.htm#About" rel="nofollow">About this application</a>

    By default this causes the help file viewer to look in the \Windows directory for the help file (since a full file path is not specified). This is unlike a standard web browser where such a link would be resolved relative to the current working directory.

    We can work around this issue if you want to place your help file in a different directory (such as the application folder) by specifying the full path to the help file within any internal hyperlinks as shown below:

    <a href="file:///Program Files/HelpExample/HelpExample.htm#About" rel="nofollow">About this application</a>

    However the problem here is the fact that you needed to hardcode the full path to the help file within your help file. If the user installs your application via a CAB file and decides to install your application to a different location (such as an SD Card) your internal hyperlinks will point to the incorrect (hardcoded) path on the main device.

    For this reason I typically always install the help file within the \Windows directory, even if the rest of the application has been installed onto a removable Storage Card.

    The reason why standard relative hyperlinks don’t work has to do with the internal implementation details of the peghelp help viewer application. In effect by the time your HTML source code reaches the web browser control it has lost any association with it’s original source file.

  3. wincoder says:

    Hi it worked fine on windows mobile 6.0 professional and pocketpc any idea on how to implement help files in windows mobile 5.0 smart phones?

    Regards,
    Manjunath

  4. Prashant Waman says:

    Hi,
    As per the guide lines for Windows Mobile certification for logo, it is not allowed to place the help file in \windows directory. In this case how to resolve the issue?

    Regards,
    Prashant

  5. MadPrince says:

    Hi,
    Thanks for the excellent tutorial, however when i created a cab using the procedure above everything works excellent except that the help file itself was showing up in the programs list along with the program’s icon, I then even deployed the cab you provided and your help file showed up in the programs list. Is there a setting to avoid this?
    Thanks

  6. hfrmobile says:

    Nice tutorial but a bit out-dated.

    You should consider using DeviceHelp.css!

    e.g.

    The main topic
    This is the main contents page for the DeviceTests help file.
    See also
    One
    Two

    Also you should consider W3C recommendations (http://validator.w3.org/#validate_by_input)

    Regards,
    Harald-René Flasch

  7. hfrmobile says:

    e.g.
    <a name=”Main_Contents”></a>
    <h1 class=”dtH1″>The main topic</h1>
    <p>This is the main contents page for the DeviceTests help file.</p>
    <h4 class=”dtH4″>See also</h4>
    <p><a href=”DeviceTests.htm#TopicOne”>One</a></p>
    <p><a href=”DeviceTests.htm#TopicTwo”>Two</a></p>

Leave a Reply