HH_ALINK_LOOKUP
Performs a lookup of one or more alternate keywords in the a compiled help (.chm) file.
Argument | Description |
---|---|
hwndCaller | Handle of the owner window or 0 |
pszFile | HTML Help URL: Compiled help (.chm) file |
uCommand | HH_ALINK_LOOKUP |
dwData | Pointer to a THHAKLink structure |
Return value:
On success the return value is the handle of the helpwindow that was opened. On
failure the return value is 0. HH_GET_LAST_ERROR does not return any usefull information.
Description:
The HH_ALINK_LOOKUP command performs a search on the alternate keyword index of the
specified compiled help (.chm) file. You use the THHAKLink record to specify the alternate
keywords, also known as associative link names, (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 search on the alternate keywords HH_KEYWORD_LOOKUP
and HH_ALINK_LOOKUP (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.
Note that the help author has to insert associative links into topic file using the ALink Names tab of the Compiler Information dialog which you can bring up by choosing API Information from the Edit mene when a topic file is opened.. I have inserted only two associative links namely the ones used in the example below.
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_LOOKUP');
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_ALINK_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_KEYWORD_LOOKUP