Basic Working Procedures > Creating Topic Files

Popups are mini-topics used to display a small amount of information in a small "popup” window, which is normally displayed when the user clicks on a link. Popups are used both in the help text itself and in applications, where they are referred to as "field-level popups". However, field-level popups are a special Microsoft technology that is only supported in HTML Help and Winhelp.

Topics used as popups should be created in the Project Files section so that they do not have TOC entries. For more details on field-level popups see Using Context-Sensitive Help and Context-Sensitive Help and Popups.

1.	Open the Project Files section In the Project Explorer and click on Topic Files, or a subfolder if you have created one and want to use it (see Creating new topics in Topic Files for more details).

2.	Click on Add File in the Project tab to create a new topic.

3.	Click on More and select Popup In the Topic Class: field. Note that you cannot select this class when creating topics in the TOC!

4.	If you plan to use the popup topic as a plain-text popup in HTML Help you must give it a help context number. This is required by the Microsoft HTML Help API and the topic will not be exported correctly without it.

Topics with the Popup class will automatically open as popups when you link to them. The HTML Template setting is irrelevant for these topics because popups do not use HTML templates.

When you create hyperlinks to popup topics in your help they will automatically be displayed as popups. See Using Context-Sensitive Help for information on calling popups directly from your application.

How popup topics are handled depends on your output formats. Some formats support more than one popup style, which must be specified in your Project Configuration settings.

HTML Help:

In the Project Explorer select Configuration > Publishing Options > HTML Help and click on Popup Topics.

•	Text-only popups are the native HTML Help popup mode. They support plain text only (no hyperlinks, no graphics, no tables, no text formatting). This is the only popup mode that supports field-level popups in HTML Help. Popup topics used in this mode must have help context numbers.

•	JavaScript Popups are generated by Help & Manual. They support formatting, links and graphics but they cannot be used as field-level popups. They can only be displayed within your help file by other links in your help file.

•	HTML encode topics are not popups at all. When this option is selected all popup topics will be opened as normal topics in the main help viewer, using the HTML template assigned to the popup topic.

Winhelp and eBooks:

Winhelp and eBooks have no special popup topics settings.

Winhelp: There is only one popup mode in Winhelp, which supports both popups displayed in the help and field-level popups. Winhelp popups support hyperlinks, graphics and formatting. However, Winhelp is obsolete and is not supported by default in Windows Vista.

eBooks: eBooks popups are similar to Winhelp popups and can only be displayed inside the eBook viewer.

Webhelp:

In the Project Explorer select Configuration > Publishing Options > Webhelp and click on Popup Topics.

•	JavaScript Popups are generated by Help & Manual. They support formatting, links and graphics but they cannot be used as field-level popups. They can only be displayed within your help file by other links in your help file.

•	HTML encoded topics are not popups at all. When this option is selected all popup topics will be opened as normal topics in the main help viewer, using the HTML template assigned to the popup topic.

In both Winhelp and HTML Help the width of popup windows is controlled by the help viewer on the basis of the amount of text in the popup and the user's screen width. Since this system was designed a long time ago it does not allow for modern computers with wide-format screens and multiple monitors. When normal popups are displayed on these computers the popups can be much too wide, which looks terrible.

Controlling popup width in HTML Help:

•	In HTML Help's plain text popup topics the only way you can control popup width is by entering a hard line break (ENTER) at the end of each line.

Controlling popup width in Winhelp and JavaScript popups:

•

In Winhelp Note that Windows Vista does not support Winhelp. If you want to be compatible with Vista you must transition to a different help format. and JavaScript popups you can control popup width precisely by entering the entire text of the popup in a single-cell table with a fixed width. (Note that this doesn't work in HTML Help's native plain text popups because the table and its contents are stripped when you compile, resulting in an empty topic.)

•	Note that you must set the width of the single-cell table you use for this to an absolute value in pixels. Select Size Table Manually and enter the value in pixels. Don't use percent for this, it won't work properly!

You can speed up the process by defining a topic content template for your popup topics. See Content templates for topics for details.

Any link within a project to a topic defined with the Popup class will automatically be displayed as a popup in any of the output formats where popups are supported (Winhelp, HTML Help, eBooks and Webhelp with JavaScript popups activated). Just create a normal link to the topic.

This is basically a job for the programmer, not the help author (you may be both, of course). All the help output formats generated by Help & Manual are fully standard-compliant so you can use the standard procedures for linking to and calling popups.

HTML Help's plain-text popups:

•	When you export to HTML Help with native, plain-text popups Help & Manual stores the popup text topics in an internal text file in the HTML Help CHM file. By default this file is called CSHelp.txt, but you can change this file name in Configuration > Publishing Options > HTML Help > Popup Topics.

•	Plain text popup calls from your application must be made to this file within the CHM file using the standard popup syntax of the HTML Help API.

•	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.

Winhelp popups:

•	Winhelp Note that Windows Vista does not support Winhelp. If you want to be compatible with Vista you must transition to a different help format. popup topics are stored in the main Winhelp HLP file.

•	Popup calls from your application must be made directly to the HLP file using the standard popup syntax of the Winhelp API.

Tutorials for interfacing between your help and your application in the most common programming languages are available on the tutorials page at the EC Software website. A free set of tools for interfacing to help and context-sensitive help Borland Delphi and Borland C++ is also available at the website, on the Delphi resources page.

Output Format

Supported Popup Types

Where Supported

HTML Help (.CHM):

•	Plain-text popups integrated in the main help file. Context numbers are required for these popup topics!

•	Formatted JavaScript popups stored in the main help file.

Plain-text popups are supported both in the help text and as field-level popups in applications.

Formatted JavaScript popups can only be used in the help text. They are not supported for context-sensitive help.

Winhelp (.HLP):

•	Fully-formatted Winhelp popups stored in the main help file.

Winhelp popups are supported both in the help text and as field-level popups in applications.

Browser-based HTML
(.HTM):

•	Fully-formatted JavaScript popups integrated in the individual HTML files.

JavaScript popups can only be used in help topics. You cannot link to them from your application.

eBooks:

•	Fully-formatted popups with graphics, fonts, emphasis (bold, italics etc.) and hyperlinks (topic and Internet links).

Only available within eBooks. eBooks do not support context calls of any kind.

Adobe PDF and printed user manuals:

•	Popups are not supported. Popup links are automatically converted to plain text.

N/A

Word RTF:

•	Popups are not supported. Popup links are automatically converted to plain text.

N/A