This section describes how to work with objects and collections in Visual Basic code, with an emphasis on efficiency. Although the concepts are illustrated with TDBContainer3D objects and collections, you can apply the same fundamentals to all Visual Basic objects and collections.

A TDBContainer3D object is created when you place a TDBContainer3D control on a Visual Basic form. TDBContainer3D objects created in Visual Basic will have default names of TDBContainer3D1, TDBContainer3D2, and so forth. You can change the control name in the Visual Basic Properties window at design time. You can also change the control's properties using property pages at design time or Visual Basic code at run time.

A TDBContainer3D object has the following collections: Effects, Children. By default, the Effects collection contains three Effect object: Raised, Inset, and Flat. The Children collection is initially empty.

You can reference an object in a collection using its one-based index. For example, the default Effect object – Raised style has an index value of 1. You can read or set the Effect object's properties as follows:

' Read an Effect object property.

variable = TDBContainer3D1.Effects(1).Property

 

' Set a Effect object property.

TDBContainer3D.Effects(1).Property = variable

You can create a reference to an object in a collection using the collection's Item property. The following code creates a reference to the Effect object:

' Declare MyEffect as an Effect object.

Dim MyEffect As TDBContainerainer3D6Ctl.Effect

 

' Set MyEffect to reference the first effect in the collection.

Set MyEffect = TDBContainer3D1.Effects.Item(1)

Note the use of the type library qualifier TDBContainer3D6Ctl in the preceding example. Using the type library qualifier is recommended in order to resolve potential naming conflicts with other controls. For example, if you use another control in the same project that also defines an object named Effect, the TDBContainer3D6Ctl type library qualifier is required, as is the type library qualifier for the other control.

Since the Item property is implicit for collections, you can omit it:

' Declare MyEffect as an Effect object.

Dim MyEffect As TDBContainer3D6Ctl.Effect

 

' Set MyEffect to reference the first effect in the collection.

Set MyEffect = TDBContainer3D1.Effects(1)

You can now use MyEffect to read or set the Effect object's properties:

' Read an Effect object property.

variable = MyEffect.Property     

 

' Set an Effect object property.

MyEffect.Property = variable 

Very often, you need to read and set more than one of an object's properties. For example:

' Read an Effect object's properties.

variable1 = TDBContainer3D1.Effects(1).Property1

variable2 = TDBContainer3D1.Effects(1).Property2

 

' Set an Effect object's properties.

TDBContainer3D1.Effects(1).Property1 = variable1

TDBContainer3D1.Effects(1).Property2 = variable2

This code is very inefficient because each time the object TDBContainer3D1.Effects(1)is accessed, Visual Basic creates a reference to the object and then discards it after the statement is completed.It is more efficient to create a single reference to the object up front and use it repeatedly:

' Declare MyEffect as an Effect object.

Dim MyEffect As TDBContainer3D6Ctl.Effect

 

' Set MyEffect to reference the first effect in the collection.

Set MyEffect = TDBContainer3D1.Effects(1)

 

' Read a Effect object's properties.

variable1 = Effect.Property1

variable2 = Effect.Property2

 

' Set a Effect object's properties.

MyEffect.Property1 = variable1

MyEffect.Property2 = variable2

This code is much more efficient and also easier to read. If your Visual Basic application accesses collection objects frequently, you can improve the performance of your code significantly by adhering to these guidelines.

Visual Basic also provides an efficient With...End With statement for setting multiple properties of an object without explicitly assigning it to a variable. For example, the following code sets multiple properties of the first member of the Effect collection (recall that collections are one-based):

With TDBContainer3D1.Effects(1)

    .Property1 = variable1

    .Property2 = variable2

End With

Some collections allow you to reference their members by name. For example, you can reference an Effect object using either its index or the key name. Thus, the following statements are equivalent:

' Declare MyEffect as a Effect object.

Dim MyEffect As TDBContainer3D6Ctl.Effect

 

' Reference by numeric index.

Set MyEffect = TDBContainer3D1.Effects.Item(1)

 

' Reference by numeric index (Item property is implicit).

Set MyEffect = TDBContainer3D1.Effects(1)

 

' Reference by numeric index.

Set MyEffect = 1

 

' Reference by Effect object key name.

Set MyEffect = TDBContainer3D1.Effects("Raised")

 

' Reference by Effect object key name.

Set MyEffect = "Raised"

To create and add an object to a collection, use the collection's Add method. For example, you can create more 3D styles by adding new Effect objects to the Effects collection:

' Create and add a Effect object.

Dim MyEffect As TDBContainer3D6Ctl.Effect

Set MyEffect = TDBContainer3D1.Effects.Add(, "Frame")

This code adds an Effect object to the Effects collection.

Note that not all collections define their Add method to return a value. If a collection does nothing more than maintain a list of the arguments passed to its Add method, then there is no need for it to return the same item that was just added. For example, you can use the following code to add a new style in a Effects collection also:

TDBContainer3D1.Effects.Add , "Frame"

Regardless of how a collection implements the Add method, the syntax for removing items is the same. To remove an existing item from a collection, use the Remove method:

' Remove the Effect object with index 2.

TDBContainer3D1.Effects.Remove 2

 

' Remove the Effect object with key name.

TDBContainer3D1.Effects.Remove "Inset"

After this statement is executed, all Effect with collection indexes greater than 2 will be shifted down by 1 to fill the place of the removed style. Note that the Remove method is called like a subroutine—its argument is not enclosed in parentheses.

You can determine the number of objects in a collection using the collection's Count property:

' Set a variable equal to the number of Effects in the collection.

variable = TDBContainer3D1.Effects.Count

You can also iterate through all objects in a collection using the Count property as in the following example, which prints the Key name of each object:

For n = 1 To TDBContainer3D1.Effects.Count

Debug.Print TDBContainer3D1.Effects(n).Key

Next n

The Count property is also useful for removing styles:

' The following loop removes Effects from the collection.

While TDBContainer3D1.Effects.Count

TDBContainer3D1.Effects.Remove 1

Wend

Visual Basic also provides an efficient For Each...Next statement that you can use to iterate through the objects in a collection without using the Count property:

Dim MyEffect As TDBContainer3D6Ctl.Effect

 

For Each MyEffect In TDBCont3D1.Effects

    Debug.Print MyEffect.Key

Next MyEffect

In fact, using the For Each...Next statement is the preferred way to iterate through the objects in a collection.

Copyright (c) GrapeCity, inc. All rights reserved.