シンプルなテキストビューアの例

この例では、カスタムアプリケーション内でQt Assistant をカスタマイズされたヘルプビューアとして使用する方法について説明します。この作業は2つの段階で行われます。まず、ドキュメントを作成し、Qt Assistant をカスタマイズします。次に、Qt Assistant を起動・制御する機能をアプリケーションに追加します。

「Simple Text Viewer」アプリケーションでは、ユーザーが既存のファイルを選択して表示することができます。このアプリケーションは独自のドキュメントを提供しており、メインウィンドウのメニューバーにある「ヘルプ」メニューから、またはアプリケーションのファイル検索ダイアログにある「ヘルプ」ボタンをクリックすることでアクセスできます。

このサンプルは4つのクラスで構成されています：

• Assistant Qt Assistant を起動する機能を提供します。
• MainWindow は、アプリケーションのメインウィンドウです。
• FindFileDialog ワイルドカード検索を使用してファイルを検索できるようにします。
• TextEdit HTMLドキュメント内で参照されている画像が正しく表示されるようにするリッチテキストブラウザを提供します。

ドキュメントの作成とカスタマイズQt Assistant

HTML ページ形式で実際のドキュメントを作成する方法については、この例の範囲外とします。 一般的に、HTML ページは手作業で作成するか、qdoc や Doxygen などのドキュメント作成ツールを用いて生成することができます。この例の目的上、HTML ファイルはすでに作成されているものと仮定します。したがって、残された作業は、Qt Assistant にヘルプ情報の構成方法と表示方法を指示することだけです。

ドキュメントの整理Qt Assistant

プレーンなHTMLファイルには、特定のトピックに関するテキストやドキュメントのみが含まれていますが、通常、複数のHTMLドキュメントが互いにどのように関連しているか、あるいはどの順序で読むべきかといった情報は含まれていません。 不足しているのは、目次と索引です。これらがあれば、ある情報を探すために大量のドキュメントを閲覧することなく、特定のヘルプコンテンツに素早くアクセスできます。

ドキュメントを整理し、Qt Assistant で利用できるようにするには、Qt Help プロジェクト (.qhp) ファイルを作成する必要があります。プロジェクトファイルの最初で最も重要な部分は、名前空間の定義です。 名前空間は一意である必要があり、Qt Assistant のページURLの先頭部分となります。さらに、ドキュメントセットの共通フォルダとして機能する仮想フォルダを設定する必要があります。これにより、異なる名前空間で識別される2つのドキュメントセット間で、HTMLファイルが相互参照できるようになります。これらのファイルは1つの大きな仮想フォルダ内に格納されるためです。 ただし、この例では利用可能なドキュメントセットは1つだけであるため、仮想フォルダの名前や機能は重要ではありません。

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
  <namespace>org.qt-project.examples.simpletextviewer</namespace>
  <virtualFolder>doc</virtualFolder>

次のステップは、フィルターセクションを定義することです。フィルターセクションには、目次、索引、およびすべてのドキュメントファイルの完全なリストが含まれており、任意の数のフィルター属性を割り当てることができます。 フィルタ属性は、自由に選択できる通常の文字列です。後でQt Assistant にて、ユーザーはこれらの属性を参照するカスタムフィルタを定義できます。フィルタセクションの属性がカスタムフィルタの属性と一致する場合、ドキュメントが表示されます。一致しない場合、Qt Assistant によってドキュメントは非表示になります。

繰り返しになりますが、ドキュメントセットは1つしか存在しないため、Qt Assistant のフィルタリング機能は必要なく、したがってフィルタ属性は省略できます。

それでは、目次を作成しましょう。 目次の項目は、section タグによって定義されます。このタグには、項目のタイトルや実際のページへのリンクを示す属性が含まれます。セクションタグは無限にネストできますが、実用上の理由から、3～4 レベル以上のネストは推奨されません。この例では、目次に以下のアウトラインを使用します：

• 簡易テキストビューア
  • ファイルの検索
    • ファイルダイアログ
    • ワイルドカード検索
    • 参照
  • ファイルを開く

ヘルププロジェクトファイルでは、アウトラインは次のように記述されます:

<filterSection>
  <toc>
    <section title="Simple Text Viewer" ref="index.html">
      <section title="Find File" ref="findfile.html">
        <section title="File Dialog" ref="filedialog.html"/>
        <section title="Wildcard Matching" ref="wildcardmatching.html"/>
        <section title="Browse" ref="browse.html"/>
      </section>
      <section title="Open File" ref="openfile.html"/>
    </section>
  </toc>

目次を定義した後、すべての索引キーワードを列挙します：

<keywords>
  <keyword name="Display" ref="index.html"/>
  <keyword name="Rich text" ref="index.html"/>
  <keyword name="Plain text" ref="index.html"/>
  <keyword name="Find" ref="findfile.html"/>
  <keyword name="File menu" ref="findfile.html"/>
  <keyword name="File name" ref="filedialog.html"/>
  <keyword name="File dialog" ref="filedialog.html"/>
  <keyword name="File globbing" ref="wildcardmatching.html"/>
  <keyword name="Wildcard matching" ref="wildcardmatching.html"/>
  <keyword name="Wildcard syntax" ref="wildcardmatching.html"/>
  <keyword name="Browse" ref="browse.html"/>
  <keyword name="Directory" ref="browse.html"/>
  <keyword name="Open" ref="openfile.html"/>
  <keyword name="Select" ref="openfile.html"/>
</keywords>

最後のステップとして、ドキュメントを構成するすべてのファイルを列挙する必要があります。ここで注意すべき重要な点は、画像ファイルはもちろん、スタイルシートが使用されている場合はそれらも含め、すべてのファイルを列挙しなければならないということです。

    <files>
      <file>browse.html</file>
      <file>filedialog.html</file>
      <file>findfile.html</file>
      <file>index.html</file>
      <file>intro.html</file>
      <file>openfile.html</file>
      <file>wildcardmatching.html</file>
      <file>images/browse.png</file>
      <file>images/fadedfilemenu.png</file>
      <file>images/filedialog.png</file>
      <file>images/handbook.png</file>
      <file>images/mainwindow.png</file>
      <file>images/open.png</file>
      <file>images/wildcard.png</file>
    </files>
  </filterSection>
</QtHelpProject>

これでヘルププロジェクトファイルは完成しました。Qt Assistant で生成されたドキュメントを確認したい場合は、このファイルからQt圧縮ヘルプファイルを生成し、Qt Assistant のデフォルトのヘルプコレクションに登録する必要があります。

qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch
assistant -register simpletextviewer.qch

ここでQt Assistant を起動すると、Qt のドキュメントの横に Simple Text Viewer のドキュメントが表示されます。これはテスト目的では問題ありませんが、最終版ではQt Assistant に Simple Text Viewer のドキュメントのみを掲載するようにします。

カスタマイズQt Assistant

Qt Assistant に Simple Text Viewer のドキュメントのみを表示させる最も簡単な方法は、独自のヘルプコレクションファイルを作成することです。コレクションファイルは、圧縮されたヘルプファイルと同様にバイナリ形式で保存され、ヘルプコレクションプロジェクトファイル (*.qhcp) から生成されます。コレクションファイルを利用することで、Qt Assistant の外観や、提供される一部の機能をカスタマイズすることができます。

まずは、ウィンドウのタイトルとアイコンを変更します。「Qt Assistant 」と表示される代わりに「Simple Text Viewer」と表示されるようになるため、ヘルプビューアが実際に当アプリケーションに属していることがユーザーにとってより明確になります。

<?xml version="1.0" encoding="UTF-8"?>
<QHelpCollectionProject version="1.0">
<assistant>
    <title>Simple Text Viewer</title>
    <applicationIcon>images/handbook.png</applicationIcon>
    <cacheDirectory>QtProject/SimpleTextViewer</cacheDirectory>

cacheDirectory タグは、ユーザーのデータディレクトリ内のサブディレクトリ（Qt Help コレクションファイルを参照）を指定し、そこに全文検索用のキャッシュファイルや設定ファイルが保存されます。

次に、新しい設定で初めて起動されたときにQt Assistant によって表示されるページを設定します。URL は、Qt Help プロジェクトファイルで定義された名前空間と仮想フォルダ、そして実際のページファイル名で構成されます。

<startPage>qthelp://org.qt-project.examples.simpletextviewer/doc/index.html</startPage>

次に、「About」メニュー項目の名前を「About Simple Text Viewer」に変更します。「About」ダイアログの内容も、説明文やアイコンのソースとなるファイルを指定することで変更できます。

<aboutMenuText>
    <text>About Simple Text Viewer</text>
</aboutMenuText>
<aboutDialog>
    <file>about.txt</file>
    <icon>images/icon.png</icon>
</aboutDialog>

Qt Assistant Qt Assistant には、設定ダイアログを通じてドキュメントを追加または削除する機能があります。この機能は、 を複数のアプリケーションの中心的なヘルプビューアとして使用する場合に役立ちますが、今回のケースでは、ユーザーがドキュメントを削除できないようにしたいと考えています。そこで、設定ダイアログの「ドキュメント」タブを非表示にします。

このような小規模なドキュメントセットではアドレスバーは実質的に不要であるため、こちらも無効にします。フィルタ属性のないフィルタセクションを1つだけ設定することで、Qt Assistant のフィルタ機能も無効にできます。これにより、フィルタページとフィルタツールバーは利用できなくなります。

    <enableDocumentationManager>false</enableDocumentationManager>
    <enableAddressBar>false</enableAddressBar>
    <enableFilterFunctionality>false</enableFilterFunctionality>
</assistant>

テストのために、すでに圧縮されたヘルプファイルを生成し、Qt Assistant のデフォルトのヘルプコレクションに登録済みです。以下のコード行を使用することで、同じ結果を得ることができます。唯一かつ重要な違いは、圧縮されたヘルプファイルをデフォルトのコレクションではなく、独自のコレクションファイルに登録する点です。

  <docFiles>
    <generate>
        <file>
            <input>simpletextviewer.qhp</input>
            <output>simpletextviewer.qch</output>
            </file>
        </generate>
    <register>
        <file>simpletextviewer.qch</file>
        </register>
    </docFiles>
</QHelpCollectionProject>

最後のステップとして、ヘルプコレクションプロジェクトファイルからバイナリコレクションファイルを生成する必要があります。これは、qhelpgenerator ツールを実行することで行われます。

qhelpgenerator simpletextviewer.qhcp -o simpletextviewer.qhc

Qt Assistant に対して行ったすべてのカスタマイズをテストするために、コマンドラインにコレクションファイル名を追加します:

assistant -collectionFile simpletextviewer.qhc

Assistant クラスによるQt Assistant の制御

まず、リモートアプリケーションからQt Assistant を起動・操作する方法について見ていきます。そのために、Assistant というクラスを作成します。

このクラスは、ドキュメントのページを表示するために使用されるパブリック関数と、Qt Assistant が正常に動作していることを確認するためのプライベートなヘルパー関数を1つ提供します。

Qt Assistant の起動は、startAssistant() 関数内で、単にQProcessを作成して起動するだけで行われます。プロセスがすでに実行中の場合、関数は直ちに返ります。そうでない場合は、プロセスをセットアップして起動する必要があります。

bool Assistant::startAssistant()
{
    if (!m_process) {
        m_process = std::make_unique<QProcess>();
        QObject::connect(m_process.get(), &QProcess::finished,
                         m_process.get(), [this](int exitCode, QProcess::ExitStatus status) {
            finished(exitCode, status);
        });
    }

    if (m_process->state() != QProcess::Running) {
        QString app = QLibraryInfo::path(QLibraryInfo::BinariesPath);
#ifndef Q_OS_DARWIN
        app += "/assistant"_L1;
#else
        app += "/Assistant.app/Contents/MacOS/Assistant"_L1;
#endif

        const QString collectionDirectory = documentationDirectory();
        if (collectionDirectory.isEmpty()) {
            showError(tr("The documentation directory cannot be found"));
            return false;
        }

        const QStringList args{"-collectionFile"_L1,
                               collectionDirectory + "/simpletextviewer.qhc"_L1,
                               "-enableRemoteControl"_L1};

        m_process->start(app, args);

        if (!m_process->waitForStarted(3000)) {
            showError(tr("Unable to launch Qt Assistant (%1): %2")
                      .arg(QDir::toNativeSeparators(app), m_process->errorString()));
            return false;
        }
    }
    return true;
}

プロセスを起動するには、Qt Assistant の実行ファイル名と、Qt Assistant をカスタマイズされたモードで実行するためのコマンドライン引数が必要です。実行ファイル名はプラットフォームによって異なるため少し扱いが難しいですが、幸いなことに macOS でのみ異なります。

Qt Assistant Qt Assistant を起動する際、 コマンドライン引数を使用することで、表示されるドキュメントを変更できます。オプションを指定せずに起動した場合、 はデフォルトのドキュメントセットを表示します。Qt がインストールされている場合、 に設定されたデフォルトのドキュメントセットには、Qt リファレンスドキュメントに加え、 や など、Qt に付属するツールが含まれています。-collectionFile Qt Assistant Qt Designer qmake

この例では、プロセスへのコマンドラインオプションとしてアプリケーション固有のコレクションファイルを指定することで、デフォルトのドキュメントセットを独自のドキュメントに置き換えます。

最後の引数として `-enableRemoteControl` を追加します。これにより、Qt Assistant は `stdin ` チャンネルをリッスンし、ドキュメント内の特定のページを表示するといったコマンドを受け取ります。その後、プロセスを開始し、実際に実行されるまで待機します。何らかの理由で `Qt Assistant ` を起動できない場合、startAssistant() は `false` を返します。

showDocumentation() の実装は、これで単純明快です。まず、Qt Assistant が実行中であることを確認し、次にプロセスのstdin チャネルを介してpage を表示するリクエストを送信します。ここで非常に重要なのは、チャネルをフラッシュするために、コマンドの末尾に行末トークンを付けることです。

void Assistant::showDocumentation(const QString &page)
{
    if (!startAssistant())
        return;

    QByteArray ba("SetSource ");
    ba.append("qthelp://org.qt-project.examples.simpletextviewer/doc/");

    m_process->write(ba + page.toLocal8Bit() + '\n');
}

最後に、アプリケーションがシャットダウンされる際に、Qt Assistant が適切に終了するようにします。QProcessのデストラクタはプロセスを強制終了させるため、アプリケーション側でユーザー設定の保存などを行うことができません。その結果、設定ファイルが破損してしまう可能性があります。これを回避するために、Assistant クラスのデストラクタ内で、Qt Assistant に終了を指示します。

Assistant::~Assistant()
{
    if (m_process && m_process->state() == QProcess::Running) {
        QObject::disconnect(m_process.get(), &QProcess::finished, nullptr, nullptr);
        m_process->terminate();
        m_process->waitForFinished(3000);
    }
}

MainWindow クラス

MainWindow クラスは、アプリケーションのメインウィンドウに2つのメニューを提供します。「ファイル」メニューでは、ユーザーが既存のファイルを開いて表示することができ、「ヘルプ」メニューでは、アプリケーションやQtに関する情報を提供するとともに、Qt Assistant を開いてアプリケーションのドキュメントを表示することができます。

ヘルプ機能を利用できるようにするため、MainWindow のコンストラクタ内でAssistant オブジェクトを初期化します。

MainWindow::MainWindow()
    : textViewer(new TextEdit)
    , assistant(new Assistant)
{
    ...
}

次に、Simple Text Viewer アプリケーションのすべてのアクションを作成します。特に注目すべきは、F1ショートカットまたは [ヘルプ] > [ヘルプの目次] メニュー項目からアクセスできる `assistantAct ` アクションです。このアクションは、MainWindow クラスの `showDocumentation() ` スロットに接続されています。

void MainWindow::createActions()
{
    assistantAct = new QAction(tr("Help Contents"), this);
    assistantAct->setShortcut(QKeySequence::HelpContents);
    connect(assistantAct, &QAction::triggered, this, &MainWindow::showDocumentation);
    ...
}

showDocumentation() スロット内では、ドキュメントのホームページのURLを引数として、Assistant クラスのshowDocumentation() 関数を呼び出します。

void MainWindow::showDocumentation()
{
    assistant->showDocumentation("index.html");
}

最後に、アプリケーションを終了する前に、アプリケーションのQt Assistant インスタンスが適切に閉じられるように、protected な QWidget::closeEvent() イベントハンドラを再実装する必要があります。

void MainWindow::closeEvent(QCloseEvent *)
{
    delete assistant;
}

FindFileDialog クラス

Simple Text Viewer アプリケーションには、ワイルドカード検索を使用してファイルを検索できるファイル選択ダイアログが用意されています。検索は指定されたディレクトリ内で行われ、ユーザーは既存のファイルシステムを参照して該当するディレクトリを見つけるオプションも利用できます。

コンストラクタでは、引数として渡されたAssistant およびQTextEdit オブジェクトへの参照を保存します。Assistant オブジェクトは、後ほど説明するように、FindFileDialog のhelp() スロットで使用されます。一方、QTextEditは、選択されたファイルを表示するために、ダイアログのopenFile() スロットで使用されます。

FindFileDialog::FindFileDialog(TextEdit *editor, Assistant *assistant)
    : QDialog(editor)
    , currentEditor(editor)
    , currentAssistant(assistant)
{
    ...
}

FindFileDialog クラスで注目すべき最も重要なメンバーは、プライベートなhelp() スロットです。このスロットはダイアログの「ヘルプ」ボタンに接続されており、Assistant のshowDocumentation() 関数を呼び出すことで、現在のQt Assistant インスタンスをフォアグラウンドに表示し、ダイアログのドキュメントを表示します。

void FindFileDialog::help()
{
    currentAssistant->showDocumentation("filedialog.html");
}

まとめ

Qt Assistant をアプリケーション用のカスタマイズされたヘルプツールとして機能させるには、Qtの圧縮ヘルプファイルを含むカスタムヘルプコレクションファイルに加え、Qt Assistant を制御するプロセスをアプリケーションに用意する必要があります。

Qt Assistant をカスタムヘルプビューアとして使用するアプリケーションで利用可能なオプションや設定の詳細については、「 Qt Assistant のカスタマイズ」を参照してください。

サンプルプロジェクト @ code.qt.io