ホーム

OFF-SOFT.net

OFF-SOFT.net

ウェブやソフトウェアに関するサポート&情報サイトです。サイト構築からソフトウェアの作成、利用まであなたの助けになるかも・・・・しれません。たぶん・・。

Qt (8)-2 QtAssistantで使うHELPファイルを作成する

公開日| 2009年06月26日 | コメントはまだありません。
概要 :
 Qtでは、WindowsでいうHTMLヘルプに変わるものとしてQtAssistantがあります。(先の記事でも記載しました。)
 このQtAssistantでは、独自ファイル(SQLite3フォーマット)のqchファイルとqhcファイルが必要となります。 (WindowsのHTMLヘルプでのchmファイルに相当します。)

 今回の記事では、そのQtAssistant用のHELPファイル(qchファイル,qhcファイル)の作成方法について記述します。

関連記事: Qt (8) QtAssistantのGUIの日本語化
関連記事: Qt (8)-3 Qtヘルプファイルを表示する

関連記事: http://doc.trolltech.com/4.5/qthelp.html

ここで使用したサンプルソースコード:

QtAssistant用のHELPファイルについて
QtAssistant用のHELPファイルは、以下の2つの種類のファイルがあります。

ファイル種別解説
.qchファイル Qt Compressed Helpファイル
つまりは、HTMLで記述されたドキュメント(画像などの付属情報も含めて)をSQLite3のデータベースファイル1つにまとめたものです。
Commpressedというが、実際には、zlibなどのような圧縮はされていないように思われます。 (あくまで、個人的な感想ですが、結構、大きなサイズになります。)

qhelpgenerator コマンドで作成します。

.qhcファイル Qt Help Collectionファイル
単純には、.qchファイルを更に、SQLite3のデータベースファイル1つにまとめたものです。
HTMLドキュメントの実体は、あくまで、.qchファイルにあります。このファイルは、.qchファイルの管理を行うもので、検索などにも利用されているようです。

qcollectiongenerator コマンドで作成します。


更に、上記の2種のファイルを作成するための元ファイルがそれぞれ存在します。

ファイル種別解説
.qhpファイル Qt Help Projectファイル
HTMLで記述されたドキュメント(画像などの付属情報も含めて)を1つのプロジェクトとして管理するためのXMLベースのファイルです。
Commpressedというが、実際には、zlibなどのような圧縮はされていないように思われます。 (あくまで、個人的な感想ですが、結構、大きなサイズになります。)

qhelpgenerator コマンドで.qchファイルへ変換します。

.qhcpファイル Qt Help Project Collectionファイル
複数(一つでも可)の.qchファイルを、1つのコレクションとしての管理をするためのXMLベースのファイルです。
ここでは、QtAssistantの画面の一部パーツのカスタマイズなども指定できます。

qcollectiongenerator コマンドで.qhcファイルへ変換します。


整理しておくと、以下のようになります。
  • HELPプロジェクトファイル(.qhp) -> .qch
  • HELPプロジェクトコレクションファイル(.qhcp) -> .qhc

ちょっと、複雑な感じです。
ただ、ここでは、以下のように捕らえておけば、なんとなく理解できるかもしれません。
  • プロジェクトをHTMLの管理
  • コレクションを全体の管理

WindowでのHTMLヘルプでは、以下のような構成だったと思います。
  • .hhcファイル(インデックス管理ファイル)
  • .hhkファイル(概要管理ファイル)
  • .hhpファイル(プロジェクト管理ファイル)

この2つのファイルから、.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>

ここでは、以下の4つのHTMLドキュメントが既にあるものとして記述しています。
  • index.html
  • doc1.html
  • doc2.html
  • doc3.html

1行目は、XML形式の宣言と文字コードの指定です。
2行目は、Qtヘルププロジェクトのバージョン指定です。 2009.6時点では、"1.0"が最新です。これを見ても、このQtヘルプが最近、導入されたことがわかります。

3行目以降の各タグについて、以下の表で簡単に解説します。

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)が既にあるものとして記述しています。

1行目は、XML形式の宣言と文字コードの指定です。
2行目は、Qtヘルプコレクションプロジェクトのバージョン指定です。 2009.6時点では、"1.0"が最新です。これを見ても、このQtヘルプが最近、導入されたことがわかります。

3行目以降の各タグについて、以下の表で簡単に解説します。

assistantタグで設定されている部分が、assistantの動作を指定したものです。
docFilesタグで設定されている部分が、まとめるHELPプロジェクトを指定したものです。

HELPプロジェクトコレクションファイル(.qhcp)
- assistantタグ
NoTAG名解説
(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ファイルを指定している場合は、 後者のコマンド1回で、.qchファイル、.qhcファイルを作成してくれます。
(つまり、前者の.qchファイル作成コマンドは、省略できるということです。)

今回のサンプルでは、以下の2つのファイルが作成されます。
  • 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に関する日本語の本が少ないですね。「入門書」は、さすがに、このページを読まれるくらいの方は不要だと思います。
やっぱり、本+ネット+試してみる!!の3本柱でやっていく以外にないように思います。


コメント

コメントをどうぞ







  • はてなブックマークへ追加する
  • Facebookでシェアする
  • twitter でつぶやく
  • Google Plusでシェアする
  • Pocketでシェアする
ページトップへ