C++Builder 6 / Delphi 7 完美整合 CHM 說明檔 (HtmlHelp API)

CHM 優勢

• 單一壓縮檔案、全文搜尋、索引、收藏夾、HTML 格式易編輯。
• Windows 內建 hh.exe (HtmlHelp Viewer) 閱讀，無需額外安裝。

工具鏈

• Microsoft HTML Help Workshop (免費)：官方下載。
• 編譯 .hhp 專案檔 → 產生 .chm。
• 推薦教學：Html Help Sample in Delphi[卡夫].chm、跟我學HtmlHelp Workshop[馮惠軍].chm。

CHM 主題識別：數字 ID vs URL

• 每個 HTML 主題對應一個 **數字 Topic ID** (在 .hhp [MAP] 區段定義)。
• 呼叫 API 時傳入 DWORD_PTR 作為 dwData 參數，指定 Topic ID。

HtmlHelp API 宣告 (BCB/Delphi)

// BCB (包含 htmlhelp.h，連結 htmlhelp.lib)
#include 
#pragma comment(lib, "htmlhelp.lib")

// Delphi
function HtmlHelp(hwndCaller: HWND; pszFile: PChar; uCommand: UINT; dwData: DWORD_PTR): HWND; stdcall;
  external 'hhctrl.ocx' name 'HtmlHelpA';

常用命令

C++Builder 實作範例

// 表單建立時指定說明檔
void __fastcall TForm1::FormCreate(TObject *Sender) {
    Application->HelpFile = ExtractFilePath(Application->ExeName) + "MyApp.chm";
}

// 按鈕點擊打開特定主題 (Topic ID = 1001)
void __fastcall TForm1::btnHelpTopicClick(TObject *Sender) {
    HtmlHelp(Handle, Application->HelpFile.c_str(), HH_DISPLAY_TOPIC, 1001);
}

// 功能表項目 F1 說明
void __fastcall TForm1::mnuHelpContentsClick(TObject *Sender) {
    HtmlHelp(Handle, Application->HelpFile.c_str(), HH_DISPLAY_TOPIC, 0); // 目錄頁
}

// 表單關閉時關閉說明視窗
void __fastcall TForm1::FormClose(TObject *Sender, TCloseAction &Action) {
    HtmlHelp(Handle, Application->HelpFile.c_str(), HH_CLOSE_ALL, 0);
}

Delphi 實作範例

procedure TForm1.FormCreate(Sender: TObject);
begin
  Application.HelpFile := ExtractFilePath(Application.ExeName) + 'MyApp.chm';
end;

procedure TForm1.btnHelpTopicClick(Sender: TObject);
begin
  HtmlHelp(Handle, PChar(Application.HelpFile), HH_DISPLAY_TOPIC, 1001);
end;

context-sensitive help (CSH) 對照表

在 .hhp [MAP] 定義：

[MAP]
#define ID_HELP_MAIN        1000
#define ID_HELP_SETTINGS    1001
#define ID_HELP_ABOUT       1002
// 對應控件 HelpContext 屬性

設定控件 HelpContext = ID_HELP_SETTINGS，啟用 Application.OnHelp 事件處理 F1/Help 按鈕。

常見問題

• CHM 無法顯示內容 (僅目錄)：Windows 安全性更新 (ItssRestrictions) 封鎖網路/非受信路徑 CHM。解決：將 CHM 複製到本機、或修改註冊表 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTMLHelp\1.x\ItssRestrictions MaxAllowedZone = 1 (本機內部網路)。
• 中文亂碼：HTML 檔存為 UTF-8 (含 BOM) 或 Big5，.hhp 指定正確字符集。
• 64-bit 應用：確保載入 64-bit hhctrl.ocx (System32)，API 宣告用 DWORD_PTR / LPARAM。