Metodo Add (oggetto Collection)

Articolo
09/12/2008

Aggiornamento: novembre 2007

Aggiunge un elemento a un oggetto Collection.

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

Parametri

Item
Obbligatorio. Oggetto di qualsiasi tipo che specifica l'elemento da aggiungere all'insieme.
Key
Facoltativo. Espressione String univoca che consente di specificare una stringa chiave da utilizzare in sostituzione di un indice di posizione per accedere al nuovo elemento dell'insieme.
Before
Facoltativo. Espressione che specifica una posizione relativa nell'insieme. L'elemento da aggiungere viene inserito nell'insieme prima dell'elemento specificato nell'argomento Before. Se Before è un'espressione numerica, dovrà trattarsi di un numero compreso tra 1 e il valore della Proprietà Count (oggetto Collection) dell'insieme. Se Before è invece un'espressione String, dovrà corrispondere alla stringa chiave specificata nel momento in cui l'elemento cui si fa riferimento è stato aggiunto all'insieme. Non è possibile specificare sia Before che After.
After
Facoltativo. Espressione che specifica una posizione relativa nell'insieme. L'elemento da aggiungere viene inserito nell'insieme dopo l'elemento specificato nell'argomento After. Se After è un'espressione numerica, dovrà trattarsi di un numero compreso tra 1 e il valore della proprietà Count dell'insieme. Se After è invece un'espressione String, dovrà corrispondere alla stringa chiave specificata nel momento in cui l'elemento cui si fa riferimento è stato aggiunto all'insieme. Non è possibile specificare sia Before che After.

Eccezioni/Codici di errore

Tipo di eccezione	Numero di errore	Condizione
ArgumentException	5	Sono specificati sia Before che After. L'argomento Before o After non fa riferimento a un elemento esistente dell'insieme. Il parametro Key specificato esiste già.

Se si esegue l'aggiornamento delle applicazioni Visual Basic 6.0 che utilizzano la gestione degli errori non strutturata, vedere la colonna "Numero di errore". È possibile confrontare il numero di errore con la Proprietà Number (oggetto Err). Se possibile, tuttavia, si consiglia di sostituire il controllo dell'errore con la procedura illustrata nella sezione Cenni preliminari sulla gestione strutturata delle eccezioni per Visual Basic.

Note

L'argomento Before o After deve fare riferimento a un elemento esistente dell'insieme. In caso contrario, verrà generato un errore.

Anche in caso di corrispondenza tra il valore specificato nell'argomento Key e la chiave di un elemento esistente dell'insieme verrà generato un errore.

Esempio

Nell'esempio riportato di seguito il metodo Add viene utilizzato per aggiungere all'insieme family oggetti child, ovvero istanze di una classe denominata child contenenti una proprietà name di tipo Public. Per comprenderne meglio il funzionamento, creare un Form con due controlli Button e impostarne le proprietà Text su Add e List. Aggiungere al codice del form la definizione della classe child e la dichiarazione family. Modificare i gestori eventi _Click per i pulsanti Add e List, come illustrato di seguito. Il pulsante Add consentirà di aggiungere elementi figlio e il pulsante List di visualizzarne tutti i nomi.

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