Using Hints to Show Contextual Help in a FireMonkey Application

Go Up to FireMonkey Application Design

This page describes how to use hints in a FireMonkey application and also contains some code snippets.

Platform Support for Hints

Platform	Supported
Windows
OS X	(10.10+)
iOS
Android

Enabling Hints

Enabling Hints for Your Application

Your application can show hints by default. The property that enables/disables hint display is TApplication.ShowHint. This is a global setting that affects all hint-related actions, such as display of hints and hint-related events. In order to disable hints for your application, use the following code:

Delphi:

  Application.ShowHint := False;

C++:

  Application->ShowHint = false;

Enabling Hints for a Control

To enable hints for the current control, do one of the following:

• Set ShowHint of the control to True.
• Set ParentShowHint of the control to True and the ShowHint of the parent control to True.

  Note: Both ShowHint and ParentShowHint of the control cannot be True at the same time.

• Set HitTest of the control to True.

  Note: For most controls, HitTest is True by default. However, this is not true for all the controls. For example, for TLabel and TPathLabel, HitTest is False by default.

Inheritance of ParentShowHint

If you place a control on the form and specify a hint for that control, by default the hint is enabled. That is because the TForm.ShowHint is True by default and the ParentShowHint of a control is True by default as well.

However, if you add another control as a child of the previous control and specify a hint for the new control, that hint is not shown by default since the rules presented in the Enabling Hints for a Control section are not respected. In this case the ParentShowHint of the child control is True but the ShowHint of the parent control is False. Modify one of those properties according to the rules to enable hint for the child control.

Setting up Hints

You can enter the hint text in the Hint property of a control in the Object Inspector at design-time or you can set a hint programatically at run-time. The following code shows how to set up and enable a hint for a button:

Delphi:

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

C++:

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

Short and Long Hints

You may specify a short and a long text for the same hint. To do this, simply separate the two with a | (pipe) character. For example:

A hint|A much longer hint

When you display a hint, you can use the following methods from the FMX.Utils unit to retrieve either the short or the long part of the hint:

• GetLongHint
• GetShortHint

Note: You may need to add FMX.Utils to your uses section/header file in the Code Editor

If your hint does not specify a short and a long part, calling any of the above methods returns the same result which is the entire hint.

The following code shows how to retrieve the long hint in the TApplication.OnHint event handler:

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);
}

Hints and Events

Every time a hint is triggered, the TApplication.OnHint event occurs. You can use this event to intercept and use all of the hints in your application. For example, you may assign a custom event handler to the TApplication.OnHint event and use it to display all hints in a label:

Delphi:
Decalare the custom event handler:

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

Add the implementation:

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

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

C++:
Add the following declaration to the project header file:

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

The implementation of the custom event:

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

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

Suppressing Hints

You may want to suppress the display of a hint but still intercept that hint. You can do that by calling TApplication.HideHint in the TApplication.OnHint event handler:

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;
}

Special Considerations

There are some exceptions and special use-cases that you may want to consider when using hints.

Menus

You may set hints for menu items, but they do not display as with other controls. Instead, menu item hints only propagate to the event handler. So if you set a hint for a menu item you can intercept and display it using a custom TApplication.OnHint event handler. You cannot disable hints for menu items. If you wish to disable a hint for a menu item, assign an empty String as the hint.

Note: Top-level menu items do not support hints.

Status Bar

A special case regarding hints is the TStatusBar control. If you add a status bar to your application and set the TStatusBar.AutoHint property to True, the TStatusBar.OnHint event automatically receives all hints.

Use this code in the event handler to display hints in a label if you have a status bar on your form:

Delphi:

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

C++:

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

Using Both OnHint Events at the Same Time

If you define a custom TApplication.OnHint event handler in an application with a status bar, the TStatusBar.OnHint event does not fire, regardless of the TStatusBar.AutoHint property. If you still wish to use both events, you can do so by calling the TStatusBar.OnHint from the TApplication.OnHint event handler.

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);
}

Actions

FireMonkey Actions also support hints. You may specify a hint for an action and that hint applies to all the controls that use that action. You cannot disable action hints (they do not have the ShowHint property). The global TApplication.ShowHint setting applies to actions as well.

Setting up Action Hints

You can specify a hint for an action in the Object Inspector or at run-time. See Action OnHint Event for an example on how to define a hint for an action at run-time. However, you still need to enable hint for that control, otherwise the hint is disabled.

Action Keyboard Shortcuts

Another thing that actions allow you is to show the TAction.ShortCut as a part of the hint. To do that, you need to set TApplication.HintShortCuts to True.

Note: Even if you do not specify a hint for an action, if the TApplication.HintShortCuts is True, the hint will display the shortcut.

Action OnHint Event

Actions have their own independent OnHint event. If you implement a custom event handler for this event, you can programatically set or modify the text of the hint or suppress that hint.

The following code is an example of an OnHint event handler for an action that modifies the hint text.

Note: The CanShow parameter does not do anything.

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";
}

If you want to remove the hint, you may do so in the Object Inspector or you can suppress it at run-time:

Delphi:

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

C++:

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

Note: If you assign an action with a hint to a control and then remove the hint in the properties of the control, the action hint is displayed anyway. See the last scenario in the table below.

The Control Hint Versus the Action Hint

When you assign an action to a control, that control automatically inherits the hint of that action. If you wish to modify the hint later, you can do so either by modifying the hint of the action or the hint of the control. However, there are some scenarios that you should consider. The following table demonstrates the different scenarios and the resulting hint.

Steps	Hint Displayed
Set a hint for the action: ActionHint Assign that action to a control	ActionHint
Set a hint for the action: ActionHint. Assign that action to a control. Suppress hint at run-time (assign it an empty string).
Set a hint for the action: ActionHint. Assign that action to a control. Modify the hint in the properties of the control, set it as ControlHint.	ControlHint
Set a hint for the action: ActionHint. Assign that action to a control. Remove the hint in the properties of the control.	ActionHint

Note: When considering the above table, keep in mind the keyboard shortcuts.

See Also

Libraries

• 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

Topics

FireMonkey Actions