Scripting Graphical Components

Cette référence présente les composants graphiques pris en charge pour le scripting ainsi que leurs principales propriétés et méthodes.

Les composants de formulaire visuels disponibles pour les scripts dans Altium Designer dérivent pour la plupart de la Visual Component Library (VCL) d’Embarcadero, qui est un ensemble de composants visuels définis pour développer des applications Windows à l’aide des langages Delphi et C++.

Développées comme une bibliothèque de classes visuelles, les classes VCL descendent de l’objet TComponent (lui-même descendant de l’objet racine TObject) dans une hiérarchie d’objets linéaire. Par conséquent, un composant de script courant, tel que l’objet TButton, hérite des propriétés, méthodes et événements de ses objets ascendants. Dans ce cas, la hiérarchie de classes est : TObject → TPersistent → TComponent → TControl → TWinControl → TButtonControl → TButton.

Notez que les composants qui descendent de l’objet TControl sont généralement des composants visuels (contrôles), et que les composants courants qui descendent de TWinControl sont principalement des encapsulations de l’API Windows.

► Voir Embarcadero RAD Studio VCL pour une vue d’ensemble de l’architecture et des composants VCL.

Lors de la création d’un formulaire dans l’éditeur de scripts d’Altium Designer, les composants sont accessibles depuis le panneau Tool Palette. Les Script Forms possèdent un fichier *.DFM associé qui inclut les détails de la configuration du formulaire, l’emplacement de ses composants et d’autres attributs – ce fichier se trouve dans le dossier hôte du projet de script. Altium Designer permet d’utiliser les composants aussi bien avec DelphiScript qu’avec VBScript lors de la conception des Script Forms.

Le panneau Tool Palette contient des contrôles visuels classés par catégories qui peuvent être déposés sur un Script Form.

Le panneau Tool Palette panel contient des sélections catégorisées de composants pouvant être placés sur un Script Form. Les composants disponibles sont regroupés en sections extensibles dans le panneau Tool Palette, classées comme suit : Standard, Additional, Win32, System, Dialogs, Altium Standard et Instrument Controls.

Les composants (ou « contrôles ») disponibles dans la palette sont des composants visuels lorsqu’ils sont utilisés sur un formulaire de script, ce qui signifie qu’un utilisateur peut voir un contrôle et éventuellement interagir avec lui à l’exécution. Tous les contrôles possèdent des propriétés, des méthodes et des événements qui décrivent des aspects de leur apparence, comme la propriété de position du contrôle, des méthodes pour dessiner ou déplacer le contrôle, et des événements qui répondent aux actions de l’utilisateur.

Les propriétés et les événements sont disponibles dans le panneau Object Inspector panel pour le composant de formulaire actuellement sélectionné, y compris le formulaire lui-même. Les méthodes sont des procédures et des fonctions prises en charge par ce composant.

Vue d’ensemble des Script Forms

Script Forms

Un Script Form est l’interface utilisateur principale dans les scripts, bien qu’il existe d’autres formulaires tels que des boîtes de dialogue, des fenêtres secondaires, etc. Pour créer un nouveau Script Form, avec un projet ouvert dans Altium Designer, sélectionnez File » New » Script » Script Form ou cliquez avec le bouton droit sur le nom du projet de script et choisissez Add New to Project » Script Form. Si le langage VBScript est activé, la commande est disponible à la fois pour VB Script et Delphi Script.

Un nouveau Script Form apparaît avec le nom de formulaire par défaut Form1, qui peut être modifié via la propriété Name (sous Misc) dans le panneau Object Inspector. Les noms de Script Form doivent être uniques dans un projet.

Lors de la conception d’un Script Form, ouvrez le panneau Object Inspector à partir du bouton Script dans la barre d’état inférieure.

Un formulaire vide est essentiellement une fenêtre visuelle à laquelle des contrôles peuvent être ajoutés. Une boîte de dialogue et un panneau sont des types de formulaires différents et, par défaut, un formulaire inclut les fonctionnalités de fenêtre standard suivantes :

• Contrôles
• Boutons Réduire et Agrandir
• Barre de titre
• Redimensionnable par glissement des bordures

Ces fonctionnalités, ainsi que toute autre propriété de formulaire disponible, peuvent être modifiées au moment de la conception à l’aide du panneau Object Inspector. Puisqu’un Script Form est un composant VCL, il comporte les trois éléments suivants :

• Properties – Les caractéristiques d’un objet qui influencent son comportement visible ou ses opérations. Par exemple, la propriété Visible détermine si un objet peut être visible sur un formulaire de script.
• Events – Les actions ou occurrences détectées par le script. Un script doit inclure du code pour chaque gestionnaire d’événement, conçu pour capturer un événement spécifique tel qu’un clic de souris.
• Methods – Les procédures de script associées aux objets (dans ce cas, des objets composants) et qui définissent leur comportement.

► Voir Writing Scripts pour un guide de base sur le développement d’un script basé sur un formulaire.

Propriétés, méthodes et événements du formulaire

Les contrôles du panneau Tool Palette sont basés sur la Visual Component Library (VCL) d’Embarcadero. Pour obtenir tous les détails sur les méthodes, propriétés et événements du composant Form (TForm), reportez-vous à la documentation VCL d’Embarcadero.

► Voir la référence Embarcadero TFormNotez que le lien ci-dessus renvoie à la référence Embarcadero RAD Studio XE6 de la bibliothèque VCL. La documentation des versions précédentes (jusqu’à la version 2010) est également disponible.

Propriétés de TForm

Les propriétés disponibles pour l’objet composant TForm, le formulaire de script de base, peuvent être consultées des façons suivantes :

• Via le panneau Object Inspector – Dans la vue Form de l’éditeur (onglet Form sélectionné), cliquez dans le corps du formulaire lui-même et sélectionnez l’onglet Object Inspector's Properties .

Notez que seuls les objets composants visuels apparaîtront dans le panneau. Les objets non visuels, qui agissent comme des contrôles en arrière-plan, ne sont pas affichés sur le formulaire.

• En utilisant la fonction de complétion de code – Dans la vue Code de l’éditeur (onglet Code sélectionné), la fenêtre de complétion de code contextuelle affiche toutes les options de code pour un nom d’objet.

Pour l’objet Form, saisissez TForm. (notez le point) pour activer la fenêtre. Affinez la recherche en saisissant les premières lettres de la propriété souhaitée – notez que les propriétés et les méthodes sont toutes deux affichées.

• Depuis la documentation de référence Embarcadero sur la page de référence des propriétés TForm.

Méthodes de TForm

Les méthodes disponibles pour l’objet composant TForm peuvent être consultées des façons suivantes :

• Utilisez la fonction de complétion de code – Dans la vue Code de l’éditeur, saisissez un nom de composant suivi d’un point. La fenêtre de complétion de code s’ouvrira pour afficher les méthodes de code (et les propriétés) d’un nom d’objet. Notez que la fenêtre de code peut être activée manuellement avec les touches de raccourci Crtl+Space.

• Reportez-vous à la documentation de référence Embarcadero sur la page de référence des méthodes TForm. Notez que celle-ci affiche toutes les méthodes héritées, bien que cette option puisse être désélectionnée.

Événements de TForm

Les événements disponibles pour l’objet composant TForm peuvent être consultés des façons suivantes :

• Le panneau Object Inspector – Dans la vue Form de l’éditeur, cliquez dans le corps du formulaire lui-même et sélectionnez l’onglet Events de l’Object Inspector.

• La documentation de référence Embarcadero sur la page de référence des événements TFrom.

Propriétés, événements et méthodes des composants

Les contrôles du panneau Tool Palette sont basés sur la Visual Component Library (VCL) d’Embarcadero. Pour obtenir tous les détails sur les méthodes, propriétés et événements de la majorité des composants, reportez-vous aux catégories de composants dans la documentation VCL d’Embarcadero. Certains types de composants dans le Tool Palette, en particulier les Altium Instrument Controls, sont exclusifs à Altium Designer et ne sont pas inclus dans la documentation de référence Embarcadero.

► Voir l’index des catégories de composants VCL EmbarcaderoNotez que le lien ci-dessus renvoie à la référence Embarcadero RAD Studio XE6 pour la bibliothèque VCL. La documentation des versions précédentes (jusqu’à la version 2010) est également disponible.

Propriétés des composants

Pour voir une liste des propriétés d’un composant :

• Sélectionnez un composant sur le formulaire et activez l’onglet Properties dans le panneau Object Inspector – comme illustré ci-dessus pour l’objet composant TForm.
• Sélectionnez le lien Properties (en haut) sur la page de référence du composant approprié dans la documentation de référence Embarcadero. Dans le cas du contrôle TButton par exemple, sélectionnez la catégorie Standard Component, la page TButton, puis la vue Properties.

Événements des composants

Pour voir une liste des événements auxquels un composant peut réagir :

• Sélectionnez un composant sur le formulaire et activez l’onglet Events dans le panneau Object Inspector – comme illustré ci-dessus pour l’objet composant TForm.
• Sélectionnez une page de référence de composant appropriée puis son lien Events dans la documentation de référence Embarcadero. Notez que cela est utile comme guide des événements disponibles pour un composant et peut ne pas correspondre entièrement aux événements disponibles pour les composants de scripting d’Altium Designer.

Pour créer une procédure de gestion d’événement, choisissez l’événement auquel le composant doit réagir dans l’onglet Object Inspector Events et double-cliquez dans le champ de saisie de l’événement. La procédure de gestion d’événement, nommée à partir du composant et de l’action d’événement, est alors générée automatiquement dans le script. Si l’événement est renommé dans le panneau Object Inspector, la procédure de code correspondante est renommée en conséquence.

Méthodes des composants

Cela inclut des références pour les catégories d’objets de contrôle suivantes.

• Standard
• Additional
• Win32
• System
• Dialog
• Altium Standard
• Instrument Controls

Dans la plupart des cas, ces catégories regroupent des types de contrôles visuels de formulaire basés sur des composants VCL standard de type Delphi. Les catégories Altium Standard et Instrument Controls font exception, car elles proposent des composants exclusifs au système de scripting d’Altium Designer.

► Voir les Tool Palette Component Categories.

Utilisation des formulaires et des composants

Personnalisation des Script Forms

• Pour qu’un formulaire reste au-dessus des autres panneaux ouverts, par exemple, 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 sélectionné, le formulaire sera modal. Autrement dit, il attendra une saisie de l’utilisateur avant de poursuivre des actions telles que sa fermeture.
  • Si fkServerPanel est sélectionné, le formulaire sera affiché comme un panneau serveur.
  • Si fkNormal est sélectionné, le formulaire se comporte comme un formulaire normal non modal.
• Pour ajouter/supprimer les barres de défilement d’un formulaire, modifiez la valeur des propriétés HorzScrollBar et VertScrollBar.
• Pour faire du formulaire un cadre ou un enfant MDI (Multiple Document Interface), utilisez la propriété FormStyle.
• Pour modifier le style de bordure d’un formulaire, utilisez les propriétés BorderIcons et BorderStyle. (Les résultats sont visibles à l’exécution.)
• Pour modifier l’icône du formulaire 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 d’un formulaire (par exemple : réduit, agrandi ou normal), utilisez la propriété WindowState.
• Pour définir la zone de travail d’un 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, tandis que Height et Width représentent la zone totale du formulaire.
• Pour spécifier quel contrôle reçoit le focus initial dans un formulaire à l’exécution, utilisez la propriété ActiveControl pour choisir parmi les composants disponibles.
• Pour transmettre tous les événements clavier à un formulaire, quel que soit le contrôle sélectionné, utilisez la propriété KeyPreview.
• Pour spécifier un menu particulier, si un formulaire contient plusieurs menus, utilisez la propriété Menu.

Actualiser les formulaires et les composants

Dans certains cas, l’aspect visuel d’un formulaire de script peut ne plus être à jour, par exemple si un traitement intensif en arrière-plan d’un script empêche la mise à jour ou le redessin des contrôles, qui peuvent alors sembler figés ou corrompus.

La méthode Update du formulaire de script fournit un moyen programmatique d’actualiser le contenu graphique d’un formulaire ou de contrôle(s) spécifique(s). Dans l’exemple de code ci-dessous, les lignes de code de la méthode Update sont mises en évidence en gris.

Using the Update method to refresh the Status Bar:

Procedure TConverterForm.loadbuttonClick(Sender: TObject);
Var
   I, J : Integer;
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
            For J := 0 to Image1.Picture.Height – 1 Do
                For I := 0 to Image1.Picture.Height – 1 Do
            Begin
                If Image1.Canvas.Pixels[I,J] <> clWhite Then
                    Image1.Canvas.Pixels[I,J] := clBlack;
            End;
        End;

        ScalingFactorChange(Nil);

        convertbutton.Enabled  := True;
        LoadButton.Enabled     := False;
        XStatusBar1.SimpleText := '  Ready...';
        XStatusBar1.Update;
    End;
End;

Reportez-vous au projet de script PCB Logo Creator situé dans le dossier Scripts\Delphiscript Scripts\PCB\PCB Logo Creator de la collection téléchargeable de scripts .