VCL アプリケーションにおける F1 ヘルプのデフォルトの処理

提供: RAD Studio
移動先: 案内、 検索

アプリケーションからの HTML ヘルプの呼び出し への移動

アプリケーションでヘルプを起動するには、通常は F1 キーを押します。RAD Studio IDE では、F1 押下時にヘルプを起動するコードを自動生成するためのヘルプ パラメータを定義するオプションを提供しています。この場合、RAD Studio は、VCL アプリケーションで F1 が押されたときにヘルプ処理関数を適切に呼び出すために必要なデフォルト コードを自動生成します。

このトピックでは、ヘルプ処理関数を呼び出すためのパラメータの定義方法と、その呼び出しがどのように実行されるかを説明します。ただし、以下の説明が当てはまるのは VCL GUI アプリケーションだけです。

設定しなければならないパラメータ

F1 を押すと、フォーカスがあるフォームの OnHelp イベントが発生します。その結果、アプリケーションによって OnHelp イベントのデフォルトのイベント ハンドラが実行されます。 IDE では、指定されたヘルプ パラメータを使って、OnHelp イベント ハンドラのコードを生成します。IDE に対して、HelpFile、HelpType、HelpContext、HelpKeyword というヘルプ パラメータを指定することができます。それについて以下のセクションで説明します。

HelpFile

まず第一に、アプリケーションのヘルプ トピックを含んでいるヘルプ ファイルを指定する必要があります。1 つまたは複数のヘルプ ファイルを指定することができます。 アプリケーションのメイン ヘルプ ファイルはグローバル オブジェクト Application の TApplication.HelpFile プロパティを使って、また、フォームそれぞれの個別のヘルプ ファイルは該当する Form オブジェクトの TForm.HelpFile プロパティを使って、指定することができます。

これらの HelpFile は、設計時に該当する IDE プロパティとして指定することができ、それを使って、対応するオブジェクトの HelpFile プロパティがプログラム内で定義されます。

アプリケーションのメイン ヘルプ ファイルを指定するには、通常は、グローバル オブジェクト Application の HelpFile プロパティを使用します。

［<プロジェクト名> のプロジェクト オプション］ダイアログ ボックスを開き（［プロジェクト｜オプション...］）、［アプリケーション｜表示］ページを選択します。［ヘルプ ファイル］オプションでヘルプ ファイルを指定します。［参照...］をクリックします。デフォルトでは、［アプリケーション ヘルプ ファイル］ダイアログ ボックスには拡張子が .hlp のファイルだけが表示されます。他の種類のヘルプ ファイルを指定するには、［ファイルの種類］コントロールで［すべてのファイル (*.*)］を選択します。そうすると、.CHM や .HTML など、他の種類のヘルプ ファイルを選択できます。

このオプションにより Application.HelpFile プロパティが設定されます。このプロパティはアプリケーションのメイン ヘルプ ファイルを定義するものです。アプリケーションは、ヘルプ処理コマンドを受け取ると、デフォルトではこのヘルプ ファイルを使ってヘルプ コマンドを実行します。

特定のフォームに個別のヘルプ ファイルを指定するには、そのフォームの HelpFile プロパティを使用することができます。

フォーム デザイナでフォームを選択すると、次の図に示すように、［オブジェクト インスペクタ］にそのフォームのプロパティが表示されます。

HelpFile

HelpFile プロパティの右の列で「Form1.chm」と指定します。これは Form1 オブジェクトの TForm.HelpFile プロパティを定義しています。このプロパティでは、この Form1 フォームに Form1.chm ヘルプ ファイルを設定しています。

アプリケーションでは通常、アプリケーションの実行可能ファイルが起動されたディレクトリ内でヘルプ ファイルを検索します。そのため、指定したいヘルプ ファイルが別のディレクトリにある場合には、そのファイルの相対パスを指定する必要があります。たとえば「.\Help\Form1.chm」のように指定することができます。

デフォルトの OnHelp イベント ハンドラは、フォーカスがあるフォームの HelpFile プロパティに指定されたヘルプ ファイルを使用します。TForm.HelpFile プロパティが空の文字列であれば、グローバル オブジェクト Application の HelpFile プロパティで指定されたヘルプ ファイルを使用します。

HelpType、HelpContext、HelpKeyword

OnHelp イベントのデフォルト イベント ハンドラのコードを生成できるよう、どのヘルプ トピックを表示するべきかを IDE に知らせる必要があります。 HelpContext プロパティおよび HelpKeyword プロパティの値によって、どのトピックを表示するかを定義できます。HelpType プロパティでは、この 2 つのプロパティのどちらを使用するべきかを定義します。

フォームの［オブジェクト インスペクタ］で、HelpType プロパティの右の列をクリックします。値 htContext を選択すると、HelpContext プロパティに指定した値が使われます。値 htKeyword を選択すると、HelpKeyword プロパティに指定した値が使われます。

生成されたコードに追加しなければならないもの

RAD Studio で開発したアプリケーションでは、外部ヘルプ ビューアを使ってさまざまな種類のヘルプ ファイルを表示します。どの外部ヘルプ ビューアを使用するかをアプリケーションに指定する必要があります。

外部ヘルプ ビューアのラッパー

VCL は外部ヘルプ ビューアに依存しないように設計されています。デフォルトのヘルプ イベント ハンドラで使用しているヘルプ機能はすべて、System.HelpIntfs ユニットのインターフェイスで宣言されています。VCL では、特定の外部ヘルプ ビューア（特定の種類のヘルプ ファイルを扱うもの）に関してそれらのインターフェイスを実装したクラスを含むパッケージ群を提供しています。たとえば Vcl.HtmlHelpViewer ユニットでは、CHM（Microsoft HTML Help）ヘルプ ファイルのビューア用の HTMLHelp API のラッパーを実装しています。

このように外部ヘルプ ビューアから独立しているため、使用したい外部ヘルプ ビューア用の HelpIntfs インターフェイスの実装があれば、uses セクションで適切なユニットを指定するだけで済みます。たとえば CHM ヘルプ ファイルを表示するには、Vcl.HtmlHelpViewer ユニットを指定します。

たとえば、上で説明したプロパティ（HelpFile、HelpType、HelpContext、HelpKeyword）を定義した場合、デフォルトの OnHelp イベント ハンドラでは次のようにヘルプ処理関数を使用することができます。 

IHelpSystem.ShowContextHelp(Form1.HelpContext, Form1.HelpFile);

これは HelpType = htContext の場合です。また、次のようにすることもできます。 

IHelpSystem.ShowHelp(Form1.HelpKeyword, Form1.HelpFile);

これは HelpType = htKeyword の場合です。この IHelpSystem は、HelpIntfs ユニットで宣言されているインターフェイスです。

外部ヘルプ ビューアへのアクセス

以下のセクションでは、HelpIntfs ユニットで宣言されている IHelpSystem などのインターフェイスが、外部ヘルプ ビューアのラッパーを提供しているユニット内のクラスでどのように実装されているかを説明します。例として、HTMLHelp 関数 API のラッパーを提供している Vcl.HtmlHelpViewer ユニットを取り上げます。 Vcl.HtmlHelpViewer ユニットでは THTMLHelpViewer クラスが実装されていて、そこで HelpIntfs ユニットのインターフェイスの実装が提供されています。ただし、この THTMLHelpViewer クラスはユニットの implementation セクションで宣言されています。そのため、Vcl.HtmlHelpViewer ユニットの外からこのクラスのメンバにアクセスする方法を理解しておく必要があります。

HelpIntfs ユニットでは、RegisterViewer および GetHelpSystem という 2 つのグローバル関数を提供しています。この関数は次のように宣言されています。 

function RegisterViewer(const newViewer: ICustomHelpViewer; out Manager: IHelpManager): Integer;
function GetHelpSystem(out System: IHelpSystem): Boolean;

Vcl.HtmlHelpViewer ユニットの initialization セクションでは、次の 2 つの呼び出しが行われます。 

HelpViewer := THtmlHelpViewer.Create;
HelpIntfs.RegisterViewer(HelpViewerIntf, HelpViewer.FHelpManager);

この呼び出しでは、THtmlHelpViewer 型のオブジェクトが作成され、ラップ対象の外部ヘルプ ビューア オブジェクトが IHelpManager 型のヘルプ システム マネージャ オブジェクト（HelpViewer.FHelpManager）として登録されます。

登録された外部ヘルプ ビューアを呼び出すには、コードでフラット関数 HelpIntfs.GetHelpSystem を呼び出します。この関数は、HelpViewer.FHelpManager に格納されたオブジェクトにアクセスして、IHelpSystem 型のオブジェクトに含まれる IHelpManager 型のオブジェクトを返すことができます。また、TApplication にも IHelpSystem 型のオブジェクトにアクセスするための HelpSystem プロパティがあり、TApplication のメソッドではそれを使ってヘルプ ビューアの関数を呼び出すことができます。IHelpSystem 型のオブジェクトは、IHelpSystem.ShowContextHelp や IHelpSystem.ShowHelp などのヘルプ関数を提供しています。デフォルトの OnHelp イベント ハンドラやユーザー コードでこれらの関数を呼び出すことができます。

F1 ヘルプを表示する手順

F1 を押すと、フォーカスがあるフォームの OnHelp イベントのデフォルト イベント ハンドラがアプリケーションによって呼び出されます。このトピックのここまでのセクションでは、［オブジェクト インスペクタ］でヘルプ プロパティを設定し、適切なヘルプ ページを呼び出すために必要なコードを追加する方法を、理論で説明しました。

それを実際に行う手順は次のとおりです。

F1 ヘルプを表示する

  1. グローバル オブジェクト Application または個別のフォームの HelpFile プロパティ（TApplication.HelpFile プロパティまたは TForm.HelpFile プロパティ）を設定します。たとえば次のように設定します。
TForm.HelpFile = Form1.chm
  1. 個別のフォームの場合には、HelpType プロパティを選択して htContext または htKeyword に設定します。たとえば次のように設定します。
TForm.HelpType = htContext
その後、適切な ContextID の値を TForm.HelpContext プロパティに設定します。ContextID は、HelpFile で指定したヘルプ ファイル中の 1 つのトピックを特定する整数でなければなりません。たとえば CHM ヘルプ ファイルの場合、ヘルプ トピックのシンボル コンテキスト ID を、プロジェクト（.hhp）ファイルの [MAP] セクションにある数値 ContextID にマッピングする必要があります。たとえば次のように設定します。
TForm.HelpContext = 714
これで、F1 を押すと、HelpFile で特定される CHM ヘルプ ファイルの中の ContextID が 714 であるトピックが表示されます。
あるいは次のように設定します。
TForm.HelpType = htKeyword
その後、適切な Keyword の値を TForm.HelpKeyword プロパティに設定します。これで、F1 を押すと、Alink タグの値が指定した Keyword の値であるトピックが表示されます。
  1. Delphi アプリケーションでは、Vcl.HtmlHelpViewer ユニットを、アプリケーションのメイン モジュールの uses 句に追加します。
    C++ アプリケーションでは、#include Vcl.HtmlHelpViewer.hpp 指令を追加します。
    #pragma package(smart_init) および #pragma link "Vcl.HtmlHelpViewer" を追加します。
    これによって、CHM ヘルプ ファイルを表示する HTMLHelp 関数の API をアプリケーションで使用することを定義します。
  2. ［実行｜実行］コマンドを選択します。アプリケーションが開きます。
  3. Form1 フォームを選択します。F1 を押します。自動生成されたデフォルトの OnHelp イベント ハンドラによって、指定した .CHM ヘルプ ファイルに含まれる、HelpContext（または HelpKeyword）の値で指定したヘルプ トピックが表示されます。

手動でプログラミングを行う必要がないことに注意してください。F1 を押したときのヘルプの処理はすべて、自動的に実装されます。［オブジェクト インスペクタ］で適切なヘルプ パラメータを指定すればよいだけです。

関連項目

「https://docwiki.embarcadero.com/RADStudio/Sydney/j/index.php?title=VCL_アプリケーションにおける_F1_ヘルプのデフォルトの処理&oldid=240198」から取得