Istruzione Event

  • Articolo

Dichiara un evento definito dall'utente.

Sintassi

[ <attrlist> ] [ accessmodifier ] _  
[ Shared ] [ Shadows ] Event eventname[(parameterlist)] _  
[ Implements implementslist ]  
' -or-  
[ <attrlist> ] [ accessmodifier ] _  
[ Shared ] [ Shadows ] Event eventname As delegatename _  
[ Implements implementslist ]  
' -or-  
 [ <attrlist> ] [ accessmodifier ] _  
[ Shared ] [ Shadows ] Custom Event eventname As delegatename _  
[ Implements implementslist ]  
   [ <attrlist> ] AddHandler(ByVal value As delegatename)  
      [ statements ]  
   End AddHandler  
   [ <attrlist> ] RemoveHandler(ByVal value As delegatename)  
      [ statements ]  
   End RemoveHandler  
   [ <attrlist> ] RaiseEvent(delegatesignature)  
      [ statements ]  
   End RaiseEvent  
End Event

Parti

In parte Descrizione
attrlist Facoltativo. Elenco degli attributi applicabili all'evento. Gli attributi sono separati da una virgola. È necessario racchiudere l'elenco degli attributi tra parentesi angolari ("<" e ">").
accessmodifier Facoltativo. Specifica il tipo di codice che può accedere all'evento. Può essere uno dei seguenti:

- Public: può accedere qualsiasi codice che sia in grado di accedere all'elemento che lo dichiara.
- Protected: può accedere solo il codice incluso nella relativa classe o in una classe derivata.
- Friend: può accedere solo il codice incluso nello stesso assembly.
- Private: può accedere solo il codice incluso nell'elemento che lo dichiara.
- Protected Friend: può accedere solo il codice nella classe dell'evento, in una classe derivata o nello stesso assembly.
- Private Protected: può accedere solo il codice nella classe dell'evento o in una classe derivata nello stesso assembly.
Shared Facoltativo. Specifica che l'evento non è associato a una specifica istanza di una classe o di una struttura.
Shadows Facoltativo. Indica che l'evento ridichiara e nasconde un elemento di programmazione omonimo o un insieme di elementi in overload di una classe base. È possibile nascondere qualsiasi tipo di elemento dichiarato con qualsiasi altro tipo.

Un elemento nascosto non è disponibile all'interno della classe derivata che lo nasconde, a meno che l'elemento di shadowing sia inaccessibile. Ad esempio, se un elemento Private nasconde un elemento della classe base, il codice che non dispone dell'autorizzazione per accedere all'elemento Private accede invece all'elemento della classe base.
eventname Obbligatorio. Nome dell'evento, conforme alle convenzioni di denominazione standard delle variabili.
parameterlist Facoltativo. Elenco di variabili locali che rappresentano i parametri dell'evento. È necessario racchiudere l'elenco dei parametri tra parentesi.
Implements Facoltativo. Indica che l'evento implementa un evento di un'interfaccia.
implementslist Necessario se si fornisce Implements. Elenco delle routine Sub implementate. Nel caso di più routine, è possibile separarle mediante virgole.

implementedprocedure [ , implementedprocedure ... ]

Ogni implementedprocedure presenta la sintassi e le parti seguenti:

interface.definedname

- interface - Obbligatorio. Nome di un'interfaccia implementata dalla classe o dalla struttura che contiene la routine.
- Definedname - Obbligatorio. Nome mediante il quale la routine viene definita in interface. Non è necessario che questo nome corrisponda al nome usato dalla routine per implementare la routine definita, ossia name.
Custom Obbligatorio. È necessario che gli eventi dichiarati come Custom definiscano funzioni di accesso AddHandler, RemoveHandler e RaiseEvent personalizzate.
delegatename Facoltativo. Nome del delegato che specifica la firma del gestore eventi.
AddHandler Obbligatorio. Dichiara una funzione di accesso AddHandler che specifica le istruzioni da eseguire quando viene aggiunto un gestore eventi, sia in modo esplicito mediante l'istruzione AddHandler che in modo implicito mediante la clausola Handles
End AddHandler Obbligatorio. Termina il blocco AddHandler.
value Obbligatorio. Nome del parametro.
RemoveHandler Obbligatorio. Dichiara una funzione di accesso RemoveHandler, che specifica le istruzioni da eseguire quando un gestore eventi viene rimosso mediante l'istruzione RemoveHandler.
End RemoveHandler Obbligatorio. Termina il blocco RemoveHandler.
RaiseEvent Obbligatorio. Dichiara una funzione di accesso RaiseEvent, che specifica le istruzioni da eseguire quando l'evento viene generato mediante l'istruzione RaiseEvent. In genere, viene richiamato un elenco di delegati gestito dalle funzioni di accesso AddHandler e RemoveHandler.
End RaiseEvent Obbligatorio. Termina il blocco RaiseEvent.
delegatesignature Obbligatorio. Elenco di parametri che corrisponde ai parametri richiesti dal delegato delegatename. È necessario racchiudere l'elenco dei parametri tra parentesi.
statements Facoltativo. Istruzioni che includono i corpi dei metodi AddHandler, RemoveHandler e RaiseEvent.
End Event Obbligatorio. Termina il blocco Event.

Osservazioni:

Dopo aver dichiarato l'evento, usare l'istruzione RaiseEvent per generarlo. Nei frammenti seguenti viene mostrato un esempio tipico di dichiarazione e generazione di un evento:

Public Class EventSource
    ' Declare an event.
    Public Event LogonCompleted(ByVal UserName As String)
    Sub CauseEvent()
        ' Raise an event on successful logon.
        RaiseEvent LogonCompleted("AustinSteele")
    End Sub
End Class

Nota

È possibile dichiarare argomenti per gli eventi analogamente a quanto avviene per gli argomenti di routine, tenendo però conto che non è possibile specificare per gli eventi argomenti denominati, argomenti ParamArray o argomenti Optional, né ottenere da essi valori restituiti.

Per gestire un evento è necessario associarlo a una subroutine del gestore eventi mediante l'istruzione Handles o AddHandler. Le firme della subroutine e dell'evento devono corrispondere. Per gestire un evento condiviso è necessario usare l'istruzione AddHandler.

Si può usare Event solo a livello di modulo. In altri termini, il contesto della dichiarazione per un evento deve essere una classe, una struttura, un modulo o un'interfaccia e non può essere un file di origine, uno spazio dei nomi, una routine o un blocco. Per altre informazioni, vedere Contesti delle dichiarazioni e livelli di accesso predefiniti.

Nella maggior parte dei casi, per dichiarare un evento è possibile usare la prima sintassi nella sezione relativa alla sintassi di questo argomento. In alcuni scenari è tuttavia necessario disporre di un controllo maggiore sui dettagli del comportamento dell'evento. L'ultima sintassi nella sezione relativa alla sintassi di questo argomento, che usa la parola chiave Custom, offre questa possibilità consentendo la definizione di eventi personalizzati. In un evento personalizzato si specifica esattamente ciò che accade quando il codice aggiunge o rimuove un gestore eventi a o dall'evento oppure quando il codice genera l'evento. Per alcuni esempi, vedere Procedura: Dichiarare eventi personalizzati per risparmiare memoria e Procedura: Dichiarare eventi personalizzati per evitare blocchi.

Esempio

Negli esempi seguenti, gli eventi vengono usati per il conto alla rovescia dei secondi, da 10 a 0. Il codice illustra numerosi metodi, proprietà e istruzioni correlati agli eventi, inclusa l'istruzione RaiseEvent.

La classe che genera un evento viene definita origine e i metodi che lo elaborano vengono definiti gestori eventi. Un'origine eventi può disporre di più gestori per gli eventi generati. Quando la classe genera l'evento, lo stesso evento viene generato in tutte le classi per cui è stato scelto di gestire eventi per tale istanza dell'oggetto.

Nell'esempio vengono usati anche un form (Form1) con un pulsante (Button1) e una casella di testo (TextBox1). Quando si fa clic sul pulsante, nella prima casella di testo viene visualizzato il conto alla rovescia dei secondi da 10 a 0. Al termine dei 10 secondi, nella prima casella di testo viene visualizzato "Done".

Il codice di Form1 specifica gli stati di inizio e fine del form. Contiene inoltre il codice eseguito quando vengono generati gli eventi.

Per usare l'esempio, aprire un nuovo progetto Windows Form. Aggiungere quindi un pulsante denominato Button1 e una casella di testo denominata TextBox1 al form principale, denominato Form1. Quindi, fare quindi clic con il pulsante destro del mouse sul form e scegliere Visualizza codice per aprire l'editor di codice.

Aggiungere una variabile WithEvents alla sezione delle dichiarazioni della classe Form1:

Private WithEvents mText As TimerState

Aggiungere il codice seguente al codice per Form1: Sostituire eventuali routine duplicate, ad esempio Form_Load o Button_Click.

Private Sub Form1_Load() Handles MyBase.Load
    Button1.Text = "Start"
    mText = New TimerState
End Sub
Private Sub Button1_Click() Handles Button1.Click
    mText.StartCountdown(10.0, 0.1)
End Sub

Private Sub mText_ChangeText() Handles mText.Finished
    TextBox1.Text = "Done"
End Sub

Private Sub mText_UpdateTime(ByVal Countdown As Double
  ) Handles mText.UpdateTime

    TextBox1.Text = Format(Countdown, "##0.0")
    ' Use DoEvents to allow the display to refresh.
    My.Application.DoEvents()
End Sub

Class TimerState
    Public Event UpdateTime(ByVal Countdown As Double)
    Public Event Finished()
    Public Sub StartCountdown(ByVal Duration As Double,
                              ByVal Increment As Double)
        Dim Start As Double = DateAndTime.Timer
        Dim ElapsedTime As Double = 0

        Dim SoFar As Double = 0
        Do While ElapsedTime < Duration
            If ElapsedTime > SoFar + Increment Then
                SoFar += Increment
                RaiseEvent UpdateTime(Duration - SoFar)
            End If
            ElapsedTime = DateAndTime.Timer - Start
        Loop
        RaiseEvent Finished()
    End Sub
End Class

Premere F5 per eseguire l'esempio precedente, quindi fare clic sul pulsante con etichetta Start. Nella prima casella di testo viene avviato il conto alla rovescia dei secondi. Al termine dei 10 secondi, nella prima casella di testo viene visualizzato "Done".

Nota

Il metodo My.Application.DoEvents non elabora gli eventi allo stesso modo del form. Per consentire al form di gestire direttamente gli eventi, si può ricorrere al multithreading. Per altre informazioni, vedere Threading gestito.

Vedi anche