Forms & Components

Présentation des composants graphiques

Le système de script gère deux types de composants : les composants visuels et les composants non visuels.

Les composants visuels servent à construire l’interface utilisateur, tandis que les composants non visuels sont utilisés pour différentes tâches, telles que les composants Timer, OpenDialog et MainMenu.

• Le composant non visuel Timer peut être utilisé pour activer un code spécifique à intervalles planifiés, et il n’est jamais visible par l’utilisateur.
• Les composants Button, Edit et Memo sont des composants visuels.

Les deux types de composants apparaissent au moment de la conception, mais les composants non visuels ne sont pas visibles à l’exécution. Les composants du panneau Tool Palette sont orientés objet et comportent les trois éléments suivants :

• Propriétés
• Événements
• Méthodes

Une Property est une caractéristique d’un objet qui influence soit son comportement visible, soit ses opérations. Par exemple, la propriété Visible détermine si cet objet peut être vu ou non sur un formulaire de script.

Un Event est une action ou un événement détecté par le script. Dans un script, le programmeur écrit du code pour chaque gestionnaire d’événement conçu pour capturer un événement spécifique, tel qu’un clic de souris.

Une Method est une procédure toujours associée à un objet et qui définit le comportement de cet objet.

Tous les formulaires de script comportent un ou plusieurs composants. Les composants affichent généralement des informations ou permettent à l’utilisateur d’effectuer une action. Par exemple, un Label sert à afficher du texte statique, une zone Edit permet à un utilisateur de saisir des données, et un Button peut être utilisé pour lancer des actions.

Toute combinaison de composants peut être placée sur un formulaire et, pendant l’exécution du script, un utilisateur peut interagir avec n’importe quel composant du formulaire. Il appartient au programmeur de décider ce qui se passe lorsqu’un utilisateur clique sur un bouton ou modifie le texte dans une zone Edit.

Le système de script fournit un certain nombre de composants pouvant être utilisés pour créer des interfaces utilisateur complexes pour les scripts. Pour placer un composant sur un formulaire, localisez son icône dans le panneau Tool Palette panel et double-cliquez dessus. Cette action place un composant sur le formulaire actif. La représentation visuelle de la plupart des composants est définie par leurs propriétés. Un composant est initialement placé à une position par défaut sur le formulaire, mais il peut être repositionné (glissé) et redimensionné (étiré) selon les besoins. Vous pouvez également modifier ultérieurement sa taille et sa position à l’aide du panneau Object Inspector .

Lorsqu’un composant est déposé sur un formulaire, le système de script génère automatiquement le code nécessaire à son utilisation et met à jour le formulaire de script. Il suffit ensuite de définir les propriétés et d’implémenter le code du gestionnaire d’événement pour utiliser les méthodes souhaitées afin de rendre le composant opérationnel sur le formulaire.

Conception de formulaires de script

Un formulaire de script est conçu pour interagir avec l’utilisateur dans l’environnement. La conception de formulaires de script est au cœur du développement visuel.

En pratique, tous les composants sont placés sur un formulaire de script, et chaque propriété définie est stockée dans un fichier décrivant le formulaire (un fichier *.DFM) qui est lié au code de script associé (le fichier *.PAS). Pour chaque formulaire de script, il existe le fichier .PAS et son fichier .DFM correspondant.

Lorsque vous travaillez avec un formulaire de script et ses composants, toutes les propriétés des éléments peuvent être examinées et modifiées à l’aide du panneau Object Inspector. Vous pouvez sélectionner plusieurs composants en maintenant la touche Maj enfoncée tout en cliquant sur les composants, ou en faisant glisser un rectangle de sélection autour des composants sur le formulaire. Un formulaire de script possède un titre (la propriété Caption dans le panneau Object Inspector).

Création d’un nouveau formulaire de script

Avec un projet de script ouvert, cliquez avec le bouton droit sur un projet dans le panneau Projects, cliquez sur l’élément Add New to Project dans le menu contextuel, puis choisissez un élément Delphi Script Form. Un nouveau formulaire de script s’ouvrira avec le nom par défaut EditScript1.pas.

Affichage d’un formulaire de script

Un script doit comporter une procédure qui affiche le formulaire lorsque le formulaire de script est exécuté. Dans cette procédure, la méthode ShowModal peut être appelée pour le formulaire. La propriété Visible du formulaire doit être définie sur false pour que la méthode ShowModal du formulaire de script fonctionne correctement.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

L’exemple ShowModal présente une approche très simple pour afficher le formulaire de script lorsque la procédure RunDialog est appelée. Notez que des valeurs peuvent être affectées aux composants de l’objet DialogForm avant l’appel de la méthode DialogForm.ShowModal.

L’exemple de propriété ModalResult présenté ci-dessous est un peu plus complexe. Les méthodes suivantes du script sont utilisées pour les boutons d’un formulaire de script. Les méthodes provoquent la fermeture de la boîte de dialogue lorsque l’utilisateur clique sur le bouton OK ou Cancel, ce qui renvoie respectivement mrOk ou mrCancel depuis la méthode ShowModal.

ModalResult Example:

Procedure TForm.OKButtonClick(Sender: TObject);
Begin
  ModalResult := mrOK;
End;

Procedure TForm.CancelButtonClick(Sender: TObject);
Begin
  ModalResult := mrCancel;
End;

Procedure RunShowModalExample;
Begin
  // Form's Visible property must be false for ShowModal to work correctly.
  If Form.ShowModal = mrOk Then ShowMessage('mrOk');
  If Form.ShowModal = mrCancel Then ShowMessage('mrCancel');
End;

Lorsque l’utilisateur clique sur l’un ou l’autre bouton de ce formulaire de script, la boîte de dialogue se ferme. Il n’est pas nécessaire d’appeler la méthode Close, car lorsque la méthode ModalResult est définie, le moteur de script ferme automatiquement le formulaire de script.

Notez que si vous souhaitez définir le ModalResult du formulaire sur Cancel lorsqu’un utilisateur appuie sur la touche Esc , utilisez le panneau Object Inspector  pour définir la propriété Cancel du bouton Cancel sur True, ou insérez Sender.Cancel := True dans le gestionnaire d’événement CancelButtonClick du bouton du formulaire.

Acceptation des saisies utilisateur

L’un des composants courants pouvant accepter une saisie utilisateur est le composant TEdit. Ce composant comporte un champ dans lequel l’utilisateur peut saisir une chaîne de caractères. Notez qu’il existe d’autres composants Delphi tels que TMaskEdit, qui est un composant d’édition avec un masque de saisie stocké dans une chaîne — celui-ci contrôle ou filtre la saisie.

L’exemple ci-dessous illustre le processus lorsque l’utilisateur clique sur le bouton après avoir saisi quelque chose dans la zone d’édition. Si l’utilisateur n’a rien saisi dans le composant d’édition (vide), le gestionnaire d’événement répond par un message d’avertissement.

Procedure TScriptForm.ButtonClick(Sender : TObject);
Begin
  If Edit1.Text = '' Then
  Begin
    ShowMessage('Warning - empty input!');
    Exit;
  End;
  // do something else for the input
End;

Notez qu’un utilisateur peut modifier le focus de saisie de la boîte de dialogue à l’aide de la touche Tab ou en cliquant sur un autre contrôle du formulaire.

Réponse aux événements

Lorsqu’un bouton sur un formulaire ou un composant est cliqué, le système de script répond en recevant une notification d’événement de Altium Designer et en appelant la méthode de gestionnaire d’événement appropriée.

See also
Le projet HelloWorld du dossier Scripts\DelphiScript Scripts\General\ de la collection de scripts .
L’exemple de script ShowModal du dossier Scripts\DelphiScript Scripts\General\ de la collection de scripts .

Écriture de gestionnaires d’événements

Chaque composant d’un script de formulaire possède un ensemble de noms d’événements, utilisés par les gestionnaires d’événements du script pour déterminer comment le script réagira aux actions de l’utilisateur dans Altium Designer. Par exemple, lorsqu’un utilisateur clique sur un bouton d’un formulaire, Altium Designer envoie un message au script et le script réagit à ce nouvel événement. Si l’événement OnClick d’un bouton est spécifié, il est exécuté.

Le code de réponse aux événements est normalement contenu dans des gestionnaires d’événements DelphiScript, et tous les composants disposent d’un ensemble d’événements auxquels ils peuvent réagir. Par exemple, tous les composants cliquables possèdent un événement OnClick qui se déclenche lorsqu’un utilisateur clique sur un composant. Tous ces composants possèdent également un événement pour recevoir et perdre le focus. Cependant, si le code pour OnEnter et OnExit n’a pas été spécifié (OnEnter - le contrôle a reçu le focus ; OnExit - le contrôle a perdu le focus), l’événement sera ignoré par un script.

En résumé, un événement est un lien entre une occurrence dans Altium Designer, telle qu’un clic sur un bouton, et un morceau de code qui répond à cette occurrence. Le code de réponse est un gestionnaire d’événement. Ce code modifie les valeurs des propriétés et appelle des méthodes.

Propriétés du composant

Pour voir une liste des propriétés d’un composant, sélectionnez un composant et ouvrez l’onglet Properties dans le panneau Object Inspector.

Événements du composant

Pour voir une liste des événements auxquels un composant peut réagir, sélectionnez un composant et ouvrez l’onglet Events dans le panneau Object Inspector. Pour créer une procédure de gestion d’événement, sélectionnez l’événement auquel vous souhaitez que le composant réagisse et double-cliquez sur le nom de l’événement — le système de script insérera automatiquement le code de base du gestionnaire d’événement.

Par exemple, sélectionnez le composant TButton dans le panneau Tool Palette et déposez-le sur le formulaire de script, puis double-cliquez à côté du nom de l’événement OnClick dans le panneau Object Inspector . Le système de script placera l’éditeur de code au premier plan et le code squelette de l’événement OnClick sera créé.

Si un bouton possède une méthode Close dans le gestionnaire d’événement CloseClick, par exemple, lorsque le bouton est cliqué, le gestionnaire d’événement du bouton capturera l’événement OnClick, ce qui entraînera l’exécution du code à l’intérieur du gestionnaire d’événement. Par conséquent, la méthode Close ferme le formulaire de script.

En résumé, sélectionnez un composant bouton soit sur le formulaire, soit à l’aide du panneau Object Inspector, sélectionnez la page Events, puis double-cliquez sur le côté droit de l’événement OnClick et un nouveau gestionnaire d’événement apparaîtra dans le script. Vous pouvez également double-cliquer sur le bouton lui-même, et le système de script ajoutera un gestionnaire pour cet événement OnClick. Notez que d’autres types de composants auront des actions par défaut différentes.

Méthodes du composant

Pour voir une liste des méthodes d’un composant, consultez le document Component Reference.

Dépôt de composants sur un formulaire de script

Pour utiliser des composants du panneau Tool Palette dans un script, un formulaire de script doit exister avant que des composants puissent y être déposés. Normalement, lorsque des composants sont déposés sur un formulaire de script, ces objets n’ont pas besoin d’être créés ni détruits — le formulaire de script s’en charge automatiquement.

Le système de script génère également automatiquement le code nécessaire pour utiliser un composant et met à jour le formulaire de script. Il ne reste alors plus qu’à définir les propriétés, placer le code dans les gestionnaires d’événements et utiliser les méthodes requises pour implémenter un formulaire de script fonctionnel.

Création de composants dans un script

Les composants peuvent être créés ou détruits directement dans un script en passant un paramètre Nil au Constructor d’un composant. Normalement, vous n’avez pas besoin de transmettre le handle du formulaire, car le formulaire de script s’en charge automatiquement. Par exemple, vous pouvez créer et détruire des boîtes de dialogue Open et Save (classes TOpenDialog et TSaveDialog de la RTL Delphi d’Embarcadero).

Personnalisation des formulaires de script

Les points essentiels pour personnaliser les formulaires de script sont les suivants :

• Pour forcer un formulaire à rester au-dessus des autres panneaux ouverts, définissez la propriété FormStyle sur fsStayOnTop.
• Pour définir le comportement par défaut d’un formulaire, définissez FormKind sur l’une des valeurs suivantes : fkNone, fkNormal, fkServerPanel ou fkModal.
• Si fkModal est fermé, le formulaire sera modal — c’est-à-dire qu’il attendra une saisie de l’utilisateur avant de poursuivre, par exemple pour fermer le formulaire. Si fkServerPanel, le formulaire sera affiché comme un panneau Server. Si fkNormal, le formulaire se comporte comme un formulaire normal non modal.
• Pour supprimer les barres de défilement par défaut du formulaire, modifiez la valeur des propriétés HorzScrollBar et VertScrollBar.
• Pour faire du formulaire un cadre MDI ou un enfant MDI, utilisez la propriété FormStyle.
• Pour modifier le style de bordure du formulaire, utilisez les propriétés BorderIcons et BorderStyle (les résultats sont visibles à l’exécution).
• Pour modifier l’icône du formulaire lorsqu’il est réduit, utilisez la propriété Icon.
• Pour spécifier la position initiale d’un formulaire dans la fenêtre de l’application, utilisez la propriété Position.
• Pour spécifier l’état initial du formulaire (par ex., réduit, agrandi ou normal), utilisez la propriété WindowState.
• Pour définir la zone de travail du formulaire à l’exécution, utilisez les propriétés ClientHeight et ClientWidth (notez que ClientHeight et ClientWidth représentent la zone à l’intérieur de la bordure du formulaire ; Height et Width représentent la zone totale du formulaire).
• Pour spécifier quel contrôle reçoit le focus initial dans le formulaire à l’exécution, utilisez la propriété ActiveControl.
• Pour transmettre tous les événements clavier au formulaire, quel que soit le contrôle sélectionné, utilisez la propriété KeyPreview.
• Pour spécifier un menu particulier, si un formulaire contient plus d’un menu, utilisez la propriété Menu.

Actualisation des formulaires de script et des composants

Lorsque la surface d’un formulaire de script n’est plus à jour, par exemple lorsque les contrôles ne sont pas mis à jour ou redessinés, les contrôles peuvent sembler figés ou corrompus — cela peut être dû à un traitement intensif en arrière-plan par ce script.

La méthode Update du formulaire de script, ainsi que de nombreux composants de script du panneau Tool Palette , permettent d’actualiser le contenu graphique du formulaire ou du ou des contrôles spécifiques. Les lignes contenant la méthode Update sont surlignées en gris dans l’exemple ci-dessous.

StatusBar component and its Update method Example:

Procedure TConverterForm.loadbuttonClick(Sender: TObject);
Begin
 If OpenPictureDialog1.Execute then
 Begin
 XPProgressBar1.Position := 0;
 XStatusBar1.SimpleText  := '  Loading...';
 XStatusBar1.Update;
 
 // loading a monochrome bitmap only
 Image1.Picture.LoadFromFile(OpenPictureDialog1.FileName);
 
 // Check if image is monochrome, otherwise prompt a warning
 If Image1.Picture.Bitmap.PixelFormat <> pf1bit Then
 Begin
 ShowWarning('The image is not a monochrome!');
 Close;
 End;
 
 lImageSize.Caption := IntToStr(Image1.Picture.Width) + ' x ' +
 IntToStr(Image1.Picture.Height) + ' mils';
 
 convertbutton.Enabled  := True;
 LoadButton.Enabled     := False;
 XStatusBar1.SimpleText := '  Ready...';
 XStatusBar1.Update;
 End;
End;

L’extrait de code ci-dessus provient du projet de script PCB Logo Creator, qui se trouve dans le dossier Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator de la collection de scripts téléchargeable.