LiveBindings de A à … Écrire un composant observable II

Il est temps de faire une parenthèse sur les noms de variables, propriétés et autres à utiliser.

Si pour un composant « maison » à usage unique les noms n’ont que peu d’importance, il n’en va pas de même lorsque l’objectif est de réutiliser ce dernier dans plusieurs programmes ou dans le cas d’un partage à large spectre (pour un public plus international), histoire de passer à la postérité ;-).

Une autre raison de bien choisir les noms de propriétés est que celles-ci seront proposées par ordre alphabétique dans l’éditeur de propriété.

De fait le choix des noms commence dès celui de l’unité. Dorénavant les unités sont souvent préfixées du type de bibliothèque : VCL, FMX donc il serait bien d’appliquer ce principe. L’équipe d’Embarcadero estime que ce n’est pas suffisant comme distinction et suggère (« fortement » ?)(1) que tout composant tiers ait un autre préfixe que ces deux-ci, histoire que le nom d’unité soit bien distingué de celui d’une unité « native ».

Ma future unité se nommera donc Lug.FMX.Diode.

C’est une étape importante, même si par la suite il se peut que vous vous aperceviez qu’il vous en faut d’autres, cela vous donnera quand même un bon point de départ.

Comment se décider ? J’avoue que ce n’est pas si évident que cela. Si l’objectif n’est qu’un changement de couleur comme montré dans la première image, il me faut évidemment une propriété en rapport avec la couleur. En définissant le gradient, je me suis aperçu que :

• je changeai le type de gradient (type radial) ;
• je nécessitai deux couleurs (celle de début et celle de fin qui simule un éclat plus brillant) ;
• un coup d’œil au composant de Gouyon m’a convaincu d’ajouter une couleur supplémentaire pour « éteindre » la diode.

Donc déjà trois propriétés.

Le fait d’utiliser un gradient de type radial permet également de déplacer le centre de celui-ci. Je vais en faire d’ores et déjà une propriété supplémentaire sans toutefois la rendre accessible, ce qui me permettra d’exposer par la suite un premier dérivé de mon composant.

Nommer ces propriétés va aussi être un peu « casse-tête ». Il est en effet assez agaçant d’aller les retrouver un peu partout dans l’inspecteur d’objet. Mon conseil : essayez de nommer toutes les propriétés d’un même groupe avec un même préfixe. Par exemple, pour ce qui est des couleurs, je vais utiliser le préfixe color, pour l’éclat le préfixe bright.

Pour récapituler :

• propriétés ColorOn, ColorOff de type TAlphaColor ;
• propriétés BrightColor de type TAlphaColor et BrightPosition de type TPosition ;
• une propriété OnOff de type Boolean pour indiquer si la diode sera allumée ou non.

type
  TDiode = class(TCircle)
  private
    { Déclarations privées }
  protected
    { Déclarations protégées }
  public
    { Déclarations publiques }
    property BrightPosition : TPosition;
  published
    { Déclarations publiées }
    property OnOff : Boolean ;
    property ColorOn : TAlphaColor;
    property ColorOff : TAlphaColor;
    property BrightColor : TAlphaColor;
  end;

Ensuite quelques autres prérequis vont être nécessaires : un constructeur et, comme dans celui-ci l’objet BrightPosition sera créé, un destructeur.

public 
  { Déclarations publiques }
  constructor Create(AOwner: TComponent); override;
  destructor Destroy; override;

À cela s’ajoute la nécessité d’une procédure de dessin.

function Paint: Boolean; reintroduce;

Comme indiqué lors du premier tutoriel de cette série, il faudra aussi ajouter trois éléments,

deux procédures et une fonction pour la prise en charge des LiveBindings.

procedure ObserverToggle(const AObserver: IObserver; const Value: Boolean);

function CanObserve(const ID: Integer): Boolean; override;  
procedure ObserverAdded(const ID: Integer; const Observer: IObserver); override;

Une fois tout ajouté, Ctrl+Shift+C permettra d’obtenir les déclarations complètes nécessaires.

  TDiode = class(TCircle)
  private
    { Déclarations privées }
    FOnOff : Boolean;
    FColorOn : TAlphaColor;
    FColorOff : TAlphaColor;
    FBrightPos: TPosition;
    FBrightColor: TAlphaColor;
    procedure ObserverToggle(const AObserver: IObserver; const Value: Boolean);
    procedure SetColorOff(const Value: TAlphaColor);
    procedure SetOnOff(const Value: Boolean);
    procedure SetColorOn(const Value: TAlphaColor);
    procedure SetBrightPosition(const Value: TPosition);
    procedure SetBrightColor(const Value: TAlphaColor);
 protected
    { Déclarations protégées }
    function CanObserve(const ID: Integer): Boolean; override;  
    procedure ObserverAdded(const ID: Integer; const Observer: IObserver); override;
  public
    { Déclarations publiques }
    constructor Create(AOwner: TComponent); override;
    destructor Destroy; override;
    function Paint: Boolean; reintroduce;
    property BrightPosition : TPosition read FBrightPos write SetBrightPosition;
  published
    { Déclarations publiées }
    property OnOff : Boolean read FOnOff write SetOnOff;
    property ColorOn : TAlphaColor read FColorOn write SetColorOn;
    property ColorOff : TAlphaColor read FColorOff write SetColorOff;
    property BrightColor : TAlphaColor read FBrightColor write SetBrightColor;
  end;

Il faut tout d’abord proposer des propriétés par défaut si nous sommes dans l’IDE, et pour cela la procédure Create est tout indiquée.

constructor TDiode.Create(AOwner: TComponent);
  begin
    if not(csloading in ComponentState) then
    begin
      inherited;
      FOnOff:=True;
      FColorOff:=TAlphaColors.Lightgray;
      FColorOn:=TAlphaColors.Red;
      FBrightPos:=TPosition.Create(PointF(0.5,0.5));

      FBrightColor:=TAlphaColors.Antiquewhite;
      Fill.DefaultColor:=FColorOn;
      Fill.Color:=FColorOn;
      Fill.Gradient.Color:=FColorOn;
      Fill.Gradient.Color1:=FBrightColor;
      Fill.Kind:=TBrushKind.Gradient;
      Fill.Gradient.Style:=TGradientStyle.Radial;
      Fill.Gradient.RadialTransform.RotationCenter.X :=FBrightPos.X;
      Fill.Gradient.RadialTransform.RotationCenter.Y :=FBrightPos.Y;
      Paint;
    end;
  end;

N’oublions pas : à la ligne 9 je fais une création d’un objet de type TPosition ; il faudra donc le détruire.

  destructor TDiode.Destroy;
  begin
    FBrightPos.Free;  // libération 
    inherited;
  end;

Passons au dessin. La fonction Paint, dont la subtilité la plus importante se situe dans la déclaration avec, à sa suite, le mot clé reintroduce.

function TDiode.Paint: Boolean;
  begin
  if FonOff then Fill.Gradient.Color:=FColorOn
            else Fill.Gradient.Color:=FColorOff;
  Fill.Gradient.Color1:=FBrightColor;
  Fill.Gradient.RadialTransform.RotationCenter.X:=FBrightPos.X;
  Fill.Gradient.RadialTransform.RotationCenter.Y:=FBrightPos.Y;
  Result:=True; // indiquera qu’il faut rafraîchir l’affichage
  end;

Pour les autres propriétés, il faudra si nécessaire détecter le changement de valeur et forcer le dessin.

  procedure TDiode.SetColorOff(const Value: TAlphaColor);
  begin
    FColorOff := Value;
  end;

  procedure TDiode.SetColorOn(const Value: TAlphaColor);
  begin
  if FColorOn<>Value then
   begin
    Fill.Color:=Value;
    FColorOn := Value;
    Paint;
   end;
  end;

  procedure TDiode.SetBrightPosition(const Value: TPosition);
  begin
   if (Value<>FBrightPos) then
       FbrightPos.Assign(Value); // attention, assign, pas := 
  end;

  procedure TDiode.SetBrightColor(const Value: TAlphaColor);
  begin
    if (Value<>FBrightColor) then
     begin
      FBrightColor:=Value;
      Fill.Gradient.Change; // force le calcul du gradient
      Paint;
     end;
  end;

  procedure TDiode.SetOnOff(const Value: Boolean);
  begin
   if FonOff<>Value then
    begin
     FOnOff := Value;
     Paint;  // force le dessin
    end ; 
  end;

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

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

procedure TDiode.ObserverToggle(const AObserver: IObserver;
    const Value: Boolean);
  var
    LEditLinkObserver: IEditLinkObserver;
  begin
    if Value then
    begin
      if Supports(AObserver, IEditLinkObserver, LEditLinkObserver) then
        Enabled := not LEditLinkObserver.IsReadOnly;
    end
    else
      Enabled := True;
end;

Reste alors à indiquer quelle propriété nous voulons voir apparaître lorsque nous utiliserons le concepteur de lien visuel.

  [ObservableMembers('ColorOn',false)]
  TDiode = class(TCircle)

À indiquer juste au-dessus de la déclaration de classe.

Mais il faut surtout faire en sorte que les propriétés soient prises en compte avec le lieur et pour cela enregistrer celles-ci au niveau du lieur de l’unité Data.Bind.Components.

initialization

Data.Bind.Components.RegisterObservableMember
  (TArray<TClass>.create(TDiode), 'ColorOn', 'FMX');

Data.Bind.Components.RegisterObservableMember
  (TArray<TClass>.create(TDiode), 'OnOff', 'FMX');

Qu’il faudra bien sûr désinscrire par la suite, à la libération du composant.

finalization

Data.Bind.Components.UnregisterObservableMember
  (TArray<TClass>.create(TDiode));

Compiler ou construire un composant se fait de la même manière que pour un programme, soit en utilisant les options du menu Projet soit en utilisant les raccourcis Ctrl+F9 et Maj+F9.

Par contre, ne vous avisez pas, par habitude, d’utiliser le menu Exécuter car un paquet n’est pas un programme. C’est un peu pour cette raison que je préfère utiliser le menu contextuel de la fenêtre Projet qui a l’avantage de proposer ces options, en plus celle d’installation.

Une première compilation vous proposera certainement d’ajouter certaines unités à votre package, acceptez.

Une installation réussie sera validée par un écran d’information recensant les composants installés.

Créez un nouveau programme FMX et posez sur votre fiche vierge le composant Diode de la palette. Pour « simuler » des données, ajoutez un TPrototypeBindSource contenant deux champs : un champ booléen pour tester la propriété OnOff, un champ de type TAlphaColor pour la propriété ColorOn. Un BindNavigator, dont on enlèvera les boutons non nécessaires, permettra de naviguer au sein de l’ensemble de données créé.

Constatations :

• Les propriétés publiées sont bien visibles dans l’inspecteur d’objets.
• Une fois liée, notre diode réagit tout de suite et ce sans aucune ligne de code, dois-je, encore, le souligner ?

• Les propriétés OnOff et ColorOff n’apparaissent pas dans le lieur. Il faudra les sélectionner en utilisant le bouton …. Faire en sorte que les propriétés autres que celle indiquée au-dessus de la déclaration de type du composant, reste encore, pour moi, un point à élucider.
• Le lien entre ColorOn et le champ AlphaColors1 est de type bidirectionnel - ça, c’est absurde. Bien sûr il est toujours possible de modifier la propriété Direction du lien en LinkDataToControl, mais il y a certainement mieux à faire. En effet, si l’on regarde le lien de la propriété OnOff, la flèche va bien uniquement du champ vers la propriété.

Pourquoi la liaison « principale » est-elle bidirectionnelle alors que les liaisons à d’autres propriétés ne le sont pas ? C’est ce qui m’a fait mettre au feu plusieurs fois mon ébauche.

Une étude des liaisons fournit une première piste.

Il est facile de remarquer que la première liaison, celle sur la propriété « principale » définie lors du recensement, crée un lien de type ControlToField alors que la seconde est de type PropertyToField.

III-C-1. Première solution▲

III-C-2. Seconde solution▲

initialization

//Data.Bind.Components.RegisterObservableMember       
// (TArray<TClass>.create(TDiode), 'ColorOn', 'FMX');
Data.Bind.Components.RegisterValuePropertyName
  (TArray<TClass>.create(TDiode), 'ColorOn', 'FMX');

finalization

// Data.Bind.Components.UnRegisterObservableMember
//   (TArray<TClass>.create(TDiode));
Data.Bind.Components.UnregisterValuePropertyName
  (TArray<TClass>.create(TDiode));

Un objet TPosition fournit la possibilité d’ajouter un évènement OnChange (voir documentation). Je vais donc lui assigner une procédure qui prendra en charge les déplacements du centre du gradient pendant le design. Cette procédure sera indiquée dans la partie protected.

  procedure TDiode.ChangeBrightPos(sender: TObject);
  begin
  if (not FInPaintTo) and (not IsUpdating) then
     begin
      if FBrightPos.X>1 then FBrightPos.X:=1;
      if FBrightPos.X<0 then FBrightPos.X:=0;
      if FBrightPos.Y>1 then FBrightPos.Y:=1;
      if FBrightPos.Y<0 then FBrightPos.Y:=0;
      Paint;
     end;
  end;

  [ObservableMembers('ColorOn',false)]
  TDiode = class(TCircle)
  private
    { Déclarations privées }
    FOnOff : Boolean;
    FColorOn : TAlphaColor;
    FColorOff : TAlphaColor;
    FBrightPos: TPosition;
    FBrightColor: TAlphaColor;
    procedure ObserverToggle(const AObserver: IObserver; const Value: Boolean);
    procedure SetColorOff(const Value: TAlphaColor);
    procedure SetOnOff(const Value: Boolean);
    procedure SetColorOn(const Value: TAlphaColor);
    procedure SetBrightPosition(const Value: TPosition);
    procedure SetBrightColor(const Value: TAlphaColor);
 protected
    { Déclarations protégées }
    function CanObserve(const ID: Integer): Boolean; override;  { declaration is in System.Classes }
    procedure ObserverAdded(const ID: Integer; const Observer: IObserver); override; { declaration is in System.Classes }
    procedure ChangeBrightPos(sender : TObject);
  public
    { Déclarations publiques }
    constructor Create(AOwner: TComponent); override;
    destructor Destroy; override;
    function Paint: Boolean; reintroduce;
    property BrightPosition : TPosition read FBrightPos write SetBrightPosition;
  published
    { Déclarations publiées }
    property OnOff : Boolean read FOnOff write SetOnOff;
    property ColorOn : TAlphaColor read FColorOn write SetColorOn;
    property ColorOff : TAlphaColor read FColorOff write SetColorOff;
    property BrightColor : TAlphaColor read FBrightColor write SetBrightColor;
  end;

L’assignation de l’évènement se fera dans le constructeur de la diode.

  constructor TDiode.Create(AOwner: TComponent);
  begin
    if not(csloading in ComponentState) then
    begin
      inherited;
      FOnOff:=True;
      FColorOff:=TAlphaColors.Lightgray;
      FColorOn:=TAlphaColors.Red;
      FBrightPos:=TPosition.Create(PointF(0.5,0.5));
      FBrightPos.OnChange:=ChangeBrightPos;
      FBrightColor:=TAlphaColors.Antiquewhite;
      Fill.DefaultColor:=FColorOn;
      Fill.Color:=FColorOn;
      Fill.Gradient.Color:=FColorOn;
      Fill.Gradient.Color1:=FBrightColor;
      Fill.Kind:=TBrushKind.Gradient;
      Fill.Gradient.Style:=TGradientStyle.Radial;
      Fill.Gradient.RadialTransform.RotationCenter.X :=FBrightPos.X;
      Fill.Gradient.RadialTransform.RotationCenter.Y :=FBrightPos.Y;
      Paint;
    end;
  end;

Avant d’installer, n’oublions pas de modifier l’unité « design » Lug.FMX.DiodeD pour déclarer ce nouveau composant et l’inclure dans la palette.

  RegisterComponents('Govel', [Tdiode,TdiodeEx]) ;

Après l’installation, nous avons maintenant deux composants Diode et DiodeEx dans la palette Govel.
Positionnons quelques éléments supplémentaires sur la forme de départ :

• Remplaçons la diode par le nouveau composant DiodeEx.
• Un ColorListbox pour donner une couleur à l’éclat.
• Ajoutons deux TrackBars qui déplaceront la lumière intérieure. C’est plus un gadget qu’autre chose mais cela permettra de montrer l’utilisation des CustomFormats.

• Un CheckBox pour activer ou désactiver la diode, qui écrasera la valeur pouvant être contenue dans l’ensemble de données prototype.
• Puis établissons quelques liaisons.

Une fois ces éléments indiqués, le programme est fonctionnel et toujours sans aucune ligne de code.

Il est désormais possible de créer le nouveau composant, à dériver de TDiode ou TDiodeEx.

Au préalable, je définis un nouveau type (TDefinedColors), afin de l’utiliser.

 TDefinedColors = Class(TItemCollection<TDiodeDataColor>);

 [ObservableMembers('DataValue',false)]
 TDiodeData = class(TDiodeEx)
  private
    FDataValue: String;
    FColors : TDefinedColors;
    function ColorsStored: Boolean;
    procedure SetColors(const Value: TDefinedColors);
    function FindColor(const Value: String) : TAlphaColor;
    procedure SetDataValue(const Value: String);
  published
    constructor Create(AOwner: TComponent); override;
    destructor Destroy; override;
  public
    property DataValue : String read FDataValue write SetDataValue;
    function Paint: Boolean; reintroduce;
  published
    { Déclarations publiées }
   property Colors : TDefinedColors read FColors write SetColors
      stored ColorsStored;
 end;
...
implementation
...
{ TDiodeData }

function TDiodeData.ColorsStored: Boolean;
begin
  result:=True;
end;

constructor TDiodeData.Create(AOwner: TComponent);
begin
    inherited;
    if (not(csloading in ComponentState)) OR (NOT Assigned(FColors)) then
        FColors:=TDefinedColors.create(Self);
end;

destructor TDiodeData.Destroy;
begin
    FreeAndNil(FColors);
    inherited;
end;

function TDiodeData.FindColor(const Value: String) : TAlphaColor;
var  I: Word;
begin
  for I := 0 to FColors.Count - 1 do
    if TDiodeDataColor(FColors.Items[I]).DataValue= Value then
    begin
      Exit(TDiodeDataColor(FColors.Items[I]).DiodeColor);
    end;
  Result := FColorOff;
end;

function TDiodeData.Paint: Boolean;
var ApplyColor : TAlphacolor;
begin
ApplyColor:=FindColor(FDataValue);
FOnOff:=ApplyColor<>FColorOff;
if FonOff then Fill.Gradient.Color:=ApplyColor
            else Fill.Gradient.Color:=FColorOff;
  Fill.Gradient.Color1:=FBrightColor;
  Fill.Gradient.RadialTransform.RotationCenter.X:=FBrightPos.X;
  Fill.Gradient.RadialTransform.RotationCenter.Y:=FBrightPos.Y;
  Result:=True;
end;

procedure TDiodeData.SetColors(const Value: TDefinedColors);
begin
  FColors.Assign(Value);
end;

procedure TDiodeData.SetDataValue(const Value: String);
begin
  FDataValue := Value;
  Paint;
end;

Par rapport aux composants déjà écrits, vous remarquerez certaines nouveautés, à commencer par la déclaration de la propriété publiée Colors qui est suivie du mot clé stored ainsi que du nom d’une fonction (ColorsStored).

Cette nouvelle propriété nécessite que le constructeur et le destructeur soient surchargés pour réserver et libérer la mémoire.

Une réintroduction de la méthode Paint sera également nécessaire.

Enfin, il faut retrouver la couleur à utiliser en fonction de la valeur du champ, ce qui sera chose faite avec une fonction de classe : FindColor.

Après ajout à la palette et installation de ce nouveau composant, un test rapide peut se réaliser en positionnant sur une forme le nouveau composant et un combobox, puis en créant deux liens.

Le combobox contiendra les éléments (R,O,V).
L’éditeur de collection fera la jonction entre ces éléments et la couleur souhaitée.

Seul bémol, il faudra exécuter le programme pour vérifier que les liaisons et le composant fonctionnent.