第２８４章ＨＴＭＬヘルプを呼び出す

有る程度プログラムが作れるようになると自分のプログラムからヘルプを呼び出したくなるものです。今回は自分のプログラムからHTMLヘルプを呼び出します。その前準備としてHTMLヘルプの各部の名称を知る必要があります。

左の図はおなじみのメモ帳のヘルプです。

まず、ツールバーがあってその下に左右のペインがあります。左側のペインをナビゲーションペイン、右側のそれをトピックペインなどと呼びます。ナビゲーションペインには「目次」「キーワード」「検索」のタブがあります。時には「お気に入り」タブがつくこともあります。

さて、HTMLヘルプに関連したAPIを扱うにはhtmlhelp.hとhtmlhelp.libの２つのファイルが必要です。これは、HTMLヘルプワークショップをインストールしてあるディレクトリのなかのincludeとlibのディレクトリに納められています。 VC++6.0の「ツール」「オプション」「ディレクトリ」でこれらのディレクトリを追加するか、もしくはこの２つのファイルをVC++のinclude,libのディレクトリにコピーしておきます。
注:HTML HELP WorkshopはVC++6.0のおまけとしてついてきます。あるいは雑誌の CDなどでも配布されているようです。

今回、作るプログラムではHTMLヘルプを呼び出すので自分でHTMLヘルプを作っておくかもしくは何かのプログラムについてきたヘルプ(*.chm)を用意しておいてください。

HTMLヘルプのトピックペインを右クリックして「プロパティ」を選択するとそのトピックの元となるhtmlファイルの名前を知ることができます。

HTMLヘルプAPIでは関数は１つしか有りません。HtmlHelp関数です。


HWND HtmlHelp(
  HWND    hwndCaller,
  LPCSTR  pszFile,
  UINT    uCommand,
  DWORD   dwData) ;

hwndCallerは、HTMLヘルプを呼び出すウィンドウのハンドルです。

pszFileはHTMLファイルの名前です。呼び出し側のプログラムと異なるディレクトリに有る場合は、パス名も付けます。

uCommandは、約２０種類に及ぶコマンドの１つを指定します。具体的にはその都度解説します。

dwDataは、uCommandの種類により意味が異なります。

では、プログラムを見てみましょう。

このプログラムは筆者が作った「INSULIN.chm」を呼び出しています。ファイル名などは適宜変えてください。


// help01.rcの一部

/////////////////////////////////////////////////////////////////////////////
//
// Menu
//

MYMENU MENU DISCARDABLE 
BEGIN
    POPUP "ファイル(&F)"
    BEGIN
        MENUITEM "終了(&X)",                    IDM_END
    END
    POPUP "ヘルプ(&H)"
    BEGIN
        MENUITEM "目次(&C)",                    IDM_MOKUJI
        MENUITEM "キーワード(&I)",              IDM_INDEX
        MENUITEM "検索(&S)",                    IDM_SEARCH
    END
END

普通のメニューのリソース・スクリプトです。


//        help01.cpp

#ifndef STRICT
    #define STRICT
#endif
#include <windows.h>
#include <htmlhelp.h>
#include "resource.h"

LRESULT CALLBACK WndProc(HWND, UINT, WPARAM, LPARAM);
ATOM InitApp(HINSTANCE);
BOOL InitInstance(HINSTANCE, int);

char szClassName[] = "help01";    //ウィンドウクラス
DWORD dwCookie;

int WINAPI WinMain(HINSTANCE hCurInst, HINSTANCE hPrevInst,
                   LPSTR lpsCmdLine, int nCmdShow)
{
    MSG msg;
    
    if (!InitApp(hCurInst))
        return FALSE;
    if (!InitInstance(hCurInst, nCmdShow)) 
        return FALSE;
    HtmlHelp(NULL, NULL, HH_INITIALIZE, (DWORD)&dwCookie);
    while (GetMessage(&msg, NULL, 0, 0)) {
        if (!HtmlHelp(NULL, NULL, HH_PRETRANSLATEMESSAGE, (DWORD)&msg)) {
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }
    }
    return msg.wParam;
}

他のコマンドが実行される前に、HH_INITIALIZEコマンドでヘルプシステムを初期化します。


HH_INITIALIZE コマンド
pszFileは、必ずNULLにします。
dwDataには、DWORD型変数のポインタを指定します。(クッキー)

このコマンドが実行されるとHTMLヘルプが呼び出し側と同一のスレッドで実行されるようになります。

この時、呼び出し側のメッセージループ内でHH_PRETRANSLATEMESSAGEコマンドを実行してキーボードメッセージが正しく処理できるようにします。
(注)忘れてもそう重大なことは起こりません。


HH_PRETRANSLATEMESSAGE コマンド
pszFileはNULLにします。
dwDataには、MSG構造体へのポインタを指定します。


//ウィンドウ・クラスの登録

ATOM InitApp(HINSTANCE hInst)
{
    WNDCLASSEX wc;
    wc.cbSize = sizeof(WNDCLASSEX);
    wc.style = CS_HREDRAW | CS_VREDRAW;
    wc.lpfnWndProc = WndProc;    //プロシージャ名
    wc.cbClsExtra = 0;
    wc.cbWndExtra = 0;
    wc.hInstance = hInst;//インスタンス
    wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);
    wc.hCursor = LoadCursor(NULL, IDC_ARROW);
    wc.hbrBackground = (HBRUSH)GetStockObject(WHITE_BRUSH);
    wc.lpszMenuName = "MYMENU";    //メニュー名
    wc.lpszClassName = (LPCSTR)szClassName;
    wc.hIconSm = LoadIcon(NULL, IDI_APPLICATION);
    return (RegisterClassEx(&wc));
}

//ウィンドウの生成

BOOL InitInstance(HINSTANCE hInst, int nCmdShow)
{
    HWND hWnd;

    hWnd = CreateWindow(szClassName,
            "猫でもわかるヘルプ", //タイトルバーにこの名前が表示されます
            WS_OVERLAPPEDWINDOW, //ウィンドウの種類
            CW_USEDEFAULT,    //Ｘ座標
            CW_USEDEFAULT,    //Ｙ座標
            CW_USEDEFAULT,    //幅
            CW_USEDEFAULT,    //高さ
            NULL, //親ウィンドウのハンドル、親を作るときはNULL
            NULL, //メニューハンドル、クラスメニューを使うときはNULL
            hInst, //インスタンスハンドル
            NULL);
    if (!hWnd)
        return FALSE;
    ShowWindow(hWnd, nCmdShow);
    UpdateWindow(hWnd);
    return TRUE;
}

いつもと同じです。


//ウィンドウプロシージャ

LRESULT CALLBACK WndProc(HWND hWnd, UINT msg, WPARAM wp, LPARAM lp)
{
    int id;
    HH_FTS_QUERY q;

    switch (msg) {
        case WM_COMMAND:
            switch (LOWORD(wp)) {
                case IDM_END:
                    SendMessage(hWnd, WM_CLOSE, 0, 0);
                    break;
                case IDM_MOKUJI:
                    HtmlHelp(hWnd, "INSULIN.chm::oldex/q01.htm > MyWin01", HH_DISPLAY_TOC, NULL);
                    break;
                case IDM_INDEX:
                    HtmlHelp(hWnd, "INSULIN.chm", HH_DISPLAY_INDEX, (DWORD)"ガラス球");
                    break;
                case IDM_SEARCH:
                    //なぜか正しく動作しません
                    memset(&q, 0, sizeof(HH_FTS_QUERY));
                    q.cbStruct = sizeof(HH_FTS_QUERY);
                    q.fUniCodeStrings = FALSE;
                    q.pszSearchQuery = "AAA";
                    q.iProximity = HH_FTS_DEFAULT_PROXIMITY;
                    q.fStemmedSearch = FALSE;
                    q.fTitleOnly = FALSE;
                    q.fExecute = TRUE;
                    q.pszWindow = NULL;
                    HtmlHelp(hWnd, "INSULIN.chm", HH_DISPLAY_SEARCH, (DWORD)&q);
                    break;
            }
            break;
        case WM_CLOSE:
            id = MessageBox(hWnd,
                "終了してもよいですか",
                "終了確認",
                MB_YESNO | MB_ICONQUESTION);
            if (id == IDYES) {
                if (HtmlHelp(hWnd, "INSULIN.chm", HH_GET_WIN_HANDLE, (DWORD)"MyWin01")) 
                    HtmlHelp(NULL, NULL, HH_CLOSE_ALL, 0) ;
                else
                    MessageBox(hWnd, "閉じるべきヘルプはありません", "ヘルプ", MB_OK);
                DestroyWindow(hWnd);
            }
            break;
        case WM_DESTROY:
            HtmlHelp(NULL, NULL, HH_UNINITIALIZE, dwCookie);
            PostQuitMessage(0);
            break;
        default:
            return (DefWindowProc(hWnd, msg, wp, lp));
    }
    return 0;
}

親ウィンドウのプロシージャです。

メニューからIDM_MOKUJIが選択されたら

HtmlHelp(hWnd, "INSULIN.chm::oldex/q01.htm > MyWin01", HH_DISPLAY_TOC, NULL); を実行します。

ヘルプファイル名の所を注目してみてください。


HTMLHELPファイル名::元になるHTMLファイル>ウィンドウタイプ

この例の場合、元になるHTMLファイルはoldexディレクトリにあるq01.htmです。元になるファイルは、最初にも書いたようにトピックペインを右クリックして「プロパティ」を選択するとわかります。


HH_DISPLAY_TOCコマンド
pszFileは、ヘルプファイル名(*.chm)または、ヘルプファイル中のトピック
dwDataは、NULLもしくはヘルプファイル中のトピックへのポインタ

ヘルプにはHH_DISPLAY_TOPICと同じ動作をすると書いてありますが若干異なります。HH_DISPLAY_TOCは指定したトピックを表示して、なおかつナビゲーションペインは「目次」を開きます。HH_DISPLAY_TOPICは「目次」を開くとは限りません。

メニューからIDM_INDEXが選択されたら

HtmlHelp(hWnd, "INSULIN.chm", HH_DISPLAY_INDEX, (DWORD)"ガラス球");

を実行します。これは、ナビゲーションペインの「キーワード」の「ガラス球」を選択して、これに相当するトピックを表示します。


HH_DISPLAY_INDEXコマンド
pszFileは、*.chmファイルを指定します。または、ファイル中の特定のトピックを指定します。
dwDataは、インデックスファイル(*.hhk)中の特定のキーワードを指定します

HTMLヘルプを実際に作ったことのある方はわかると思いますが、キーワードはインデックスファイル(*.hhk)に格納されます。

IDM_SEARCHが選択されたら、

HtmlHelp(hWnd, "INSULIN.chm", HH_DISPLAY_SEARCH, (DWORD)&q);

を実行します。これは、ナビゲーションペインに「検索」タブを開いて HH_FTS_QUERY構造体で示された検索を実行します。このサンプルではなぜか、検索タブは開きますが検索が実行されません。


HH_DISPLAY_SEARCHコマンド
pszFileは、*.chmファイルまたは、ヘルプファイル中のトピックを指定します。
dwDataにはHH_FTS_QUERY構造体へのポインタを指定します。

FTSはFull Text Searchの略です(多分)。


typedef struct tagHH_FTS_QUERY
{
     int      cbStruct;          
     BOOL     fUniCodeStrings;        
     LPCTSTR  pszSearchQuery;
     LONG     iProximity;
     BOOL     fStemmedSearch;
     BOOL     fTitleOnly; 
     BOOL     fExecute;
     LPCTSTR  pszWindow;
       
} HH_FTS_QUERY;

cbStructはこの構造体のサイズを指定します。

fUniCodeStringsは、もしすべての文字列がUNICODEであればTRUEを指定します。

pszSearchQueryには、検索する文字列を指定します。

iProximityには、Word proximityを指定します。デフォルトはHH_FTS_DEFAULT_PROXIMITY(-1)です。

fStemmedSearchは、Stemmed SearchをするならTRUEを指定します

fTitleOnlyは、Title SearchをするならTRUEを指定します

fExecuteは、検索を始めるならTRUEにします。

pszWindowには、表示するウィンドウを指定します。

プログラム終了時にヘルプだけ残ってしまっては格好が悪いので

HtmlHelp(NULL, NULL, HH_CLOSE_ALL, 0) ;

でHTMLヘルプを終了します。


HH_CLOSE_ALLコマンド
hWndCallerはNULLにします
pszFileもNULLを指定します
dwDataは０にします

呼び出しプログラムから直接、間接に開かれたウィンドウをすべて閉じます。

この時HtmlHelp関数の戻り値は常にNULLとなります。ヘルプが開いていないときこのコマンドを実行しても良いのかもしれませんがここでは、HH_GET_WIN_HANDLEコマンドを実行して、NULLでないときにHH_CLOSE_ALL を実行するようにしてみました。


HH_GET_WIN_HANDLEコマンド

pszFileには、*.chmファイルを指定します。
dwDataには取得しようとしているウィンドウのタイプを指定します。

戻り値にウィンドウハンドルが来ます。ウィンドウがなければNULLとなります。 (注:HTMLファイルを作るときにウィンドウタイプを定義していなければ常にNULLとなります)

アプリケーションの終了時にHH_UNINITIALIZEコマンドを実行します。


HH_UNINITIALIZEコマンド
pszFileはNULLにします
dwDataは、HH_INITIALIZEコマンドで取得したクッキーを指定します。

今回は、簡単でしたかHTMLヘルプを自分で作ったことがない方にはちょっとわかりにくい点が有ったかもしれません。当HPをここまで読み進んでこられた人はHTMLヘルプを作るのは非常に簡単ですので、まだ作ったことのない方は是非作ってみてください。本来の使い方以外にHTMLヘルプというのはいろいろなことに応用できます。

[SDK第3部 Index] [総合Index] [Previous Chapter] [Next Chapter]

Update 22/Aug/2000 By Y.Kumei
当ホーム・ページの一部または全部を無断で複写、複製、転載あるいはコンピュータ等のファイルに保存することを禁じます。

第２８４章 ＨＴＭＬヘルプを呼び出す

HWND HtmlHelp( HWND hwndCaller, LPCSTR pszFile, UINT uCommand, DWORD dwData) ;

HH_INITIALIZE コマンド pszFileは、必ずNULLにします。 dwDataには、DWORD型変数のポインタを指定します。(クッキー)

HH_PRETRANSLATEMESSAGE コマンド pszFileはNULLにします。 dwDataには、MSG構造体へのポインタを指定します。

HTMLHELPファイル名::元になるHTMLファイル>ウィンドウタイプ

HH_DISPLAY_TOCコマンド pszFileは、ヘルプファイル名(*.chm)または、ヘルプファイル中のトピック dwDataは、NULLもしくはヘルプファイル中のトピックへのポインタ

HH_DISPLAY_INDEXコマンド pszFileは、*.chmファイルを指定します。または、ファイル中の特定のトピックを指定します。 dwDataは、インデックスファイル(*.hhk)中の特定のキーワードを指定します

HH_DISPLAY_SEARCHコマンド pszFileは、*.chmファイルまたは、ヘルプファイル中のトピックを指定します。 dwDataにはHH_FTS_QUERY構造体へのポインタを指定します。

typedef struct tagHH_FTS_QUERY { int cbStruct; BOOL fUniCodeStrings; LPCTSTR pszSearchQuery; LONG iProximity; BOOL fStemmedSearch; BOOL fTitleOnly; BOOL fExecute; LPCTSTR pszWindow; } HH_FTS_QUERY;

HH_CLOSE_ALLコマンド hWndCallerはNULLにします pszFileもNULLを指定します dwDataは０にします

HH_GET_WIN_HANDLEコマンド pszFileには、*.chmファイルを指定します。 dwDataには取得しようとしているウィンドウのタイプを指定します。

HH_UNINITIALIZEコマンド pszFileはNULLにします dwDataは、HH_INITIALIZEコマンドで取得したクッキーを指定します。

第２８４章ＨＴＭＬヘルプを呼び出す

HH_DISPLAY_INDEXコマンド pszFileは、.chmファイルを指定します。または、ファイル中の特定のトピックを指定します。 dwDataは、インデックスファイル(.hhk)中の特定のキーワードを指定します