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. However, your application may have commands or terms that correspond to terms in a similar, but different, application.

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 for the alternate keyword table and the full keyword in a MULTIKEYHELP structure. The MULTIKEYHELP structure specifies a keyword table and an associated keyword to be used by the Windows Help application.

The MULTIKEYHELP structure has the following form:

typedef struct tagMULTIKEYHELP {    /* mkh */
    WORD  mkSize;
    BYTE  mkKeyList;
    BYTE  szKeyPhrase[1];
} MULTIKEYHELP;

where

mkSize

Specifies the length, in bytes, of the MULTIKEYHELP structure, including the keyword (or phrase) and the associated keyword-table letter.

mkKeyList

Contains a single character that identifies the keyword table to be searched.

szKeyPhrase

Contains a null-terminated text string that specifies the keyword to be located in the alternate keyword table.

The following example illustrates a keyword search for the word “frame” in the alternate keyword table designated with the footnote character L:

HANDLE hqmk;
MULTIKEYHELP far *qmk;
char szKeyword[] = "frame";

case MULTIKEY:
    hqmk = GlobalAlloc(GHND, (sizeof(MULTIKEYHELP) + lstrlen(szKeyword)));
    if (hqmk == NULL)
        break;
    qmk = (MULTIKEYHELP far *) GlobalLock(hqmk);
    qmk -> mkSize = sizeof(MULTIKEYHELP) + strlen(szKeyword);
    qmk -> mkKeylist = 'L';
    lstrcpy(qmk->szKeyphrase, szKeyword);

    WinHelp(hWnd, szHelpFileName, HELP_MULTIKEY, (DWORD) (LPSTR) qmk);

    GlobalUnlock(hqmk);
    GlobalFree(hqmk);

    break;