QtAssistant用のHELPファイルについて
QtAssistant用のHELPファイルは、以下の２つの種類のファイルがあります。
| ファイル種別 | 解説 |
| .qchファイル |
Qt Compressed Helpファイル
つまりは、HTMLで記述されたドキュメント(画像などの付属情報も含めて)をSQLite3のデータベースファイル１つにまとめたものです。
Commpressedというが、実際には、zlibなどのような圧縮はされていないように思われます。
(あくまで、個人的な感想ですが、結構、大きなサイズになります。)
qhelpgenerator コマンドで作成します。
|
| .qhcファイル |
Qt Help Collectionファイル
単純には、.qchファイルを更に、SQLite3のデータベースファイル１つにまとめたものです。
HTMLドキュメントの実体は、あくまで、.qchファイルにあります。このファイルは、.qchファイルの管理を行うもので、検索などにも利用されているようです。
qcollectiongenerator コマンドで作成します。
|
更に、上記の２種のファイルを作成するための元ファイルがそれぞれ存在します。
| ファイル種別 | 解説 |
| .qhpファイル |
Qt Help Projectファイル
HTMLで記述されたドキュメント(画像などの付属情報も含めて)を１つのプロジェクトとして管理するためのXMLベースのファイルです。
Commpressedというが、実際には、zlibなどのような圧縮はされていないように思われます。
(あくまで、個人的な感想ですが、結構、大きなサイズになります。)
qhelpgenerator コマンドで.qchファイルへ変換します。
|
| .qhcpファイル |
Qt Help Project Collectionファイル
複数(一つでも可)の.qchファイルを、１つのコレクションとしての管理をするためのXMLベースのファイルです。
ここでは、QtAssistantの画面の一部パーツのカスタマイズなども指定できます。
qcollectiongenerator コマンドで.qhcファイルへ変換します。
|
整理しておくと、以下のようになります。
- HELPプロジェクトファイル(.qhp) -> .qch
- HELPプロジェクトコレクションファイル(.qhcp) -> .qhc
ちょっと、複雑な感じです。
ただ、ここでは、以下のように捕らえておけば、なんとなく理解できるかもしれません。
- プロジェクトをHTMLの管理
- コレクションを全体の管理
WindowでのHTMLヘルプでは、以下のような構成だったと思います。
- .hhcファイル(インデックス管理ファイル)
- .hhkファイル(概要管理ファイル)
- .hhpファイル(プロジェクト管理ファイル)
この２つのファイルから、.chmファイル(HTMLヘルプファイル)を作成します。
iniファイルフォーマットとXMLフォーマットの違いや、書く場所は異なりますが、
基本的にHTMLヘルプファイル作成で必要な情報は、Qtヘルプでも必要と考えておけば良いと思います。
以降に、詳細な項目の説明がありますのでご参照ください。
Qtヘルプの元となる、HELPプロジェクトファイル(.qhp)、HELPプロジェクトコレクションファイル(.qhcp)の構成を
以降に説明し、簡単な、Qtヘルプファイルを作成してみましょう。
HELPプロジェクトファイル(.qhp)について
HELPプロジェクトファイル(.qhp)は、XML形式で、一般的にUTF8で記述します。
まずは、簡単なサンプルを見てみましょう。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
| <?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
<namespace>Sample_Help</namespace>
<virtualFolder>doc</virtualFolder>
<customFilter name="Sample Help 1.0">
<filterAttribute>Sample Help Application</filterAttribute>
<filterAttribute>1.0</filterAttribute>
</customFilter>
<filterSection>
<filterAttribute>Test Help Application</filterAttribute>
<filterAttribute>1.0</filterAttribute>
<toc>
<section title="Sample Help" ref="index.html">
<section title="Chapter 1" ref="doc1.html"/>
<section title="Chapter 2" ref="doc2.html"/>
<section title="Chapter 3" ref="doc3.html"/>
</section>
</toc>
<keywords>
<keyword name="keyword1" id="TestHelp::key1" ref="doc1.html"/>
<keyword name="keyword2" ref="doc2.html" />
<keyword id="TestHelp::key2" ref="doc3.html"/>
</keywords>
<files>
<file>index.html</file>
<file>doc1.html</file>
<file>doc2.html</file>
<file>doc3.html</file>
<file>img1.png</file>
<file>img2.png</file>
<file>img3.png</file>
</files>
</filterSection>
</QtHelpProject>
|
ここでは、以下の４つのHTMLドキュメントが既にあるものとして記述しています。
- index.html
- doc1.html
- doc2.html
- doc3.html
１行目は、XML形式の宣言と文字コードの指定です。
２行目は、Qtヘルププロジェクトのバージョン指定です。
2009.6時点では、"1.0"が最新です。これを見ても、このQtヘルプが最近、導入されたことがわかります。
３行目以降の各タグについて、以下の表で簡単に解説します。
HELPプロジェクトファイル(.qhp)
| TAG名 | 解説 |
| Namespace |
このプロジェクトの名前(このプロジェクトへアクセスするためのアドレスになります) |
| virtualFolder |
仮想ディレクトリ名(Namespaceに続くアドレスになります) |
| filterSection |
フィルター定義
デフォルトのフィルター定義です。
このフィルター定義には、以下の更に詳細なタグを設定できます。
- filterAttributeタグ:フィルター名、バージョンなどを定義します。
- tocタグ:コンテンツツリーを定義します。
ここでは、sectionタグを用いて、コンテンツタブに表示する情報を、階層化して表示順序を指定します。
- keywordsタグ:インデックスを定義します。
ここでは、keywordタグを用いて、インデックスタブに表示するキーワードを指定します。
- filesタグ:HTMLドキュメントで使用しているファイルを定義します。
ここでは、fileタグを用いて、HTMLドキュメントで使用している全てのファイルを定義します。
|
| customFilter |
カスタムフィルター定義
filterSectionタグと同様の定義でき、フィルターバーで選択することで、
ここに定義したものだけを表示するようにもできます。
|
ここで、注意すべき点は、
HTMLドキュメントで使用している全てのファイルを定義しなければならないことです。
関連している画像ファイルや、CSSファイル、jsファイルなども全て指定しなければならないことに注意しなければなりません。
WindowのHTML ヘルプワークショップでは、HTMLファイルさえ指定すれば、自動で関連ファイルを取り込んでくれたのですが、
Qtヘルプの各コマンドでは、取り込みません。
さすがに、この部分は、閉口感があります。（早く、改善して欲しいものです。）
続けて、HELPプロジェクトコレクションファイル(.qhcp)について解説したいと思います。
HELPプロジェクトコレクションファイル(.qhcp)について
HELPプロジェクトコレクションファイル(.qhcp)は、XML形式で、一般的にUTF8で記述します。
HELPプロジェクトの時と同じように、簡単なサンプルを見てみましょう。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
| <?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
<assistant>
<title>Sample Help Applicatio Help</title>
<startPage>qthelp://Sample_Help/doc/doc3.html</startPage>
<currentFilter>Sample Help 1.0</currentFilter>
<applicationIcon>star.png</applicationIcon>
<enableFilterFunctionality>true</enableFilterFunctionality>
<enableDocumentationManager>true</enableDocumentationManager>
<enableAddressBar visible="true">true</enableAddressBar>
<cacheDirectory>mycompany/myapplication</cacheDirectory>
<aboutMenuText>
<text>About Sample Help Application</text>
<text language="ja">サンプルヘルプアプリケーション...</text>
</aboutMenuText>
<aboutDialog>
<file>liecnce.txt</file>
<file language="ja">liecnce_ja.txt</file>
<icon>star.png</icon>
</aboutDialog>
</assistant>
<docFiles>
<generate>
<file>
<input>doc.qhp</input>
doc.qch
</file>
</generate>
<register>
<file>doc.qch</file>
</register>
</docFiles>
</QHelpCollectionProject>
|
ここでは、HELPプロジェクト(doc.qhp)が既にあるものとして記述しています。
１行目は、XML形式の宣言と文字コードの指定です。
２行目は、Qtヘルプコレクションプロジェクトのバージョン指定です。
2009.6時点では、"1.0"が最新です。これを見ても、このQtヘルプが最近、導入されたことがわかります。
３行目以降の各タグについて、以下の表で簡単に解説します。
assistantタグで設定されている部分が、assistantの動作を指定したものです。
docFilesタグで設定されている部分が、まとめるHELPプロジェクトを指定したものです。
HELPプロジェクトコレクションファイル(.qhcp)
- assistantタグ
| No | TAG名 | 解説 |
| (1) |
title |
タイトル名 |
| - |
startPage |
開始ページアドレス |
| - |
applicationIcon |
画面左上のアイコン画像 |
| (2) |
currentFilter |
カレントフィルター名 |
| (3) |
enableAddressBar |
アドレスバーを有効にする |
| (4) |
enableFilterFunctionality |
フィルターバーを有効にする |
| (5) |
enableDocumentationManager |
ドキュメントマネージャを有効にする |
| - |
cacheDirectory |
一時的なキャッシュファイルの置き場所 |
| (6) |
aboutMenuText |
ヘルプメニューのタイトル名
textタグを使う
|
| (7) |
aboutDialog |
Aboutダイアログのカスタマイズ
file,iconタグを使う
|
実際の画面への影響部分を各番号で、以下の画面に記載していますのでご参照ください。
HELPプロジェクトコレクションファイル(.qhcp)
- docFilesタグ
| TAG名 | 解説 |
| generate |
コレクションを作成する前にHELPプロジェクトファイル(.qhp) -> .qch ファイルを作成する場合に指定します。
fileタグ
inputタグ : 入力トファイル(.qhp ファイル)
outputタグ : 出力ファイル(.qch ファイル)
|
| register |
コレクションに登録するQt Compress Helpファイル(.qch)ファイルをfileタグで指定します。
|
ここまで、できたら、ようやくコマンドで作成です。
Qtヘルプファイルを作成する
Qtヘルプファイル(qchファイル,qhcファイル)は、先にも記述したようにコマンドで作成します。
以下は、
.qhpファイルから
.qchファイルを作成するときのコマンドの例です。
1
| > qhelpgenerator doc.qhp -o doc.qch
|
以下は、
.qhcpファイルから
.qhcファイルを作成するときのコマンドの例です。
1
| > qcollectiongenerator collection_doc.qhcp -o collection_doc.qhc
|
.qhcpファイルでgenerateで.qhpファイル、.qchファイルを指定している場合は、
後者のコマンド１回で、.qchファイル、.qhcファイルを作成してくれます。
(つまり、前者の.qchファイル作成コマンドは、省略できるということです。)
今回のサンプルでは、以下の２つのファイルが作成されます。
- doc.qch
- collection_doc.qhc
これで、Qtヘルプファイルができました。
早速、表示してみましょう。
コマンドラインから、以下のように入力します。
1
| > assistant -collectionFile collection_doc.qhc
|
※カレントディレクトリは、collection_doc.qhcがある場所です。
※Qtのインストール先のbinにpathが張れていないと動作しません。
もし、動作しないようであれば、以下のようにpathにQtのインストール先のbinを含めて、
再度、実行してみてください。
例）
1
| > set path=%path%;c:\qt\4.5\qt\bin
|
以下のような画面が表示されれば、正しく読めています。
まだ、導入されて間もないこともあってか、環境的に整っていないようなところもあります。
Windowsであれば、HTMLヘルプをリンクさせるのは、それほど難しいことではありませんから、
HTMLヘルプが良いような気もしますが、Qtでアプリケーションを作るということは、
基本的に、マルチプラットフォームを目指しているのだと思いますので、Qtヘルプに沿った
ヘルプファイルの作成を行っておく方が無難だと思います。
また、先にも記述しましたが、Qtヘルプファイルは、SQLite3で作成されていますので、
簡単に中をのぞくこともできます。
色々とテーブルの中をのぞいてみるのも理解を深めることになるかもしれません。
もし、アプリケーションを作成して、配布する際にQtヘルプも同時に配布する場合は、
.qchファイル、
.qhcファイルの一式を配布しなければならないことに注意してください。
また、Qtの環境がないシステムへは、QtAssistantを含めて実行環境も必要となります。
Windowsの環境であれば、少なくとも以下のファイルも同梱しないと動作しないでしょう。
- ASSISTANT.EXE
- QTHELP4.DLL
- QTWEBKIT4.DLL
- QTSQL4.DLL
- QTGUI4.DLL
- QTNETWORK4.DLL
- QTCORE4.DLL
すこし、量がありますね。
これからも、あまりにも小さなアプリケーションには、Qtの環境は、不向きかもしれませんね。
しかし、昨今の.netの環境一式をダウンロードさせるのに比べれば、かわいいものかもしれません。
また、このQtヘルプファイルは、QtAssistantを使わなくても、独自の画面に表示させることもできます。
次回の記事に、そのあたりを詳しく記述したいと思います。
もっと、Qt関連について詳しく知りたい方は、以下の本なども良いと思います。
Qtに関する日本語の本が少ないですね。「入門書」は、さすがに、このページを読まれるくらいの方は不要だと思います。
やっぱり、本＋ネット＋試してみる！！の３本柱でやっていく以外にないように思います。
概要 : 
がおすすめ！！ 
コメントをどうぞ