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.
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.
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
Set MyObj = New clsMyClass
Then you can access the properties, functions, and subroutines written in the
Class block using the
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
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.
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 can be defined in the "class" scope similar to variables declared in the global scope. They use the
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.
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.
To retrieve a value from an object, you are "getting" a value by that name. A
Property Get appears very similar to a
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.
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.
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.
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.
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
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
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
Private. You cannot use
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
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:
Or you can get the property just by using the object's name:
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
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
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.