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