VBSCRIPT

VBScript

Date Published:
Last Modified:

Child Pages

  • Corel Draw Macros
  • Overview

    Visual basic is one of the scripting languages you can use to write code for interfacing with the PCB design software Altium, through it’s provided API.

    The Basics

    VBScript is not case-sensitive. That is, the variable myInt is the same as the variable myint. This said, I prefer to capitalise the start of any system word in VBScript (e.g. And, For, If, End If, Dim).

    There is no end of command/end of line delimiter. This is probably one of the first things you will notice when coming from another language such as C.

    Variables

    Variables are defined with the keyword Dim. However, by default, you do not need to do this before using them (you can create them on the fly).

    Forcing You To Declare Variables

    By default, VBScript does not force you to declare variables. This can generate hard-to-find bugs when you accidentally type a variable name in incorrectly and end up creating a new variable rather than using an old one. To prevent this from occurring, add the following line of code to the top of every script file:

    Option Explicit

    This forces you to declare every variable with Dim before using it. I make sure to add this to the top of every file!

    Comments

    Single-line comments are started with the ‘ character, and continue until a new line occurs.

    Dim myVar ' This is a single-line comment

    Strings

    Strings are delimited by double-quotation marks (“).

    "This is a string in VBScript"

    You can add non-printable characters the using system constants.

    VbCr ' Carriage return
    VbLf ' Line feed

    You can format doubles into strings with the function FormatNumber().

    Regex

    Regex is particularly easy in VBScript, as it comes with a built-in regex engine (as of VBScript v5.0). Regex is performed through iteration with the RegExp object. The regex syntax in VBScript is very similar to that used for JScript.

    The RegExp object provides 3 properties and 3 methods. The properties are:

    PropertyDescription
    PatternA string containing the regex pattern to match input with. This is a core part of the object! This must be set before any RegExp methods are called.
    IgnoreCaseA boolean that when True ignores the case (case insensitive) when matching the pattern.
    GlobalA boolean that if True, will match only the first pattern it finds. If False, the regex engine will find all patterns. Default is False.

    The methods are:

    MethodDescription
    Test(searchString)Returns True if the regex pattern set by Pattern can be matched in searchString, otherwise False.
    Replace(searchString, replaceString)Replaces any match of Pattern in searchString by replaceString, and returns the new string. If no matches were found, the original string (searchString) is returned.
    Execute(searchString)Returns a Matches collection object, containing a Match object for each successful match of Pattern in searchString. It doesn't modify searchString.

    Match Object

    The Match object is returned when the Execute method of the RegExp object is called. It has three properties:

    PropertyDescription
    FirstIndexThe position within the original string where the match occurred. This is zero-based (the first position is 0).
    LengthThe total length of the matched string.
    ValueA string of the matched text. This is the default property when accessing the Match object.

    Test() Example

    The following example uses regex to search for a component designator.

    ' Setup a test string
    Dim componentDesignator
    componentDesignator = "C23"
    
    ' Now do the regex
    Set regex = New RegExp
    regex.IgnoreCase = True
    regex.Global = True
    ' Look for designator that starts with C and is followed by one or more numbers
    regex.Pattern = "^C[0-9][0-9]*"
    
    ' Check for pattern match
    If regex.Test(componentDesignator) Then
        StdOut("Capacitor found!")
    End If

    Integers

    A unary operator for easy increment/decrement is not supported (like ++ and – in C), so the best way is to just use:

    myInt = myInt + 1

    Function Pointers

    Function pointers, in the C style of using them, are not available in VBScript. However, you can use the GetRef() function to get similar functionality.

    You pass into GetRef(funcNameString) a string of the name of the function you want to get a reference to (i.e. pointer).

    Function IAmAFunction ()
        ShowMessage("Test function!")
    End Function
    
    ' Create a function pointer
    myFunc = GetRef(IAmAFunction)
    ' This line calls the function pointed to by myFunc
    Call myFunc()

    GetRef() is one of the functions you can’t use when doing Altium Scripting.

    Sets (The MkSet()/InSet() Functions)

    Sets of objects are supported in VBScript through the MkSet() and InSet() functions. It creates a set of the given input objects. You can have a maximum of 32 objects in a set. You can also create an empty set, by providing no input variables.

    Dim var1, var2, set1, set2
    
    ' Creating a populated set
    set1 = MkSet(var1, var2)
    
    ' Creating an empty set
    set2 = MkSet()

    Sets are a common design object used in a number of other scripting languages such as DelphiScript, JScript, C++Script and C#Script.

    Trigonometry

    VBScript has no built in value for Pi. What?!? The best way to do this is to use the following expression:

    ' Get a value for Pi, which is a precise as the computer will allow
    ' Better than a hand typed constant!
    Pi = 4 * Atn(1)

    This will give Pi to the maximum precision available on the platform you a running on. You can’t ask for better!

    Thankfully, VBScript has built in support for the cos() and sin() family of functions. They take an input angle in radians. To convert between radians and degrees you can use the following expressions:

    ' Let's first get a value for Pi
    Pi = 4 * Atn(1)
    
    ' Converting from radians to degrees
    ValueInDeg = ValueInRad*180/Pi
    
    ' Converting from degrees to radians
    ValueInRad = ValueInDeg*Pi/180

    Like this page? Upvote with shurikens!

    Related Content:

    Tags:

    comments powered by Disqus