More Advanced Procedures > Using Context-Sensitive Help

Context-sensitive help displays a normal topic or a popup topic. Context-sensitive popup topics are known as "field-level popups" because they are displayed directly in your application, not in the main help window. Field-level popups are only supported in HTML Help and the obsolete Winhelp format. The JavaScript popups used in Webhelp cannot be used as field-level popups.

As the help author you don't need to do anything special to create context-sensitive topics. They are simply normal TOC topics and normal popup topics. They become "context-sensitive" when they are called directly from the application. What makes field-level popup topics a little different is the fact that they can be called on their own, without the help, but within the help they are still just the same as other popup topics.

For more background information see the Context-Sensitive Help & Popups chapter in the Reference section.

Normal context-sensitive topics are simply normal topics in the TOC. Just follow the instructions in Creating new topics to create a new topic in the TOC.

These topics become context-sensitive topics when they are called directly from the application. How this is done depends on the programming language and your output format. For details see Application calls to context-sensitive topics.

Plain text popup topics used in HTML Help must have context numbers! This is required by the Microsoft HTML Help API for popups and if your popup topics do not have help context numbers they will not be exported to the internal popup text file in the CHM.

Field-level popup topics are simply normal popup topics. Just follow the instructions in Creating popup topics to create and edit popup topics.

Popup mode for field-level popups:

Field-level popup topics are only supported in Winhelp and HTML Help. In HTML Help you must select Text-only popups in Configuration > Publishing Options > HTML Help > Popup Topics. There are no special configuration settings for field-level popups in Winhelp.

Using field-level popups:

To use field-level popups your programmers must call the popup topic inside the help file from your application, using the appropriate API calls for HTML Help or Winhelp. The syntax of these calls depends on your programming language. You can download tutorials for most current languages from our website. See Application calls to context-sensitive topics for more details.

Auto-generating your popup topics from a map file:

If your programmers provide you with a "map file" of the topic IDs and context numbers for the elements in the program that need to be documented you can also generate your field-level popup topics automatically! See Auto-generating context-sensitive topics for details.

Don't use links in field-level popups:

Even in the obsolete Winhelp format where links are supported it is bad practice to use links in field-level popups. These topics are designed to be viewed, read quickly and then closed again. If you need to use links it is better to use a normal topic instead of a popup topic. Then the programmer can make a context call to the normal topic, which will call up entire help so that the user can browse it.

HTML Help popups are plain-text only, they do not support graphics or formatted text like the popups in the obsolete Winhelp format. In the past, help authors used to create HTML Help with an additional Winhelp file for the popups. This approach was known as "dual-mode help".

Since Winhelp is now obsolete dual-mode help is no longer supported in Help & Manual because using it makes your help incompatible with Windows Vista.