VBScript

Ce document décrit le langage de script Visual Basic utilisé pour créer des scripts dans Altium Designer. Il fournit des informations détaillées sur les instructions, les fonctions et les extensions de Visual Basic prises en charge par le système de script.

Également dans ce guide :

• Instructions VBScript
• Sous-programmes et fonctions VBScript
• Utilisation des composants de formulaire avec VBScript

Le langage VBScript

Le langage Visual Basic Scripting (ou VBScript en abrégé) permet de créer des scripts qui gèrent les modèles d’objets et les composants visuels d’Altium Designer. Dans ce guide, nous partons du principe que vous maîtrisez les concepts de programmation de base ainsi que le fonctionnement général d’Altium Designer.

Le système de script d’Altium Designer prend en charge le langage VBScript (ainsi que d’autres langages de script), qui est dérivé du système Microsoft ActiveX Scripting. Ainsi, par exemple, vous devriez pouvoir utiliser des scripts CScript ou WScript, qui reposent sur le même moteur de script ActiveX que celui utilisé dans Altium Designer.

Tous les langages de script pris en charge par Altium Designer sont sans type, ce qui signifie qu’un script ne peut pas définir d’enregistrements ou de classes, ni passer de pointeurs en tant que paramètres à des fonctions.

VBScript script example

Sub DisplayName (sName)
  MsgBox "My Name is " & sName
End Sub

Altium Designer et la bibliothèque RTL de Delphi

Le système de script prend en charge un sous-ensemble de la bibliothèque d’exécution (RTL) Embarcadero Delphi et de l’API d’Altium Designer.

Les scripts VBScript peuvent accéder à plusieurs modèles d’objets dans Altium Designer. Par exemple, le modèle d’objets PCB peut être utilisé dans les scripts VBScript pour manipuler les objets PCB d’un document PCB, ou le modèle d’objets du Gestionnaire d’espace de travail pour interagir avec les projets et leurs documents afin d’extraire des données de liste d’interconnexions.

Le guide de référence des scripts contient des informations sur les interfaces relatives aux modèles d’objets d’Altium Designer, aux composants, aux routines globales, aux types et aux variables qui composent ce langage de script. Consultez la documentation Microsoft Visual Basic pour plus d’informations sur les fonctions VBScript.

Processus serveur

Un script peut être utilisé pour exécuter des processus serveur, qui correspondent à des commandes dans Altium Designer.

Fichiers source VBScript

Un projet VBScript est organisé de manière à stocker des documents de script (unités de script et formulaires de script). Un script peut être exécuté à partir d’un élément de menu, d’un bouton de la barre d’outils ou de la Run Script boîte de dialogue du menu Système.

Fichiers PRJSCR, VBS et DFM

Les scripts sont organisés en projets portant l’ *.PRJSCR extension. Chaque projet VBScript est constitué de fichiers portant une *.vbs . Les fichiers peuvent être soit des unités de script, soit des formulaires de script — chaque formulaire dispose d’un fichier de script VBScript portant l’ *.vbs et d’un formulaire correspondant portant l’extension *.dfm extension). Un formulaire de script est une fenêtre graphique (boîte de dialogue) qui héberge différents contrôles s’exécutant par-dessus Altium Designer.

Il est possible d’associer des scripts à différents projets, et il est fortement recommandé d’organiser les scripts en projets distincts afin de gérer leur nombre ainsi que leurs procédures et fonctions. Les scripts (unités de script et formulaires de script) se composent de fonctions et de procédures pouvant être appelées depuis Altium Designer.

Exemples VBScript

Les exemples simples inclus dans cette référence illustrent les fonctionnalités de base de la programmation VBScript dans Altium Designer.

Les scripts VBScript peuvent utiliser des formulaires de script, des unités de script, des fonctions et des objets issus de l’API de script d’Altium Designer, ainsi qu’un sous-ensemble de fonctions et d’objets issus de l’RTL Embarcadero Delphi qui sont exposés dans le système de script.

Écriture de scripts VBScript

Cette section aborde les concepts de base de l’écriture de scripts VBScript dans Altium Designer.

Conventions de nommage VBScript

Les variables VBScript ne sont pas sensibles à la casse ; en d’autres termes, les variables en majuscules et en minuscules ont la même signification :

Example

The variables b and B are the same.
b = 60
B = 60

Variables locales et globales

Étant donné que tous les scripts comportent des variables locales et globales, il est important d’utiliser des noms de variables uniques dans vos scripts au sein d’un même projet de script. Si les variables sont définies outside des sous-routines ou des fonctions, elles sont globales et peuvent être utilisées par n'importe quelle unité du même projet.

Si les variables sont définies inside une routine, ces variables locales ne sont pas accessibles en dehors de cette routine. Les scripts étant sans type, les variables ne sont pas initialisées avec leur type.

Les variables locales à l’intérieur d’une procédure sont automatiquement initialisées.

Variable Initialization

Sub Example
  Dim X
  Dim s
  ' x set to 0
  x =  0
  ' s set to empty
  s = ""
End Sub

Sous-routines et fonctions

VBScript autorise deux types de procédures : les sous-routines et les fonctions — une fonction renvoie uniquement une valeur. La syntaxe d’appel d’une sous-routine ou d’une fonction dans un script est la suivante :

Call SubRoutineA(parameters)
...ou
SubRoutine parameters

Subroutine example

Sub SetTheHeight AHeight
  Set Component.Height = AHeight
End Sub

Function example

Function Addone(value)
  AddOne = Value + 1
End Function

Another Function example

Function Test(s)
 Test = S + " rules.."
End Function
 
Sub DisplayName (sName)
 MsgBox sName
End Sub
 
Sub Main
Dim S
 S = "Altium Designer"
 DisplayName Test(s)
End Sub

Paramètres et arguments

En VBScript, la déclaration d’une procédure comporte généralement une liste de paramètres — notez que les variables sont considérées comme sans type et que le système de script détermine automatiquement leurs types. La valeur utilisée à la place du paramètre lors de l’appel d’une procédure est appelée « argument ».

Example of a subroutine with a parameter

Sub DisplayName (sName)
  MsgBox "My Name is " & sName
End Sub

Example of calling a subroutine

Sub Main
  DisplayName "Altium Designer  Rules"
End Sub

Notez que l’utilisation du Call pour appeler une sous-routine ou une fonction est facultative (conservée pour des raisons de compatibilité ascendante).

Commentaires dans les scripts

Dans un script, les commentaires sont des lignes de code non exécutées qui sont incluses à l'intention du programmeur. Les commentaires peuvent être insérés pratiquement n'importe où dans un script.

Avec les commentaires VBScript :

• Tout texte suivant ' est ignoré.
• Tout texte suivant Rem est ignoré.

Example

' This whole line is a comment
REM this whole line is also a comment
DocName = Document.Name ' Get name of active document

Fractionnement d'une ligne de script

En VBScript, chaque instruction de code se termine à la fin de la ligne (par une combinaison CR/LF) pour indiquer la fin de l'instruction. VBScript vous permet d'écrire une instruction sur plusieurs lignes de code, afin de fractionner une longue instruction sur deux lignes ou plus, à l'aide du caractère de soulignement (_).

VBScript n'impose aucune limite pratique à la longueur d'une ligne de code dans un script. Cependant, pour des raisons de lisibilité et pour faciliter le débogage, il est recommandé de limiter la longueur des lignes de code afin qu'elles puissent être facilement lues à l'écran ou sur papier. Si une ligne de code est très longue, elle peut être divisée en plusieurs lignes ; ce code sera alors traité par l’interpréteur VB comme s’il était écrit sur une seule ligne.

Unformatted code example

If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,"Choose first corner","Choose final corner",x1,y1,x2,y2)) Then EndIf

Formatted code example

If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,_ 
                                        “Choose first corner”,_ 
                                        “Choose final corner”,_ 
                                        x1,y1,x2,y2)) Then EndIf

Utilisation des modèles d’objets d’Altium Designer

La principale caractéristique du système de script réside dans le fait que les interfaces des objets Altium Designer (interfaces d’objets) sont disponibles pour être utilisées dans les scripts VBScript. Par exemple, vous pouvez mettre à jour des objets de conception dans les documents de schéma et de circuit imprimé en utilisant respectivement les interfaces de schéma et les interfaces de circuit imprimé.

Les interfaces d’objets d’Altium Designer peuvent être utilisées dans n’importe quel script. En règle générale, il n’est pas nécessaire d’instancier une interface dans les scripts. L’interface représentant un objet Altium Designer existant est extraite, et à partir de cette interface, les objets d’interface intégrés ou agrégés peuvent être extraits pour obtenir ou définir leurs valeurs de propriété.

Pour accéder à un document PCB et à ses objets de données, vous devez d’abord appeler la PCBServer fonction. Par convention, les noms d’interface sont précédés d’un I caractère — par exemple, IPCB_Board représente une interface pour un document de circuit imprimé existant dans Altium Designer.

Example

' Checks if the current document is a Schematic document
  If SchServer Is Nothing Then Exit Sub
  Set CurrentSheet = SchServer.GetCurrentSchDocument
  If CurrentSheet Is Nothing Then Exit Sub

Pour accéder à un document de circuit imprimé, appelez la PCBServer.

Creation of a PCB Object Using the PCB Object Model

Sub ViaCreation
  Dim Board
  Dim Via
  Set Board = PCBServer.GetCurrentPCBBoard
  If Board is Nothing Then Exit Sub
  ' Create a Via object
  Via = PCBServer.PCBObjectFactory(eViaObject, eNoDimension, eCreate_Default)
  Via.X = MilsToCoord(7500)
  Via.Y = MilsToCoord(7500)
  Via.Size   = MilsToCoord(50)
  Via.HoleSize   = MilsToCoord(20)
  Via.LowLayer   = eTopLayer
  Via.HighLayer = eBottomLayer
  ' Put this via in the Board object
  Board.AddPCBObject(Via)
End Sub

Objets, interfaces et fonctions

Les objets, interfaces et fonctions d’Altium Designer sont accessibles dans les scripts via les éléments suivants :

• API client
• API du serveur de circuits imprimés
• API du serveur de schémas
• API du serveur Work Space Manager
• API Nexus
• Fonctions de l'API Altium Designer
• Processus paramétriques

Mots réservés et fonctions

Le système de script prend en charge le langage VBScript, dérivé de la technologie Microsoft Active Scripting. Les mots réservés en VBScript sont les suivants :

A, B
Abs, Array, Asc, Atn
C
Call, Case, CBool, CByte, CCur, CDate, CDbl, Chr, CInt, Class, CLng, Const, Conversions, Cos, CreateObject, CSng, CStr
D, E
DateAdd, DateDiff, DatePart, DateSerial, DateValue, Day, Derived Math, Dim, Do, Each, Erase, Escape, Empty, Eval, Execute, Exit, Exp
F, G, H
False, Filter, For, FormatCurrency, FormatDateTime, FormatNumber, FormatPercent, Function GetLocale, GetObject, GetRef, Hex, Hour
I, L, M
If, Is, InputBox, Instr, InStrRev, Int, IsArray, IsDate, IsEmpty, IsNull, IsNumeric, IsObject, Join, LBound, LCase, Left, Len, LoadPicture, Log, LTrim, Maths, Mid, MInute, Month, MonthName, MsgBox
N, O
Next, Nothing, Now, Null, Oct, On Error
P, R
Private, Property, Public, Randomize, ReDim, Rem, RTrim, Replace, RGB, Right, Rnd, Round
S, T
ScriptEngine, ScriptEngineBuildVersion, ScriptEngineMajorVersion, ScriptEngineMinorVersion, Second, Select, Set, SetLocale, Sgn, Sin, Space, Split, Sqr, Stop, StrComp, String, StrReverse, Sub, Tan, Then, Time, Timer, Timeserial, TimeValue, Trim, True, TypeName
U, V, W, X, Y
UCase, Unescape, While, Wend, With, VarType, Weekday, WeekdayName, Year