Microsoft Windows CE Help for the Pocket PC 2002

  • Article

 

Susan Buckley
Microsoft Mobile Device Division

February 2002

Applies to:
   Microsoft® Windows® Powered Pocket PC 2002

Summary: This article discusses how to create Windows CE Help for the Pocket PC 2002. (10 printed pages)

Contents

Introduction
Brief History
Windows CE Help Overview
Creating a Help System
Capturing Screen Shots
Testing a Help System
Final Design Considerations

Introduction

The Pocket PC runs the Microsoft® Windows® CE operating system and provides users with companion programs to Microsoft Office for Windows, Microsoft Outlook® for Windows, and Microsoft Internet Explorer on the desktop computer. Using Microsoft ActiveSync®, the information on mobile devices can be synchronized with larger computers and networks, providing users with up-to-date information on all of their computers.

Though these companion programs are designed with user interfaces that are similar to the desktop programs, users may need additional information to use their devices to their fullest. Windows CE Help provides users with immediate and context-sensitive Help. The following topics provide detailed information about the history and features of Help as well as a tutorial on developing a Help system for Windows CE.

Brief History

The first two versions of Windows CE Help, versions 1.0 and 2.0, were developed for the earliest versions of the Handheld PC and Palm-size PC. These versions are no longer used. Other early versions of Windows CE Help are documented in the following locations:

This article focuses on Windows CE Help version 2.3 for the Pocket PC 2002. Windows CE Help version 2.3 incorporates all the features of version 2.2 along with a new Find feature. For more information on the Find feature, see Adding Find Functionality.

Other devices running Windows CE, such as the Auto PC and WebTV, do not use Windows CE Help.

Windows CE Help Overview

The Windows CE Help window consists of a content area and a navigation toolbar. Peghelp.exe provides the navigation toolbar, and an HTML-rendering program displays the content. The window is always displayed at full size.

Figure 1. Solitaire Help

Tapping the Help command on the Start menu accesses Help. The results vary depending on where users use this command. When Help is accessed from the Today screen, Help displays a list of all installed Help files that can be customized using link files. For more information, see Creating a Master List of All Installed Help Files. When accessed from any other screen, Help displays a context-sensitive Help topic for the current area of the user interface (UI). For example, if the user is in the New Appointment dialog box, the "Add an appointment" Help topic appears.

Once Help is opened, navigation within Help files also varies depending on the device. The following table lists navigational aids for the Pocket PC.

Button Function
View Provides access to the Contents command that displays the first level of contents for the current Help files, and the All Installed Help command that displays a list of all installed Help files. The All Installed Help list can be customized using link files. For more information, see Creating a Master 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 set to search for Help content.

Creating a Help System

This section discusses the following topics:

Tools
HTML Tags
Creating Topics
Adding Jumps
Adding Images
Adding Find Functionality
Creating a Master List of All Installed Help Files
Linking Help Topics to Programs

Tools

A Windows CE Help system consists of regular HTML (.htm) files and graphics. HTML Help (.chm) files will not run on Windows CE. To create a Windows CE Help system, you need the following tools:

  • An HTML editor to write Help file content.
  • A program that captures screen shots from a mobile device. One such program is called Remote Zoomin. For more information, see Capturing Screen Shots.

HTML Tags

You can use most of the HTML version 3.2 tags supported in Microsoft Pocket Internet Explorer. Scripting, Dynamic HTML (DHTML), and eXtensible Markup Language (XML) are not supported. Additional HTML coding and special HTML tags are needed to enable Windows CE Help to determine individual topics and files and to add a file to the list of all installed Help files.

  • Each topic in a Help file must be separated with the <!-- PegHelp --> tag. Note the space at the beginning and end of "PegHelp." This tag is placed at the end of header information and each topic, to mark chunks of text as individual topics to Help. If you do not use this tag, all of your topics will run together in one long file.
  • The <META> tag must be included as follows: <META HTTP-EQUIV="Htm-Help" Content="foo.htm#Main_Contents">. This tag is used by Windows CE Help with the link files to create a dynamic All Topics list.

You may also want to use the <!-- **Topic Break** --><HR> tag combination to help locate topic breaks. These tags are not necessary and do not change the display of Help to users, but make it easier to scan through your files and find the topic you need to revise.

Creating Topics

The first topic in each Help file must be named Main_Contents. This name is used with the link (.lnk) files to add the Help file to the list of all installed Help files. Each additional topic should have a unique anchor name, and you can name additional topics whatever you want. At the end of each topic, insert the <!-- PegHelp --> tag. The following example is the Setting Solitaire Options topic in Solitaire Help:

<A NAME="setting_solitaire_options"></A><B>Setting Solitaire Options</B>

<OL>
<LI>Select <B>Options</B>.
<LI>Select desired options.
</OL>

<B>See Also</B><BR>
<A HREF="soltr.htm#playing_the_game">Playing the Game</A><BR>
<A HREF="soltr.htm#solitaire_scoring_systems">Solitaire Scoring Systems</A>
<BR CLEAR=ALL>
<!-- PegHelp --><HR>

<!-- ************************Topic Break************************* -->

You can also use the <HR> tag to further separate Help topics during editing. Because the <HR> tag is located after the <!-- PegHelp --> tag, it will not be displayed in Windows CE Help.

Adding Jumps

To create a jump to another file, use the <A HREF> tag:

<A HREF="soltr.htm">

Unlike regular Web pages, to jump to a topic within the current file, you must include the file name and the anchor name:

<A HREF="soltr.htm#about">

Some software used to verify links will not work correctly because the name of the file is in the internal jump. Simply searching and replacing ".htm#" with "#" before running a link test will resolve the problem. Be sure to do this on a copy of the file, not the original.

Adding Images

Windows CE Help only recognizes image files with the .2bp extension. The .gif and .jpg extensions are not currently supported. Simply create a bitmap (.bmp) file and change the extension to .2bp. No other conversion is needed. To save disk space, use black and white images only. To add a bitmap to a topic, use the <IMG SRC> tag to specify the file name of the image you want to include:

<IMG SRC="button.2bp">

Adding Find Functionality

Windows CE Help uses keywords and the Find program, installed on the Pocket PC by default, to enable users to quickly search for Help information. Users access the keyword functionality by tapping Find located in the command bar at the bottom of the Help window. The Find command opens the Find program preset to the Help information type. Users then enter a word to search for and tap Go (See Figure 2).

Figure 2. Find Results

Find then lists all Help topic titles tagged with the same keyword. To access a topic, users tap a topic title.

Authors tag topics with keywords using a special tag in the header section of the Help file using the following syntax:

<HEAD>
<KEYWORD VALUE="keyword1;keyword2" TITLE="Title of the topic" HREF="file.htm#anchorname">
</HEAD>

The <KEYWORD> element has 3 attributes: VALUE, TITLE, and HREF. VALUE sets the actual keywords separated by a semicolon. There is no limit to keywords per topic. TITLE denotes the actual title of the topic and sets the title that appears in the Results section of Find. Finally, HREF sets the link to the actual topic.

For example:

<HEAD>
<KEYWORD VALUE="typing;writing;drawing;recording;type;write;record" TITLE="About SIP" 
HREF="notes.htm#aboutsip">
</HEAD>

Enter one <KEYWORD> tag for each topic in the Help file, and list the appropriate keywords for that topic. Authors should use the same strategy they would for selecting indexing keywords.

Windows CE Help does search for partial matches against keywords. For example, the word "advantage" will match with the keywords "advantage" and "advantages."

Phrases cannot be used as keywords, but users can use phrases, such as "high score," when searching in the Find dialog box. Windows CE Help will search for all words listed in the phrase. Users cannot perform OR searches in Find.

Creating a Master List of All Installed Help Files

The master list of all installed Help files provides users with a fast way to scan all the Help file titles for the exact type of information they need. In versions prior to 2.10, this list was a separate HTML file that could not be updated. Version 2.10 and later creates this list dynamically through the use of the name of the first topic in each file, and a corresponding link (.lnk) file. New links can be added at any time.

To add a file to the list, the first topic in the Help file must be named "Main_Contents." Also, the "Main_Contents" name must appear in the <META> tag. For example, the header information of the Solitaire Help files is written as:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Htm-Help" CONTENT="soltr.htm#Main_Contents">
<TITLE>Solitaire Help</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000">
<!-- PegHelp -->
<P><A NAME="Main_Contents"></A><B>Solitaire Help</B></P>
<A HREF="soltr.htm#playing_the_game">Playing the Game</A><BR>
<A HREF="soltr.htm#setting_solitaire_options">Setting Solitaire Options</A><BR>
<A HREF="soltr.htm#solitaire_scoring_systems">Solitaire Scoring Systems</A><BR>
<BR CLEAR=ALL>
<!-- PegHelp --><HR>
<!-- ************************Topic Break************************* -->

Create a link (.lnk) file in Notepad or another ASCII editor. The link file should be named the way you want the link to appear in the list. For example, the Solitaire Help file is named "soltr.htm" and the link file is named "Solitaire.lnk." The link will be "Solitaire." You can use spaces in the link file name, for example, "Pocket Word.lnk."

The text in the link file tells Windows CE Help which Help file to open when the link is clicked or tapped in the list. The following text was entered in the Solitaire.lnk file:

18#\windows\soltr.htm

The number 18 represents the number of characters in "\windows\soltr.htm." During the installation of your program, install the link file in the \Windows\Help folder on the device. The Help file can be installed in any folder on the device or on a CompactFlash card.

Linking Help Topics to Programs

Desktop computer programs generally have both a Help system and What's This? content. The Help system is written and compiled by the Help authors as a WinHelp (.hlp) or HTML Help (.chm) file, and is accessed from the Help menu. What's This? content is stored in the Help file, and is accessed by a Help button or by pressing F1. Help is then called using a header file that maps the Help topic IDs to numeric values that represent a specific dialog box or dialog box options.

The concept behind all Help linking on the Pocket PC is very similar to What's This? Help with two main differences. First, the Help command always relates to the entire Pocket PC screen the user is working with at the time Help is accessed, and cannot be set for a specific option on a dialog box. Second, instead of using numeric values and then mapping those values to topic names, the actual Help file name and topic name are listed in the code.

Otherwise, tapping Start and then Help on the Pocket PC is the same as pressing F1 on a desktop computer. The WM_Help message triggers code written for the topmost active dialog box to call Help and tell Help what to display.

The CreateProcess function is one way the call can be made. Using the TEXT macro to first convert the string to Unicode, pass the "peghelp.exe" string, which is the name of the Help engine, as the first parameter. In the second argument, use the TEXT macro again and pass a string containing the file name and the specific Help topic you want to display. Set all other parameters to NULL, FALSE, or 0, respectively.

The following code example shows how Help could be accessed from each dialog box in the Solitaire program using the CreateProcess function.

CreateProcess(TEXT("peghelp.exe"), TEXT("file:soltr.htm#playing_the_game"), NULL, NULL, FALSE,
 0, NULL, NULL, NULL, NULL);
CreateProcess(TEXT("peghelp.exe"), TEXT("file:soltr.htm#setting_solitaire_options"), NULL, NULL, FALSE,
 0, NULL, NULL, NULL, NULL);
CreateProcess(TEXT("peghelp.exe"), TEXT("file:soltr.htm#Main_Contents"), NULL, NULL, FALSE,
 0, NULL, NULL, NULL, NULL);

Capturing Screen Shots

To use pictures of your program's UI, you will need to use a tool specially designed to capture screen shots from the Pocket PC. If you have already installed Microsoft eMbedded Visual Tools 3.0, you can use Remote Zoomin to take screen shots of a connected device through your desktop computer. For more information, see the eMbedded Visual Tools Web page.

Testing a Help System

You should test your Help files on a device to ensure that they look and act the way you expect. Connect your device to your desktop computer and create a partnership using ActiveSync. Copy and drag the new version of the Help file to the device. Choose not to synchronize or convert the file.

To check all of your context-sensitive links, access Help from all of the windows and dialog boxes in your program. If a link for the Help file has not been added to the list of all installed Help files or connected to the program, you can still access the Help file from the Run dialog box:

  1. In the Today screen, press and hold the Action button. Then, tap and hold the clock in the upper-right corner of the screen, and tap Run.
  2. In the Run dialog box, enter:
    \Windows\peghelp.exe \Windows\filename.htm#Main_Contents
    Note the space between "peghelp.exe" and "\Windows\". Also, you should substitute the actual file name for filename.

To open a Help file in Pocket Internet Explorer, tap the file after copying it to the device. You can scroll through all of the Help topics as you would in Internet Explorer on your desktop computer. This is a great way to quickly check for typos. However, to truly test how your Help file will behave, test it in Windows CE Help. This is especially true since anchor links will not work in Help files directly opened in Pocket Internet Explorer.

Final Design Considerations

Remember that fairly comprehensive information is needed because users will more than likely not carry manuals. When writing Help, try to convey as much information in as little text as possible. For example, instead of using the traditional "On the File menu, tap Open", use "File > Open." Consider limiting graphics to pictures of buttons that are not menu commands or familiar to experienced Windows users. You can also use black and white images instead of color to further conserve memory.

The writing style you choose will affect readability and the amount of memory used. When developing topics, use HTML tags that are supported by Pocket Internet Explorer. You may also want to limit formatting tags to a few to make your Help topics consistent and easy to read. Using fewer tags also reduces the overall size of your files.

The features and functionality of devices are beginning to diverge, and you may not always know what type of hardware your users will have. This calls for flexible style guides and the use of more generic terms. For example, if you do not know whether the device will have a touch screen and stylus, or a mouse, you might want to use "select" instead of "tap" or "click."