HH_DISPLAY_TEXT_POPUP

Displays a text popup window.

Argument Description
hwndCaller Ignored
pszFile HTML Help URL: Compiled help (.chm) file [::/Name of text file containing the popup topics] or nil
uCommand HH_DISPLAY_TEXT_POPUP
dwData Pointer to a THHPopup record

Return value:
The return value is always a handle to the poup window that was shown. Unfortunately this popup might not display the text you intended. If HTML Help cannot display the specified text, for example because you specified a non-existent idString, then a generic popup is displayed with the text: "No help topic is associated with this item". There is no way to distinquish between success and failure. You can let HTML Help display it's authoring messages which do provide insight into what happened but this of course is not something you want for your end users.

Description:
The HH_DISPLAY_TEXT_POPUP command opens a popup window which displays the specified text. The text can be provided in three ways, by using an explicit string, a string resource or by specifying the ID of popup topic inside the helpfile. The examples below show all three possibilities. The pszFile parameter in combination with theTHHPopup record control which and how the topic is displayed. Only the fields specific to specifying the text to use are discussed below, for more information about formatting the topic see THHPopup. Note that the current version of HTML Help does not allow you to use an actual topic (a HTML file) as the source of a popup, only plain text. Through the THHPopup record you do have some control over how the text is displayed.

Examples:

Displaying a popup using a popup topic compiled into the helpfile.

The topic is contained in the cshelp.txt file which was compiled into the CHM by selecting the HTML Help API Information button, selecting the Text Pop-up's tab and then adding the file using the Text File... button. The cshelp.txt file contains the following text:

.TOPIC 1
This is a text string used for popup's

.TOPIC 2
All these text strings live inside the CHM

.TOPIC 3
In a file called cshelp.txt

To show this one of these topics, use the URL of this topic file (JediHtmlHelp.chm::/cshelp.txt) as the pszFile parameter and specify the topic id by using the THHPopup.idString member. Here is the code to display the topic with ID 1. To display any of the other topics change the Popup.idString assignment to either 2 or 3:

var
  Popup: THHPopup;
  Pt: TPoint;
begin
  FillChar(Popup, SizeOf(Popup), 0);
  Popup.cbStruct := SizeOf(Popup);
  Popup.hinst := 0;
  Popup.idString := 1;
  Popup.pszText := nil;
  GetCursorPos(Pt);
  Popup.pt := Pt;
  Popup.clrForeGround := TColorRef(-1);
  Popup.clrBackground := TColorRef(-1);
  Popup.rcMargins := Rect(-1, -1, -1, -1);
  Popup.pszFont := '';
  HtmlHelp(0, PChar('JediHtmlHelp.chm::/cshelp.txt'), HH_DISPLAY_TEXT_POPUP, DWORD(@Popup));
end;

Displaying a literal string

If you want to display a literal string you can use the same approach. However, this time the pszFile parameter of the HtmlHelp function must be set to nil, the THHPopup.idString field must be set to 0 and the THHPopup.pszText must be set to the string you want to display. Here's the full code to accomplish this:

var
  Popup: THHPopup;
  Pt: TPoint;
begin
  FillChar(Popup, SizeOf(Popup), 0);
  Popup.cbStruct := SizeOf(Popup);
  Popup.hinst := 0;
  Popup.idString := 0;
  Popup.pszText := PChar('This is a literal string');
  GetCursorPos(Pt);
  Popup.pt := Pt;
  Popup.clrForeGround := TColorRef(-1);
  Popup.clrBackground := TColorRef(-1);
  Popup.rcMargins := Rect(-1, -1, -1, -1);
  Popup.pszFont := '';
  HtmlHelp(0, nil, HH_DISPLAY_TEXT_POPUP, DWORD(@Popup));
end;

Displaying a string from a resource

Finally you can also use a string resource as the text for the popup. Again the pszFile parameter of the HtmlHelp function must be nil. This time the THHPopup.hinst field must be set to the instance handle of the module that contains the string resource. This will usually be your applications executable so you can use HInstance global variable (declared in sysinit.pas). The THHPopup.idString is used to specify the resource id and the THHPopup.pszText field must be nil. Here's the code to display the topic with resource id 50000:

var
  Popup: THHPopup;
  Pt: TPoint;
begin
  FillChar(Popup, SizeOf(Popup), 0);
  Popup.cbStruct := SizeOf(Popup);
  Popup.hinst := HInstance;
  Popup.idString := 50000;
  Popup.pszText := nil;
  GetCursorPos(Pt);
  Popup.pt := Pt;
  Popup.clrForeGround := TColorRef(-1);
  Popup.clrBackground := TColorRef(-1);
  Popup.rcMargins := Rect(-1, -1, -1, -1);
  Popup.pszFont := '';
  HtmlHelp(0, nil, HH_DISPLAY_TEXT_POPUP, DWORD(@Popup));
end;

See also:
HH_DISPLAY_TOPIC
HH_HELP_CONTEXT