3.5.4 Searching for Help with Keywords

An application can enable the user to search for help topics based on full or partial keywords. This method is similar to employing the Search dialog box in Windows Help to find useful topics. The following example searches for the keyword “Keyboard” and displays the corresponding topic, if found:

WinHelp(hwnd, "myhelp.hlp", HELP_KEY, "Keyboard");

If the topic is not found, Windows Help displays an error message. If more than one topic has the same keyword, Windows Help displays only the first topic.

An application can give the user more options in a search by specifying partial keywords. When a partial keyword is given, Windows Help usually displays the Search dialog box to allow the user to continue the search or return to the application. However, if there is an exact match and no other topic exists with the given keyword, Windows Help displays the topic. The following example opens the Search dialog box and selects the first keyword in the list starting with the letters Ke:

WinHelp(hwnd, "myhelp.hlp", HELP_PARTIALKEY, "Ke");

When the HELP_KEY and HELP_PARTIALKEY values are specified in the WinHelp function, Windows Help searches the K keyword table. This table contains keywords generated by using the letter K with \footnote statements in the topic file. An application can search alternative keyword tables by specifying the HELP_MULTIKEY value in the WinHelp function. In this case, the application must specify the footnote character and the full keyword in a MULTIKEYHELP structure, as follows:

HANDLE hmkh;
MULTIKEYHELP far *mkh;
char *szKeyword = "Frame";
WORD wSize;

wSize = sizeof(MULTIKEYHELP) + lstrlen(szKeyword);

hmkh = GlobalAlloc(GHND, (DWORD)wSize);
if (hmkh == NULL)
    break;
mkh = (MULTIKEYHELP far *) GlobalLock(hmkh);

mkh->mkSize    = wSize;
mkh->mkKeylist = 'L';
lstrcpy(mkh->szKeyphrase, szKeyword);

WinHelp(hwnd, "myhelp.hlp", HELP_MULTIKEY, (DWORD)mkh);

GlobalUnlock(hmkh);
GlobalFree(hmkh);

If the keyword is not found, Windows Help displays an error message. If more than one topic has the keyword, Windows Help displays only the first topic. (For a full description of the MULTIKEYHELP structure, see the Microsoft Programmer's Reference, Volume 3.)

Applications cannot use alternative keyword tables unless the MULTIKEY option is specified in the [OPTIONS] section of the project file.