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