VBScript
De un vistazo
- Comprende las convenciones de nomenclatura de VBScript, el ámbito de las variables, las llamadas a procedimientos, los comentarios y la continuación de línea.
- Aprende cómo se organizan las unidades de script y los formularios en proyectos y cómo se pueden ejecutar los scripts.
- Descubre cómo los scripts acceden a los modelos de objetos de Altium Designer, a las API compatibles y a un subconjunto de la biblioteca de tiempo de ejecución de Delphi.
Esta referencia describe el lenguaje VisualBasic Scripting utilizado para crear scripts en Altium Designer. Proporciona información detallada sobre las instrucciones, funciones y extensiones de VisualBasic Scripting compatibles con el sistema de scripting.
También en esta referencia:
- Instrucciones de VBScript
- Subrutinas y funciones de VBScript
- Uso de componentes de formulario con VBScript
El lenguaje VBScript
Visual Basic Scripting (o VBScript, para abreviar) permite crear scripts que trabajan con los modelos de objetos y los componentes visuales de Altium Designer. En esta referencia se da por hecho que conoce los conceptos básicos de programación y el funcionamiento básico de Altium Designer.
El sistema de scripting de Altium Designer admite el lenguaje VBScript (junto con otros lenguajes de scripting), que se deriva del sistema Microsoft ActiveX Scripting. Así, por ejemplo, debería poder utilizar CScripts o WScripts basados en el mismo motor de scripting ActiveX que se utiliza en Altium Designer.
Todos los lenguajes de scripting compatibles con Altium Designer carecen de tipos, lo que significa que un script no puede definir registros ni clases, ni pasar punteros como parámetros a funciones.
VBScript script example
Sub DisplayName (sName)
MsgBox "My Name is " & sName
End Sub
Altium Designer y la RTL de Delphi
El sistema de scripting admite un subconjunto de la biblioteca de tiempo de ejecución (RTL) de Embarcadero Delphi y de la API de Altium Designer.
Los scripts de VBScript pueden acceder a varios modelos de objetos de Altium Designer. Por ejemplo, el modelo de objetos de PCB se puede utilizar en scripts de VBScript para trabajar con objetos de PCB en un documento de PCB, o el modelo de objetos de Workspace Manager para trabajar con proyectos y sus documentos y extraer datos de la lista de conexiones.
La referencia de scripting contiene información sobre las interfaces de los modelos de objetos de Altium Designer, los componentes, las rutinas globales, los tipos y las variables que conforman este lenguaje de scripting. Consulte la documentación de Microsoft Visual Basic para obtener más información sobre las funciones de VBScript.
Procesos del servidor
Se puede utilizar un script para ejecutar procesos del servidor, que representan comandos en Altium Designer.
Archivos de código fuente de VBScript
Un proyecto de VBScript se organiza para almacenar documentos de script (unidades de script y formularios de script). Un script se puede ejecutar desde un elemento de menú, un botón de la barra de herramientas o desde el cuadro de diálogo Run Script del menú del sistema.
Archivos PRJSCR, VBS y DFM
Los scripts se organizan en proyectos con la extensión *.PRJSCR. Cada proyecto de VBScript consta de archivos con la extensión *.vbs. Los archivos pueden ser unidades de script o formularios de script: cada formulario tiene un archivo de script de VBScript con la extensión *.vbs y su correspondiente formulario con la extensión *.dfm. Un formulario de script es una ventana gráfica (cuadro de diálogo) que aloja distintos controles que se ejecutan sobre Altium Designer.
Es posible adjuntar scripts a distintos proyectos, y se recomienda encarecidamente organizarlos en proyectos diferentes para gestionar la cantidad de scripts y sus procedimientos y funciones. Los scripts (unidades de script y formularios de script) constan de funciones y procedimientos que se pueden llamar desde Altium Designer.
Ejemplos de VBScript
Los ejemplos sencillos incluidos en esta referencia ilustran las características básicas de la programación en VBScript en Altium Designer.
Los scripts de VBScript pueden utilizar formularios de script, unidades de script, funciones y objetos de la API de scripting de Altium Designer, así como un subconjunto de funciones y objetos de la RTL de Embarcadero Delphi que están disponibles en el sistema de scripting.
Escritura de scripts de VBScript
Esta sección trata los conceptos básicos de la escritura de scripts de VBScript en Altium Designer.
Convenciones de nomenclatura de VBScript
Las variables de VBScript no distinguen entre mayúsculas y minúsculas; es decir, las variables escritas en mayúsculas y minúsculas tienen el mismo significado:
Example
The variables b and B are the same.
b = 60
B = 60
Variables locales y globales
Dado que todos los scripts tienen variables locales y globales, es importante utilizar nombres de variable únicos en los scripts de un mismo proyecto de scripts. Si las variables se definen outside de cualquier subrutina o función, son globales y se puede acceder a ellas desde cualquier unidad del mismo proyecto.
Si las variables se definen inside de una rutina, estas variables locales no son accesibles desde fuera de ella. Dado que los scripts carecen de tipos, las variables no se inicializan con sus tipos.
Las variables locales de un procedimiento se inicializan automáticamente.
Variable Initialization
Sub Example
Dim X
Dim s
' x set to 0
x = 0
' s set to empty
s = ""
End Sub
Subrutinas y funciones
VBScript admite dos tipos de procedimientos: subrutinas y funciones; solo las funciones devuelven un valor. La sintaxis para llamar a una subrutina o función en un script es:
Call SubRoutineA(parameters)
...o
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
Parámetros y argumentos
En VBScript, la declaración de un procedimiento suele tener una lista de parámetros; tenga en cuenta que las variables se consideran sin tipo y que el sistema de scripting determina automáticamente sus tipos. El valor que se utiliza en lugar del parámetro al llamar a un procedimiento se denomina argumento.
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
Tenga en cuenta que el uso de la palabra clave Call para invocar una subrutina o una función es opcional (se mantiene por compatibilidad con versiones anteriores).
Comentarios en los scripts
En un script, los comentarios son líneas de código que no se ejecutan y que se incluyen para ayudar al programador. Los comentarios se pueden incluir prácticamente en cualquier parte de un script.
En los comentarios de VBScript:
-
Se ignora cualquier texto que aparezca después de
'. -
Se ignora cualquier texto que aparezca después de
Rem.
Example
' This whole line is a comment
REM this whole line is also a comment
DocName = Document.Name ' Get name of active document
División de una línea de script
En VBScript, cada instrucción de código termina en la misma línea (mediante una combinación CR/LF) para indicar el final de la instrucción. VBScript permite escribir una instrucción en varias líneas de código, dividiendo una instrucción larga en dos o más líneas mediante el carácter de guion bajo (_).
VBScript no impone ningún límite práctico a la longitud de una sola línea de código de un script. Sin embargo, para facilitar la lectura y la depuración, es recomendable limitar la longitud de las líneas de código de modo que se puedan leer fácilmente en pantalla o en papel. Si una línea de código es muy larga, se puede dividir en varias líneas, y el intérprete de VB tratará este código como si estuviera escrito en una sola línea.
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 de los modelos de objetos de Altium Designer
La característica más destacada del sistema de scripting es que las interfaces de los objetos de Altium Designer (interfaces de objetos) están disponibles para su uso en scripts de VBScript. Por ejemplo, puede actualizar objetos de diseño en documentos de esquemáticos y de PCB mediante las interfaces de esquemáticos y de PCB, respectivamente.
Las interfaces de objetos de Altium Designer se pueden utilizar en cualquier script. Normalmente, en los scripts no es necesario crear una instancia de una interfaz. Se obtiene la interfaz que representa un objeto existente de Altium Designer y, a partir de ella, se pueden obtener los objetos de interfaz integrados o agregados para consultar o establecer los valores de sus propiedades.
Para acceder a un documento de PCB y a sus objetos de datos, primero se invoca la función PCBServer. Por convención, los nombres de las interfaces llevan como prefijo el carácter I; por ejemplo, IPCB_Board representa una interfaz de un documento de PCB existente en 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
Para acceder a un documento de PCB, invoque 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
Objetos, interfaces y funciones
Se puede acceder a los objetos, interfaces y funciones de Altium Designer desde los scripts mediante las siguientes API:
- API del cliente
- API del servidor de PCB
- API del servidor de esquemáticos
- API del servidor de Work Space Manager
- API de Nexus
- Funciones de la API de Altium Designer
- Procesos paramétricos
Palabras reservadas y funciones
El sistema de scripts admite el lenguaje VBScript, derivado de la tecnología de lenguajes Microsoft Active Scripting. Las palabras reservadas de VBScript son:
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