VBScript

Esta referencia describe el lenguaje de secuencias de comandos VisualBasic utilizado para crear scripts en Altium Designer. Proporciona detalles 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) puede utilizarse para crear scripts que trabajen con los modelos de objetos y componentes visuales de Altium Designer. En esta referencia, se asume que está familiarizado con los conceptos básicos de programación y con 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 deriva del sistema Microsoft ActiveX Scripting. Así, por ejemplo, debería poder usar CScripts o WScripts, que se basan en el mismo motor de ActiveX Scripting que se utiliza en Altium Designer.

Todos los lenguajes de scripting compatibles con Altium Designer son no tipados, lo que significa que un script no puede definir registros ni clases ni pasar punteros como parámetros a las funciones.

VBScript script example

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

Altium Designer y Delphi RTL

El sistema de scripting admite un subconjunto de la biblioteca en tiempo de ejecución (RTL) de Embarcadero Delphi y la API de Altium Designer.

Los scripts VBScripts pueden acceder a varios modelos de objetos en Altium Designer. Por ejemplo, el modelo de objetos PCB puede utilizarse en VBScripts para trabajar con objetos PCB en un documento PCB, o el modelo de objetos Workspace Manager para trabajar con proyectos y sus documentos y extraer datos de netlist.

La referencia de scripting contiene información sobre interfaces relativas a los modelos de objetos de Altium Designer, componentes, rutinas globales, tipos y 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

Un script puede utilizarse para ejecutar procesos del servidor, que representan comandos en Altium Designer.

Archivos fuente de VBScript

Un proyecto de VBScript se organiza para almacenar documentos de script (unidades de script y formularios de script). Un script puede ejecutarse 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 una extensión *.PRJSCR. Cada proyecto de VBScript consta de archivos con una extensión *.vbs. Los archivos pueden ser unidades de script o formularios de script; cada formulario tiene un archivo de script VBScript con extensión *.vbs y un formulario correspondiente con 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/funciones. Los scripts (unidades de script y formularios de script) constan de funciones/procedimientos que pueden llamarse 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 VBScripts pueden usar 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 Embarcadero Delphi RTL expuestos en el sistema de scripting.

Escritura de scripts VBScript

Esta sección cubre los conceptos básicos para escribir VBScripts en Altium Designer.

Convenciones de nomenclatura de VBScript

Las variables de VBScript no distinguen entre mayúsculas y minúsculas; es decir, las variables 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 tener nombres de variables únicos en sus scripts dentro de un proyecto de script. Si las variables se definen outside cualquier subrutina o función, son globales y cualquier unidad del mismo proyecto puede acceder a ellas.

Si las variables se definen inside una rutina, entonces estas variables locales no son accesibles fuera de esas rutinas. Como los scripts no son tipados, las variables no se inicializan con sus tipos. Las variables locales dentro 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 permite dos tipos de procedimientos: subrutinas y funciones; solo una función devuelve 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, una declaración de procedimiento normalmente tiene una lista de parámetros; tenga en cuenta que las variables se consideran no tipadas y el sistema de scripting determina automáticamente cuáles son sus tipos. El valor utilizado en lugar del parámetro cuando se realiza una llamada 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 scripts

En un script, los comentarios son líneas de código que no se ejecutan y que se incluyen en beneficio del programador. Los comentarios pueden incluirse prácticamente en cualquier lugar de un script.

Con los comentarios de VBScript:

• Cualquier texto que siga a ' se ignora.
• Cualquier texto que siga a Rem se ignora.

Example

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

Dividir una línea de script

En VBScript, cada instrucción de código termina en la línea (mediante una combinación CR/LF) para indicar el final de la instrucción. VBScript le permite escribir una instrucción en varias líneas de código, para dividir una instrucción larga en dos o más líneas, usando el carácter de subrayado (_).

VBScript no impone ningún límite práctico a la longitud de una sola línea de código en un script. Sin embargo, por legibilidad y facilidad de depuración, es una buena práctica limitar la longitud de las líneas de código para que puedan leerse fácilmente en pantalla o impresas. Si una línea de código es muy larga, puede dividirse 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 principal característica del sistema de scripting es que las interfaces de los objetos de Altium Designer (interfaces de objetos) están disponibles para usarse en VBScripts. Por ejemplo, puede actualizar objetos de diseño en documentos esquemáticos y PCB mediante el uso de interfaces de esquemático e interfaces PCB, respectivamente.

Las interfaces de objetos de Altium Designer están disponibles para usarse en cualquier script. Normalmente, en los scripts no es necesario crear una instancia de una interfaz. Se extrae la interfaz que representa un objeto existente de Altium Designer y, a partir de esta, pueden extraerse los objetos de interfaz incrustados o agregados para obtener o establecer los valores de sus propiedades.

Para acceder a un documento PCB y a sus objetos de datos, primero invoque la función PCBServer. Por convención, los nombres de las interfaces llevan como prefijo un carácter I; por ejemplo, IPCB_Board representa una interfaz para un documento 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 tener acceso a un documento 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 en scripts a los objetos, interfaces y funciones de Altium Designer desde lo siguiente:

• API del cliente
• API del servidor PCB
• API del servidor esquemático
• API del servidor Work Space Manager
• API de Nexus
• Funciones de la API de Altium Designer
• Procesos paramétricos

Palabras reservadas y funciones

El sistema de scripting admite el lenguaje VBScript, que deriva de la tecnología de lenguaje 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