Add, méthode (objet Collection)

Article
09/12/2008

Mise à jour : novembre 2007

Ajoute un élément à un objet Collection.

Public Sub Add( _
   ByVal Item As Object, _
   Optional ByVal Key As String, _
   Optional ByVal { Before | After } As Object = Nothing _
)

Paramètres

Item
Requis. Objet de tout type qui spécifie l'élément à ajouter à la collection.
Key
Facultatif. Expression String unique qui spécifie une chaîne clé qui peut être utilisée à la place d'un index positionnel pour accéder à ce nouvel élément dans la collection.
Before
Facultatif. Expression spécifiant une position relative dans la collection. L'élément à ajouter est placé dans la collection avant l'élément identifié par l'argument Before. Si Before est une expression numérique, il doit avoir pour valeur un nombre compris entre 1 et la valeur de la propriété Count (voir Count, propriété (objet Collection)) de la collection. Si Before est une expression String, il doit correspondre à la chaîne clé spécifiée au moment où l'élément auquel il est fait référence a été ajouté à la collection. Vous ne pouvez pas spécifier Before et After à la fois.
After
Facultatif. Expression spécifiant une position relative dans la collection. L'élément à ajouter est placé dans la collection après l'élément identifié par l'argument After. Si After est une expression numérique, il doit avoir pour valeur un nombre compris entre 1 et la valeur de la propriété Count de la collection. Si After est une expression String, il doit correspondre à la chaîne clé spécifiée au moment où l'élément auquel il est fait référence a été ajouté à la collection. Vous ne pouvez pas spécifier Before et After à la fois.

Exceptions/Codes d'erreur

Type d'exception	Numéro de l'erreur	Condition
ArgumentException	5	Before et After sont tous deux spécifiés. L'argument Before ou After ne fait pas référence à un élément existant de la collection. La Key spécifiée existe déjà.

Consultez la colonne « Numéro d'erreur » si vous mettez à niveau des applications Visual Basic 6.0 qui utilisent la gestion non structurée des erreurs. (Vous pouvez comparer le numéro d'erreur par rapport à Number, propriété (objet Err).) Toutefois, lorsque cela est possible, vous devez envisager de remplacer un tel contrôle d'erreurs par Vue d'ensemble de la gestion structurée des exceptions pour Visual Basic.

Notes

L'argument Before ou After doit faire référence à un élément existant de la collection ; sinon, une erreur se produit.

Une erreur se produit également si une valeur Key spécifiée correspond à la clé pour un élément existant de la collection.

Exemple

L'exemple suivant utilise la méthode Add pour ajouter des objets child (instances d'une classe appelée child contenant un name de propriété Public) à une collection appelée family. Pour voir comment cela fonctionne, créez un Form avec deux contrôles Button, puis affectez Ajouter et Liste à leurs propriétés Text. Ajoutez la définition de classe child et la déclaration family au code du formulaire. Modifiez les gestionnaires d'événements _Click pour les boutons Ajouter et Liste comme indiqué. Le bouton Ajouter vous permet d'ajouter des enfants. Le bouton Liste permet d'afficher les noms de tous les enfants.

Public Class child
    Public name As String
    Sub New(ByVal newName As String)
        name = newName
    End Sub
End Class
' Create a Collection object.
Private family As New Collection()
Private Sub addChild_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles Button1.Click
    Dim newName As String
    newName = InputBox("Name of new family member: ")
    If newName <> "" Then
        family.Add(New child(newName), newName)
    End If
End Sub
Private Sub listChild_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles Button2.Click
    For Each aChild As child In family
        MsgBox(aChild.name)
    Next
End Sub