VBScript class

From StealthBot Wiki
Jump to: navigation, search

Use a VBScript class to make custom objects.

A class is to a variable as an object is to a value: the class tells what things the object can store and what operations the object can perform.

Class block

The class is a container containing functions, subroutines, "properties", and variables which only are made accessible when the class is initialized into a new object.

Use the Class keyword followed by the class's name (must be a valid identifier) to start a class, and End Class to end it.

Class clsMyClass
    ' put contents here
End Class

A class can have any of the above four items inside the starting and ending lines.

Creating custom objects

A class is a "template" for a custom object. To create and use an instance of this object, use the Set keyword and the New keyword:

Set MyObj = New clsMyClass

Then you can access the properties, functions, and subroutines written in the Class block using the . operator:

MyObj.DoSomething

Functions and subroutines

Functions in the "class" scope are written just like functions written in the global scope: they have a name, a variable amount of parameters, and (for Functions) a return value.

They are written the same, except now they are inside the class block:

Class clsMyClass
    Sub DoSomething()
        ' do something
    End Sub
    
    Function ClassFunction()
        ' do something
        ClassFunction = SomeValue
    End Function
End Class

To call these functions, create this custom object and call the function using the . operator: MyObj.DoSomething.

If you are coding inside the class and wish to call another function also inside the class, use just that function's name as you would call a function in the global scope. Inside the class, the object is not known since the class can be initialized multiple times to any other variable in the script.

Now the Public and Private modifiers are in the context of the class and not the script. Trying to call a function declared Private from outside a class will fail. Functions default to Public in a class. Private functions are useful for making code that can only be activated by other function or property calls.

Public subroutines and functions can be collectively be called the "methods" of the class or object.

Variables

Variables can be defined in the "class" scope similar to variables declared in the global scope. They use the Public or Private keywords to define privacy (or Dim which means public) similarly to functions.

Class clsMyClass
    Public YourVar
    Private MyVar
    
    Sub DoSomething()
        ' do something
    End Sub
    
    Function ClassFunction()
        ' do something
        ClassFunction = SomeValue
    End Function
End Class

Public variables can be accessed from outside the object: MyObj.YourVar. Public and private variables can be accessed from inside the class's functions using just their identifier.

Properties

A property is the special thing that objects have that allow you to define "read-only" "variables", "variables" calculated on the spot, "variables" stored in a special way, and other variations.

There are three types of properties, those that Get a value from the object, those that Let a value into the object, and those that Set an object value into the object.

Get

To retrieve a value from an object, you are "getting" a value by that name. A Property Get appears very similar to a Function.

    Property Get MyValue()
        ' do something
        MyValue = SomeValue
    End Property

To get a value from this property: MyObj.MyValue. An example property getter is the Count property of a Scripting.Dictionary.

Properties can define required parameters like functions can. An example of this is the Item(Key) property of a Scripting.Dictionary. It returns a certain value based on which key was requested.

Sometimes, property getters are just one line, getting the value of a private variable.

Let

To store a value into an object, you are "letting" a value by that name. A Property Let is defined like a subroutine, but is stored into like a variable.

    Property Let MyValue(NewValue)
        ' do something with NewValue
    End Property

To let a value into this property: MyObj.MyValue = SomeValue. An example property letter is the CompareMode property of a Scripting.Dictionary.

Property Lets must provide one parameter, the value that is to be let, plus additional parameters from zero to as many as needed. The last parameter provided in the parameter list corresponds to the value on the right of the = in the storing statement, while the remaining parameters correspond to arguments that go in parentheses to the left of the = in the storing statement.

An example of this is the Item(Key) property of a Scripting.Dictionary. It stores the provided value based on which key was also provided. The signature of this property would look like:

    Property Let Item(Key, NewItem)
        ' ...
    End Property

This property would be stored to by the code: Dict.Item(Key) = SomeValue.

Sometimes, property letters are just one line, storing the passed value into a private variable.

Set

To store an object value into an object, you are "setting" a value by that name. A Property Set is almost identical to a Property Let, but will be accessed instead of the letter if the passed value was an object.

Property Sets must provide one parameter but can provide as many as needed.

Example usage:

    Property Set MyValue(NewValue)
        ' do something with NewValue (object)
    End Property

And to set the value:

Set MyObj.MyValue = SomeObject

In other programming languages' lingo, "set" is used in place of Visual Basic's "let" and stands for both VB "let" and VB "set", but in VB "let" is for non-objects and "set" is for objects.

Sometimes, property setters are just one line, storing the passed object into a private variable. Setters aren't as common as letters.

Summary

Property Gets and Property Lets (and/or Property Sets) can be put in the same class with the same name (but not more than one each) to store and retrieve that conceptual "property" of the object.

The number of parameters must match between properties of the same name, except one more for Set and Let than Get for the "new value" parameter. For example, if there is one parameter in a Property Get there must be two parameters in the Property Let or Property Set of the same name.

We will put all of the above together into:

Class clsMyClass
    Private ROVal
    Private CVal
    Private Obj
    
    Property Get ReadOnlyValue()
        ReadOnlyValue = ROVal
    End Property
         
    Property Get CheckedValue()
        CheckedValue = CVal
    End Property
    
    Property Let CheckedValue(NewVal)
        If CVal >= 0 And CVal < 1000 Then
            CVal = NewVal
        End If
    End Property
    
    Property Get TheObj()
        Set TheObj = Obj
    End Property
    
    Property Set TheObj(NewObj)
        Set Obj = NewObj
    End Property
End Class

Here the ROVal can only be changed by methods inside this class, the CVal can only be changed to a valid value, and the Obj can be accessed and set to.

You can use Exit Property to exit properties just as you can functions and subroutines.

Properties may also declare privacy by preceding the Property keyword with Public or Private. You cannot use Public or Private keywords with the Class block. You cannot access classes to make custom objects from other scripts.

It is recommended to use private variables and public properties in the way shown in this example so that you have more control over what can be stored and retrieved.

The methods, public variables, and public properties can be collectively called the "members" of the class or object.

You should indent your code for readability based on the starting and ending of classes and its methods and properties.

Default property or method

A property get or function can be declared as the Default property or function of that class. There can be only one default member, and it cannot be a variable, a property let, or a property set. A Default member must always be declared Public.

Syntax:

Class clsMyClass
    Public Default Property Get Name()
        Name = "MyObject"
    End Property
End Class

To access this special default property, you can use the object name, the ., and the name:

AddQ MyObj.Name

Or you can get the property just by using the object's name:

AddQ MyObj

If the result of an object value is used as a non-object (as it is in the case of AddQ: looking for a string), and there is an available default member, that member will be evaluated.

You can also do this with a function:

Class clsMyClass
    Public Default Function GetName()
        Name = "MyObject"
    End Function
End Class
...
Set MyObj = New clsMyClass
AddQ MyObj

Or a subroutine:

Class clsMyClass
    Public Default Sub ShowName()
        AddQ "MyObject"
    End Sub
End Class
...
Set MyObj = New clsMyClass
Call MyObj()

Here is an example of an object that you can store a non-object value into (using a default property):

Class clsMyClass
    Private TheValue
    
    Private Sub Class_Initialize()
        TheValue = "MyObject"
    End Sub
    
    Public Default Property Get Value()
        Value = TheValue
    End Property
    
    Public Property Let Value(NewValue)
        TheValue = NewValue
    End Property
End Class
...
Set MyObj = New clsMyClass
AddQ MyObj ' "MyObject"
MyObj.NewValue = "the new value"
AddQ MyObj ' "the new value"

Try not to use parameter-less default properties, because you might get tricked into thinking that assigning MyObj = some value assigns to the let property of the same name as the default. Instead, the variable MyObj is just being reassigned.

The Scripting.Dictionary is an example of an object with a default property which requires an argument. You can access the Item property without typing the .Item part:

Set Dict = CreateObject("Scripting.Dictionary")
' old way:
Dict.Item(Key) = Value
AddQ Dict.Item(Key)
' new way:
Dict(Key) = Value
AddQ Dict(Key)

Constructing and deconstructing

To create or "construct" an object, use the New keyword as mentioned before:

Set MyObj = New clsMyClass

When this is done, the object is created and a "initialize" event is fired inside the class. If there is a subroutine in the class with the name Class_Initialize, that subroutine will be called. This is a simple "constructor", which allows you to have the object do something to prepare its contents, if necessary.

To destroy or "deconstruct" an object, set the variable to Nothing:

Set MyObj = Nothing

The object will fire a "terminate" event, then clean itself up. If there is a subroutine with the name Class_Terminate, that will be called in the same manner.

Constructors and deconstructors cannot have parameters like in other programming languages.

See also