處理線上說明
線上說明可以採用各種形式，從詳細的概念資訊到快速定義。 本主題包含下列各節。
關於說明
使用者易記應用程式的重要元素可在線上說明中立即取得。 Windows 提供函式和訊息，當與 Windows 說明應用程式搭配使用時，可讓您輕鬆地在應用程式中實作線上說明。 本概觀討論支援線上說明的 Windows 元素。 它描述如何使用這些元素來為使用者提供要求協助的方法，並說明如何使用 Windows 說明應用程式來顯示說明。
說明要求
大部分以 Windows 為基礎的應用程式會以各種形式提供線上說明資訊，範圍從說明應用程式功能的概念說明到快速定義應用程式使用者介面中個別元素的說明。 您可以使用函式和訊息來為使用者提供各種方法來要求存取這項資訊。 下列各節說明這些說明要求。
說明功能表
大部分的應用程式都會在主視窗中包含 [說明 ] 功能表，讓使用者存取說明資訊。 當使用者從 [ 說明 ] 功能表選取專案時，對應的視窗程式會收到可識別所選項目的 WM_COMMAND 訊息。 應用程式會藉由顯示適當的說明資訊來回應，例如說明主題清單、索引或應用程式的簡介。
鍵盤的說明
Windows 會在使用者按下 F1 鍵時通知應用程式，讓使用者能夠從鍵盤存取協助資訊。 系統會將 WM_HELP 訊息傳送至當使用者按下按鍵時具有鍵盤焦點的視窗。 例如，如果視窗是子視窗 (，則對話方塊中的控制項) ， DefWindowProc 函式會將訊息傳遞至父視窗。 如果按下 F1 時功能表為作用中，系統會將訊息傳送至與功能表相關聯的視窗。 應用程式會藉由顯示與具有焦點或作用中之視窗、控制項或功能表相關聯的說明資訊來回應。 例如，如果使用者在對話方塊中選取控制項，然後按 F1，應用程式會顯示該控制項的說明資訊。
WM_HELP的lParam參數是HELPINFO結構的指標，其中包含要求說明之專案的詳細資訊。 您可以使用這項資訊來判斷要顯示的說明主題。 HELPINFO結構也包含使用者按下按鍵時滑鼠游標的座標。 您可以使用這項資訊，根據滑鼠游標的位置提供協助。
滑鼠的說明
每當使用者按一下滑鼠右鍵或按一下視窗、控制項或功能表，按一下 [問題 (？) ] 按鈕時，Windows 即可讓使用者存取協助從滑鼠取得資訊。 應用程式會藉由顯示與指定視窗、控制項或功能表相關聯的說明資訊來回應。
當使用者按一下滑鼠右 鍵 時，系統會傳送WM_CONTEXTMENU訊息。 按一下的視窗會收到訊息。 如果視窗是子視窗，例如控制項， DefWindowProc 函式會將訊息傳遞至父視窗。 WM_CONTEXTMENU訊息會指定滑鼠游標的座標。 x 座標是 lParam 參數的低序字，而 y 座標則是高序字。 如果使用者按一下控制項， wParam 參數就是接收點選之控制項的控制碼。
當使用者按一下視窗標題列中出現的 [問題 (？) ] 按鈕之後，系統就會傳送 WM_HELP 訊息。 您可以在建立視窗時，在CreateWindowEx函式中指定WS_EX_CONTEXTHELP樣式，將 [問題] 按鈕新增至標題列。 WM_HELP的lParam參數是HELPINFO結構的指標，其中包含要求說明之專案的詳細資訊，包括使用者按一下滑鼠按鍵時滑鼠游標的座標。
建議只在對話方塊中使用 [問題] 按鈕。 在過去，應用程式已提供使用者存取對話方塊的說明資訊，方法是在對話方塊中提供 [說明 ] 按鈕。 不再建議使用這個方法。 請改用 [問題] 按鈕。
說明顯示和 Windows 說明
一旦應用程式收到協助要求，它應該會顯示適當的說明資訊。 因為 Windows 說明應用程式提供一致的使用者介面，所以建議應用程式使用 Windows 說明，而不是其他方法。 若要指示 Windows 說明顯示說明資訊，應用程式會使用 WinHelp 函式，並指定要顯示的詳細資訊，以及顯示資訊所在的視窗格式。 下列各節說明如何使用 WinHelp 來顯示說明資訊。
說明檔
若要檢視說明資訊，您必須在呼叫 WinHelp 函式時指定說明檔。 說明檔必須具有 Windows 說明 (.hlp) 檔案格式和一或多個主題。 每個主題都是不同的資訊單位，例如概念描述、一組指示、圖片、詞彙定義等等。 主題必須經過唯一識別，Windows 說明可以在每次要求時找出主題。 在內部，Windows 說明會使用主題識別碼來尋找主題，但應用程式最常使用內容識別碼 (唯一的整數值) 來指定要顯示的主題。 說明檔作者必須明確將內容識別碼對應至用來建置說明檔之專案檔 [MAP] 區段中的主題識別碼。
當您指定說明檔但未指定路徑時， WinHelp 會在說明目錄中或 PATH 環境變數所指定的目錄中尋找說明檔。 此外， WinHelp 還可以尋找名稱列在下列登錄位置的說明檔：
HKEY_LOCAL_MACHINE
Software
Microsoft
Windows
Help
若要利用登錄，您必須建立與說明檔同名的值名稱。 指派給該名稱的值必須是說明檔所在的目錄。
如果 WinHelp 找不到指定的說明檔，則會顯示一個對話方塊，允許使用者指定說明檔的位置。 由於 WinHelp 會將位置資訊儲存在登錄中，因此不會再次要求相同說明檔的位置。
如需如何撰寫和建置說明檔的詳細資訊，請參閱開發工具所提供的檔。
啟動 Windows 說明
下列範例會使用 WinHelp 函式來啟動 Windows 說明應用程式，並將說明檔開啟至其 Contents 主題。
HWND hwnd; // main window handle
BOOL bResult // for checking Boolean function result
bResult = WinHelp(hWnd, "WINNT.HLP", HELP_CONTENTS, 0L);
下一個範例會開啟使用者說明檔、搜尋與關鍵字字串相關聯的主題，然後顯示主題。
HWND hwnd; // main window handle
BOOL bResult // for checking Boolean function result
bResult = WinHelp(hWnd, "WINNT.HLP", HELP_KEY, (DWORD) "finding topics");
[說明主題] 對話方塊
您可以使用HELP_FINDER命令呼叫WinHelp函式，以顯示 [說明主題] 對話方塊。 [ 說明主題 ] 對話方塊可讓使用者藉由檢視主題的標題、與主題相關聯的關鍵字，或主題中找到的字詞和片語，讓使用者選取要顯示的主題。 當使用者從 [說明] 功能表選擇命令，例如 [說明主題] 時，應用程式通常會顯示此對話方塊。 如果使用者在應用程式中沒有特定視窗、控制項或功能表具有焦點或作用中時按下按鍵，應用程式也可能顯示此對話方塊。
在過去，應用程式已搭配WinHelp函式使用HELP_CONTENTS和HELP_INDEX命令來顯示 [說明] 檔案的 Contents 主題和關鍵字索引。 不再建議使用這些命令。 請改用 HELP_FINDER 命令。
資訊主題
您可以使用 HELP_CONTEXT 命令呼叫 WinHelp 函式，並指定主題的內容識別碼，以顯示特定主題。 應用程式通常會使用 HELP_CONTEXT 命令來回應包含概念性資訊或程式說明的主題，而不是特定控制項或功能表的相關資訊。 在這種情況下，使用者可能會在返回應用程式之前，繼續流覽尋找相關資訊的說明檔。
HELP_CONTEXT命令會叫用 Windows 說明的一般實例，讓使用者能夠在說明檔中尋找其他主題。 它通常會顯示主 [說明] 視窗，其中包含標題列、系統功能表、最小化和最大化按鈕、主功能表、選擇性導覽列、調整大小框線和工作區。 選取主題的文字會出現在工作區中，而且使用者可以使用主視窗中的常用連結或瀏覽按鈕來流覽說明檔。 Windows 說明的一般實例也可以用來在一或多個次要視窗中顯示說明，而不是主視窗。
快顯主題
您可以使用 HELP_WM_HELP 或 HELP_CONTEXTMENU 命令呼叫 WinHelp 函式，以顯示包含特定控制項或功能表資訊的快顯主題。 這些命令會在靠近對應控制項或功能表的快顯視窗中顯示主題。 若要讓使用者立即返回以在應用程式中工作，只要使用者按下按鍵或按一下滑鼠左鍵，快顯視窗就會終結。
當您處理控制項視窗 的WM_HELP 訊息時，您可以使用 HELP_WM_HELP 命令。 因為大部分控制項都會將 WM_HELP 訊息傳遞至 DefWindowProc 函式，所以對應的對話方塊程式 (或父視窗程式) 處理此訊息。 對話方塊程式必須傳遞控制項和內容識別碼組的陣列給WinHelp，以及以WM_HELP訊息傳遞之HELPINFO結構的hItemHandle成員中指定的控制項控制碼，而不是提供特定內容識別碼。 函式會決定產生 WM_HELP 訊息的控制項識別碼，並使用相符的內容識別碼來顯示適當的主題。
處理WM_CONTEXTMENU訊息時，您可以使用 HELP_CONTEXTMENU 命令。 由於大部分控制項會將 WM_CONTEXTMENU 訊息傳遞至 DefWindowProc 函式，因此對應的對話方塊程式 (或父視窗程式) 處理此訊息。 程式會指定控制項和內容識別碼組的陣列;它也會在呼叫WinHelp時指定wParam參數中的控制碼，讓函式可以從陣列挑選適當的內容識別碼，並顯示適當的主題。 不同于HELP_WM_HELP命令，HELP_CONTEXTMENU會先在功能表中顯示 What's This？ 命令。 如果使用者選擇命令， WinHelp 會顯示主題。 否則，會取消要求。
您也可以使用 HELP_CONTEXTPOPUP 命令並指定主題的內容識別碼來顯示快顯主題。 此命令類似于 HELP_CONTEXT 命令，但會叫用 HELP_WM_HELP 和 HELP_CONTEXTMENU 所使用的 Windows 說明快顯實例。 應用程式可以使用此命令來回應 WM_HELP 訊息，以顯示功能表和未在對話方塊中控制項之視窗的說明。 若要有效地使用此命令，應用程式應該將這些功能表和視窗的內容識別碼指派給這些功能表和視窗。
您可以將內容識別碼指派給應用程式中的任何視窗或功能表。 產生WM_HELP訊息時，系統會在WM_HELP訊息中傳遞至父視窗的 HELPINFO結構中包含內容識別碼。 然後，父視窗可以將內容識別碼傳遞至 WinHelp 以顯示所要求的說明主題。
您可以使用 SetWindowCoNtextHelpId 函式，將內容識別碼指派給視窗或控制項，以及 SetMenuCoNtextHelpId 函式，將內容識別碼指派給功能表。 您可以使用 GetWindowCoNtextHelpId 或 GetMenuCoNtextHelpId 函式來擷取視窗或功能表的內容識別碼。
關鍵字搜尋
您可以藉由將關鍵字指派給說明檔中的主題，讓使用者能夠尋找和檢視主題。 關鍵字只是與一或多個主題相關聯的字串。 Windows 說明會收集說明檔中的所有關鍵詞、將它們放在資料表中，並將其顯示在 [ 說明主題 ] 對話方塊的 [索引] 清單中。 當使用者選取關鍵字時，Windows 說明會顯示相關聯的說明主題，或者，如果有一個與 關鍵字相關聯的主題，則會顯示使用者可以選擇的主題清單。
在應用程式中，您可以使用 HELP_KEY、HELP_PARTIALKEY 或 HELP_MULTIKEY 命令搭配 WinHelp 函式，根據整個或部分關鍵字來搜尋及顯示說明主題。 您可以指定命令、關鍵字字串、說明檔，以及擁有者視窗的控制碼。 在所有情況下，如果找到單一相符專案， WinHelp 會顯示對應的主題。 如果找到多個相符專案，函式會顯示 [找到的主題] 對話方塊，而且使用者可以選擇要檢視的主題。 如果找不到相符專案， WinHelp 會針對 HELP_KEY 和 HELP_PARTIALKEY) 顯示索引清單 (，或針對 HELP_MULTIKEY) 顯示錯誤訊息 (。
您的應用程式可以在單一呼叫 WinHelp 中搜尋多個關鍵字，方法是使用分號分隔關鍵字。 (針對 Windows 版本 3 建立的說明檔不支援搜尋多個關鍵字。x) 如果指定的說明檔具有包含 ：Index 或 ：Link 命令的內容 (.cnt) 檔案，它也可以搜尋多個說明檔中的關鍵字。 使用 HELP_KEY 命令， WinHelp 會搜尋這些命令所指定所有檔案中的關鍵字。 使用 HELP_MULTIKEY 和 HELP_PARTIALKEY 命令，函式會搜尋 ：Link 命令所指定檔案以外的所有檔案。
根據預設，Windows 說明只會辨識說明來源檔案中 K 註腳字元所識別的關鍵字資料表。 您可以在說明來源檔案中新增 K 以外的註腳字元，並加上關鍵字定義，以引導 Windows 說明建立其他關鍵字資料表。 不過， (註腳字元 A 是保留的。) 建置說明檔時，您必須在專案檔的 [OPTIONS] 區段中使用 MULTIKEY 語句定義任何其他關鍵字資料表。
應用程式可以使用 HELP_SETINDEX 命令搭配 WinHelp 函式，指示 Windows 說明在其索引清單中顯示 K 以外的關鍵字資料表。 若要指示 Windows 說明在替代關鍵字資料表中搜尋關鍵字，應用程式可以使用 HELP_MULTIKEY 命令。 您會在 MULTIKEYHELP 結構中指定關鍵字和關鍵字資料表，而該結構會傳遞至 WinHelp。
當 WinHelp 顯示主題時，它會在主題的 「 > 」 註腳所指定的視窗、內容檔案中的 ：Base 命令所指定的視窗中，或在主視窗中顯示該主題。 如果您在呼叫 WinHelp時，主視窗已經開啟至不同的說明檔，則函式會在搜尋時隱藏主視窗。 在此情況下，取消 [ 找到的主題 ] 和 [ 說明主題 ] 對話方塊都會關閉主視窗。
次要說明視窗
Windows 說明應用程式的主視窗稱為主要視窗。 Windows 說明也可以在次要視窗中顯示說明主題。 不同于主要 [說明] 視窗，次要視窗不包含功能表列。 您可以在次要視窗中包含導覽列，並將按鈕新增至列。 您也可以選擇讓 Windows 說明自動調整次要視窗的高度，以容納主題。
您必須在說明專案檔的 [WINDOWS] 區段中定義次要視窗，並提供每個視窗的名稱和選擇性的初始大小和位置。 您可以指示 Windows 說明應用程式將角括弧 () > 附加至次要視窗的名稱，以在次要視窗中顯示主題。 產生的字串接著會傳遞至 WinHelp 函式。
應用程式可以藉由指定 HELPWININFO 結構的位址，以及呼叫 WinHelp中的 HELP_SETWINPOS 命令，來變更主要或次要視窗的大小和位置。 HELPWININFO 會指定視窗的名稱及其新的大小和位置。
訓練卡片說明
使用訓練卡片說明，應用程式可以顯示一連串的指示，引導使用者完成工作的步驟。 定型卡片通常包含一個文字，說明與 TCard 宏相關聯的特定步驟和按鈕，讓使用者能夠告訴應用程式下一步要做什麼。 定型卡片只能顯示在次要視窗中，且不得包含說明檔中其他主題的熱連結。
應用程式會呼叫 WinHelp 函式並指定HELP_TCARD命令與另一個命令，例如HELP_CONTEXT，以起始 Windows 說明的定型卡片實例。 接著，當使用者按一下定型卡片中的按鈕時，按一下指派給 TCard 宏的作用點，或關閉訓練卡片，Windows 說明會透過傳送 WM_TCARD 訊息來通知應用程式。 wParam參數會識別按鈕或使用者動作，而 lParam參數包含其他資料，其意義取決於wParam的值。
取消說明
Windows 說明要求應用程式明確取消說明，以便釋放用來追蹤應用程式及其說明檔的任何資源。 應用程式可以隨時呼叫 WinHelp 函式並指定 HELP_QUIT 命令來執行此動作。 請注意，這不適用於 Windows 說明的快顯實例。 應用程式不應該嘗試關閉快顯實例。
如果應用程式已對 WinHelp進行任何呼叫，則必須在關閉主視窗 (之前取消協助，以回應主視窗程式中WM_DESTROY訊息) 。 不論已開啟多少說明檔案，應用程式只需要呼叫 WinHelp 一次即可取消說明。 Windows 說明會繼續執行，直到所有應用程式或 DLL 都已取消說明為止。
若要關閉 Windows 說明的定型卡片實例，您必須在呼叫 WinHelp時同時指定HELP_TCARD和HELP_QUIT命令。 如果使用者先取消訓練卡片實例，應用程式就不需要取消 Windows 說明的定型卡片實例。 Windows 說明會在使用者透過將wParam參數設定為 IDCLOSE 的WM_TCARD訊息來取消定型卡片實例時通知應用程式。
使用說明
本節說明如何提供對話方塊的內容相關說明，以及如何設定次要說明視窗的外觀。
在對話方塊中提供說明
若要在對話方塊中提供內容相關的說明，您必須建立包含 一組 DWORD 值的陣列。 每個配對中的第一個值都是對話方塊中控制項的識別碼，而第二個值則是控制項說明主題的內容識別碼。 陣列應該包含對話方塊中每個控制項的一對識別碼。
對話方塊程式必須處理 WM_HELP 和 WM_CONTEXTMENU 訊息。 當使用者按下按鍵，並在使用者按一下滑鼠右鍵時WM_CONTEXTMENU時，對話方塊程式會收到WM_HELP。
WM_HELP的lParam參數包含HELPINFO結構的位址。 此結構的 hItemHandle 成員會識別使用者要求協助的控制項。 您必須將此控制碼傳遞至 WinHelp 函式，以及HELP_WM_HELP命令、說明檔的名稱，以及識別碼陣列的指標。 WinHelp函式會搜尋陣列中指定控制項的控制項識別碼，然後擷取對應的說明內容識別碼。 接下來，函式會將說明內容識別碼傳遞至 Windows 說明，它會尋找對應的主題，並將其顯示在快顯視窗中。 如果控制項的識別碼為 -1，則系統會搜尋下一個控制項為定位停駐點，然後使用其識別碼來尋找說明內容識別碼。 基於這個理由，請務必在資源檔中控制項之前放置靜態文字。
呼叫 WinHelp 函式時，處理 WM_CONTEXTMENU 類似于處理下列兩個例外 狀況WM_HELP ：
- 您可以從WM_CONTEXTMENU傳遞wParam參數，這是傳送訊息之控制項的控制碼。
- 您可以指定 HELP_CONTEXTMENU 命令，而不是 HELP_WM_HELP。
HELP_CONTEXTMENU命令會導致 Windows 說明在顯示說明主題之前顯示功能表。 功能表是系統定義的。 它可讓使用者顯示控制項的說明，或顯示 [ 說明主題 ] 對話方塊。
下列範例示範如何在對話方塊中實作內容相關的說明。
LRESULT CALLBACK EditDlgProc(HWND hwndDlg, UINT uMsg,
WPARAM wParam, LPARAM lParam)
{
// Create an array of control identifiers and context identifiers.
static DWORD aIds[ ] =
{
ID_SAVE, IDH_SAVE,
ID_DELETE, IDH_DELETE,
ID_COPY, IDH_COPY,
ID_PASTE, IDH_PASTE,
0,0
};
switch (uMsg)
{
case WM_HELP:
WinHelp(((LPHELPINFO)lParam)->hItemHandle, "helpfile.hlp",
HELP_WM_HELP, (DWORD)(LPSTR)aIds);
break;
case WM_CONTEXTMENU:
WinHelp((HWND)wParam, "helpfile.hlp", HELP_CONTEXTMENU,
(DWORD)(LPVOID)aIds);
break;
// Process other messages here.
}
return FALSE;
}
設定次要說明視窗的外觀
應用程式可以將HELP_SETWINPOS命令和 HELPWININFO 結構的位址傳遞至 WinHelp 函式，來設定次要說明視窗的大小、位置和顯示狀態。 HELPWININFO的成員會指定要變更的視窗名稱，以及視窗的新大小、位置和顯示狀態。
下列範例會設定名為 「wnd_menu」 的次要視窗外觀。 名稱必須在說明專案檔的 [WINDOWS] 區段中定義。
BOOL DoWindowSize(VOID)
{
HANDLE hhwi;
LPHELPWININFO lphwi;
WORD wSize;
char *szWndName = "wnd_menu";
size_t NameLength; // Does not include the terminating null character
HRESULT hr
BOOL retval;
hr = StringCbLengthA(szWndName, STRSAFE_MAX_CCH, &NameLength);
if (SUCCEEDED(hr))
{
// Add 1 to account for the name string's terminating null character.
NameLength++;
// The HELPWININFO structure contains a minimal TCHAR array of size [2]
// that is used for the window name. Since sizeof(HELPWININFO)
// includes those two TCHARS, they must be subtracted from the
// total when adding the actual string length to calculate the
// size of the structure.
wSize = sizeof(HELPWININFO) - 2 + NameLength;
}
else
// Something's amiss with the string.
return FALSE;
hhwi = GlobalAlloc(GHND, wSize);
lphwi = (LPHELPWININFO)GlobalLock(hhwi);
lphwi->wStructSize = wSize;
lphwi->x = 256; // horizontal position
lphwi->y = 256; // vertical position
lphwi->dx = 767; // width
lphwi->dy = 512; // height
lphwi->wMax = SW_SHOW; // show the window
// secondary window
hr = StringCbCopyA(lphwi->rgchMember, sizeof(lphwi->rgchMember), szWndName);
if (SUCCEEDED(hr))
{
WinHelp(hwnd, "myhelp.hlp", HELP_SETWINPOS, (DWORD)lphwi);
GlobalUnlock(hhwi);
GlobalFree(hhwi);
return TRUE;
}
else
// There was a problem copying the window name.
return FALSE;
}