Product classes and objects

Creating objects

The product automatically creates some objects (cells in a spreadsheet for example). You can use the product user interface to create objects, and you can create objects in a script.

To create an object in a script, you must supply whatever arguments the product requires to create an instance of the particular class, and you must assign an object reference to a variable. The syntax is usually:

Dim objRef As prodClass

Set objRef = New [ prodClass ] [( argList )]

The Dim statement declares an object reference variable. The Set...New statement creates a product object and assigns the variable a reference to that object. You can also combine these operations in a single statement:

Dim objRef As New prodClass [( argList ])]

You can use a method to create the object. For example, in Notes® Release 4, you use the NotesDatabase Create method to create a new .NSF file.

You can also use a container method to create objects in scripts. A container method applies to the object that contains the object you are creating. For example, Freelance Graphics® for Windows™ provides container methods for creating objects.

Referring to objects

To refer in a script to an object that already exists, you can usually use the name that the product or user gave to the object. You can (and in some cases you must) assign your own object reference.

One way to assign your own object reference to a variable is to declare an object variable, such as:

Dim objRef As prodClass

and bind it to the product object. For example:

Set objRef = Bind [ prodClass ] [( objName ])]

The product can supply a function or method that you can use to set an object reference.

The following Initialize sub works with three Notes® objects: a database, a view, and a document. The sub uses a Dim...New statement to create a new NotesDatabase object to work with ORGSTRUC.NSF on the HR_ADMIN server, and it uses methods in Set statements to set variable references to a view and a document. GetView is a NotesDatabase class method, and GetFirstDocument is a NotesView class method.

Sub Initialize
   Dim db As New NotesDatabase("HR_ADMIN", "ORGSTRUC.NSF")
   Dim view As NotesView, doc As NotesDocument
   Set view = db.GetView("Main View")
   Set doc = view.GetFirstDocument
End Sub

Bracket notation

In some cases, you can use names in brackets rather than object reference variables to identify IBM® software objects.

For example, the product might allow you to use:

[A1].Value = 247000

instead of:

Dim myCell As Cell
Set myCell = Bind Cell("A1")
myCell.Value = 247000

Properties, methods, and events

Each product class defines a set of properties, methods, and events. As with user-defined classes, you use dot notation to specify properties and methods.

Properties are object attributes. Like variables, properties have values. You can get and set a property value. However, some properties you can only get, and some you can only set.

Methods are object operations. You call methods to perform actions on classes.

Events are object-related actions to which you can attach scripts to perform activities in an application. When the event occurs, the script attached to the event executes. For example, you can set the value of the Title property in the Click event script:

db.Title = "HQEVB Group Discussion"

IBM® products normally handle the process of attaching scripts you write to the events you specify. You can also use IBMScript On Event statements to attach subs to object events.

For example, a db object is an instance of the Notes/Domino NotesDatabase class. It has a number of properties, including FileName, FilePath, and Title.

The value of the Title property is a string specifying the title of the database. In a script, you can get and set the value of Title. You can only get the values of FileName and FilePath, which specify the location the database in the file system.

Deleting objects

You can sometimes use the Delete statement to delete a product object or the object reference variable. The object reference variables that you explicitly declare and bind to product objects have a scope. When all object references (there may be more than one) to an object created in a script are out of scope, the object itself may be deleted. Some products supply methods to remove actual objects. For example, in Notes®, you use the NotesDatabase class Remove method to delete an .NSF file.

Collection classes

Some IBM® products provide collection classes, also known as container classes. A collection object (an instance of a collection class) contains a collection of objects.

For example, in Freelance Graphics® an Application object contains an instance of the Documents collection class. Each Document object contains an instance of the Pages collection class and each page object contains an instance of the ObjectCollection class. The ObjectCollection object can include text boxes, charts, tables, and other objects belonging to classes derived from the DrawObject class.

You can use ForAll loops or indexing to access individual members of a collection class. The following script uses three nested ForAll loops to iterate through the collections. Within individual TextBlock objects, the script uses indexing to set list entries levels 2 through 5 in each TextBox object to italic.

Dim level As Integer
ForAll doc In CurrentApplication.Documents
   ForAll page In Document.Pages
      ForAll obj In Page.Objects
         ' If the object is a TextBlock, set the font
         ' to Garamond, and set list entries at levels 
         ' 2 through 5 to Italic.
         If obj.IsText Then ' IsText is a DrawObject property.
            obj.Font.FontName = "Garamond"
            For level% = 2 to 5
               obj.TextProperties(level%).Font.Italic = TRUE
            Next level%
         End If
      End ForAll
   End ForAll
End ForAll