Event-Anweisung

  • Artikel

Deklariert ein benutzerdefiniertes Ereignis.

Syntax

[ <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

Bestandteile

Teil Beschreibung
attrlist Optional. Liste der Attribute, die für dieses Ereignis gelten. Mehrere Attribute werden durch Kommas getrennt. Sie müssen die Attributliste in spitze Klammern ("<" und ">") einschließen.
accessmodifier Optional. Gibt an, welcher Code auf dieses Ereignis zugreifen kann. Dabei kann es sich um eine der folgenden Methoden handeln:

- Public: Code, der auf das Element zugreifen kann, welches ihn deklariert, hat Zugriff.
- Protected: Nur Code innerhalb der entsprechenden Klasse oder einer abgeleiteten Klasse hat Zugriff.
- Friend: Nur Code in derselben Assembly hat Zugriff.
- Private: Nur Code in dm Element, das ihn deklariert, hat Zugriff.
- Protected Friend: Nur Code in der Klasse des Ereignisses, einer abgeleiteten Klasse oder derselben Assembly hat Zugriff.
- Private Protected: Nur Code in der Klasse des Ereignisses, einer abgeleiteten Klasse oder in derselben Assembly hat Zugriff.
Shared Optional. Gibt an, dass dieses Ereignis nicht mit einer bestimmten Instanz einer Klasse oder Struktur verknüpft ist.
Shadows Optional. Gibt an, dass dieses Ereignis ein identisch benanntes Programmierelement oder einen Satz überladener Elemente in einen Basisklasse erneut deklariert und ausblendet. Sie können ein Shadowing von jedem deklarierten Element mit einer anderen Art vornehmen.

Ein schattiertes Element steht in der abgeleiteten Klasse, die es spiegelt, nicht zur Verfügung, und zwar mit Ausnahme von dem Punkt, wo nicht auf das Shadowing-Element zugriffen werden kann. Wenn beispielsweise ein Private-Element ein Basisklassenelement spiegelt, greift der Code, der nicht über die Berechtigung für den Zugriff auf das Private-Element verfügt, anstelle auf das Basisklassenelement zu.
eventname Erforderlich. Der Name des Ereignisses; folgt standardmäßigen Variablennamenskonventionen.
parameterlist Optional. Liste der lokalen Variablen, die die Parameter dieses Ereignisses darstellen. Sie müssen die Parameterliste in Klammern umschließen.
Implements Optional. Gibt an, dass dieses Ereignis ein Ereignis einer Schnittstelle implementiert.
implementslist Erforderlich, wenn Implements angegeben wird. Liste der zu implementierenden Sub-Prozeduren. Mehrere Prozeduren werden durch Kommas getrennt:

implementedprocedure [ , implementedprocedure ... ]

Jede implementedprocedure weist folgende Syntax und Bestandteile auf:

interface.definedname

- interface – Erforderlich. Name einer Schnittstelle, die von der in dieser Prozedur enthaltenen Klasse oder Struktur implementiert wird.
- Definedname – Erforderlich. Name, wodurch die Prozedur in interface definiert ist. Hierbei muss es sich nicht um demselben Namen wie name (den Namen, den dieser Prozedur verwendet, um die definierte Prozedur zu implementieren) handeln.
Custom Erforderlich. Als Custom deklarierte Ereignisse müssen benutzerdefinierte AddHandler-, RemoveHandler- und RaiseEvent-Accessoren definieren.
delegatename Optional. Der Name eines Delegaten, der die Signatur des Ereignishandlers angibt.
AddHandler Erforderlich. Deklariert eine AddHandler-Zugriffsmethode, die die auszuführenden Anweisungen angibt, wenn ein Ereignishandler hinzugefügt wird, und zwar entweder explizit mithilfe der AddHandler-Anweisung oder implizit mithilfe der Handles-Klausel.
End AddHandler Erforderlich. Beendet den AddHandler-Block.
value Erforderlich. Parametername.
RemoveHandler Erforderlich. Deklariert einen RemoveHandler-Accessor, der die auszuführenden Anweisungen angibt, wenn ein Ereignishandler mithilfe der RemoveHandler-Anweisung entfernt wird.
End RemoveHandler Erforderlich. Beendet den RemoveHandler-Block.
RaiseEvent Erforderlich. Deklariert einen RaiseEvent-Accessor, der die auszuführenden Anweisungen angibt, wenn ein Ereignis mithilfe der RaiseEvent-Anweisung ausgelöst wird. Für gewöhnlich wird dadurch eine Liste der Delegaten aufgerufen, die durch die AddHandler- und RemoveHandler-Accessoren verwaltet werden.
End RaiseEvent Erforderlich. Beendet den RaiseEvent-Block.
delegatesignature Erforderlich. Liste der Parameter, die mit dem Parametern übereinstimmen, die durch das delegatename-Delegat erforderlich sind. Sie müssen die Parameterliste in Klammern umschließen.
statements Optional. Anweisungen, die die Textteile der Methoden AddHandler, RemoveHandler und RaiseEvent enthalten.
End Event Erforderlich. Beendet den Event-Block.

Bemerkungen

Verwenden Sie nach erfolgter Deklarierung des Ereignisses die Anweisung RaiseEvent zum Auslösen des Ereignisses. Ein typisches Ereignis könnte analog zur Darstellung in den folgenden Fragmenten deklariert und ausgelöst werden.

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

Hinweis

Sie können Ereignisargumente deklarieren, wie Sie dies bei Argumenten von Prozeduren vornehmen, und zwar mit den folgenden Ausnahmen: Ereignisse können nicht über benannte Argumente, ParamArray- oder Optional-Argumente verfügen. Ereignisse haben keine Rückgabewerte.

Zum Verarbeiten eines Ereignisses müssen Sie es mithilfe der Anweisung Handles oder AddHandler mit einer Ereignishandler-Unterroutine verknüpfen. Die Signaturen der Unterroutine und des Ereignisses müssen übereinstimmen. Zum Verarbeiten eines freigegebenen Ereignisses müssen Sie die Anweisung AddHandler verwenden.

Sie können Event nur auf Modulebene verwenden. Der Deklarationskontext für ein Ereignis muss demnach eine Klasse, Struktur, ein Modul oder eine Schnittstelle sein und kann weder Quelldatei, Namespace, Prozedur noch Block sein. Weitere Informationen finden Sie unter Deklarationskontexte und Standardzugriffsebenen.

In den meisten Fällen können Sie zum Deklarieren von Ereignissen die erste Syntax im Syntaxabschnitt dieses Themas verwenden. In einigen Szenarien ist es jedoch erforderlich, dass Sie mehr Kontrolle über das detaillierte Verhalten des Ereignisses verfügen. Die letzte Syntax im Syntaxabschnitt dieses Themas, die das Schlüsselwort Custom verwendet, enthält diese Steuerung, indem Ihnen ermöglicht wird, benutzerdefinierte Ereignisse zu definieren. In einem benutzerdefinierten Ereignis geben Sie genau an, was geschieht, wenn ein Ereignishandler mithilfe von Code zum Ereignis hinzugefügt oder daraus entfernt wird oder wenn der Code das Ereignis auslöst. Entsprechende Beispiele finden Sie unter Vorgehensweise: Deklarieren von Ereignissen, um Speicherplatz zu sparen und Vorgehensweise: Deklarieren benutzerdefinierter Ereignisse zum Vermeiden der Blockierung.

Beispiel

Im folgenden Beispiel werden Ereignisse zum Herunterzählen der Sekunden von 10 bis 0 verwendet. Der Code veranschaulicht mehrere der ereignisbezogene Methoden, Eigenschaften und Anweisungen. Dies schließt die RaiseEvent-Anweisung mit ein.

Die Klasse, die ein Ereignis auslöst, ist die Ereignisquelle, und die Methoden, die das Ereignis verarbeiten, sind die Ereignishandler. Eine Ereignisquelle kann über mehrere Handler für die Ereignisse verfügen, die sie generiert. Wenn die Klasse das Ereignis auslöst, wird dieses Ereignis in jeder Klasse ausgelöst, die das Verarbeiten von Ereignissen für diese Instanz des Objekts ausgewählt hat.

Im Beispiel wird außerdem ein Formular (Form1) mit einer Schaltfläche (Button1) und einem Textfeld (TextBox1) verwendet. Wenn Sie auf die Schaltfläche klicken, zeigt das erste Textfeld einen Countdown von 10 bis 0 Sekunden an. Nach Ablauf der vollständigen Zeitspanne (10 Sekunden) wird im ersten Textfeld „Fertig“ angezeigt.

Der Code für Form1 gibt die Anfangs- und Beendigungsstatus des Formulars an. Er enthält zudem den Code, der ausgeführt wird, wenn Ereignisse ausgelöst werden.

Um dieses Beispiel zu verwenden, öffnen Sie ein neues Windows Forms-Projekt. Fügen Sie dem Hauptformular mit dem Namen Form1 anschließend eine Schaltfläche mit dem Namen Button1 und ein Textfeld mit dem Namen TextBox1 hinzu. Klicken Sie dann mit der rechten Maustaste auf das Formular, und klicken Sie auf Code anzeigen, um den Code-Editor zu öffnen.

Fügen Sie eine WithEvents-Variable zum Deklarationsabschnitt der Form1-Klasse hinzu:

Private WithEvents mText As TimerState

Fügen Sie den folgenden Code zum Code für Form1 hinzu. Ersetzen Sie ggf. vorhandene doppelte Prozeduren, beispielsweise Form_Load oder 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

Drücken Sie F5, um das vorherige Beispiel auszuführen, und klicken Sie auf die Schaltfläche Start. Im ersten Textfeld werden die Sekunden heruntergezählt. Nach Ablauf der vollständigen Zeitspanne (10 Sekunden) wird im ersten Textfeld „Fertig“ angezeigt.

Hinweis

Die My.Application.DoEvents-Methode verarbeitet Ereignisse nicht in der gleichen Weise wie das Formular. Damit das Formular die Ereignisse direkt verarbeiten kann, können Sie Multithreading verwenden. Weitere Informationen finden Sie unter Verwaltetes Threading.

Siehe auch