VBScript

Il presente documento descrive il linguaggio di scripting Visual Basic utilizzato per creare script in Altium Designer. Fornisce dettagli sulle istruzioni, le funzioni e le estensioni di Visual Basic supportate dal sistema di scripting.

Inoltre, in questa guida:

• Istruzioni VBScript
• Subroutine e funzioni VBScript
• Utilizzo dei componenti di modulo con VBScript

Il linguaggio VBScript

Il Visual Basic Scripting (o VBScript in breve) può essere utilizzato per creare script che gestiscono i modelli a oggetti e i componenti visivi di Altium Designer. In questa guida si presume che l'utente abbia familiarità con i concetti di programmazione di base e con il funzionamento di base di Altium Designer.

Il sistema di scripting di Altium Designer supporta il linguaggio VBScript (insieme ad altri linguaggi di scripting), derivato dal sistema Microsoft ActiveX Scripting. Pertanto, ad esempio, è possibile utilizzare CScript o WScript, basati sullo stesso motore di scripting ActiveX utilizzato in Altium Designer.

Tutti i linguaggi di scripting supportati in Altium Designer sono senza tipi o non tipizzati, il che significa che uno script non può definire record o classi né passare puntatori come parametri alle funzioni.

VBScript script example

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

Altium Designer e la RTL di Delphi

Il sistema di scripting supporta un sottoinsieme della Run Time Library (RTL) di Embarcadero Delphi e dell’API di Altium Designer.

Gli script VBScript possono accedere a diversi modelli a oggetti in Altium Designer. Ad esempio, il modello a oggetti PCB può essere utilizzato negli script VBScript per gestire gli oggetti PCB in un documento PCB, oppure il modello a oggetti Workspace Manager per lavorare con i progetti e i relativi documenti al fine di estrarre i dati della netlist.

La Guida di riferimento allo scripting contiene informazioni sulle interfacce relative ai modelli a oggetti di Altium Designer, ai componenti, alle routine globali, ai tipi e alle variabili che costituiscono questo linguaggio di scripting. Per ulteriori informazioni sulle funzioni VBScript, consultare la documentazione di Microsoft Visual Basic.

Processi del server

È possibile utilizzare uno script per eseguire processi server, che rappresentano comandi in Altium Designer.

File sorgente VBScript

Un progetto VBScript è organizzato per memorizzare documenti di script (unità di script e moduli di script). Uno script può essere eseguito da una voce di menu, da un pulsante della barra degli strumenti o dalla finestra di dialogo Run Script finestra di dialogo accessibile dal menu di sistema.

File PRJSCR, VBS e DFM

Gli script sono organizzati in progetti con estensione *.PRJSCR estensione. Ogni progetto VBScript è costituito da file con un’ *.vbs estensione. I file possono essere unità di script o moduli di script: ogni modulo ha un file di script VBScript con *.vbs estensione e un modulo corrispondente con estensione *.dfm estensione). Un modulo di script è una finestra grafica (finestra di dialogo) che ospita diversi controlli che vengono eseguiti all’interno di Altium Designer.

È possibile associare gli script a diversi progetti ed è vivamente consigliato organizzarli in progetti distinti per gestire il numero di script e le relative procedure/funzioni. Gli script (unità di script e moduli di script) sono costituiti da funzioni/procedure che possono essere richiamate all’interno di Altium Designer.

Esempi di VBScript

Gli esempi semplici inclusi in questa guida illustrano le caratteristiche di base della programmazione VBScript in Altium Designer.

Gli script VBScript possono utilizzare moduli di script, unità di script, funzioni e oggetti provenienti dall’API di scripting di Altium Designer, nonché un sottoinsieme di funzioni e oggetti provenienti dall’RTL di Embarcadero Delphi che sono resi disponibili nel sistema di scripting.

Scrittura di script VBScript

Questa sezione illustra i concetti di base relativi alla scrittura di script VBScript in Altium Designer.

Convenzioni di denominazione VBScript

Le variabili VBScript non distinguono tra maiuscole e minuscole, ovvero le variabili in maiuscolo e in minuscolo hanno lo stesso significato:

Example

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

Variabili locali e globali

Poiché tutti gli script contengono variabili locali e globali, è importante che i nomi delle variabili all’interno di uno stesso progetto di script siano univoci. Se le variabili sono definite outside subroutine o funzioni, sono globali e sono accessibili da qualsiasi unità dello stesso progetto.

Se le variabili sono definite inside una subroutine, queste variabili locali non sono accessibili al di fuori di tali subroutine. Poiché gli script sono senza tipo, le variabili non vengono inizializzate con i rispettivi tipi.

Le variabili locali all’interno di una procedura vengono inizializzate automaticamente.

Variable Initialization

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

Subroutine e funzioni

VBScript consente due tipi di procedure: subroutine e funzioni — una funzione restituisce solo un valore. La sintassi per richiamare una subroutine o una funzione in uno script è:

Call SubRoutineA(parameters)
...oppure
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

Parametri e argomenti

In VBScript, la dichiarazione di una procedura presenta solitamente un elenco di parametri; si noti che le variabili sono considerate senza tipo e che il sistema di scripting determina automaticamente i tipi delle variabili. Il valore utilizzato al posto del parametro quando si effettua una chiamata alla procedura è denominato argomento.

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

Si noti che l’uso della Call per richiamare una subroutine o una funzione è facoltativo (mantenuto per motivi di compatibilità con le versioni precedenti).

Commenti negli script

In uno script, i commenti sono righe di codice non eseguite che vengono incluse a beneficio del programmatore. I commenti possono essere inseriti praticamente ovunque all’interno di uno script.

Per quanto riguarda i commenti in VBScript:

• Qualsiasi testo che segue ' viene ignorato.
• Qualsiasi testo che segue Rem viene ignorato.

Example

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

Suddivisione di una riga di script

In VBScript, ogni istruzione di codice termina alla fine della riga (con una combinazione CR/LF) per indicare la fine dell'istruzione. VBScript consente di scrivere un'istruzione su più righe di codice, per suddividere un'istruzione lunga su due o più righe, utilizzando il carattere di sottolineatura (_).

VBScript non impone alcun limite pratico alla lunghezza di una singola riga di codice in uno script. Tuttavia, per motivi di leggibilità e facilità di debug, è buona norma limitare la lunghezza delle righe di codice in modo che possano essere facilmente lette sullo schermo o in formato stampato. Se una riga di codice è molto lunga, può essere suddivisa in più righe; tale codice verrà trattato dall’interprete VB come se fosse scritto su un’unica riga.

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

Utilizzo dei modelli a oggetti di Altium Designer

La caratteristica principale del sistema di scripting è che le interfacce degli oggetti di Altium Designer (Interfacce oggetto) sono disponibili per l’uso nei VBScript. Ad esempio, è possibile aggiornare gli oggetti di progetto nei documenti Schematico e PCB utilizzando rispettivamente le interfacce Schematico e PCB.

Le interfacce degli oggetti di Altium Designer sono disponibili per l’uso in qualsiasi script. Normalmente negli script non è necessario istanziare un’interfaccia. Viene estratta l’interfaccia che rappresenta un oggetto esistente di Altium Designer e, da questa interfaccia, è possibile estrarre gli oggetti di interfaccia incorporati o aggregati per ottenere o impostare i valori delle loro proprietà.

Per accedere a un documento PCB e ai suoi oggetti dati, occorre innanzitutto richiamare la PCBServer funzione. Per convenzione, i nomi delle interfacce sono preceduti da un I — ad esempio, IPCB_Board rappresenta un'interfaccia per un documento PCB esistente in 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

Per accedere a un documento PCB, si richiama 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

Oggetti, interfacce e funzioni

È possibile accedere agli oggetti, alle interfacce e alle funzioni di Altium Designer negli script tramite:

• API client
• API del server PCB
• API del server Schematic
• API del server Work Space Manager
• API Nexus
• Funzioni dell'API di Altium Designer
• Processi parametrici

Parole riservate e funzioni

Il sistema di scripting supporta il linguaggio VBScript, derivato dalla tecnologia linguistica Microsoft Active Scripting. Le parole riservate di VBScript sono:

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