Copyright: 1994 R&R Engineering


Contents

This is a short help file which demonstrates the use of EWDLL for including 256 color bitmaps in Windows 3.1 help files.  Click on the pictures below for more information.

How it Works

Caveats

Legal Stuff

The Palette Limitation

Credits

If you have questions, comments, or suggestions regarding this embedded window DLL, the author can be contacted via Internet e-mail at  pacheco@harding.edu.  The latest version of EWDLL and its source code can be obtained via ftp from ftp.harding.edu in the directory /pub/pacheco.


 How it Works

OVERVIEW

The 256-color bitmap in this help topic is being displayed by the EWDLL embedded window DLL.  Embedded windows in a Windows help file allow a child window of the main help window to be placed under the control of a DLL. In this case, the DLL is being used to display a 256-color bitmap in the child window.

The bitmap itself is not actually stored in the help file, but should be located where it is accessible to EWDLL.  To display a bitmap, the name of the bitmap is passed in the "user data" field in one of the {ewx...} embedded window commands in the Windows help file, where x is either an "l" to indicate that the embedded window should be placed to the left of the paragraph, an "r" to indicate that it should be placed to the right of the paragraph, or a "c" to indicate that it should be treated as a character in the paragraph.  (For more information about using embedded window commands, consult the RTF file which created this help file, or get a copy of the Windows Help Authoring Guide available at ftp.cica.indiana.edu as hag.zip in the directory /pub/pc/win3/programr.)

TECHNICAL INFORMATION

The complete source code for EWDLL is distributed with this example help file.  The following paragraphs give a brief overview of what is going on.  This section will probably be of interest only to those who might be considering modifications to the code, but does provide some useful information to those who might be planning on simply using the DLL.

An embedded window DLL works by creating a window class which will be used by Windows Help to create child windows of the main help window. An embedded window command contained in a topic file then specifies the name of a DLL and a window class for an embedded window.  When the topic containing the embedded window is displayed, Windows Help creates a window of the specified class.  Typically, Windows Help only keeps the window while it is displayed.  If the embedded window is scrolled completely off the screen or another help topic is selected, the embedded window will be destroyed.  It will be recreated when Windows Help determines that it is necessary to display it once again.

In the topic file, the command which specifies the name of the embedded window DLL and the window class also allows a user-specified string to be passed to the window during WM_CREATE.  EWDLL uses this paramter to allow the help topic writer to specify the name of the bitmap which will be displayed.  (Consult the topic file for this example help file for an example of how this works.)

In addition to most normal messages, embedded windows receive three special messages.  One of these, EWM_QUERYSIZE, is a query from Windows Help to find the size of the embedded window.  Windows Help uses this information to place the embedded window in the help topic display. EWDLL simply returns the dimensions of the bitmap which will be displayed.  The EWM_ASKPALETTE message is also a query from Windows Help, this time asking for the palette which should be used for the embedded window.  EWDLL returns the color palette for the bitmap which will be displayed in the window.  Finally, the EWM_RENDER message is sent by Windows Help when the help topic containing the embedded window is copied to the clipboard or is printed.  When the help topic is copied to the clipboard, Windows Help expects the embedded window to return the handle of a null-terminated text string, and when the topic is printed, Windows Help expects the handle of a bitmap compatible with the printer device.  At present, EWDLL does not process the EWM_RENDER message.


 Caveats

PALETTE LIMITATIONS

When more than one embedded window is included in a single help topic, the palette requested by the first help topic is the one realized by Windows Help.  For 256-color bitmaps, this results in the first bitmap in the topic being displayed correctly, but all other bitmaps are displayed using the palette of the first bitmap.  Unless additional bitmaps have the same palette as the first bitmap, their colors will not look correct on a 256-color display device.  The Palette Limitation topic illustrates this problem visually.  With a 24-bit color display this should not be a problem.

PRINTING HELP TOPICS

When a request is made to print a help topic containing a 256-color bitmap, the bitmap is not printed.  This may be implemented in a future version of this DLL.

BMP FILE FORMAT

Presently, this DLL handles only uncompressed, Windows BMP files.  Using the same techniques, the DLL could be expanded to handle any type of graphics file format.  The initial goal was to get this up and running, and BMP were the simplest file format to work with, but additional file formats could be included in a future version of EWDLL.

WIN16 ONLY

Presently this DLL supports only 16-bit Windows 3.1.  It should not be difficult to modify the library to support 32-bit Windows NT as well, and this could be included in a future version of this library.

MODIFICATIONS

If you make a useful modification to EWDLL (such as support for printing or including additional graphics file formats), I would be happy to hear from you and to include your modifications, with proper credit, in a future version of EWDLL.  See the Contents page for information on how to contact the author.


 Legal Stuff

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


 The Palette Problem

This purpose of this topic is to illustrate the palette limitation discussed in the Caveats topic.  The problem is caused by the fact that Windows Help realizes the palette requested by the first embedded window in the topic.

Since the palette being used is that of the first embedded window, additional bitmaps appear with incorrect colors.  The bitmap shown here is the same bitmap shown in the Caveats topic, but now the bitmap is displayed incorrectly because its palette has not been realized.


 Credits

This library is primarily the work of Ron Pacheco, a professor of Mathematics & Computer Science at Harding University, Searcy, Ark.  Special thanks go to Harding student Brad Choate for his efforts in locating a working example of an embedded window DLL.