HH_KEYWORD_LOOKUP

Performs a lookup of one or more keywords in the a compiled help (.chm) file.

Argument Description
hwndCaller Handle of parent or window or 0
pszFile HTML Help URL: Compiled help (.chm) file
uCommand HH_KEYWORD_LOOKUP
dwData Pointer to a THHAKLink record

Return value:
On success the return value is the handle of the helpwindow that was displayed. On failure the result is 0. Note that when the compiled help (.chm) file could not be found, 0 is returned but unlike most other commands HH_GET_LAST_ERROR does not return usefull information. Also, when a keyword lookup finds multiple result topics a "Topics found" dialog is shown allowing the user to choose one of the topics. When the user presses the cancel button in this dialog the command is considered "failed" and the result value will be 0.

Description:
The HH_KEYWORD_LOOKUP command performs a search on the primary keyword index of the specified compiled help (.chm) file. You use the THHAKLink record to specify the keywords (semicolon delimted list) to search for as well as the action to take when the search fails. See THHAKLink for more information.

Note that keyword searches are case sensitive and that the helpwindow must have been created before using this command (e.g. a topic has been shown). Well, at least that's what the HTML Help API reference says. Testing showed that this is not the case with HTML Help 1.21. If the window wasn't created then it is and searches are not case sensitive.

Example:
The following example performs a keyword search on the keywords HH_KEYWORD_LOOKUP and HH_AKLINK (pszKeywords) located in the JediHtmlHelp.chm (pszFile parameter) helpfile. It also specifies that if a keyword is found that is should be shown in the window type Main (pszWindow) which is defined in this helpfile. If anything goes wrong, which could be that the helpfile is not found or the keywords do not exist in the helpfile, then a messagebox is displayed with a title of Lookup failure (pszMsgTitle) and a text of Unable to find keywords (pszMsgText). Since the helpfile will be succesfullylocated and these keywords do appear in the helpfile HTML Help displays a dialog that allows the user to select the topic to display (multiple topics are found) and then displays that topic. If only one topic would have been found (try removing one of the keywords) then this dialog is skipped and the topic is displayed immediately.

procedure TMainForm.Button1Click(Sender: TObject);
var
  Link: THHAKLink;
begin
  FillChar(Link, SizeOf(Link), 0);
  Link.cbStruct := SizeOf(Link);
  Link.fReserved := False;
  Link.pszKeywords := PChar('HH_KEYWORD_LOOKUP;HH_AKLINK');
  Link.pszUrl := nil;
  Link.pszMsgText := PChar('Unable to find keywords');
  Link.pszMsgTitle := PChar('Lookup failure');
  Link.pszWindow := PChar('Main');
  Link.fIndexOnFail := False;
  HtmlHelp(0, PChar('JediHtmlHelp.chm'), HH_KEYWORD_LOOKUP, DWORD(@Link));
end;

If instead of displaying a message box in failure situations you would rather want to simply display the index tab then set fIndexOnFailure to True and pszMsgText and pszMsgTitle to nil. If you want to display a generic 'Not found' topic included in you helpfile then set the pszUrl member to point to this topic and pszMsgText and pszMsgTitle to nil.

See also:
THHAKLink
HH_ALINK_LOOKUP