VBScript

Esta referencia describe el lenguaje de scripting Visual Basic que se utiliza para crear scripts en Altium Designer. Ofrece información detallada sobre las sentencias, funciones y extensiones de Visual Basic Scripting compatibles con el sistema de scripting.

También en esta guía:

• 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) se puede utilizar para crear scripts que trabajen con los modelos de objetos y los componentes visuales de Altium Designer. En esta referencia, se da por hecho que estás familiarizado con los conceptos básicos de programación y con el funcionamiento básico de Altium Designer.

El sistema de scripts de Altium Designer es compatible con el lenguaje VBScript (junto con otros lenguajes de script), que se deriva del sistema Microsoft ActiveX Scripting. Así, por ejemplo, deberías poder utilizar CScripts o WScripts, que se basan en el mismo motor de scripts ActiveX que se utiliza en Altium Designer.

Todos los lenguajes de scripting compatibles con Altium Designer son de tipo libre o sin tipos, 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 la biblioteca RTL de Delphi

El sistema de scripts es compatible con un subconjunto de la biblioteca de tiempo de ejecución (RTL) de Embarcadero Delphi y la API de Altium Designer.

Los scripts VBScript pueden acceder a varios modelos de objetos de Altium Designer. Por ejemplo, el modelo de objetos de PCB se puede utilizar en VBScript para gestionar objetos de PCB en un documento de PCB, o el modelo de objetos del Gestor del espacio de trabajo para trabajar con proyectos y sus documentos con el fin de extraer datos de la lista de conexiones.

La Referencia de scripts contiene información sobre las interfaces relacionadas con los modelos de objetos de Altium Designer, los componentes, las rutinas globales, los tipos y las variables que conforman este lenguaje de scripts. Consulte la documentación de Microsoft Visual Basic para obtener más información sobre las funciones de VBScript.

Procesos de servidor

Se puede utilizar un script para ejecutar procesos de servidor, que representan comandos en Altium Designer.

Archivos fuente de VBScript

Un proyecto de VBScript está organizado para almacenar documentos de script (unidades de script y formularios de script). Un script se puede ejecutar desde una opción de menú, un botón de la barra de herramientas o desde el Run Script cuadro de diálogo del menú del sistema.

Archivos PRJSCR, VBS y DFM

Los scripts se organizan en proyectos con la *.PRJSCR extensión. Cada proyecto de VBScript consta de archivos con una *.vbs . Los archivos pueden ser unidades de script o formularios de script; cada formulario cuenta con un archivo de script VBScript con *.vbs extensión y un formulario correspondiente con una *.dfm extensión). Un formulario de script es una ventana gráfica (cuadro de diálogo) que alberga diferentes controles que se ejecutan sobre Altium Designer.

Es posible adjuntar scripts a diferentes proyectos, y se recomienda encarecidamente organizarlos en proyectos distintos para gestionar el número de scripts y sus procedimientos o funciones. Los scripts (unidades de script y formularios de script) constan de funciones o procedimientos que pueden invocarse 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 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 Embarcadero Delphi RTL que están disponibles en el sistema de scripting.

Cómo escribir scripts de VBScript

Esta sección aborda los conceptos básicos de la escritura de scripts 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 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 que los nombres de las variables sean únicos dentro de un mismo proyecto de scripts. Si las variables se definen outside en subrutinas o funciones, son globales y cualquier unidad del mismo proyecto puede acceder a ellas.

Si las variables se definen inside una rutina, estas variables locales no son accesibles fuera de dichas rutinas. Dado que los scripts no tienen tipos, 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 admite dos tipos de procedimientos: subrutinas y funciones; una función solo 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, la declaración de un procedimiento suele incluir una lista de parámetros; ten en cuenta que las variables se consideran sin tipo y que el sistema de scripts determina automáticamente cuáles son los tipos de las variables. 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

Ten en cuenta que el uso de la Call para invocar una subrutina o una función es opcional (se mantiene por motivos de 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 facilitar el trabajo del programador. Los comentarios pueden incluirse prácticamente en cualquier parte de un script.

En 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

División de una línea de script

En VBScript, cada instrucción de código finaliza en la línea (mediante una combinación de CR/LF) para indicar el final de la instrucción. VBScript 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, utilizando 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, en aras de la legibilidad y la facilidad de depuración, es recomendable limitar la longitud de las líneas de código para que puedan leerse fácilmente en pantalla o en formato impreso. 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 scripts es que las interfaces de los objetos de Altium Designer (interfaces de objetos) están disponibles para su uso en VBScripts. Por ejemplo, se pueden actualizar objetos de diseño en documentos de esquemas y PCB mediante el uso de las interfaces de esquemas y de PCB, respectivamente.

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

Para acceder a un documento de PCB y a sus objetos de datos, primero hay que invocar la PCBServer función. Por convención, los nombres de las interfaces van precedidos de un I carácter; por ejemplo, IPCB_Board representa una interfaz para 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 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

Objetos, interfaces y funciones

Se puede acceder a los objetos, interfaces y funciones de Altium Designer en scripts desde lo siguiente:

• API de cliente
• API del servidor de PCB
• API del servidor de esquemas
• API del servidor del gestor del espacio de trabajo
• API de Nexus
• Funciones de la API de Altium Designer
• Procesos paramétricos

Palabras y funciones reservadas

El sistema de scripts es compatible con el lenguaje VBScript, derivado de la tecnología de lenguaje Active Scripting de Microsoft. 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