Embedding FLIC animations in Windows Help files

One feature of the Microsoft Windows Help system (WinHelp) is that it can be extended with "plug-in" DLLs. The EGI animation engine provides the interface that WinHelp requires, and thus, the EGI player DLLs can function as WinHelp extensions. This paper describes how to embed standard or extended FLIC animations in a WinHelp .HLP file and how to invoke these animations. It covers the WinHelp engine for Windows 3.1, Windows 95 and Windows NT; the newer HTML-help system does not use WinHelp and it is not discussed in this paper.

Microsoft provides several help compilers and several help viewers. The basic distinction is between "16-bit" versions and "32-bit" versions of the tools.

The help viewer of Windows 3.1 can only use 16-bit DLLs and the help file must be compiled with the 16-bit compiler.
The 32-bit help viewer of Windows 95 can use 16-bit DLLs through thunking; however, thunking sometimes crashes WinHelp. A better approach is to use 16-bit DLLs in 16-bit help files and 32-bit DLLs in 32-bit help files.
Windows NT is stricter: a 32-bit help file cannot use a 16-bit DLL. Also, Windows NT starts the 16-bit viewer when a 16-bit program calls the WinHelp() API function. For that reason, 16-bit programs should use a 16-bit help file that calls 16-bit DLLs, and 32-bit programs should use a 32-bit help file that calls 32-bit DLLs.

To embed an animation in a Microsoft Windows help file, you must add an "embedded window" command in the text of the help file. There are several applications in which the help text can be written. This appendix assumes a text editor that uses or supports the "Rich Text Format" (RTF), because that is the format that the diverse help compilers from Microsoft support.

Adding the command to the text file

The syntax for an embedded window is:

{ewc eplay, EGI_Player, filename }	for 16-bit help files
{ewc eplay32, EGI_Player, filename }	for 32-bit help files

where filename is the name of the animation file, including the extension and excluding the directory path.

The ewc command is not the only command that creates an embedded window. The full set of commands is:

ewc
WinHelp aligns the window on the baseline of the type in exactly the same place in the paragraph where the command occurs. The embedded window is treated as a character, and paragraph formatting properties assigned to the paragraph also apply to the window. Text coming before or after the window does not wrap around the window
ewl
The left edge of the embedded window aligns with the left paragraph margin, and the paragraph text wraps to the right of the embedded window.
ewr
The right edge of the embedded window aligns with the right paragraph margin, and the paragraph text wraps to the left of the embedded window.

An alternative to these formatting commands is to add the embedded windows in cells of a table. The table formatting options support a more precise placement of embedded windows, especially if several animations should be vertically stacked.

Embedding the animation file

The second step is to compile the animation file(s) with the help file. The EGI player DLLs load and play the animations directly from the .HLP file. Internally, the .HLP file format functions as a kind of "archive file" that contains several subfiles for the topics and various tables. You can add your own files to a .HLP file by adding the filenames under the [baggage] section in the help project file (the .HPJ file). If you are using a product that automatically generates a project file, refer to the product manual to add files to the [baggage] section.

Example project file

[OPTIONS]
  TITLE = EGI Animation demo
  ERRORLOG = error.log
  COMPRESS = No
[BUILDTAGS]

[FILES]
  EGIDEMO.RTF

[BITMAPS]
[ALIAS]
[CONFIG]
  BrowseButtons()
[WINDOWS]
[BAGGAGE]
  fanni3.flc

References

Josef Becker's HelpMaster: A good resource for writing help files and extending Windows help. This site contains many add-ons, RTF file generators and articles.