Add Method

Applies To

Collection object.

Description

Adds a member to a Collection object.

Syntax

object.Add item, key, before, after

The Add method syntax has the following object qualifier and named arguments

Part	Description

object	Required. An object expression that evaluates to an object in the Applies To list.
item	Required. An expression of any type that specifies the member to add to the collection.
key	Optional. A unique string expression that specifies a key string that can be used, instead of a positional index, to access a member of the collection.
before	Optional. An expression that specifies a relative position in the collection. The member to be added is placed in the collection before the member identified by the before argument. If a numeric expression, before must be a number from 1 to the value of the collection's Count property. If a string expression, before must correspond to the key specified when the member being referred to was added to the collection. You can specify a before position or an after position, but not both.

(continued)

Part	Description

after	Optional. An expression that specifies a relative position in the collection. The member to be added is placed in the collection after the member identified by the after argument. If numeric, after must be a number from 1 to the value of the collection's Count property. If a string, after must correspond to the key specified when the member referred to was added to the collection. You can specify a before position or an after position, but not both.

Remarks

Whether the before or after argument is a string expression or numeric expression, it must refer to an existing member of the collection, or an error occurs.

An error also occurs if a specified key duplicates the key for an existing member of the collection.

See Also

Item method, Remove method.

Specifics (Microsoft Access)

Items added to a user-defined collection are automatically indexed. You can refer to an individual item by this index. For example, if you have a collection colThings that contains four objects, you can refer to the third item in the collection with the expression colThings(3).

Note When you add items to a Collection object, they are automatically indexed beginning with the number 1. Therefore, when you enumerate a Collection object, keep in mind that the index begins at 1. This may be different from built-in collections, which usually are indexed beginning with 0.

When you add an object to a user-defined collection, you can also specify a custom key for that object in addition to the automatic index. In subsequent references to the object, you can refer to the custom key. For example, you can add an object objMine with the following key.

colThings.Add Item := objMine, key := ("A")

Subsequently you can refer to this particular object in the collection either as colThings(A), or by its numeric index.

Example

This example uses the Add method to add Inst objects (instances of a class called Class1 containing a Public variable InstanceName) to a collection called MyClasses. To see how this works, insert a class module and declare a public variable called InstanceName at module level of Class1 (type Public InstanceName) to hold the names of each instance. Leave the default name as Class1. Copy and paste the following code into the Form_Load event procedure of a form module.

Dim MyClasses As New Collection    ' Create a Collection object.
Dim Num As Integer                        ' Counter for individualizing keys.
Dim Msg
Dim TheName                                ' Holder for names user enters.
Do
    Dim Inst As New Class1            ' Create a new instance of Class1.
    Num = Num + 1                        ' Increment Num, then get a name.
    Msg = "Please enter a name for this object." & Chr(13) _
        & "Press Cancel to see names in collection."
    TheName = InputBox(Msg, "Name the Collection Items")
    Inst.InstanceName = TheName    ' Put name in object instance.
    ' If user entered name, add it to the collection.
    If Inst.InstanceName <> "" Then
        ' Add the named object to the collection.
        MyClasses.Add item := Inst, key := CStr(Num)
    End If
    ' Clear the current reference in preparation for next one.
    Set Inst = Nothing
Loop Until TheName = ""
For Each x In MyClasses
    MsgBox x.instancename, , "Instance Name"
Next

Example (Extensibility Object Model)

The following example uses the Add method to add one standard module to the VBComponents collection.

Application.VBE.VBProjects(1).VBComponents.Add(vbext_ct_StdModule)