Writing Scripts

Écriture de scripts

Il existe un certain nombre de concepts et de termes essentiels applicables à l’écriture de scripts :

• Les processus sont des chaînes de commande que vous pouvez utiliser pour exécuter des commandes dans des scripts.
• Les composants sont des objets de contrôle visuels du panneau Tool Palette panel que vous pouvez glisser-déposer sur un formulaire de script afin de manipuler la conception.
• Un composant placé sur un formulaire de script possède des méthodes, des propriétés et des événements.
• Les interfaces objet sont des interfaces objet spéciales que vous pouvez utiliser pour extraire et modifier des données dans les documents de conception à partir de vos scripts.

Langages de script

Le langage de script par défaut est défini sur DelphiScript (*.pas). Le moteur de script lui-même est écrit en Embarcadero Delphi, et le panneau Tool Palette est basé sur la VCL (Visual Component Library) de Delphi.

Une unité DelphiScript

Un exercice de script simple et rapide peut être réalisé en créant d’abord un nouveau projet et un nouveau fichier de script. En supposant que le projet et le fichier de script soient définis sur le langage DelphiScript, un script simple « Hello World » peut être saisi comme ci-dessous.

Procedure ShowAMessage;
Var
 DefaultMessage;
Begin
 DefaultMessage := 'Hello World!';
 ShowMessage(DefaultMessage);
End;

Dans la procédure, il existe une fonction DelphiScript standard ShowMessage qui ouvre une boîte de dialogue avec le message « Hello World », tel que défini par la variable DefaultMessage.

Exécution du script

Pour exécuter l’un des scripts, sélectionnez File » Run Script dans les menus principaux, puis choisissez une procédure de script disponible dans la boîte de dialogue Select Item To Run. Lorsqu’une version est exécutée, une boîte de dialogue s’ouvre pour afficher le message.

Exécution d’une unité de script HelloWorld simple depuis le menu File » Run Script.

Un script peut également être exécuté à l’aide de la commande Exécuter de l’éditeur, accessible via le bouton Run (), le raccourci clavier F9 , ou en sélectionnant Run » Run dans les menus principaux.

Outre la commande Exécuter elle-même, le menu déroulant Run propose une série de commandes de contrôle et de débogage des scripts.

Lorsque la commande Run est sélectionnée pour la première fois, la boîte de dialogue Select Item to Run s’ouvre et vous permet de spécifier la procédure principale d’un script (ShowAMessage dans ce cas). Une fois définie, le script peut être relancé facilement depuis l’éditeur à l’aide de la commande Run . Utilisez Run » Set Project Startup Procedure pour modifier ce réglage vers une autre procédure, ou fermez puis rouvrez le projet de script pour effacer ce réglage.

Pour arrêter un script en cours d’exécution, utilisez le bouton Stop (), sélectionnez Run » Stop dans le menu principal, ou utilisez le raccourci Ctrl+F3.

En développant le projet HelloWorld créé ci-dessus, un script similaire peut être créé à l’aide d’une unité de formulaire.

Un formulaire de script est une fenêtre de dialogue pouvant héberger divers contrôles tels que des boutons, des mémos et des zones de liste. Il possède des gestionnaires d’événements qui réagissent lorsqu’un contrôle génère un événement, par exemple lorsqu’un bouton est cliqué.

Pour créer le nouveau formulaire de script, cliquez avec le bouton droit sur le nom du projet dans le panneau Projects panel, choisissez l’option Add New to Project, puis sélectionnez Script Form. Le script peut être enregistré et renommé à l’aide de File » Save As dans les menus principaux.

Une fois le nouveau projet de script créé, ajoutez un nouveau script au projet.

Pour afficher et modifier les valeurs de propriété du formulaire actuellement actif ou de ses composants, ouvrez le panneau Object Inspector. Le panneau Object Inspector sert à modifier les propriétés du formulaire et à insérer du code dans les gestionnaires d’événements associés au formulaire actif.

La configuration de la fenêtre et les propriétés du formulaire de script sont présentées dans le panneau Object Inspector.

Notez que le formulaire de script propose deux onglets en bas du document : les onglets Code et Form .

L’onglet Code contient les gestionnaires d’événements et les procédures comme indiqué ci-dessus, tandis que l’onglet Form représente la boîte de dialogue et contient les contrôles ainsi que les gestionnaires d’événements associés. Utilisez les onglets ou le raccourci clavier F12 pour passer de l’un à l’autre.

Le panneau Object Inspector vous permet d’examiner et de modifier les propriétés et les événements des composants du formulaire de script actif. Cliquer sur un composant unique du formulaire de script actif dans la fenêtre de l’éditeur de conception sélectionne ce composant et affiche dans le panneau Object Inspector les attributs qui lui sont associés. Vous pouvez également utiliser le champ déroulant en haut du panneau pour choisir dans une liste de tous les composants actuellement placés sur le formulaire actif. Le formulaire lui-même est également inclus.

 
Utilisez le panneau Object Inspector pour configurer la boîte de dialogue du formulaire et son action.

Les informations sont affichées sur deux onglets – Properties et Events :

• L’onglet Properties du panneau répertorie tous les attributs de propriété du composant sélectionné. La liste exacte des attributs disponibles dépend du type particulier de composant actuellement inspecté. Une propriété est une caractéristique d’un objet qui influence soit son comportement visible, soit son fonctionnement. Par exemple, la propriété Visible (dans la sous-catégorie Behavior ) détermine si l’objet est affiché ou non sur le formulaire de script sur lequel il est placé. Les propriétés d’un composant peuvent être modifiées selon les besoins. Cliquez dans le champ à droite d’une propriété, puis saisissez directement une valeur, cochez/décochez une case ou sélectionnez une entrée dans une liste déroulante, selon le cas.
• L’onglet Events du panneau fournit une liste de tous les événements auxquels le composant actuellement sélectionné peut réagir. Là encore, la liste exacte des événements disponibles dépend du type particulier de composant actuellement inspecté. Lorsqu’un événement se produit, par exemple lorsqu’un bouton d’un formulaire est cliqué, le script exécute l’action appropriée, à condition qu’une procédure de gestion de cet événement ait été définie dans le code. Ce type de procédure est appelé gestionnaire d’événement.

La structure de base d’un gestionnaire d’événement peut être ajoutée au code du document de script depuis le panneau Object Inspector. Sélectionnez simplement le composant pour lequel vous souhaitez définir un événement, choisissez le type d’événement concerné, puis double-cliquez dans le champ à droite de l’événement. Un nom est créé pour l’événement et utilisé dans la définition du nom de la procédure de gestion d’événement - FormName.EventName. Le code squelette de la procédure de gestion d’événement est alors ajouté au code principal du script, qui devient l’onglet actif dans l’espace de conception. Le contenu de la procédure de gestion d’événement peut ensuite être codé afin de fournir la réponse souhaitée lorsque l’événement se produit et est détecté par le script en cours d’exécution.

La section inférieure du panneau fournit, lorsqu’elle est disponible, une description récapitulative de la propriété ou de l’événement actuellement sélectionné.

Pour ce script de formulaire, modifiez les propriétés Caption du formulaire dans le panneau Object Inspector de HelloWorldForm à Hello World!. Ces chaînes correspondent à celles utilisées dans l’exemple de gestionnaire d’événement et dans le code de procédure présenté plus bas.

Ajouter et configurer des contrôles

Une fois la forme de base configurée, des contrôles peuvent être ajoutés à la boîte de dialogue selon les besoins en accédant au panneau Tool Palette. Le Tool Palette, basé sur la Visual Component Library de Delphi, est une palette de composants qui offre un large éventail de contrôles de fenêtre organisés en catégories de composants (voir les pages  Scripting Graphical Components et Component Categories pour plus de détails).

Les sections du panneau Tool Palette peuvent être développées et réduites à l’aide des onglets d’en-tête de région.

Utilisez les contrôles en haut du panneau, les noms de catégories et le menu contextuel accessible par clic droit pour configurer la présentation des contrôles dans le panneau : développer/réduire les catégories, modifier la présentation des éléments de la palette, etc.

Pour la version boîte de dialogue du projet « Hello World », il y a deux boutons sur la forme : Display et Close. Cliquez sur TButton dans la région Standard du panneau Tool Palette.

Faites-le deux fois pour placer deux boutons sur la forme. Un bouton sera utilisé pour afficher un message « Hello World! » dans une boîte de dialogue distincte, et le second bouton servira à fermer la boîte de dialogue principale.

Tous les composants du panneau possèdent des propriétés, des méthodes et des événements associés, où :

• Une Property est une caractéristique d’un objet qui influence soit son comportement visible, soit son fonctionnement. Par exemple, la propriété Visible détermine si un objet peut être vu sur une forme de script.
• Une Method est une procédure toujours associée à un objet et qui définit le comportement de cet objet.
• Un Event est une action ou une occurrence détectée 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.

Les propriétés et événements d’un composant peuvent être examinés et modifiés après son placement à l’aide du panneau Object Inspector.

À l’aide du panneau Object Inspector, les configurations des deux boutons peuvent être modifiées à partir de leurs noms et légendes par défaut.

Configurez le nom du premier bouton sur bDisplay et sa légende sur Display. Configurez le nom du second bouton sur bClose et sa légende sur Close. Cela permet de correspondre à l’exemple de code de gestionnaire d’événement présenté ci-dessous.

Sélectionnez un composant et modifiez ses propriétés dans le panneau Object Inspector.

Le code du gestionnaire d’événement peut être construit en référençant directement les contrôles de la forme. Dans cet exemple, le bouton Display déclenchera une boîte de dialogue ShowMessage au-dessus de la forme existante, et l’action du bouton Close fermera cette forme.

Code du gestionnaire d’événement

Un double-clic sur le bouton Display ouvrira la forme en vue Code et créera le squelette de code pour son gestionnaire d’événement. Sinon, sélectionnez le bouton puis l’onglet Events dans le panneau Object Inspector. Un double-clic sur l’événement OnClick dans le panneau ouvrira la vue Code comme ci-dessus. Dans la vue Code, l’instruction ShowMessage peut être incluse dans le gestionnaire d’événement comme indiqué dans la liste ci-dessous.

Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
 ShowMessage('Hello World!');
End;

Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
 Close;
End;

Une fois les gestionnaires d’événement définis, il doit y avoir une procédure dans le script qui servira de point de départ lors de l’appel de la boîte de dialogue depuis le logiciel. Celle-ci est ajoutée à la fin du script de code.

Notez que le nom de la forme est HelloWorldForm et que le nom de la procédure est RunHelloWorld — il est important d’avoir des noms de forme uniques dans un même script afin d’éviter les conflits de noms de forme.

Procedure RunHelloWorld;
Begin
 HelloWorldForm.ShowModal;
End;

Le script peut être enregistré puis exécuté depuis les menus principaux (File» Run Script) en exécutant l’élément de procédure RunHelloWorld sous l’entrée HelloWorldDialog.

Sinon, la procédure peut être affectée à la commande/bouton Run () via le menu Run » Set Startup Project Procedure.

Exécution d’un script de forme HelloWorld, où le bouton Display de la forme active une boîte de dialogue ShowMessage.

Le panneau Object Inspector permet de modifier facilement les propriétés et événements d’une unité de forme. Par exemple, pour changer la position de la forme dans l’espace de travail, utilisez le panneau pour modifier la valeur poScreenCenter de la propriété de position de la forme. La boîte de dialogue sera alors placée au centre de l’écran du bureau lorsque le script sera exécuté.

Appel d’une procédure

Comme indiqué ci-dessus, tout script (utilisant le même langage) au sein d’un projet a accès aux variables globales et aux procédures ; ainsi, une procédure dans un script peut appeler une autre procédure dans un script différent du projet.

Cela peut être démontré par la section de code supplémentaire ShowAParametricMessage dans le projet d’exemple HelloWorld :

Procedure ShowAParametricMessage(S : String);
Var
    DefaultMessage;
Begin
    DefaultMessage := 'Hello World!';

    If S = '' Then ShowMessage(DefaultMessage)
              Else ShowMessage(S);
End;

Cela établit une variable chaîne « S » qui peut être transmise à la procédure ShowAParametricMessage.

La chaîne transmise sera affichée à l’aide de la fonction de boîte de dialogue ShowMessage, tandis qu’une simple méthode If-Then-Else provoque l’affichage d’un message « Hello World! » par défaut si la chaîne est vide.

Pour voir cela en action, ouvrez le projet d’exemple (HelloWorld.PrjScr) et ajoutez la ligne surlignée en gris dans le script HelloWorldDialog (et non dans le script HelloWorld), comme indiqué ci-dessous.

...
Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
    Showmessage('Hello World!');
End;

Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
    ShowAParametricMessage('Goodbye World');
    close;
End;

Procedure RunHelloWorld;
Begin
    HelloWorldForm.ShowModal;
End;
...

Lorsque le script HelloWorldDialog est exécuté et que le bouton Close est cliqué, la procédure globale ShowAParametricMessage est appelée depuis le script HelloWorld.

Une procédure paramétrique du script HelloWorld est appelée depuis le script HelloWorldDialog.

L’appel transmet la chaîne de message « Goodbye World » à la procédure ShowAParametricMessage, de sorte que ce message s’affiche lorsque le bouton Fermer est cliqué, avant la fermeture de la forme.

L’appel de script présenté ci-dessus insère un message spécifié dans la procédure de fermeture de la forme HelloWoldDialog.

Si le paramètre de chaîne transmis est vide, ShowAParametricMessage(''), le message « Hello World! » par défaut s’affiche comme défini dans la procédure ShowAParametricMessage.

Parcourir les identifiants de script à l’aide du panneau Code Explorer

Le panneau Code Explorer fournit un résumé visuel de tous les identifiants (variables, fonctions et procédures) utilisés dans le document de script actif.

Le panneau Code Explorer

Les informations sur les identifiants qui apparaissent dans le panneau sont regroupées dans les dossiers de niveau supérieur suivants :

• Procedures & Functions – inclut toutes les procédures et fonctions déclarées dans le document de script actif. Pour chaque procédure/fonction, tous les paramètres transmis à la procédure/fonction ou les variables qui lui sont locales sont également répertoriés.

  

• Variables – inclut toutes les variables globales déclarées dans le document de script actif.

  

Si des variables locales sont déclarées pour une procédure/fonction, elles apparaîtront dans un sous-dossier de variables, sous cette procédure/fonction. Des icônes distinctes sont utilisées pour différencier les divers identifiants :

Un double-clic sur une entrée dans le panneau (ou sa sélection puis l’appui sur la touche Enter) permet d’accéder à la zone de code correspondante dans l’espace de conception.