Visual Basic Concepts

Guidelines for Creating Collection Classes

A collection provides a way to connect a group of dependent objects with an object that ‘contains’ them. For example, an Invoice object might have a collection of LineItem objects.

As discussed earlier in "Naming Guidelines," the name of a collection should be the plural of the name of the object it contains. Thus an Invoice object might have a LineItems collection to contain its LineItem objects.

Implementing Collections

Visual Basic provides a generic Collection class for managing groups of objects, as discussed in "The Visual Basic Collection Object," in "Programming with Objects" in the Visual Basic Programmer’s Guide.

You can implement collections for your component’s object model by wrapping a private Collection object in a class module, thus defining a collection class from which you can create instances as needed. This is explained in "Creating Your Own Collection Classes," in "Programming with Objects" in the Visual Basic Programmer’s Guide.

In addition to describing the steps you need to take, "Creating Your Own Collection Classes" includes code examples that show why collection classes are the most robust way to use the Collection object.

A robust implementation is critical to the successful reuse of component code. Other programmers will rely on the robustness of the objects you create. Don’t take shortcuts.

Collection Class Properties and Methods

The following table shows properties and methods you should implement for collection classes.

Method or property	Description
Add	Adds an item to a collection. If used for object creation, the method should return a reference to the newly created object.
Count (property)	Returns the number of items in the collection.
Item	Returns a reference to a single item from the collection. The argument may be a numeric index or a key value. This is usually the default property.
Remove	Removes an item from a collection. The argument may be a numeric index or a key value.
NewEnum	Returns the IUnknown interface of an enumerator object that For Each … Next can use to iterate over the items in a collection. Should be hidden in the type library. Must have a Procedure ID value of -4 to work with For Each … Next.

Implementing an Add or Insert Method

One of the keys to creating a robust collection class is implementing your own Add method. Your Add method can delegate to the Add method of a Visual Basic Collection object, while providing type safety or controlling access to the collection.

Type safety is very easily implemented, as shown in the following code fragment for the Add method of a hypothetical Widgets collection class:

Public Sub Add(ByVal NewWidget As Widget, _
      Optional ByVal Key As String = "")
   If String = "" Then
      mcolWidgets.Add NewWidget
   Else
      mcolWidgets.Add NewWidget, Key
   End If
End Sub

All the work of maintaining the collection and generating error messages is delegated to a private instance of the Visual Basic Collection class, a reference to which is kept in mcolWidgets. The Add method of the private Collection object, which can accept objects of any type, is shielded by the declaration shown above, which can accept only Widget objects.

Note   Many existing collection implementations use Add as the name of a method that creates a new element within a collection. You may want to name a method like that shown above — which puts an externally created object into a collection — "Insert" instead of "Add."

You can use the Add method to control access to a collection by making the class of objects the collection contains PublicNotCreatable. In this way, the Add method becomes the only way to create new objects within the collection. If you implement your Add method in this fashion, it should return a reference to the newly created object.

The Add method is a good place to call Friend functions that set the values of read-only properties such as the Parent property.

Examples and Utilities

"Creating Your Own Collection Classes" provides sample code for a collection class implemented according to these guidelines, and explains how to make Item the default method; how to hide NewEnum in the type library; and how to give NewEnum the correct Procedure ID.

The Class Builder utility, included in the Professional and Enterprise Editions of Visual Basic, creates collection class source code that follows these guidelines. You can customize this source code with your own events, properties, and methods.

For More Information   See the "Add Method," "Remove Method," "Item Method," or "Count Property" reference topic, or see "The Visual Basic Collection Object," in "Programming with Objects," in the Visual Basic Programmer’s Guide.