Utilisation des conseils pour afficher de l'aide contextuelle dans une application FireMonkey

De RAD Studio
Aller à : navigation, rechercher

Remonter à Conception d'applications FireMonkey


Cette page décrit comment utiliser les conseils dans une application FireMonkey et elle contient également quelques extraits de code.

Plates-formes prenant en charge les conseils

Plate-forme Prise en charge

Windows

Checkmark.svg

macOS

Checkmark.svg
(10.10+)

iOS

Android

Activation des conseils

Activation des conseils pour votre application

Votre application peut afficher par défaut les conseils. La propriété qui active/désactive l'affichage des conseils est TApplication.ShowHint. C'est un paramétrage global qui affecte toutes les actions associées aux conseils, telles que l'affichage des conseils et les événements associés aux conseils. Afin de désactiver les conseils pour votre application, utilisez le code suivant :

Delphi :
  Application.ShowHint := False;
C++ :
  Application->ShowHint = false;

Activation des conseils pour un contrôle

Pour activer les conseils pour le contrôle en cours, effectuez l'une des opérations suivantes :

  • Définissez la propriété ShowHint du contrôle sur True.
  • Définissez la propriété ParentShowHint du contrôle sur True et la propriétéShowHint du contrôle parent sur True.
Remarque: Les deux propriétés ShowHint et ParentShowHint du contrôle ne peuvent pas être définies sur True en même temps.
  • Définissez la propriété HitTest du contrôle sur True.
Remarque: Pour la plupart des contrôles, HitTest vaut True par défaut. Toutefois, cela n'est pas valable pour l'ensemble des contrôles. Par exemple, pour TLabel et TPathLabel, HitTest vaut False par défaut.

Héritage de ParentShowHint

Si vous placez un contrôle sur la fiche et spécifiez un conseil pour ce contrôle, le conseil est activé par défaut. C'est parce que la propriété TForm.ShowHint est définie sur True par défaut et que la propriété ParentShowHint d'un contrôle est également définie sur True par défaut.

Toutefois, si vous ajoutez un autre contrôle en tant qu'enfant du contrôle précédent et spécifiez un conseil pour le nouveau contrôle, ce conseil n'est pas affiché par défaut puisque les règles présentées dans la section Activation des conseils pour un contrôle ne sont pas respectées. Dans ce cas, la propriété ParentShowHint du contrôle enfant est définie sur True, mais la propriété ShowHint du contrôle parent est définie sur False. Modifiez l'une de ces propriétés conformément aux règles afin d'activer le conseil pour le contrôle enfant.

Définition des conseils

Vous pouvez entrer le texte du conseil dans la propriété Hint d'un contrôle dans l'inspecteur d'objets à la conception, ou bien définir un conseil par programmation à l'exécution. Le code suivant montre comment définir et activer un conseil pour un bouton :

Delphi :
  Button1.Hint := 'This is a button';
  Button1.ShowHint := True;
C++ :
  Button1->Hint = "This is a button";
  Button1->ShowHint = true;

Conseils courts et longs

Vous pouvez spécifier un texte court et un texte long pour le même conseil. Pour cela, séparez simplement les deux textes par un caractère | (barre verticale). Par exemple :

A hint|A much longer hint

Lorsque vous affichez un conseil, vous pouvez utiliser les méthodes suivantes de l'unité FMX.Utils pour récupérer la partie courte ou la partie longue du conseil :

Remarque: Vous devez ajouter FMX.Utils à votre section uses/fichier d'en-tête dans l'éditeur de code. Si votre conseil ne spécifie pas une partie courte et une partie longue, l'appel de l'une des deux méthodes citées ci-dessus renvoie le même résultat qui représente le conseil entier.

Le code suivant montre comment récupérer le conseil long dans le gestionnaire d'événement 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);
}

Conseils et événements

Chaque fois qu'un conseil est déclenché, l'événement TApplication.OnHint se produit. Vous pouvez utiliser cet événement pour intercepter et utiliser tous les conseils dans votre application. Par exemple, vous pouvez assigner un gestionnaire d'événement personnalisé à l'événement TApplication.OnHint et l'utiliser pour afficher tous les conseils dans un libellé :

Delphi :

Déclarez le gestionnaire d'événement personnalisé :

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

Ajoutez l'implémentation :

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

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

Ajoutez la déclaration suivante au fichier d'en-tête du projet :

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

L'implémentation de l'événement personnalisé :

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

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

Suppression des conseils

Supposons que vous souhaitez supprimer l'affichage d'un conseil, mais toujours intercepter ce conseil. Vous pouvez le faire en appelant TApplication.HideHint dans le gestionnaire d'événement TApplication.OnHint :

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

Considérations spéciales

Quelques exceptions et cas d'utilisation spéciaux sont à considérer lors de l'utilisation des conseils.

Menus

Vous pouvez définir des conseils pour les éléments de menu, mais ils ne s'affichent pas comme avec les autres contrôles. A la place, les conseils d'éléments de menu se propagent uniquement sur le gestionnaire d'événement. Ainsi, si vous définissez un conseil pour un élément de menu, vous pouvez l'intercepter et l'afficher en utilisant un gestionnaire d'événement TApplication.OnHint personnalisé. Vous ne pouvez pas désactiver les conseils pour les éléments de menu. Si vous voulez désactiver un conseil pour un élément de menu, assignez une chaîne vide au conseil.

Remarque: Les éléments de menu de niveau supérieur ne prennent pas en charge les conseils.

Barre d'état

En ce qui concerne l'utilisation des conseils, le contrôle TStatusBar est un cas particulier. Si vous ajoutez une barre d'état à votre application, puis définissez la propriété TStatusBar.AutoHint sur True, l'événement TStatusBar.OnHint reçoit automatiquement tous les conseils.

Si votre fiche possède une barre d'état, utilisez ce code dans le gestionnaire d'événement pour afficher les conseils sur un libellé :

Delphi :
procedure TForm1.StatusBar1Hint(Sender: TObject);
begin
  Label1.Text := Application.Hint;
end;
C++ :
__fastcall TForm1:StatusBar1Hint(TObject* Sender);
{
  Label1->Text = Application->Hint;
}

Utilisation des deux événements OnHint en même temps

Si vous définissez un gestionnaire d'événement TApplication.OnHint personnalisé dans une application ayant une barre d'état, l'événement TStatusBar.OnHint ne se déclenche pas, quel que soit l'état de la propriété TStatusBar.AutoHint. Si vous souhaitez toujours utiliser les deux événements, vous pouvez le faire en appelant TStatusBar.OnHint à partir du gestionnaire d'événement TApplication.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);
}

Actions

Les actions FireMonkey prennent également en charge les conseils. Vous pouvez spécifier un conseil pour une action. Ce conseil s'applique dans ce cas à l'ensemble des contrôles qui utilisent cette action. Vous ne pouvez pas désactiver les conseils relatifs aux actions (ils ne disposent pas de la propriété ShowHint). Le paramètre TApplication.ShowHint global s'applique également aux actions.

Définition des conseils d'actions

Vous pouvez spécifier un conseil pour une action dans l'inspecteur d'objet ou à l'exécution. Voir Evénement OnHint des actions pour un exemple de définition d'un conseil pour une action à l'exécution. Toutefois, vous devez toujours activer le conseil de ce contrôle, sinon le conseil sera désactivé.

Raccourcis clavier relatifs aux actions

Les actions vous permettent également d'afficher le TAction.ShortCut dans le conseil. Pour cela, vous devez définir TApplication.HintShortCuts sur True.

Remarque: Même si vous ne spécifiez pas de conseil pour une action, le conseil affichera le raccourci si TApplication.HintShortCuts est défini sur True.

Evénement OnHint des actions

Les actions ont leur propre événement OnHint indépendant. Si vous implémentez un gestionnaire d'événement personnalisé pour cet événement, vous pouvez définir ou modifier le texte de ce conseil par programmation, ou bien le supprimer.

Le code suivant est un exemple de gestionnaire d'événement OnHint d'une action qui modifie le texte du conseil.

Remarque: Le paramètre CanShow n'a aucun effet.
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";
}

Si vous souhaitez retirer le conseil, vous pouvez le faire via l'inspecteur d'objets ou bien vous pouvez le supprimer à l'exécution :

Delphi :
procedure TForm1.Action1Hint(var HintStr: string; var CanShow: Boolean);
begin
  HintStr := '';
end;
C++ :
__fastcall TForm1:Action1Hint(System:UnicodeString HintStr, boolean CanShow);
{
  HintStr = "";
}
Remarque: Si vous assignez une action dotée d'un conseil à un contrôle puis que vous supprimez le conseil dans les propriétés du contrôle, le conseil de l'action continue à s'afficher. Examinez le dernier scénario du tableau ci-dessous.

Conseils de contrôle vs conseils d'action

Si vous assignez une action à un contrôle, ce dernier hérite automatiquement du conseil de cette action. Si vous souhaitez modifier le conseil ultérieurement, vous devez modifier le conseil de l'action ou le conseil du contrôle. Toutefois, vous devez tenir compte des considérations et scénarios suivants. Le tableau suivant présente les différents scénarios et leur résultat sur le conseil.

Etapes Conseil affiché
  1. Définissez un conseil pour l'action : ActionHint
  2. Assignez cette action au contrôle.

ActionHint

  1. Définissez un conseil pour l'action : ActionHint.
  2. Assignez cette action au contrôle.
  3. Supprimez le conseil à l'exécution (assignez-le à une chaîne vide).
  1. Définissez un conseil pour l'action : ActionHint.
  2. Assignez cette action au contrôle.
  3. Modifiez le conseil dans les propriétés du contrôle, définissez-le en tant ControlHint.

ControlHint

  1. Définissez un conseil pour l'action : ActionHint.
  2. Assignez cette action au contrôle.
  3. Retirez le conseil dans les propriétés du contrôle.

ActionHint

Remarque: Lorsque vous consultez le tableau ci-dessus, tenez compte des raccourcis clavier.

Voir aussi

Bibliothèques

Rubriques

Actions FireMonkey