Microsoft Office 2000/Visual Basic Programmer's Guide   

Creating Context IDs

To display Help topics in Office solutions by using standard properties or the Help method of the Application object, your compiled Help file must have a numeric value, called a context ID, for each topic you want to display. This is true for both context-sensitive Help and standard Help topics, and whether you are using a compiled HTML Help file or a WinHelp 4.0 file.

Creating Context IDs for WinHelp 4.0 Files

For WinHelp 4.0 files, the process of mapping context IDs is the same for both context-sensitive pop-up Help and standard Help topics.

To create and map context IDs in a WinHelp 4.0 Help file

  1. Use Word to create a document, inserting a page break between each topic.

  2. On the Insert menu, click Footnote to add a footnote to the first paragraph in each topic. In the Footnote and Endnote dialog box, click Custom mark and type # as the footnote symbol. As the footnote text, type a unique string called a topic ID for each topic; for example, HelpTopic1.

  3. Save the document as a Rich Text Format file (.rtf).

  4. Use Microsoft Help Workshop to create a Help project file that specifies this .rtf file as your topic file, and then either manually map each topic ID to a unique numeric context ID or create a C header file to do this.

  5. Compile your Help file.

For more information about creating WinHelp files, see the Help system in Microsoft Help Workshop.

Creating Context IDs for HTML Help Files

In Office applications, HTML Help files can be used only for standard Help topics, and the process of mapping context IDs in HTML Help files is different than that used for WinHelp 4.0 files. In HTML Help, Help topics that will be displayed in the HTML Help Viewer or a Help window are authored by using a separate HTML file for each topic. After you have authored your Help topics, you will want to create jumps between them. To do this, instead of using a topic ID to specify the topic to jump to as is done for WinHelp 4.0 files, you author a standard HTML hyperlink that specifies the HTML file name of the topic. For example, the following <A> (anchor) tag creates a jump to the topic authored in the Options.htm file:

<A HREF="Options.htm">Options</A>




To retain compatibility with applications that expect context IDs, HTML Help requires you to perform two steps to create numeric context IDs for each topic file you want to display:

    

  1. 
Create a C header file that maps an arbitrary topic ID text string to a numeric context ID.

    2. 

  2. 
Map each topic ID from the header file to the actual HTML file name of the topic you want to display. In HTML Help Workshop, this is called aliasing topic IDs to HTML file names. You can do this manually through the HTML Help Workshop user interface, or by creating a text file with an .h extension.
    3. 




The following procedures assume you have already created Help topics for your HTML Help file.



To create a C-style header file to map topic IDs to context IDs

    

  1. 
Create a new text file in HTML Help Workshop or in your favorite text editor.

    2. 

  2. 
For each topic you want to create a context ID for, enter a line in this format:
    
#define   topic_id    nnnn   // comment
    
The string constant after #define is the topic ID and the number following it is the context ID. Each topic ID and context ID must be unique within your Help project. The "//" comment introducer and comment text are optional.
    3. 

  3. 
Save the text file with your other HTML Help source files and make sure it is named with an .h extension.

    4. 

  4. 
In HTML Help Workshop, open your Help project file, click the HtmlHelp API Information button  on the Project tab, and then on the Map tab, click Header File and specify the header file.
    5. 




After you have created your header file and specified it for your Help project file, you must alias each of the topic ID strings in the header file. You can do this manually or by including a text file that defines each alias. Before doing this, you should print out or open a copy of the map header file you created in the previous procedure so that you can view the names of each topic ID string.



To manually alias topic IDs to context IDs

    

  1. 
Open your Help project file in HTML Help Workshop.

    2. 

  2. 
Click the HtmlHelp API Information button  on the Project tab, and then click the Alias tab.

    3. 

  3. 
To manually specify the alias for each topic ID string, click Add, type the topic ID string you want to alias in the first box, and then select the HTML file that contains the topic in the second box.
    4. 




To alias topic IDs to context IDs by using a text file

    

  1. 
Create a text file and enter a line in this format for each topic ID you want to alias to an HTML file:
    
topic_id=filename.htm ; comment
    
The topic_id string constant is the topic ID from the mapping header file, and the file name following the equal sign (=) is the HTML file name of the topic you want to display. The ";" comment introducer and comment text that follows are optional.
    2. 

  2. 
Save the text file, making sure it has an .h extension.

    3. 

  3. 
Open your Help project file in HTML Help Workshop.
    4. 

  4. 
Click the HtmlHelp API Information button  on the Project tab, and then click the Alias tab.

    5. 

  5. 
Click Include and specify the text file you just created.
    6. 




Once you have mapped context IDs to the topic IDs in your compiled WinHelp 4.0 and HTML Help files, you use the appropriate context IDs in the design-time settings of forms and controls, and in your program code to display the correct Help topic.



For more information about creating HTML Help files, see the Help system in HTML Help Workshop.