VBScript
Questo riferimento descrive il linguaggio di scripting VisualBasic utilizzato per creare script in Altium Designer. Fornisce dettagli sulle istruzioni, le funzioni e le estensioni di VisualBasic Scripting supportate nel sistema di scripting.
Anche in questo riferimento:
Il linguaggio VBScript
Visual Basic Scripting (o VBScript, in breve) può essere utilizzato per creare script che operano con gli Object Model e i componenti visivi di Altium Designer. In questo riferimento si presume che l'utente abbia familiarità con i concetti base della programmazione 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. Ad esempio, dovrebbe essere possibile usare CScripts o WScripts, basati sullo stesso motore di scripting ActiveX utilizzato in Altium Designer.
Tutti i linguaggi di scripting supportati in Altium Designer sono senza tipo 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 Delphi RTL
Il sistema di scripting supporta un sottoinsieme della Embarcadero Delphi Run Time Library (RTL) e dell'API di Altium Designer.
Gli script VBScript possono accedere a diversi Object Model in Altium Designer. Ad esempio, il PCB Object Model può essere usato negli script VBScript per operare sugli oggetti PCB in un documento PCB, oppure il Workspace Manager Object Model per lavorare con i progetti e i relativi documenti ed estrarre i dati della netlist.
Il riferimento di scripting contiene informazioni sulle interfacce relative agli Object Model di Altium Designer, ai componenti, alle routine globali, ai tipi e alle variabili che costituiscono questo linguaggio di scripting. Consultare la documentazione Microsoft Visual Basic per ulteriori informazioni sulle funzioni VBScript.
Processi server
Uno script può essere utilizzato 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 form di script). Uno script può essere eseguito da una voce di menu, da un pulsante della barra degli strumenti oppure dalla finestra di dialogo Run Script del menu di sistema.
File PRJSCR, VBS e DFM
Gli script sono organizzati in progetti con estensione *.PRJSCR. Ogni progetto VBScript è costituito da file con estensione *.vbs. I file possono essere unità di script o form di script: ogni form ha un file di script VBScript con estensione *.vbs e un form corrispondente con estensione *.dfm). Un form di script è una finestra grafica (finestra di dialogo) che ospita diversi controlli eseguiti sopra Altium Designer.
È possibile collegare script a progetti diversi ed è fortemente consigliato organizzare gli script in progetti distinti per gestire il numero di script e le relative procedure/funzioni. Gli script (unità di script e form di script) sono costituiti da funzioni/procedure che possono essere richiamate all'interno di Altium Designer.
Esempi VBScript
I semplici esempi inclusi in questo riferimento illustrano le funzionalità di base della programmazione VBScript in Altium Designer.
Gli script VBScript possono usare form di script, unità di script, funzioni e oggetti dell'API di scripting di Altium Designer, nonché un sottoinsieme di funzioni e oggetti della Embarcadero Delphi RTL esposti nel sistema di scripting.
Scrittura di script VBScript
Questa sezione tratta i concetti di base per la scrittura di script VBScript in Altium Designer.
Convenzioni di denominazione VBScript
Le variabili VBScript non sono sensibili alle maiuscole/minuscole, cioè 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 hanno variabili locali e globali, è importante usare nomi di variabili univoci negli script all'interno di un progetto di script. Se le variabili sono definite outside qualsiasi sottoprogramma o funzione, sono globali e possono essere accessibili da qualsiasi unità nello stesso progetto.
Se le variabili sono definite inside una routine, allora queste variabili locali non sono accessibili al di fuori di tali routine. Poiché gli script sono non tipizzati, le variabili non vengono inizializzate con i loro 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
Sottoprogrammi e funzioni
VBScript consente due tipi di procedure: sottoprogrammi e funzioni; solo una funzione restituisce un valore. La sintassi per chiamare un sottoprogramma 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, una dichiarazione di procedura ha normalmente un elenco di parametri; si noti che le variabili sono considerate non tipizzate e il sistema di scripting determina automaticamente quali sono i tipi delle variabili. Il valore usato al posto del parametro quando si effettua una chiamata di procedura è chiamato 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 parola chiave Call per richiamare un sottoprogramma o una funzione è facoltativo (mantenuto per compatibilità con le versioni precedenti).
Commenti negli script
In uno script, i commenti sono righe di codice non eseguite incluse a beneficio del programmatore. I commenti possono essere inseriti praticamente ovunque in uno script.
Con i commenti VBScript:
-
Qualsiasi testo che segue
'viene ignorato. -
Qualsiasi testo che segue
Remviene 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 sulla riga (tramite una combinazione CR/LF) per indicare la fine dell'istruzione. VBScript consente di scrivere un'istruzione su più righe di codice, suddividendo un'istruzione lunga su due o più righe, usando 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 pratica limitare la lunghezza delle righe di codice in modo che possano essere lette facilmente sullo schermo o in forma stampata. Se una riga di codice è molto lunga, può essere suddivisa in più righe e questo codice verrà trattato dall'interprete VB come se fosse scritto su una singola 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
Uso degli Object Model di Altium Designer
La caratteristica principale del sistema di scripting è che le interfacce degli oggetti di Altium Designer (Object Interfaces) sono disponibili per l'uso negli script VBScript. Ad esempio, è possibile aggiornare gli oggetti di progettazione nei documenti Schematic e PCB tramite l'uso rispettivamente delle interfacce Schematic e PCB.
Le Object Interfaces di Altium Designer sono disponibili per l'uso in qualsiasi script. Normalmente, negli script non è necessario istanziare un'interfaccia. L'interfaccia che rappresenta un oggetto esistente di Altium Designer viene estratta e, da questa interfaccia, è possibile estrarre gli oggetti interfaccia incorporati o aggregati per ottenere o impostare i relativi valori di proprietà.
Per accedere a un documento PCB e ai relativi oggetti dati, occorre prima richiamare la funzione PCBServer. Per convenzione, i nomi delle interfacce sono preceduti dal carattere 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 avere accesso a un documento PCB, richiamare 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 negli script a oggetti, interfacce e funzioni di Altium Designer dai seguenti elementi:
- Client API
- PCB Server API
- Schematic Server API
- Work Space Manager Server API
- Nexus API
- funzioni API di Altium Designer
- processi parametrici
Parole riservate e funzioni
Il sistema di scripting supporta il linguaggio VBScript, derivato dalla tecnologia 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
Localizzato tramite A