Formulaires et composants

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 Timer, OpenDialog et MainMenu .

• Le Timer composant non visuel peut être utilisé pour déclencher un code spécifique à intervalles réguliers ; il n’est jamais visible par l’utilisateur.
• La Button, Edit et Memo sont des composants visuels.

Les deux types de composants apparaissent lors de la conception, mais les composants non visuels ne sont pas visibles lors de l'exécution. Les composants du 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 est visible ou non dans 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.

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

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 est utilisé pour afficher du texte statique, une Edit zone de saisie permet à l'utilisateur de saisir des données, un Button peut servir à déclencher des actions.

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

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, repérez son icône dans lepanneau « Palette d’outils » et double-cliquez dessus. Cette action place le 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é à un emplacement par défaut sur le formulaire, mais il peut être repositionné (glissé) et redimensionné (étiré) selon les besoins. Vous pouvez également modifier sa taille et sa position ultérieurement à l’aide du Object Inspector panneau.

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 de définir les propriétés et d’implémenter le code du gestionnaire d’événements pour utiliser les méthodes souhaitées et faire fonctionner le composant sur le formulaire.

Conception de formulaires de script

Un formulaire de script est conçu pour interagir avec l’utilisateur au sein de 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 *.DFM fichier) qui est lié au code de script associé (le *.PAS fichier). À chaque formulaire de script correspond le .PAS fichier et son .DFM fichier.

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

Création d’un nouveau formulaire de script

Une fois un projet de script ouvert, cliquez avec le bouton droit sur un projet dans le Projects panneau, cliquez sur l’ Add New to Project élément dans le menu contextuel qui s'affiche, puis choisissez un Delphi Script Form élément. 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 celui-ci est exécuté. Au sein de cette procédure, la ShowModal méthode peut être appelée pour le formulaire. La Visible propriété du formulaire doit être définie sur « false » pour que la ShowModal méthode du formulaire de script fonctionne correctement.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

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

L’ ModalResult exemple de propriété 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. Ces méthodes provoquent la fermeture de la boîte de dialogue lorsque l’utilisateur clique sur l’un des boutons OK ou Cancel , ce qui renvoie mrOk ou mrCancel à partir de la ShowModal méthode, respectivement.

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 des boutons de ce formulaire de script, la boîte de dialogue se ferme. Il n’est pas nécessaire d’appeler la Close méthode, car lorsque la ModalResult méthode est définie, le moteur de script ferme automatiquement le formulaire de script.

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

Accepter les entrées de l’utilisateur

L'un des composants courants permettant d'accepter les entrées de l'utilisateur est le TEdit . Ce composant dispose d’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 doté d'un masque de saisie stocké dans une chaîne de caractères — celui-ci contrôle ou filtre la saisie.

L'exemple ci-dessous illustre le processus qui se déroule 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 (champ vide), le gestionnaire d'événements affiche 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 déplacer le focus de la boîte de dialogue à l’aide de la Tab ou en cliquant sur un autre contrôle du formulaire.

Réponse aux événements

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

See also
Le projet HelloWorld situé dans le Scripts\DelphiScript Scripts\General\ dossier de la collection de scripts.
Le script d'exemple ShowModal situé dans le Scripts\DelphiScript Scripts\General\ dossier de la collection de scripts.

Écriture de gestionnaires d’événements

Chaque composant d’un script de formulaire dispose d’un ensemble de noms d’événements, qui sont utilisés par les gestionnaires d’événements du script pour déterminer comment celui-ci 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 celui-ci réagit à ce nouvel événement. Si l’ OnClick événement associé à un bouton est spécifié, celui-ci est exécuté.

Le code permettant de répondre aux événements est généralement contenu dans les 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 disposent d’un OnClick événement qui se déclenche lorsqu’un utilisateur clique sur un composant. Tous ces composants disposent également d’un événement pour l’obtention et la perte du focus. Cependant, si le code pour OnEnter et OnExit n’a pas été défini (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 un événement dans Altium Designer, tel que le clic sur un bouton, et un fragment de code qui répond à cet événement. Le code de réponse est un gestionnaire d’événements. Ce code modifie les valeurs des propriétés et appelle des méthodes.

Propriétés d’un composant

Pour afficher la liste des propriétés d’un composant, sélectionnez-le puis ouvrez l’ Properties onglet du Object Inspector panneau.

Événements du composant

Pour afficher la liste des événements auxquels un composant peut réagir, sélectionnez un composant et ouvrez l' Events onglet du Object Inspector panneau. Pour créer une procédure de gestion d’événement, sélectionnez l’événement auquel vous souhaitez que le composant réagisse, puis 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 TButton composant dans le Tool Palette panneau et déposez-le sur le formulaire de script, puis double-cliquez à côté du OnClick nom de l’événement dans le Object Inspector panneau. Le système de script mettra l’éditeur de code au premier plan et le code squelette de l’ OnClick sera généré.

Si un bouton possède une Close méthode dans le CloseClick gestionnaire d’événements, par exemple, lorsque l’on clique sur ce bouton, le gestionnaire d’événements du bouton capturera l’ OnClick événement, ce qui entraînera l’exécution du code contenu dans ce gestionnaire. Par conséquent, la Close méthode fermera le formulaire de script.

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

Méthodes des composants

Pour consulter la liste des méthodes d’un composant, reportez-vous au document « Référence des composants ».

Déposer des composants sur un formulaire de script

Pour utiliser les composants du panneau « Palette d’outils » dans un script, un formulaire de script doit exister avant que les 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 ou détruits : le formulaire de script s’en charge automatiquement.

Le système de script génère également automatiquement le code nécessaire à l’utilisation d’un composant et met à jour le formulaire de script. Il suffit ensuite de définir les propriétés, d’insérer du code dans les gestionnaires d’événements et d’utiliser les méthodes requises pour mettre en œuvre un formulaire de script fonctionnel.

Création de composants dans un script

Les composants peuvent être directement créés ou détruits dans un script en passant un Nil paramètre à la Constructor d’un composant. En règle générale, vous n’avez pas besoin de passer le descripteur du formulaire, car le formulaire de script s’en charge automatiquement. Par exemple, vous pouvez créer et détruire Open et Save boîtes de dialogue (TOpenDialog et TSaveDialog de la bibliothèque RTL d’Embarcadero Delphi).

Personnalisation des formulaires de script

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

• Pour forcer un formulaire à rester au premier plan par rapport aux autres panneaux ouverts, définissez la FormStyle propriété sur fsStayOnTop.
• Pour définir le comportement par défaut d'un formulaire, définissez la FormKind sur l’une des valeurs suivantes : fkNone, fkNormal, fkServerPanel ou fkModal.
• Si fkModal est fermé, alors le formulaire sera un formulaire modal — c’est-à-dire qu’il attendra une action de l’utilisateur avant de poursuivre, par exemple la fermeture du formulaire. Si fkServerPanel alors le formulaire s’affichera sous la forme d’un panneau serveur. Si fkNormal alors 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 de l’attribut HorzScrollBar et VertScrollBar .
• Pour faire du formulaire un cadre MDI ou un enfant MDI, utilisez la FormStyle .
• Pour modifier le style de bordure du formulaire, utilisez la BorderIcons et BorderStyle (les résultats sont visibles à l'exécution).
• Pour modifier l'icône du formulaire minimisé, utilisez la Icon propriété.
• Pour spécifier la position initiale d'un formulaire dans la fenêtre de l'application, utilisez la Position propriété.
• Pour définir l'état initial du formulaire (par exemple, minimisé, maximisé ou normal), utilisez la WindowState propriété.
• Pour définir la zone de travail du formulaire lors de l'exécution, utilisez la ClientHeight et ClientWidth (notez que ClientHeight et ClientWidth représentent la zone située à l'intérieur des bordures du formulaire ; Height tandis que Width représentent la zone entière du formulaire).
• Pour spécifier quel contrôle a le focus initial dans le formulaire lors de l'exécution, utilisez la ActiveControl propriété.
• Pour transmettre tous les événements clavier au formulaire, quel que soit le contrôle sélectionné, utilisez la KeyPreview propriété.
• Pour spécifier un menu particulier, si un formulaire contient plusieurs menus, utilisez la Menu propriété.

Actualisation des formulaires et composants de script

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

La Update méthode du formulaire de script, ainsi que de nombreux composants de script du Tool Palette panneau, permettent d’actualiser le contenu graphique du formulaire ou d’un ou plusieurs contrôles spécifiques. Les lignes contenant la Update méthode 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 est tiré du PCB Logo Creator projet de script, disponible dans le Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator dossier de la collection de scripts téléchargeables.