Using VBScript Form Components

Utilisation des composants dans les formulaires VBScript

Bien que les formulaires et les composants soient basés sur la Visual Component Library (VCL) d'Embarcadero Delphi™, le Tool Palette basé sur Delphi d'Altium Designer est toujours utilisé pour déposer des contrôles sur un formulaire lors de l'utilisation de VBScript. De plus, les gestionnaires d'événements sont générés et le code est écrit en langage VBScript, indépendamment des origines Delphi des formulaires/composants dans Altium Designer.

Vue d'ensemble des composants

Le système de script gère deux types de composants : les composants visuels et les composants non visuels. Les composants visuels sont utilisés pour construire l'interface utilisateur et les composants non visuels sont utilisés pour différentes tâches, telles que les fonctions fournies par les composants Timer, OpenDialog et MainMenu. Par exemple, le composant non visuel Timer est utilisé pour activer un code spécifique à des intervalles planifiés et n'est jamais visible par un utilisateur. Les composants Button, Edit et Memo sont des composants visuels — ils sont visibles par un utilisateur.

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 le comportement visible, soit les opérations de cet objet. Par exemple, la propriété Visible détermine si cet objet peut être visible 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.

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 à un utilisateur d'effectuer une action. Par exemple, un Label est utilisé pour 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, permettant à un utilisateur d'interagir avec eux lorsque le script est en cours d'exécution. Il appartient au programmeur du script 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 une gamme de composants pour créer des interfaces utilisateur simples ou complexes pour les scripts. Tous les composants pouvant être placés sur un formulaire se trouvent dans le panneau Tool Palette.

Pour placer un composant sur un formulaire, localisez son icône dans le panneau Tool Palette et double-cliquez dessus. Cette action place un composant sur le formulaire actif à sa position par défaut, avec sa largeur et sa hauteur par défaut. La représentation visuelle de la plupart des composants est déterminée par l'ensemble de leurs propriétés associées.

Un composant placé, dans sa position et avec ses dimensions par défaut, peut être redimensionné ou repositionné à l'aide de la souris ou via le panneau Object Inspector. Lorsqu'un composant est déposé sur un formulaire, le système de script génère automatiquement le code de base nécessaire à son utilisation et met à jour le formulaire de script. Pour rendre le composant opérationnel dans le formulaire, il ne reste plus qu'à définir les propriétés, ajouter du code dans les gestionnaires d'événements et utiliser les méthodes selon les besoins.

Conception de formulaires de script

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

Chaque composant placé sur un formulaire de script et chaque propriété définie sont stockés dans un fichier décrivant le formulaire (un fichier *.dfm) et sont liés au code de script associé (le fichier *.vbs). Ainsi, pour chaque formulaire de script, il existe le fichier *.vbs et le fichier *.dfm correspondant.

Lorsque vous travaillez avec un formulaire de script et ses composants, ses propriétés peuvent être consultées et modifiées à l'aide du panneau Object Inspector. Plusieurs composants peuvent être sélectionnés 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 de script. Un formulaire de script possède un titre associé à 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 le projet dans le panneau Projects et sélectionnez les éléments Add New to Project puis VB Script Form dans les menus contextuels. Un nouveau formulaire de script est créé avec le nom par défaut EditScript1.vbs . Sinon, dans un projet *.PrjPCB, sélectionnez la commande File » New » Script Files » VB Script Form.

Affichage d'un formulaire de script

Un script doit comporter une routine qui affiche le formulaire lorsque celui-ci est exécuté dans Altium Designer. Dans cette routine, la méthode ShowModal est appelée pour le formulaire. La propriété Visible du formulaire doit être définie sur false (décochée) pour que la méthode ShowModal du formulaire de script fonctionne correctement.

Exemple ShowModal

Sub RunDialog
  DialogForm.ShowModal
End Sub

L'exemple ShowModal ci-dessus est une manière simple d'afficher le formulaire de script lorsque la boîte de dialogue RunDialog du script est invoqué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 ModalResult présenté ci-dessous est plus complexe. Ses dernières méthodes sont utilisées pour les boutons du formulaire de script. Les méthodes du script provoquent la fermeture de la boîte de dialogue lorsqu'un utilisateur clique sur le bouton OK ou Cancel, ce qui renvoie respectivement mrOk ou mrCancel depuis la méthode ShowModal.

ModalResult Example

sub bOKButtonClick(Sender)
  ModalResult := mrOK
end sub
 
sub bCancelButtonClick(Sender)
  ModalResult := mrCancel
end sub
 
sub RunShowModalExample
  'Form Visible property must be false for ShowModal to work properly.
  If Form.ShowModal = mrOk     Then ShowMessage("mrOk")
  If Form.ShowModal = mrCancel Then ShowMessage("mrCancel")
end sub

La même chose que ci-dessus pourrait être obtenue en définissant la valeur ModalResult sur mrOk pour le bouton OK et sur mrCancel pour le bouton Cancel dans leurs gestionnaires d'événements. Lorsqu'un utilisateur clique sur l'un ou l'autre bouton, 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 a été définie, le moteur de script ferme automatiquement le formulaire de script.

Notez que pour définir le ModalResult du formulaire sur cancel lorsqu'un utilisateur appuie sur la touche Esc, définissez la propriété Cancel du bouton Cancel sur true (cochée) dans le panneau Object Inspector, 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 EditBox. Ce composant EditBox possède un champ de texte dans lequel un utilisateur peut saisir une chaîne de caractères. Il existe également d'autres composants pouvant accepter du texte, comme le composant masked edit, qui est un composant d'édition avec un masque de saisie pour le champ texte. Le masque contrôle, ou filtre, la saisie et est stocké dans une chaîne de paramètres.

L'exemple ci-dessous illustre ce qui se produit lorsqu'un utilisateur clique sur le bouton après avoir saisi du texte dans la zone d'édition. Notez que si un utilisateur n'a saisi aucun texte dans le composant d'édition, le gestionnaire d'événement répond par un message d'avertissement

sub TScriptForm.ButtonClick(Sender)
  If Edit1.Text = "" Then
  ShowMessage("Warning - empty input!")
  Exit
  End
  ' do something else for the input
End sub

Notez qu'un utilisateur peut déplacer le focus de saisie sur le formulaire à l'aide de la touche Tab ou en cliquant sur un autre contrôle du formulaire.

Réponse aux événements

Lorsqu'un formulaire ou un composant est sélectionné par un utilisateur, Altium Designer envoie un message au système de script, qui répond à la notification d'événement en appelant la méthode de gestionnaire d'événement appropriée.

Écriture de gestionnaires d'événements

Un script peut devoir répondre à des événements susceptibles de se produire sur un composant à l'exécution. 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, qui modifie les valeurs des propriétés et appelle des méthodes.

En plus des propriétés d'un composant, chacun possède un ensemble de noms d'événements. Un programmeur de script décide de la manière dont il réagira aux actions d'un utilisateur dans Altium Designer. Par exemple, lorsqu'un utilisateur clique sur un bouton dans 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é.

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'est pas spécifié (OnEnter - le contrôle a le focus ; OnExit - le contrôle perd le focus), l'événement sera ignoré par le script.

Propriétés des composants

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

Événements des composants

Pour voir une liste des événements auxquels un composant peut réagir, sélectionnez un composant et activez l'onglet Events dans le panneau Object Inspector. Pour créer une procédure de gestion d'événement à laquelle un composant doit réagir, choisissez un événement approprié et double-cliquez sur son nom.

Par exemple, sélectionnez le composant Button1 dans le panneau Tool Palette, déposez-le sur le formulaire de script, puis double-cliquez à côté du nom de l'événement OnClick. Le système de script redonnera le focus à l'éditeur de code, où le squelette de code pour l'événement OnClick aura été créé. Si un bouton possède une méthode Close dans son gestionnaire d'événement CloseClick, lorsqu'on clique sur le bouton, son gestionnaire capture l'événement de clic et le code à l'intérieur du gestionnaire est exécuté. Autrement dit, la méthode Close ferme le formulaire de script.

En résumé, un gestionnaire d'événement est créé dans un script en sélectionnant un composant sur le formulaire, ou avec le panneau Object Inspector, puis en double-cliquant à droite de l'événement souhaité (par exemple, OnClick) dans l'onglet Events de l'Inspector — l'ossature de code appropriée apparaîtra dans le script.

Sinon, en double-cliquant sur un bouton, le système de script ajoutera un gestionnaire pour un événement OnClick. D'autres types de composants auront des actions par défaut complètement différentes.

Méthodes des composants

Consultez la référence des composants pour obtenir une liste des méthodes d'un composant, et reportez-vous à la documentation Embarcadero Delphi pour des informations plus détaillées.

Création de composants à l’exécution

Les composants peuvent être créés et détruits directement dans un script. Normalement, il n’est pas nécessaire de transmettre le handle de la fiche, car la fiche du script s’en charge automatiquement — transmettez plutôt un paramètre Nil au constructeur du composant.

Par exemple, les boîtes de dialogue Open et Save peuvent être créées et détruites (les classes TOpenDialog et TSaveDialog, qui font partie de la RTL Delphi).