Basic Working Procedures > Creating and Editing Topics

In this topic:

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 "context-sensitive popups".

The topics used for popups are all created in the Invisible Topics pane below the Table of Contents pane. How these topics are presented and handled in your output depends on the output format you are using and on your settings for that format, and also on how you link to the popup topics. A link from an application displays the popup in the application, a link from a topic in the help displays the popup in the help.

For more details on context-sensitive popups see Using Context-Sensitive Help and Context-Sensitive Help and Popups.

NEWS: Winhelp is no longer supported in Windows Vista!

Please note that support for the Winhelp format has been completely discontinued in Microsoft Windows Vista. Even if your applications run under Vista, any calls to Winhelp help will simply produce an error message. This also applies to dual-mode popups in HTML Help. We thus strongly recommend that you start transitioning to an alternative help format as soon as possible. See here for details

How to create a popup topic:

1.	Click in the Invisible Topics section (below the TOC) in the position where you want to insert your topic.

2.	Use any of the standard procedures for creating a new topic.

3.	New topics in the Invisible Topics section are created as popup topics by default. Check this by selecting the Topic Options tab of the new topic. The help window type should be set to Popup in the Help Window: field.

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.

Configuring and editing popup topics:

How popup topics are processed in your output depends on the output format you choose and the settings for the output format. These factors also influence what features are supported in your popup topics. Some output formats do not support popups at all, other formats only support plain ASCII text without any formatting.

Popups are only supported in HTML Help, 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., Browser-based Help and eBooks. They are ignored in all other formats. See below for full details on popup support in Help & Manual's output formats.

HTML Help:

•	Go to Project > Project Properties > HTML Help > Popup Topics to select the popup type used when you output HTML Help. The features of the various popup styles available are described in the dialog displayed.

If you choose Text-only popups remember that you can only use plain text. Formatted text (bold, italics, fonts), graphics, hyperlinks are all not supported and will be ignored in the output even if you use them. Tables and all their contents will be deleted.

You can create formatted popups in HTML Help with the Dual-mode Help and JavaScript Popups options. See below for details.

Winhelp:

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. supports formatted text, fonts, graphics and hyperlinks in popups. There are no configuration settings for popups in Winhelp – Winhelp popups are actually normal Winhelp topics without headers.

Browser-based Help :

•	Go to Project > Project Properties > Browser-based Help > Popup Topics to configure the settings for popups in Browser-based Help.

Help & Manual 4 introduces support for popups in Browser-based Help, generated with JavaScript code. These popups are highly-configurable and support formatted text, graphics, hyperlinks and even animations and videos. See Using JavaScript popups for full details.

eBooks:

Formatted popups with links and graphics are supported in eBooks but they are not configurable. Links to popup topics in your project will be displayed automatically as formatted popups in eBooks. They are sized automatically on the basis of their content and they use the background color set for the Popup help window type in Project > Project Properties > Help Windows.

Creating formatted popups in HTML Help:

The "native" popups supported by HTML Help are plain-text only – they do not support graphics or formatted text like the 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.. Help & Manual now provides two different solutions for this problem – Dual-mode Help and JavaScript popups:

Dual-mode HTML Help with a Winhelp popup file:

•	Go to Project > Project Properties > HTML Help > Popup Topics and select Create a dual-mode help file. You can also select the name of the .HLP file that will be generated for the popups here (the default is default_popup.hlp).

This solution outputs all your popup topics to a separate Winhelp .HLP file, which must be distributed together with your HTML Help .CHM file. Popup links in your topics will automatically link to this file. Context popup links from your application must make calls directly to the Winhelp .HLP file using the Winhelp API.

When this mode is selected all formatting, graphics etc. in your popup topics will be supported in the popups in your output, both in your help file and in context-sensitive popups called from your application.

Topic hyperlinks are not supported in dual-mode help – i.e. you cannot include links to topics in your main help file in your popups. (It is not possible to link topics between Winhelp and HTML Help files.)

You can also use formatted dual-mode popups as context popups called directly in your application. See Formatted context popups in HTML Help in the Advanced Procedures section.

JavaScript popups:

•	Go to Project > Project Properties > Browser-based Help > Popup Topics and select JavaScript Popups.

•	Click on to configure your popups. (JavaScript popups are highly customizable!)

For more details see Using JavaScript popups.

Controlling the width of popup topics:

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. This can make editing hard work and is yet another reason for using dual-mode or JavaScript popups.

Controlling popup width in Winhelp, dual-mode HTML Help 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., dual-mode HTML Help 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 generate the table automatically when new popup topics are created by defining a standard topic template for your popup topics. See Content templates for topics for details.

Linking to a popup topic from your help:

Any link within a project to a topic with the Popup window type will automatically be displayed as a popup in any of the output formats where popups are supported (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., HTML Help, eBooks and Browser-based Help with JavaScript popups activated). Just create a normal link to the topic. You no longer need to specify a popup link as was necessary in Help & Manual 3 and earlier.

Linking to a popup topic from your application:

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 Project > Project Properties > 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 .

Winhelp popups and dual-mode HTML Help 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.

•	When you create dual-mode popups in HTML Help the popup topics are stored in a separate .HLP file. This file is a standard Winhelp .HLP file.

•	In both cases popup calls from your application must be made directly to the .HLP file using the standard popup syntax of the Winhelp API (not the HTML Help 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.

Where popups are supported:

The support for popups depends on the output format you are using. The following table provides a quick reference to the kinds of popups available and where you can use them.

Output Format

Supported Popup Types

Where Supported

HTML Help (.CHM):

•	Plain-text popups integrated in the main help file.

•	Formatted dual-mode popups stored in an external Winhelp .HLP file.

•	Formatted JavaScript popups stored in the main help file.

Plain-text and formatted dual-mode Winhelp popups are supported both in the help text and as context-sensitive 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 context-sensitive 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.

Help & Manual 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 from applications.

Adobe PDF and printed user manuals:

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

Word RTF:

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