VBScript

Cette référence décrit le langage de script VisualBasic utilisé pour créer des scripts dans Altium Designer. Elle fournit des détails sur les instructions, fonctions et extensions de VisualBasic Scripting prises en charge par le système de script.

Également dans cette référence :

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

Le langage VBScript

Visual Basic Scripting (ou VBScript en abrégé) peut être utilisé pour créer des scripts qui exploitent les modèles objet et les composants visuels d’Altium Designer. Dans cette référence, on suppose que vous connaissez les concepts de base de la programmation ainsi que le fonctionnement de base d’Altium Designer.

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

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

VBScript script example

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

Altium Designer et la RTL Delphi

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

Les scripts VBScript peuvent accéder à plusieurs modèles objet dans Altium Designer. Par exemple, le modèle objet PCB peut être utilisé dans des scripts VBScript pour manipuler les objets PCB d’un document PCB, ou le modèle objet Workspace Manager pour travailler avec les projets et leurs documents afin d’extraire des données de netlist.

La référence de script contient des informations sur les interfaces relatives aux modèles objet 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 représentent des commandes dans Altium Designer.

Fichiers source VBScript

Un projet VBScript est organisé pour 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 barre d’outils ou depuis la boîte de dialogue Run Script du menu système.

Fichiers PRJSCR, VBS et DFM

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

Il est possible d’attacher des scripts à différents projets, et il est fortement recommandé d’organiser les scripts dans différents projets afin de gérer le nombre de scripts et leurs procédures/fonctions. Les scripts (unités de script et formulaires de script) se composent de fonctions/procédures pouvant être appelées dans 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 de l’API de script d’Altium Designer, ainsi qu’un sous-ensemble de fonctions et d’objets de la RTL Embarcadero Delphi exposés dans le système de script.

Écriture de scripts VBScript

Cette section couvre 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 — autrement dit, 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

Comme tous les scripts possèdent des variables locales et globales, il est important d’avoir des noms de variables uniques dans vos scripts au sein d’un projet de script. Si les variables sont définies outside toute sous-routine ou fonction, elles sont globales et peuvent être accessibles depuis n’importe quelle unité du même projet.

Si des variables sont définies inside une routine, alors ces variables locales ne sont pas accessibles en dehors de ces routines. Comme les scripts sont sans typage, les variables ne sont pas initialisées avec leur type.

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

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 — seule une fonction renvoie une valeur. La syntaxe d’appel d’une sous-routine ou d’une fonction dans un script est :

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, une déclaration de procédure comporte normalement 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 quels sont les types des variables. La valeur utilisée à la place du paramètre lors de l’appel d’une procédure est appelée un 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 mot-clé Call pour invoquer une sous-routine ou une fonction est facultative (maintenue pour compatibilité ascendante).

Commentaires dans les scripts

Dans un script, les commentaires sont des lignes de code non exécutées incluses pour le bénéfice du programmeur. Les commentaires peuvent être inclus 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 sur 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 scinder une instruction longue sur deux lignes ou plus, à l’aide du caractère de soulignement (_).

VBScript n’impose aucune limite pratique à la longueur d’une seule ligne de code dans un script. Cependant, pour des raisons de lisibilité et de facilité de débogage, il est recommandé de limiter la longueur des lignes de code afin qu’elles puissent être facilement lues à l’écran ou sous forme imprimée. Si une ligne de code est très longue, elle peut être divisée en plusieurs lignes, et ce code sera traité par l’interpréteur VB comme s’il avait été é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 objet d’Altium Designer

La principale fonctionnalité du système de script est que les interfaces des objets d’Altium Designer (interfaces objet) sont disponibles pour être utilisées dans les scripts VBScript. Par exemple, vous pouvez mettre à jour des objets de conception dans des documents schématiques et PCB grâce à l’utilisation respective des interfaces schématiques et PCB.

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

Pour accéder à un document PCB et à ses objets de données, vous invoquez d’abord la fonction PCBServer. Par convention, les noms d’interface sont préfixés par le caractère I — par exemple, IPCB_Board représente une interface pour un document PCB 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 avoir accès à un document PCB, invoquez 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 à partir des éléments suivants :

• API Client
• API du serveur PCB
• API du serveur schématique
• API du serveur Work Space Manager
• API Nexus
• Fonctions API d’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 de langage Microsoft Active Scripting. Les mots réservés de VBScript sont :

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