Concepteur LiveBindings XE3 : liaison des contrôles aux champs

L'un des types de liaisons supportés par le concepteur LiveBindings est la liaison entre des contrôles simples et les champs d'une source de données. Les contrôles simples sont les composants visuels qui acceptent une entrée utilisateur afin d'éditer des valeurs. TEdit et TCheckBox sont des exemples de contrôles simples.

La première partie de cet article décrit comment lier des contrôles aux champs d'une source de données grâce au concepteur LiveBindings. La seconde partie décrit comment rendre compatible un contrôle avec le concepteur LiveBindings.

Vous pouvez trouver l'ensemble du code de cet article sur sourceforge :
https://radstudiodemos.svn.sourceforge.net/svnroot/radstudiodemos/branches/RadStudio_XE3/LiveBindings/observers/vcl.

Après avoir déposé un TEdit et un TCheckBox sur un formulaire VCL, les contrôles sont représentés dans l'éditeur de LiveBindings (faire Affichage/Editeur LiveBindings pour afficher ce dernier). Le TEdit est affiché avec son attribut « Text » et le TCheckBox avec son attribut « Checked ». Ce sont là les attributs du contrôle modifiés par l'utilisateur.

Le concepteur LiveBindings peut être utilisé pour lier ces attributs aux champs d'une source de données.

Le composant TPrototypeBindSource est un moyen simple de créer une source de données. Déposer un TPrototypeBindSource sur le formulaire. Faire un clic droit dessus et choisir l'option « Ajouter un champ… ».

Choisir un champ booléen, Entier et Chaîne de caractères comme ci-dessous.

Le concepteur LiveBindings affiche le PrototypeBindSource1 et les nouveaux champs :

Vous pouvez alors lier les attributs des contrôles aux champs. Notez que lorsqu'un attribut est sélectionné, les autres attributs changent de couleur. La couleur verte indique quels attributs peuvent être liés.

Vous pouvez lier ceux-ci ainsi que le montre l'image suivante (utiliser le bouton réarranger afin d'avoir l'organisation ci-dessous)

Vous pouvez également essayer différentes liaisons. Si le LiveBindings ne peut effectuer de conversion entre le type de l'attribut du contrôle et le type du champ, un message d'erreur sera affiché. Pour changer les liaisons, cliquer sur la flèche et la faire pointer vers un autre attribut. Si vous désirez retirer une liaison, faire un clic droit dessus et choisir l'option « Retirer le lien ». Plusieurs contrôles peuvent être liés au même champ, mais un attribut en particulier ne peut être lié qu'à un seul champ. Si vous désirez ajouter une seconde liaison à l'attribut, une boîte de message vous invitera à supprimer le lien existant.

Vous pouvez ajouter un contrôle de navigation en effectuant un clic droit sur le TPrototypeBindSource (dans l'éditeur de formulaire et non dans l'éditeur de liaisons LiveBindings) et choisir l'option « Ajouter un navigateur ». À présent l'application est prête à être exécutée.

Si vous déposez un TTrackBar sur le formulaire, le concepteur LiveBindings l'affichera ainsi :

Notez que le concepteur LiveBindings n'affiche aucun attribut du TrackBar1. Ceci parce que le TTrackBar n'a pas été activé pour du LiveBindings.

Il y a deux exigences pour activer un simple contrôle comme le TTrackBar au LiveBindings. Le premier c'est que le contrôle implémente le support « observer ». LiveBindings dépend des observateurs afin de souscrire aux notifications du contrôle. La seconde exigence c'est d'enregistrer la valeur du nom du contrôle (ex. : « Position » pour le TTrackBar). La valeur du nom du contrôle est utilisée par les composants LiveBindings afin de générer les expressions qui permettent de lire ou définir la valeur de l'attribut du contrôle.

Nous ne pouvons modifier directement le TTrackBar, alors le support « observer » doit être implémenté dans une sous-classe. Nous l'avons nommé TObservableTrackBar et son unité nommée VCL.Sample.ObservableTrackBar. Voici un extrait de sa section interface.

interface

uses Vcl.ComCtrls, System.Classes, WinApi.Messages, WinApi.CommCtrl, Vcl.Controls;

type

  [ObservableMember('Position')]
  TObservableTrackBar = class(TTrackBar)
  private
    procedure CNHScroll(var Message: TWMHScroll); message CN_HSCROLL;
    procedure CNVScroll(var Message: TWMVScroll); message CN_VSCROLL;
    procedure ObserverToggle(const AObserver: IObserver; const Value: Boolean);
  protected
    function CanObserve(const ID: Integer): Boolean; override;
    procedure ObserverAdded(const ID: Integer; const Observer: IObserver);  override;

  end;

implementation

uses System.SysUtils;

Les deux sections « uses » ont été affichées ici afin de montrer qu'il n'y a aucune référence aux unités LiveBindings. Les déclarations des interfaces observer et autres sont dans l'unité System.Classes.

L'annotation ObservableMember identifie la valeur de l'attribut du contrôle.

  [ObservableMember('Position')]
  TObservableTrackBar = class(TTrackBar)

Les contrôles implémentant les observers doivent toujours redéfinir la méthode TComponent.CanObserver(). Cette méthode identifie les types d'observers supportés par TObservableTrackbar.

function TObservableTrackBar.CanObserve(const ID: Integer): Boolean;
begin
  case ID of
    TObserverMapping.EditLinkID,
    TObserverMapping.ControlValueID:
      Result := True;
  else
    Result := False;
  end;
end;

EditLinkID est un observer utilisé pour les liaisons contrôle->champ.

Les redéfinitions pour CNHscroll et CNVScroll sont les lieux où TObservableTrackBar appelle les interfaces observables afin de notifier les composants LiveBindings lorsque l'utilisateur déplace le slider.

procedure TObservableTrackBar.CNHScroll(var Message: TWMHScroll);
var
  LPosition: Integer;
begin
  LPosition := Position;
  inherited;
  if LPosition <> Position then
    TLinkObservers.ControlChanged(Self);
end;

procedure TObservableTrackBar.CNVScroll(var Message: TWMVScroll);
var
  LPosition: Integer;
begin
  Message.Result := 0;
  LPosition := Position;
  inherited;
  if LPosition <> Position then
    TLinkObservers.ControlChanged(Self);
end;

Ces deux redéfinitions sont suffisantes pour monitorer les entrées utilisateur sur TObservableTrackBar. TLinkObservers.ControlChanged est une méthode utilitaire effectuant le plus gros du travail. Vous pouvez trouver son implémentation dans l'unité System.Classes.

Les méthodes suivantes empêchent l'utilisateur de bouger le curseur lorsque le contrôle TObservableTrackBar est lié à un champ en lecture seule.

procedure TObservableTrackBar.ObserverAdded(const ID: Integer;
  const Observer: IObserver);
begin
  if ID = TObserverMapping.EditLinkID then
    Observer.OnObserverToggle := ObserverToggle;
end;

procedure TObservableTrackBar.ObserverToggle(const AObserver: IObserver;
  const Value: Boolean);
var
  LEditLinkObserver: IEditLinkObserver;
begin
  if Value then
  begin
    if Supports(AObserver, IEditLinkObserver, LEditLinkObserver) then
      // Disable the trackbar if the associated field does not support editing
      Enabled := not LEditLinkObserver.IsReadOnly;
  end
  else
    Enabled := True;
end;

Tous les contrôles supportant l'observer EditLink doivent empêcher l'utilisateur de changer la valeur du contrôle. Désactiver le contrôle est l'un des moyens d'y arriver. Certaines implémentations d'observer ignorent certaines entrées afin d'empêcher l'utilisateur de changer la valeur du contrôle.

Un code supplémentaire est requis afin de rendre le TObservableTrackBar complètement activé pour le concepteur LiveBindings. La valeur du nom de la propriété du contrôle doit être enregistrée en utilisant la fonction RegisterObservableMember(). Ce code peut aller dans la même unité où le composant est enregistré.

unit VCL.Sample.ObservableTrackbarReg;

interface

procedure Register;

implementation

uses System.Classes, VCL.Sample.ObservableTrackbar, Data.Bind.Components;

procedure Register;
begin
  RegisterComponents('LiveBindings Samples', [TObservableTrackBar]);
end;

initialization
  Data.Bind.Components.RegisterObservableMember(TArray<TClass>.Create(
    TObservableTrackBar),
    'Position', 'DFM');
finalization
  Data.Bind.Components.UnregisterObservableMember(TArray<TClass>.Create(
    TObservableTrackBar));
end.

« Position » est identifié comme la valeur du nom du contrôle dans deux endroits : dans VCL.Sample.ObservableTrackbar.pas avec l'annotation ObservableMember et dans VCL.Sample.ObservableTrackbarReg.pas par l'appel à RegisterObservableMember(). L'annotation ObservableMember sera utilisée par les composants LiveBindings pour générer les expressions de liaison. RegisterOservableMember() sera utilisé lors de la conception pour informer le concepteur LiveBindings.

Après l'installation du package contenant VCL.Sample.ObservableTrackbar et VCL.Sample.ObserbableTrackbarReg, le composant TObservableTrackbar peut être sélectionné à partir de la palette des composants. TObservableTrackbar est représenté dans le concepteur LiveBindings ainsi :

ObservableTrackbar1.Position peut être connecté à un champ en utilisant le concepteur LiveBindings. Les liaisons suivantes comprennent un TEdit, ainsi, lorsque l'application est exécutée, vous verrez les valeurs du champ lorsque le slider sera déplacé.

Les valeurs Min et Max par défaut du TObservableTrackBar sont 0 et 10. Les données générées par le TPrototypeBindSource sont hors de cet intervalle. Il faut donc modifier les propriétés Min et Max du composant dans l'inspecteur d'objet et définir Min et Max à -100 et 100 respectivement.

Le concepteur LiveBindings dispose d'une commande permettant de créer un controler et le connecter à un champ en une seule étape. Cette commande est disponible lorsque l'on fait un clic droit sur un champ dans le concepteur LiveBindings.

« Liason vers un nouveau contrôle… » affiche une liste de contrôles ayant été enregistrés via la méthode RegisterObservableMember(). Faire défiler afin de trouver le contrôle TObservableTrackBar.

En plus de la possibilité de se lier à des champs, TObservableTrackBar peut se lier aux propriétés de composants. La liaison de contrôles simples aux propriétés de composants fera l'objet d'un prochain article.