Microsoft Office 2000/Visual Basic Programmer's Guide

Accessing Objects in a Custom Object Model

If you create an object model that has a hierarchical organization, you must include object properties to access the lower-level members of the object model. For example, in the EnumWindows.xls example, located in the ODETools\V9\Samples\OPG\Samples\CH10 subfolder on the Office 2000 Developer CD-ROM, every ParentWindow object has a ChildWindows collection. To work with the ChildWindows collection, you must return a reference to it that's associated with the ParentWindow object. The sample uses an object property within the ParentWindow object to do this, the ChildWindows property. The ChildWindows property has the same name as the collection it returns, which simplifies its use and makes the custom object model consistent with the built-in object models in Office 2000.

Here are the Property Set and Property Get procedures for the ChildWindows property of the ParentWindow object. Note that the Property Set procedure takes an argument of type ChildWindows, and the Property Get procedure returns a reference to a ChildWindows collection.

Public Property Set ChildWindows(colChildWindows As ChildWindows)
   ' This property sets a reference to the ParentWindow
   ' object's ChildWindows collection.
   ' Write-once property.

   If p_colChildWindows Is Nothing Then
      ' Assign reference to passed-in object to private
      ' module-level variable.
      Set p_colChildWindows = colChildWindows
   End If
End Property

Public Property Get ChildWindows() As ChildWindows
   ' This property returns a reference to the ParentWindow
   ' object's ChildWindows collection.

   ' Return reference to ChildWindows collection stored in
   ' private module-level variable.
   Set ChildWindows = p_colChildWindows
End Property

The Property Set procedure is a write-once property. For each instance of the ParentWindow class, you can set the ChildWindows property only once, although you can return it as many times as you want. Since every ParentWindow object has a ChildWindows collection, whether or not it contains any elements, the ChildWindows property is set in the Class_Initialize event procedure of the ParentWindow class. From the perspective of the programmer using the ParentWindow object, the ChildWindows property is read-only; because the property is set in the Class_Initialize event procedure, the property returns a reference to the ChildWindows collection as soon the object has been created.

Note that every property that is read-only must be set somewhere within your code. The difference between a read-write property and a read-only property is whether the property can be set by the programmer who's using the object, or whether it can only be set internally, by your code.

The line of code that sets the ChildWindows property is shown in the following example, taken from the Class_Initialize event procedure:

' Create a new ChildWindows collection and assign it
' to the ParentWindow object's ChildWindows property.
Set Me.ChildWindows = New ChildWindows

This statement creates a new instance of the ChildWindows collection. Rather than assigning the reference directly to an object variable, the statement assigns it to the ChildWindows property of the ParentWindow object. The ChildWindows property takes care of handling the reference to the parent window's ChildWindows collection.

After the object property has been set, it returns a reference to the collection, so that you can use it to traverse the object hierarchy. For example, the following line of code prints the value of the first child window's Caption property to the Immediate window:

? ParentWindows.Item(1).ChildWindows.Item(1).Caption