Programming Room.
C++Builder Tips.
アプリケーション用ヘルプの作り方.
アプリケーションを作って公開するなら、よほど簡単なものでもない限りヘルプも用意すべき。ヘルプの作り方は一応C++Builderのヘルプや、Microsoft Help WorkShopのヘルプ（英文）にも載っているけど解りにくいので、説明してみようかなと。このページの内容を先頭から順に実施すれば、ヘルプが作れるはずです。
ここで説明するのはMicrosoft Help WorkShopで作成する、拡張子.hlp／.cntのヘルプファイルです。HTMLヘルプ（拡張子.chm）ではありません。
おしながき.
準備.
全体の流れ.
ヘルプファイル作成の全体的な手順は以下のとおり。Help WorkShopのヘルプで説明されているのと最初の方の順番が違いますが、この方が作りやすいと思うので。
Help WorkShopでヘルプの目次であるコンテンツファイル（.cnt）を作成
↓
Wordなどでヘルプの内容であるリッチテキスト（.rtf）のトピックファイルを作成
↓
Help WorkShopでプロジェクトファイル（.hpj）を作成し、コンパイル
↓
ヘルプファイル（.hlp）が得られる
ファイルの入出力という観点からまとめると、以下の表のとおり。
| ファイルの概要 | 入力ファイル | 作成に使うソフト | 出力ファイル | 変換に使うソフト |
| ヘルプファイル作成に関する設定の記録 | ヘルププロジェクトファイル（.hpj） | Help WorkStop （C++Builderに付属） |
なし | なし |
| ヘルプの目次に表示される項目 | ヘルプコンテンツファイル（.cnt） | 無変換（.cntをそのまま使用） | なし | |
| ヘルプの各ページの内容 | トピックファイル（.rtf） | Microsoft Wordなどリッチテキストが作れるなら何でもOK | ヘルプファイル（.hlp） | Help WorkStop（C++Builderに付属） |
表のバックが■色の項目のファイルを作成し、それをHelp WorkStopでコンパイルしてヘルプファイルを作成します。アプリケーションの配布の際に必要なファイルはバックが■色の項目のファイルです。
1つのヘルプファイルに対して、プロジェクトファイル（.hpj）とコンテンツファイル（.cnt）は1つずつだけ使用します。それに対してトピックファイル（.rtf）は複数に分割して作成することができます。
ヘルプファイルを開くと、ヘルプファイルのあるフォルダに.GIDという拡張子の隠しファイルが勝手に作られます。
実行ファイル.
C++Builderのインストールと同時にHelp WorkShopもインストールされますが、ショートカットは作成されません。自分でショートカットを作成した方が使いやすいと思います。
Help WorkShopは、標準では "C:\Program Files\Borland\CBuilder6\Help\Tools" にインストールされている、"hcw.exe" というファイルです。
コンテンツファイルの作成.
ファイルの作成.
コンテンツファイルにはヘルプの目次を書きます。最初に目次を作成した方が、全体の構成を考えながら作成できるので、この順で説明しています。
まずはHelp WorkShopを起動。メニューバーからFile→Newを選択し、「New」ダイアログからHelp Projectを選択。「Untitled1」というMDI子ウィンドウが開かれます。
デフォルトの設定.
最初にデフォルト値を設定します。MDI子ウィンドウの上部に2つ並んだDefault filenameとDefault titleを入力します。
Default filenameはヘルプファイルのファイル名を拡張子なしで入力してください。この項目は「トピックの検索」ダイアログからヘルプファイル本体を探すときに使用されるようです。
Default titleはヘルプファイルのタイトルを入力します。アプリケーション名くらいで十分です。この項目は「トピックの検索」ダイアログのタイトルに使われます。
目次の作成.
Add Above／Add Belowボタンで新しい項目を追加するためのダイアログが出ます。2つのボタンの違いは、リストの選択されている項目の上に追加するか下に追加するかだけ。最初は選択されている項目がないので、どちらも同じです。
上部4つのラジオボタンで追加する項目の種類を指定しますが、HeadingとTopicだけ使えば十分です。それぞれの意味と設定すべき内容は以下のとおり。
| 項目の種類 | 意味 | 設定すべき内容 | 内容の説明 | 設定の必要性 |
| Heading | 見出し | Title（他は設定不可能） | 目次に表示する文字列。 | 必須 |
| Topic | 実際に説明の 表示を行うページ |
Title | 目次に表示する文字列。 | 必須 |
| Topic ID | トピック（各ページ）を識別するための一意な文字列。 トピックごとに異なる文字列を指定する。 アプリケーションから特定のページを表示したい場合、「IDH_」から始まる名前にする必要がある。 |
必須 | ||
| Help file | トピックファイル名の指定。 | 任意 | ||
| Window | 表示するウィンドウタイプの指定。 | 任意 |
アプリケーションからヘルプ内の特定のページを表示させたい場合、Topic IDに注意する必要があります。この場合は「IDH_」から始まる名前にしなくてはなりません。「IDH_specific_page」みたいな感じで。このルールを守らない場合、「ヘルプが見つからない」旨の警告が表示され、目的のページは表示されません。(2009/05/15追記)
TopicのHelp fileとWindowはここで指定しなくてもいいので、空のままで。
Headingの場合、Move Right／Move Leftで階層を指定します。ツリービューのような感じで。Topicは作成直後は直前のHeadingの直下ですが、Heading同様にMove
Right／Move Leftで階層を指定できます。以下の例では1-2でMove Rightを、1-3でMove Leftを1回使って階層を指定しています。
これを繰り返して目次を作成します。
付記.
Help WorkShopには項目の順番を入れ替える手段が用意されていませんので、項目の順番を考えてからコンテンツファイルを作成する必要があります。
それでも、どうしても項目の順番を入れ替えたい場合は抜け道が。
コンテンツファイルはテキストなので、エディタで開いて編集すればOk。1項目／1行なので、行単位で切り貼りして順番を入れ替えればいいのです。イリーガルな編集方法なので、結果については自己責任で。
トピックファイルの作成.
ファイルの作成.
Wordなどリッチテキストファイルを作れるアプリケーションを使って、ヘルプファイルの本体であり、ウィンドウに表示される内容であるトピックファイルを作成します。
ただし、いくつか守らなければならないルールがあります。
- 1トピック／1ページ。各トピックは改ページで区切る。
- 目次であるコンテンツファイルの各項目と、ヘルプトピックの各項目を関連付けるために、特定の書式の注釈が必要。
- テーブルの枠には対応していない。
トピックの作成.
トピックとはヘルプ本文の、各ページのこと。
リッチテキストファイルのエディタを起動したら、トピックを記述できます。トピック本文は自由な書式で書けます。
注釈の記入.
ヘルプでは注釈を利用してユーザの目的とするトピックを検索します。検索の方法によって利用する注釈も違い、それぞれ固有の書式を必要とします。アプリケーション用のヘルプなら以下に示す注釈を記入しておけば十分だと思います。
| 種類 | 書式 | 説明 |
| # | # (TopicID) |
トピック（各ページ）を識別する。 Topic IDは識別のための一意な文字列。トピックごとに異なる文字列を指定する。 対応する目次の項目の目次の作成で指定したTopic IDと同じ文字列を指定。 同じTopic IDを持つトピックが複数あると、最初のものだけが検索される。 |
| $ | $ (Title) |
トピックの検索ダイアログの「キーワード」／「テキスト検索」タブでトピックのタイトルとして表示される文字列。 Titleはトピックのタイトルの文字列。 対応する目次の項目の目次の作成で指定したTitleと同じ文字列を指定。 |
| + | + (Browse code) |
ブラウズボタンで前後のトピックを検索するため使用する。 Browse codeは検索のための一意な文字列。 ブラウズボタンではBrowse codeをアスキーコード順で比較し、前後のページを検索する。 ブラウズボタンを付けないなら必要なし。+注釈のないトピックにはブラウズボタンでは到達不可能。 |
| K | K (keywork[,keyword...] [;keyword[,keyword...]]...) |
キーワード検索のためのキーワードを指定する。 Keywordはキーワードの文字列。複数のキーワードのORを指定するときは「;」で、AND（順番も影響）を指定するときは「,」で、キーワードを区切って複数記述。 トピックの検索ダイアログの「キーワード」タブで使用。Kマクロのジャンプ先としても使用。 K注釈がない場合はトピックの検索ダイアログに「キーワード」タブがなくなる。 |
私の使用している注釈はこんな感じ。CopyAllの最初のトピック「概要」の注釈です。
# introduce $ 概要 + 0101
ご覧のとおり、K注釈がないので「キーワード」タブが表示されません。
+注釈は、1番目のHeadingの「はじめに」を"01"、その中の1番目のHeading/Topicなのでもう1つ"01"を追加して、"0101"としています。なので「使用方法→ウィンドウ→手動モード→コピーオプション」は"03010504"という具合に、自分でBrowse code決定のルールを決めています。
ビットマップの埋め込み.
Wordを使っているのであれば、直接リッチテキストファイルにビットマップを埋め込んでもかまいません。
bmリンクを使用すると、ビットマップの配置の指定や、ヘルプの表示時にディスプレイの色深度に合わせて複数のビットマップから1つを自動的に選ばせることができます。最近は32ビットカラーが当たり前なので、色深度への適合は意味ないかもしれませんが。
bmリンクの書式は以下のとおり。より詳しくはHelp WorkShopのヘルプを参照。
{bmx filename[;filename...]}
xは次のいずれかの文字です。
| 文字 | 意味 |
| c | 文字として表示。bmリンクを使わずに直接埋め込んだのと同じ。 |
| l | 左側に表示。 |
| r | 右側に表示。 |
ディスプレイの色深度に合わせて複数のビットマップから1つを自動的に選ばせるには、";"で区切って複数のビットマップファイルを指定します。
以下に例を示します。
{bml sample_color4.bmp;sample_color16.bmp;sample_color1.bmp}
以上をトピックごとに繰り返して、トピックファイルを生成します。
プロジェクトファイルの作成.
ファイルの作成.
Help WorkShopで、プロジェクトを生成して設定を行います。メニューバーから「File→New」を選択し、「New」ダイアログからHelp Projectを選択。ファイル名入力のダイアログに変るので、ファイル名を入力して保存。この時入力したファイル名の拡張子を ".HLP" に変えたものが、生成されるヘルプファイルのファイル名です。ファイル名を決めると、初期値で作成されたプロジェクトファイルが、MDI子ウィンドウで開かれます。
トピックファイルの指定.
Filesボタンを押して表示される「Topic Files」ダイアログで、トピックファイルの作成で作成したファイルを追加します。複数あればすべて追加。
ウィンドウタイプの作成.
ヘルプでは255種類までのウィンドウタイプを作成し、その中から同時に9個までのウィンドウを表示できます。アプリケーション用ヘルプの場合は1つで十分な場合がほとんどでしょうが、プロジェクトの作成直後は1つもウィンドウタイプが作成されていないので、最低1つはウィンドウタイプを作ります。
Windowsボタンを押して表示される「Create a window」ダイアログで新しウィンドウタイプを作成します。「Create a window named:」は作成するウィンドウタイプの名前で、8バイト以下の任意の文字列です。最初はヘルプのメインウィンドウを作るので「main」とかでいいでしょう。「Based on this standard window:」はProcedureでOk。
ウィンドウタイプの設定.
「Window Properties」ダイアログに変るので、設定を行います。「Window Type:」に設定したいウィンドウタイプが選択されていることを確認してください。ウィンドウが複数ある場合は、それぞれ異なる設定にできるので、重要です。
ここで設定を行った方がよいと思われる項目は以下のとおり。
| タブ | 項目名 | 設定内容 |
| General | Title bar text: | ウィンドウのタイトルパーに表示するキャプション。 |
| Position | Adjust for user's screen resolution | ディスプレイの解像度に合わせて位置を調整するか否か。 |
| Auto-Sizer | 位置とサイズの調整を視覚的に行える。 | |
| Buttons | Browse | ボタンバーにブラウズボタンを追加するか否か。やっぱある方が便利。 |
| Find | ボタンバーにテキスト検索ボタンを追加するか否か。 |
オプションの設定.
Optionsボタンを押して表示される「Options」ダイアログで、その他の設定を行います。ここで設定を行った方がよいと思われる項目は以下のとおり。
| タブ | 項目名 | 設定内容 |
| Compression | - | 圧縮を行うか否か。ヘルプファイルサイズが小さくなるので、Maximumがお勧め。 圧縮するとコンパイルに数秒程度かかるが、表示は待たされることはない。 |
| Files | Contents file: | コンテンツファイルの指定。コンテンツファイルの作成で作成したファイルを指定。 |
コンパイルと配布.
コンパイル.
以上のファイルの作成・設定が終わったら、コンパイルしてヘルプファイルを作成します。プロジェクトファイルウィンドウのSave and CompileボタンまたはCompileスピードボタンを押すのだ!
「Compilation1」というMDI子ウィンドウにコンパイル結果が表示され、エラーがなければヘルプファイルが生成されます。
配布.
アプリケーション配布の際には、コンテンツファイルの作成で作成したコンテンツファイル（.cnt）と、ここでコンパイルして生成されたヘルプファイル（.hlp）を、アプリケーションに付属させます。
Copyright 2005-2016, yosshie.