さるもすなるぷろぐらむⅣ HTML-HELP
■自作のWindowsアプリにヘルプを付けたい
えっいまさら？の解説
＜内容＞
●はじめに
●ツールのダウンロード
●インストール
●HTMLヘルプの出来上がりイメージを考える
●ヘルプ本文：HTMLページの作成
●ヘルプ（.chm）のビルド
●ＨＴＭＬヘルプの呼び出し方
●はじめに
個人的に作成しているWindows用のツールにヘルプを付け足そうと思いたった。
そういえば、これまでヘルプなんか付けた事がなかったのでやり方を知りません。
あっちこっちに説明してくれているサイトを見つけて参考にしたが、結構な試行錯誤をしてしまった。
使用している環境の違いと、頭のデキが違う（劣る）からだとは思うが、・・・
サルでもヤレルレベルでメモを書いてみます。
●ツールのダウンロード
まずは、Microsoftが提供しているHTML Help Workshopというツールをダウンロードする。
（2019/01現在）↓からダウンロードできた。
https://www.microsoft.com/en-us/download/details.aspx?id=21138
「Download」をクリックすると、以下３つのファイルをチェックしてダウンロードするようになっている。
・htmlhelp.exe ツール本体
・HelpDocs.zip ツールのヘルプドキュメントだと思う。
・htmlhelpj.exe 日本語対応用の何かだと思う。（後で分かる。）
全部ダウンロードする。
●インストール
1)htmlhelp.exeを実行するとインストールが始まる。
特に選択できる項目はインストール先フォルダくらいで、あとは無かったように思う。
インストール先はデフォルトのまま「C:\Program Files (x86)\HTML Help Workshop」とした。
タスクバーのスタートメニューに「HTML Help Workshop」というフォルダができて、さらにその中に同じ名前のツールが入っています。
2)次に、HelpDocs.zipを解凍する。中身は以下の内容だった。
解凍してみた。
htmlhelp.libは、前のWorkshopのインストール先フォルダにlibサブフォルダがあって、そこに同じ名前で日付の古いlibがあったので置換えた。
その他はどうも「C:\Windows\Help」に入れるのが正しいらしい。
3)上記の英語版ヘルプを日本語にするのがhtmlhelp.exeらしい。
実行すると「C:\Windows\Help」に上書きされるようだ。
C:\Windowsにアクセス権を持たないユーザで実行すると何かメッセージが出るらしい。（未確認）
●HTMLヘルプの出来上がりイメージを考える
まずは、どんなヘルプを作るのかイメージせずに始めると何がなんだかさっぱり分からなくなる。
まずは、一般的なHTMLヘルプ（ウィンドウ）の構成を見てみましょう。
上のウィンドウの右側にタブが３つ（「目次」、「キーワード」、「検索」）見えるが、さらに右側に「お気に入り」というタブもある。
ウィンドウ右側はヘルプ本文が表示される欄、上部のアイコンボタンはそれぞれの機能。
「HTML Help Workshop」というツールは、このウィンドウの構成を設計するツール。（以降、単に「Workshop」と呼びます。）
もっと極端に言うと、左側のタブ構成を作るツールです。
右側ヘルプ本文はhtmlで、別口で作成する必要があります。
上部のアイコンボタンは、黙っていても付いてきます。（ちょっと言いすぎ。Workshopで設定します。）
とっととツールを使って、自作のヘルプっぽいウィンドウを出してみたいのは分かりますが、まずはヘルプ本文（ページ）を作るところから始めましょう。
●ヘルプ本文：HTMLページの作成
手近にあったOffice Wordをまずは使ってみました。
１）作成時の注意点
|
・Wordの［表示］で［Webレイアウト］を選択 ・あまり凝ったレイアイト／装飾を施したものを作ると、html化した際に崩れる。なので極シンプルに作成することを意識しましょう。 上記の例として ・最初に「ページ設定」基本のフォントと字ピッチ／改行ピッチを指定 ・「スタイル」で「標準」スタイルを設定 さるの場合、このスタイルのみを使うことにした。 ・文字の脚色は、サイズ変更／太字／イタリック／文字色／文字背景色くらい。 ・インデントや、列のある箇条書きイメージは罫線なしの表で。 なぜかというと、出来上がったhtml形式の文書をレイアウトを調整する際に、htmlのタグ<>を直にいじりたかったから。 でも結局、ものすごいスタイル設定のタグがゴチャゴチャーと入っていて、さっぱり理解不能だったので止めた。 ・表を作った場合、「表のプロパティ」－「表」タブで「サイズ」のところでサイズを指定しない。 ブラウザの表示幅に合わせて大きさが変わる表になります。 ・キャプチャイメージ＋図形の組合せで作る「図」は、グループ化して、「文字列の折り返し」は「行内」を選択。 そうすると「図」が１個の画像になるようです。 ・図形内の文字列（例えば「吹き出し」）や表内の文字列の改行位置はhtml化した場合に変化する。 後者は、勝手に行の高さが変わるだけで大した問題ではないが、前者は文字列末尾が見えなくなったりするので要注意。 |
いい感じにページを作成したら、一旦そのWordの標準の形式（.doc、.docx）で文書をセーブします。
３）html化
「ファイル」－「名前を付けて保存」（＋「参照」）でダイアログを開いて、「ファイルの種類」で 「Webページ(フィルター後)」を選択してセーブします。（ただの「Webページ」というファイルの種類もありましたが、 データが軽くなるような気がして「（フィルター後）」にしました。）
本文htmlと同じ名前のサブフォルダが作られます。「ファイルの種類」でただの「Webページ」サブフォルダで セーブすると、図以外にもごちゃごちゃ分からないものが入ります。
他のhtmlに、作成したページ上からリンクする場合は、この段階で行います。
Wordでhtmlファイルを開きます。
文字列範囲を選択して右クリックして表示されるメニューから「ハイパーリンク」を選択、あるいは 「挿入」－「ハイパーリンク」で表示されるダダイアログからリンク先htmlファイルを選択します。
なので、複数のhtmlでヘルプを作成する場合は同一フォルダに作成しましょう。
４）表示確認
作成されたhtmlファイルをブラウザで確認。
気に入らなかったら、htmlファイルを削除します。（付属のサブフォルダもこのとき消えます。そんな仕掛けがあるとは・・・）
ベース文書として保存したWord文書を再度開いて、修正後に２）～４）を繰り返します。
●ヘルプ（.chm）のビルド
いよいよWorkshopの出番です。
まずは複数ページ（階層）のあるヘルプを作ります。
このWorkshop環境で作成／使用するソースは、以下の構成になります。
| No. |
ソース |
用途 |
補足 |
| 1 |
Xxxxx.hhp |
Workshopのプロジェクトファイルです。 |
結局のところテキストです。 |
| 2 |
Xxxxx.hhc |
「目次」タブを構成するhtml形式のデータでした。 |
Workshop上で編集するのが少々煩わしい場合は、途中までできたものをテキストエディタで編集したほうが楽かもしれない。 |
| 3 |
Xxxxx.hhk |
「キーワード」タブを構成するhtml形式のデータでした。 |
|
| 4 |
*.html |
前項で作成したヘルプ本文。 |
参照している図とかは勝手に取り込まれるようです。 |
Workshopを起動すると、以下のメインウィンドウが表示されます。
既に途中まで作ったものがある場合は、［File］－［Open］メニューを選択して、 前に作成したプロジェクトファイル（Xxxxx.hhp）を開きます。
まずは、新しく作るところからだと、以下の手順です。
１）プロジェクトの新規作成
［File］－［New］メニューを選択します。
以下のダイアログから「Project」を選択して、［OK］ボタンをクリック。
こんな↓ダイアログが出ますが、新規に作るので、何もせずに［次へ］をクリック。
以下のようなダイアログが出ます。プロジェクトの作成先とプロジェクトファイル名を指定するものです。
［Browse...］ボタンをクリックして、htmlファイルが格納されているフォルダを選択し、
入力されたパスの後に、「\Xxxxx.hhp」と入力します。拡張子を忘れても付け足してくれなかったので、要注意です。
.hhpは付けておいた方がいいと思います。
次に、以下のようなダイアログが出ます。前に説明したヘルプのタブ構成や準備したヘルプ本文（html）を 指定するかどうかを指定するものです。ここで、指定しなくても、後で追加することも可能です。
もし、「目次」タブや「キーワード」タブを用意したい場合は、チェックしてください。
上記で、チェックした項目毎に以下のダイアログが順次出ます。
「Table of Contents」（目次）と「Index」（キーワード） ※の構成ファイルはここで名前を付けちゃいましょう。
プロジェクトファイルと同じ場所に作る場合は、パスは必要ないみたい。
プロジェクトファイルのとき同様、拡張子は省略しない方がよさそうです。
「HTML Files」は準備したhtmlを全部入れます。
※英語表現と日本語がぴったりこなくて、若干ここで混乱します。「Table ...って何のこと？」「Indexってなんだよ。」
指定しつつ［次へ］をクリックしていくと最後に以下のメッセージが出ます。
（「Existing Files」ダイアログで何もチェックしない場合はいっきにこのメッセージが出ます。）
［完了］をクリックすると、メインウィンドウが以下の感じになります。
「Project」タブには現時点の設定内容が表示されています。
初めて見る内容なので意味は分からなくてOK。次へいきましょう。
（でも、Workshop付属のヘルプを素直に読んだ方が、いいかと思います。さるは一切読まずに書いてます。）
２）プロジェクトの設定
プロジェクトの詳細を設定する必要があります。
メインウィンドウ上の「Project」タブを選択している状態で、左側のアイコンの一番上
をクリックします。下のようなダイアログが出ます。
「Title」は、いちおう付けておきましょう。
「Default file」は、何かのときに出すヘルプのページだと思います。念のため指定しておきます。
「Files」タブでは、「Compile file」：完成ヘルプ（.chm）の名前を指定します。（デフォルトで入っているかも。）
「Contents file」、「Index file」は、プロジェクトの新規作成時に指定した名前（.hhcと.hhk）が入っているはずです。
それぞれ、完成ヘルプに「目次」「キーワード」タブを設けたいのであれば指定してください。
※その他の項目は・・・気になる場合は、後でやってみてください。もしくはWorkshopのヘルプをしっかり読んで。
「Compiler」タブでは、「Create a binary Index」がデフォルトでチェック状態のはずです。 意味は分からないのでそのままにしました。
完成ヘルプに「検索」タブを付けたい場合は、「Compile full-text search information」をチェックしてください。
※その他の項目は・・・Workshopのヘルプをしっかり読んで。
「Merge Files」タブは、意味が想像できないので、何も触りませんでした。
３）ヘルプ本文ファイルの指定
メインウィンドウの「Project」タブの左側のアイコンの上から2番目をクリックすると以下のダイアログが出ます。
プロジェクトの新規作成時の「HTML files」を指定しなかった場合、あるいはヘルプ本文（html）が 増えたり減ったりしたときに、ここで指定します。
「Topic」と呼んでいるのは、ヘルプのページ（html)のことです。
４）ヘルプウィンドウの設定
メインウィンドウの「Project」タブの左側のアイコンの上から3番目をクリックすると以下のダイアログが出ます。
完成ヘルプウィンドウの構成を決める作業になります。
まずは、しょっぱなはメインのウィンドウ（タイプ）に名前をつけます。なんでもいいかと思います。
名前を入力して［OK］をクリックすると以下のダイアログが出ます。
「Window type」にはさっき入れた名前が入力済みです。
「Title bar text」は、完成ヘルプを表示したときのウィンドウタイトルになります。指定しましょう。
「Button」タブでは、完成ヘルプのアイコンバーに表示するアイコン＝使用できるようにする機能です。
複数のページのヘルプを作成するのであれば、「Hide/Show」（完成ヘルプのタブの表示／非表示）、 「Back」（「戻る」）、「Home」（「ホーム」）「Foward」（「進む」）、「Option」（「オプション」）、 「Print」（「印刷」）くらいかな・・・好きずきです。
「Position」タブでは、完成ヘルプを最初に表示するときの位置とサイズを指定できます。
通常、最初のときだけで、その次から表示するときは前に閉じたときの位置とサイズで出るような・・・ それを指定するのが「Save user defined．．．」かと思います。
初期位置／サイズは、［Autosizer］ボタンを押すと、ダミーのウィンドウが表示されるので、 そのウィンドウの位置とサイズを操作した後、ダミーウィンドウ上の［OK］ボタンでウィンドウを閉じると、 ダイアログ上の「Left」～「Height」が入力されます。
「Files」タブでは、「目次」、「キーワード」タブ用のデータファイルと「ホーム」アイコンクリック時のヘルプページを指定します。
「TOC」は「目次」タブの定義ファイルを指定します。「Table of contents」の略みたいです。
「Index」は「キーワード」タブの定義ファイルを指定します。
「Home」も指定しましょう。「Default」は「Options」－「General」で指定したのと同じかと思います。
「Navigation Pane」タブは、完成ヘルプのタブの有り無しを指定するところのようです。
「Window with navigation pane,...」をチェックすると、その下の指定項目が表示されます。
「Default tab」：完成ヘルプを開いたときに表示されるタブ。
「Search tab」：「検索」タブを設けるか否か。
「Favorite tab」：「お気に入り」タブを設けるか否か。
「Styles」「Extend Styles」タブは、・・・放置しました。
５）「目次」タブ内容の作成
完成ヘルプに「目次」タブを作らない場合はやらなくていいです。
メインウィンドウの左側から「Contents」タブを表示します。
※よく見る目次だと、大項目（マトメ）のページがあって、その中に小項目（詳細） ページが並んでいる構成になっていますよね。
「そうじゃない」：単に同じレベルの説明ページを並べようとしたのですが、
どうしても前の方に持ってきたページがマトメページとしてビルドされて、最悪の場合、 項目として出て来ないページなんかも。
思ったとおりに作られない場合は、素直にWorkshopのヘルプを参照してくださいね。
大項目（ブックのアイコン）エントリを作りたい場合は、「Contents」タブ左側のブックのアイコンをクリックしてください。
小項目（「？」アイコン）エントリを作りたい場合は、「？」アイコンをクリックします。出るダイアログは一緒です。
ダイアログの「Entry title」に表示するページのタイトルを入力します。
そのエントリをクリックしたときに表示するヘルプページのhtmlファイルを［Add］ボタンをクリックして表示されるダイアログから指定します。
［Advanced］タグの内容は良く分からなかったので、指定しませんでした。
「Table of Contents Entry」ダイアログでエントリを追加する場合、「Contents」タグ上で選択状態の登録済み項目の次に追加されます。
追加したエントリが思った順番になっていなかった場合は、「↑」「↓」アイコンでエントリの上下位置を変更できます。
大項目（ブックのアイコン）より下に大項目と同じ階層でエントリを追加するには、エントリを追加してから「←」アイコンをクリックします。
逆に、同じ階層で作った項目を前の項目の下位に変更する場合は、「→」アイコンをクリックします。
追加してしまったエントリを削除する場合は、「×」アイコンで消せます。
鉛筆マークのアイコンは、エントリ情報の修正です。
「Table of Contents」のプロパティの設定（「Contents」タブ左側の一番上のアイコンボタン）もあるようですが、特に指定しませんでした。
プログラム上からヘルプの表示内容をなんらか制御したい場合等に必要なんだと思います。
６）「キーワード」タブ内容の作成
完成ヘルプに「キーワード」タブを作らない場合はやらなくていいです。
メインウィンドウの左側から「Index」タブを表示します。
エントリを追加したい場合は、鍵マークのアイコンをクリックします。以下のダイログが出ます。
ダイアログの「Keyword」に表示するページのキーワードを入力します。
そのエントリをクリックしたときに表示するヘルプページのhtmlファイルを［Add］ボタンをクリックして表示されるダイアログから指定します。
［Advanced］タグの内容は良く分からなかったので、指定しませんでした。
「Table of Contents」のプロパティの設定（「Index」タブ左側の一番上のアイコンボタン）もあるようですが、特に指定しませんでした。
７）ビルドと動作確認
Workshopの［File］－［Compile］メニューを選択するか、アイコンバーの左から3番目のアイコンをクリックすると、 「Create a compiled file」ダイアログが表示されます。
ビルドしたいプロジェクト（.hhp）を選択して、［OK］ボタンをクリックします。
Logウィンドウが表示されて、その中でビルド結果が出るので、内容を確認してください。ERROR の文字がなければたぶん成功です。
Workshopの［View］－［Compiled Help File］メニューを選択するか、アイコンバーのメガネマークのアイコンをクリックすると、 「View compiled file」ダイアログが表示されます。
動作確認したいヘルプファイル（.chm）を選択して、［OK］ボタンをクリックします。
表示されたヘルプウィンドウが、意図したものになっているか確認してください。
●ＨＴＭＬヘルプの呼び出し方
以下、VC6.0で実施してみた結果で記述しています。
特に新たなSDKのインストールとかはせずに使えたけど、たまたまなのかは未確認。
■共通
1)ヘッダ（htmlhelp.h）をインクルード
HtmlHelp関数を呼び出すソースに#includeされているヘッダか、ソースコード自体に以下を追加する。
#include <htmlhelp.h>
2)ライブラリ(htmlhelp.lib）をプロジェクトに追加
2-1)［プロジェクト］－［設定］メニューを選択
2-2）［リンク］タブを選択し、「オブジェクト／ライブラリモジュール」欄に「htmlhelp.lib」を下を追加（区切りのスペースを忘れずに。）
2-3)プロジェクト設定にはDebugとReleaseがあるので両方に入っていることを確認します。
■VC++（MFC）
普通、F1キーを押すとヘルプが表示されることが多いので、それに倣います。
|
CXxxxx::OnCommand( UINT nID, LPARAM lParam) { : : if (nID == ID_HELP) { HWND hwndHelp = ::HtmlHelp(m_hWnd, "Xxxxx.chm", HH_DISPLAY_TOPIC, NULL); } : : } |
もっと、MFCアプリらしい記述もありそうだったが、動いたのでこれ以上追わなかった。
既にヘルプが出ているのにF1キーを押すと、ヘルプの内容がTopicページに戻るようです。（よしとします。）
HtmlHelp関数は、失敗するとNULLを返します。原因を調べる手立て（GetLastError()とか）は無い？
さるの場合も、最初にNULLが返されたので焦ったが、指定していた.chmファイルの名前の記述が間違っていたせいでした。
たいていはこの類で、エラーになってしまったら、まずはファイル名か、そのパス指定が正しいかを確認しましょう。
特に相対パス指定とかだと、さるの場合はボンミスしがちでした。
■VC++（普通のWin32アプリ）
こっちも、F1キーを押したら出るようにします。
最も安易な感じとしては、
|
LRESULT
CALLBACK WndProc( HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) { : switch(message) { case WM_KEYDOWN: if (wParam == VK_F1) { hwndHelp = HtmlHelp(hWnd, "Xxxxx.chm", HH_DISPLAY_TOPIC, NULL); } break; ： } ： } |
アクセラレータを使用して、メニューとF1キー併用とする場合
リソースファイルにアクセラレータを追加し、IDM_HELP（VK_F1）を追加する。
メニューにも例えば「概要説明」と追加してIDはIDM_HELPとする。
メッセージループでアクセラレータを有効にして、IDM_HELPをWM_COMMANDメッセージで受け取る。
|
//メイン int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow ) { ： ： hAccelTable = LoadAccelerators(hInstance, (LPCTSTR)IDC_XXXXX); // メイン メッセージ ループ: while(GetMessage(&msg, NULL, 0, 0)) { if(!TranslateAccelerator(msg.hwnd, hAccelTable, &msg)) { TranslateMessage(&msg); DispatchMessage(&msg); } } : : } // LRESULT CALLBACK WndProc( HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) { : switch(message) { case WM_COMMAND: switch (LOWORD(wParam)) { case IDM_HELP: hwndhelp = HtmlHelp(hDlg, "Xxxxx.chm", HH_DISPLAY_TOPIC, NULL); break; } break; ： ： } ： } |
以上、HTML-HELPの作り方でした。