FireMonkey アプリケーションでヒントを使用して状況依存ヘルプを表示する方法

FireMonkey アプリケーションの設計 への移動

ここでは、FireMonkey アプリケーションでのヒントの使用方法を説明し、サンプル コードもいくつか示します。

各プラットフォームでのヒントのサポート状況

プラットフォーム	サポート
Windows
macOS	（10.10 以上）
iOS
Android

ヒントの有効化

アプリケーションのヒントを有効にする

アプリケーションでは、デフォルトでヒントを表示できます。ヒントの表示を有効/無効にするプロパティが TApplication.ShowHint です。これは、ヒントの表示やヒント関連イベントなどのすべてのヒント関連アクションに影響を及ぼすグローバル設定です。 アプリケーションのヒントを無効にするには、次のコードを使用します。

Delphi の場合：

  Application.ShowHint := False;

C++ の場合：

  Application->ShowHint = false;

コントロールのヒントを有効にする

現在のコントロールのヒントを有効にするには、次のいずれかを行います。

• コントロールの ShowHint を True に設定します。
• コントロールの ParentShowHint を True に設定し、親コントロールの ShowHint を True に設定します。

メモ: コントロールの ShowHint と ParentShowHint の両方を、同時に True にすることはできません。

• コントロールの HitTest を True に設定します。

メモ: 大抵のコントロールでは、HitTest はデフォルトで True に設定されています。しかしながら、これはすべてのコントロールに当てはまるわけではありません。たとえば、TLabel や TPathLabel、HitTest の場合、デフォルトは False です。

ParentShowHint の継承

フォームにコントロールを配置し、そのコントロールのヒントを指定した場合、そのヒントがデフォルトで有効になります。これは、TForm.ShowHint がデフォルトで True で、コントロールの ParentShowHint もデフォルトで True だからです。

ただし、先のコントロールの子として別のコントロールを追加し、新しいコントロールのヒントを指定した場合、そのヒントはデフォルトでは表示されません。「コントロールのヒントを有効にする」セクションで示したルールが守られていないからです。この場合、子コントロールの ParentShowHint は True ですが、親コントロールの ShowHint は False になっています。これらのプロパティのいずれかを「ルール」に従って変更すれば、子コントロールのヒントが有効になります。

ヒントのセットアップ

設計時には、［オブジェクト インスペクタ］でコントロールの Hint プロパティにヒント テキストを入力でき、実行時には、プログラムでヒントを設定できます。次のコードでは、ボタンのヒントをセットアップし有効にする方法を示しています。

Delphi の場合：

  Button1.Hint := 'This is a button';
  Button1.ShowHint := True;

C++ の場合：

  Button1->Hint = "This is a button";
  Button1->ShowHint = true;

短いヒントと長いヒント

同じヒントに短いテキストと長いテキストを両方指定してもかまいません。それには、|（パイプ）文字で両者を区切るだけです。次に例を示します。

A hint|A much longer hint

ヒントを表示するときは、FMX.Utils ユニットの次のメソッドを使用して、短いヒントと長いヒントのどちらかを取得できます。

• GetLongHint
• GetShortHint

メモ: コード エディタで uses セクションまたはヘッダー ファイルに FMX.Utils を追加しなければならない可能性があります。 ヒントの短い部分と長い部分を指定しない場合、上記メソッドのどちらを呼び出しても、同じ結果つまりヒント全体が返されます。

次のコードでは、TApplication.OnHint イベント ハンドラで長いヒントを取得する方法を示しています。

Delphi の場合：

procedure TForm1.OnApplicationHint(Sender: TObject);
begin
  Label1.Text := GetLongHint(Application.Hint);
end;

C++ の場合：

void _fastcall TForm1::OnApplicationHint(TObject* Sender);
{
  Label1->Text = GetLongHint(Application->Hint);
}

ヒントとイベント

ヒントがトリガされるたびに、TApplication.OnHint イベントが発生します。このイベントを使用すれば、アプリケーションであらゆるヒントをインターセプトし使用することができます。たとえば、次のように、TApplication.OnHint イベントにカスタム イベント ハンドラを割り当て、それを使用してすべてのヒントをラベルに表示することができます。

Delphi の場合：

カスタム イベント ハンドラを次のように宣言します。

  private
    { Private declarations }
    procedure OnApplicationHint(Sender: TObject);

実装を次のように追加します。

procedure TForm1.FormCreate(Sender: TObject);
begin
  Application.OnHint := OnApplicationHint;
end;

procedure TForm1.OnApplicationHint(Sender: TObject);
begin
  Label1.Text := Application.Hint;
end;

C++ の場合：

次の宣言をプロジェクトのヘッダー ファイルに追加します。

private:	// User declarations
  void __fastcall OnApplicationHint(TObject* Sender);

カスタム イベントの実装は次のとおりです。

__fastcall TForm1:FormCreate(TObject* Sender);
{
  Application->OnHint = OnApplicationHint;
}

void __fastcall TForm1:OnApplicationHint(TObject* Sender);
{
  Label1->Text = Application->Hint;
}

ヒントを非表示にする

ヒントを非表示にはするものの、そのヒントのインターセプトはまだ行うという場合もあります。その場合は、次のように、TApplication.OnHint イベント ハンドラで TApplication.HideHint を呼び出します。

Delphi の場合：

procedure TForm1.OnApplicationHint(Sender: TObject);
begin
   Label1.Text := Application.Hint;
   Application.HideHint;
end;

C++ の場合：

void __fastcall TForm1:OnApplicationHint(TObject* Sender);
{
   Label1->Text = Application->Hint;
   Application->HideHint;
}

特に考慮すべき事項

ヒントの使用時に考慮したほうがよい例外事項や特殊な使用法がいくつかあります。

メニュー

メニュー項目のヒントを設定してもかまいませんが、それらは、他のコントロールの場合のようには表示されません。 むしろ、メニュー項目ヒントはイベント ハンドラに伝播するだけです。 そのため、メニュー項目のヒントを設定した場合は、TApplication.OnHint イベントのカスタム イベント ハンドラを使ってそれをインターセプトし表示することができます。 メニュー項目のヒントを無効にすることはできません。 メニュー項目のヒントを事実上無効にしたければ、空の文字列をヒントに割り当てます。

メモ: 最上位のメニュー項目では、ヒントをサポートしていません。

ステータス バー

ヒントに関して特殊なのは TStatusBar コントロールです。アプリケーションにステータス バーを追加し TStatusBar.AutoHint プロパティを True に設定した場合、TStatusBar.OnHint イベントでは、すべてのヒントを自動的に受け取ります。

イベント ハンドラで次のコードを使用すると、フォームにステータス バーがある場合、ヒントをラベルに表示できます。

Delphi の場合：

procedure TForm1.StatusBar1Hint(Sender: TObject);
begin
  Label1.Text := Application.Hint;
end;

C++ の場合：

__fastcall TForm1:StatusBar1Hint(TObject* Sender);
{
  Label1->Text = Application->Hint;
}

同時に両方の OnHint イベントを使用する

ステータス バーのあるアプリケーションにカスタム TApplication.OnHint イベント ハンドラを定義しても、TStatusBar.AutoHint プロパティに関係なく、TStatusBar.OnHint イベントは発生しません。それでも両方のイベントを使用するには、次のように、TApplication.OnHint イベント ハンドラから TStatusBar.OnHint を呼び出します。

Delphi の場合：

procedure TForm1.OnApplicationHint(Sender:TObject);
begin
   Label1.Text := Application.Hint;
   StatusBar1Hint(Sender);
end;

C++ の場合：

void __fastcall TForm1:OnApplicationHint(TObject* Sender);
{
   Label1->Text = Application->Hint;
   StatusBar1Hint(Sender);
}

アクション

FireMonkey のアクションでもヒントをサポートしています。アクションのヒントを指定することができ、その場合、そのヒントは、そのアクションを使用するすべてのコントロールに適用されます。アクションのヒントを無効にすることはできません（アクションには ShowHint プロパティがありません）。グローバルな TApplication.ShowHint 設定はアクションにも適用されます。

アクションのヒントをセットアップする

アクションのヒントは、設計時に［オブジェクト インスペクタ］で指定するか、実行時に指定することができます。実行時にアクションのヒントを指定する方法の例については、「アクションの OnHint イベント」を参照してください。ただし、やはりそのコントロールのヒントを有効にする必要はあります。そうしないと、ヒントが無効になります。

アクションのキーボード ショートカット

また、アクションでは、TAction.ShortCut をヒントの一部として表示することもできます。 このためには、TApplication.HintShortCuts を True に設定する必要があります。

メモ: たとえアクションのヒントを指定しなくても、TApplication.HintShortCuts が True であれば、ショートカットがヒントに表示されます。

アクションの OnHint イベント

アクションには、それ自身の独立した OnHint イベントがあります。このイベントのカスタム イベント ハンドラを実装すれば、プログラムでヒントのテキストを設定または変更したりヒントを非表示にすることができます。

次のコードは、アクションの OnHint イベント ハンドラでヒントのテキストを変更する例です。

メモ: CanShow パラメータは、何もしません。

Delphi の場合：

procedure TForm1.Action1Hint(var HintStr: string; var CanShow: Boolean);
begin
  HintStr := HintStr + 'My hint text';
end;

C++ の場合：

__fastcall TForm1:Action1Hint(System:UnicodeString HintStr, boolean CanShow);
{
  HintStr = HintStr + "My hint text";
}

ヒントを削除する場合は、［オブジェクト インスペクタ］で削除してもかまいませんし、実行時に非表示にすることもできます。

Delphi の場合：

procedure TForm1.Action1Hint(var HintStr: string; var CanShow: Boolean);
begin
  HintStr := '';
end;

C++ の場合：

__fastcall TForm1:Action1Hint(System:UnicodeString HintStr, boolean CanShow);
{
  HintStr = "";
}

メモ: ヒントを設定されたアクションをコントロールに割り当てた後で、そのコントロールのプロパティに格納されているヒントを削除しても、そのアクション ヒントはいずれにせよ表示されます。 下表の最後のシナリオを参照してください。

コントロールのヒントとアクションのヒント

コントロールにアクションを割り当てると、そのコントロールは、そのアクションのヒントを自動的に継承します。ヒントを後で変更する場合は、アクションのヒントを変更することも、コントロールのヒントを変更することもできます。ただし、その場合に考慮すべきシナリオがいくつかあります。これらの異なるシナリオとそれぞれの場合に表示されるヒントを次の表に示します。

手順	表示されるヒント
アクションのヒント ActionHint を設定します。 そのアクションをコントロールに割り当てます。	ActionHint
アクションのヒント ActionHint を設定します。 そのアクションをコントロールに割り当てます。 実行時にヒントを非表示にします（空の文字列を割り当てます）。
アクションのヒント ActionHint を設定します。 そのアクションをコントロールに割り当てます。 コントロールのプロパティに格納されているヒントを変更し、それを ControlHint として設定します。	ControlHint
アクションのヒント ActionHint を設定します。 そのアクションをコントロールに割り当てます。 コントロールのプロパティに格納されているヒントを削除します。	ActionHint

メモ: 上記の表を考慮する際には、キーボード ショートカットのことを忘れないでください。

関連項目

関連ライブラリ

• FMX.Controls.THint
• FMX.Controls.TControl.Hint
• FMX.Controls.TControl.HitTest
• FMX.Controls.TControl.ShowHint
• FMX.StdCtrls.TStatusBar.OnHint
• FMX.StdCtrls.TStatusBar.AutoHint
• FMX.Forms.TApplication.OnHint
• FMX.Forms.TApplication.Hint
• FMX.Forms.TApplication.ShowHint
• FMX.Forms.TApplication.HideHint
• FMX.Forms.TApplication.HintShortCuts
• FMX.Utils.GetLongHint
• FMX.Utils.GetShortHint

関連トピック

FireMonkey アクション