Windows Help displays embedded windows within topic windows. To Windows Help, an embedded window is simply a child window of that topic window. Users cannot minimize, maximize, or resize an embedded window. Embedded windows cannot be used as hot spots. However, you can include hot spots in an embedded window if they are controlled by the DLL, but users will not be able to use the keyboard equivalents to access the hot spots. That is because embedded windows cannot receive the input focus, which means they cannot process keystrokes. So, you should not place anything in an embedded window that requires keyboard input from users.
Windows Help positions the embedded window using the justification character (left, right, or character) specified by the author in the embedded window reference. The embedded window DLL is expected to display the information in the window and resize the window appropriately. Help expects the window size to remain fixed as long as the topic is displayed. The window element and DLL determine the size and content of the embedded window, and Help arranges the other elements of the topic around the embedded window.
Windows Help displays embedded windows only when necessary—while the topic containing the embedded window is being displayed. However, an embedded window may exist while it is not being displayed (if the user scrolls the topic past the embedded window, for example). Because it is part of a specific topic, an embedded window goes away when the user displays a different topic.
Windows Help creates embedded windows with window style WS_CHILD and a default size. It initializes the DLL for an embedded window before it displays the window.
When Windows Help creates the embedded window, it passes two strings in the WM_CREATE message. The lparam parameter points to a CREATESTRUCT structure, and the lpCreateParams field of the CREATESTRUCT structure points to a second structure defined as follows in the DLL.H header file:
typedef struct tagCreateInfo
{
short idMajVersion;
short idMinVersion;
LPSTR lpstrFileName;
LPSTR lpstrAuthorData;
HANDLE hfs;
DWORD coForeground;
DWORD coBackground;
} CREATEINFO;The fields in the structure are defined in the following table.
| Field | Use |
| idMajVersion, idMinVersion |
Identifies the version of Windows Help (and the version of the CREATESTRUCT structure used for embedded windows in that version of Windows Help). Currently, these fields are 0. If the idMinVersion field is a value other than 0, additional interfaces may be available to DLLs, but all the interfaces described in this chapter are still supported.
The DLL should always verify that the value in the idMajVersion and idMinVersion fields of the CREATESTRUCT structure are 0. If they are not, the DLL might not work with that version of Windows Help. |
| lpstrFileName | Points to the fully qualified name of the .HLP file containing the embedded window. This field will be NULL if the data is not available. If the DLL uses the string contained in this field, it should make a copy of the string. |
| lpstrAuthorData | Points to the author-data parameter in the ewl, ewc, or ewr reference from the source RTF file. This field will be NULL if the data is not available. If the DLL uses the string contained in this field, it should make a copy of the string. |
| hfs | Specifies a handle to the file system for the .HLP file. |
| CoForeground, CoBackground |
Specify the foreground and background colors of the main Windows Help window. If the embedded window uses the same colors as the main Windows Help window, the DLL can use the color values in these fields to set those colors in the embedded window. |
While a topic is being displayed, Windows Help creates embedded windows when it needs to lay them out and destroys them when they are no longer needed. The window can be created and destroyed, then created again if necessary, while Windows Help tries to lay out the embedded window object. If you load information, you might want to do so during WM_SHOWWINDOW processing so that you don’t have to load this information twice.
An embedded window may exist while it is not being displayed (for example, if the topic requires scrolling and the embedded window resides in the portion not currently displayed in the Help window). Do not set the window style to WS_VISIBLE or call the ShowWindow function during WM_CREATE processing. Windows Help displays the window when necessary.
As an embedded window DLL processes a WM_CREATE message, it is expected to set up any window styles the window uses and resize the window appropriately.
Windows Help positions the window using the justification character (left, right, or character) authored into the RTF file. Windows Help expects the window size to remain fixed during the window’s lifetime.
Because it is a child window of the main topic window, an embedded window does not need to destroy itself; it will be destoyed when the parent window is destroyed.