Objects (topic)

The Basic Control Engine defines two types of objects: data objects and OLE automation objects.

Syntactically, these are referenced in the same way.

What Is an Object

An object in the Basic Control Engine is an encapsulation of data and routines into a single unit. The use of objects in the Basic Control Engine has the effect of grouping together a set of functions and data items that apply only to a specific object type.

Objects expose data items for programmability called properties. For example, a sheet object may expose an integer called NumColumns. Usually, properties can be both retrieved (get) and modified (set).

Objects also expose internal routines for programmability called methods. In the Basic Control Engine, an object method can take the form of a function or a subroutine. For example, a OLE automation object called MyApp may contain a method subroutine called Open that takes a single argument (a filename), as shown below:

  MyApp.Open "c:\files\sample.txt"

Declare Object Variables

In order to gain access to an object, you must first declare an object variable using either Dim, Public, or Private:

  Dim o As Object  'OLE automation object

Initially, objects are given the value 0 (or Nothing). Before an object can be accessed, it must be associated with a physical object.

Assign a Value to an Object Variable

An object variable must reference a real physical object before accessing any properties or methods of that object. To instantiate an object, use the Set statement.

  Dim MyApp As Object
  Set MyApp = CreateObject("Server.Application")

Access Object Properties

Once an object variable has been declared and associated with a physical object, it can be modified using the Basic Control Engine code. Properties are syntactically accessible using the dot operator, which separates an object name from the property being accessed:

  MyApp.BackgroundColor = 10
  i% = MyApp.DocumentCount

Properties are set using the Basic Control Engine normal assignment statement:

  MyApp.BackgroundColor = 10

Object properties can be retrieved and used within expressions:

  i% = MyApp.DocumentCount + 10
  MsgBox "Number of documents = " & MyApp.DocumentCount

Access Object Methods

Like properties, methods are accessed via the dot operator. Object methods that do not return values behave like subroutines in the Basic Control Engine (that is, the arguments are not enclosed within parentheses):

  MyApp.Open "c:\files\sample.txt",True,15

Object methods that return a value behave like function calls in the Basic Control Engine. Any arguments must be enclosed in parentheses:

  If MyApp.DocumentCount = 0 Then MsgBox "No open documents."
  NumDocs = app.count(4,5)

There is no syntactic difference between calling a method function and retrieving a property value, as shown below:

  variable = object.property(arg1,arg2)   variable = object.method(arg1,arg2)

Compare Object Variables

The values used to represent objects are meaningless to the script in which they are used, with the following exceptions:

  • Objects can be compared to each other to determine whether they refer to the same object.
  • Objects can be compared with Nothing to determine whether the object variable refers to a valid object.

Object comparisons are accomplished using the Is operator:

  If a Is b Then MsgBox "a and b are the same object."
  If a Is Nothing Then MsgBox "a is not initialized."
  If b Is Not Nothing Then MsgBox "b is in use."

Collections

A collection is a set of related object variables. Each element in the set is called a member and is accessed via an index, either numeric or text, as shown below:

  MyApp.Toolbar.Buttons(0)
  MyApp.Toolbar.Buttons("Tuesday")

It is typical for collection indexes to begin with 0.

Each element of a collection is itself an object, as shown in the following examples:

  Dim MyToolbarButton As Object
  Set MyToolbarButton = MyApp.Toolbar.Buttons("Save")
  yAppp.Toolbar.Buttons(1).Caption = "Open"

The collection itself contains properties that provide you with information about the collection and methods that allow navigation within that collection:

  Dim MyToolbarButton As Object
  NumButtons% = MyApp.Toolbar.Buttons.Count
  MyApp.Toolbar.Buttons.MoveNext
  MyApp.Toolbar.Buttons.FindNext "Save"
  For i = 1 To MyApp.Toolbar.Buttons.Count
    Set MyToolbarButton = MyApp.Toolbar.Buttons(i)
    MyToolbarButton.Caption = "Copy"
  Next i

Predefined Objects

The Basic Control Engine predefines a few objects for use in all scripts. These are:

Clipboard System HWND 
Net Basic Screen