Event, instruction

Article
08/10/2011

Déclare un événement défini par l'utilisateur.

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

Éléments

Élément	Description
attrlist	Facultatif. Liste des attributs s'appliquant à cet événement. Les attributs multiples sont séparés par des virgules. Vous devez placer le Liste d'attributs (Visual Basic) entre des signes "inférieur à" et "supérieur à" ("<" et ">").
accessmodifier	Facultatif. Spécifie le code pouvant accéder à l'événement. Il peut s'agir de l'une des valeurs suivantes : Public — tout code pouvant accéder à l'élément qui le déclare peut y accéder. Protected — seul le code dans sa classe ou une classe dérivée peut y accéder. Friend — seul le code dans le même assembly peut y accéder. Private —- seul le code dans l'élément qui le déclare peut y accéder. Vous pouvez spécifier Protected Friend pour autoriser l'accès à partir du code dans la classe de l'événement, dans une classe dérivée ou dans le même assembly.
Shared	Facultatif. Spécifie que cet événement n'est pas associé à l'instance spécifique d'une classe ou d'une structure.
Shadows	Facultatif. Indique que cet événement redéclare et masque un élément de programmation de même nom ou un ensemble d'éléments surchargés, dans une classe de base. Vous pouvez occulter tout type d'élément déclaré par un autre type. Un élément occulté n'est pas disponible à partir de la classe dérivée qui l'occulte, sauf à partir de l'emplacement où l'élément d'occultation est inaccessible. Par exemple, si un élément Private occulte un élément de classe de base, le code qui n'est pas autorisé à accéder à l'élément Private accède à la place à l'élément de classe de base.
eventname	Obligatoire. Nom de l'événement. Ce nom respecte les conventions standard d'affectation de noms aux variables.
parameterlist	Facultatif. Liste des variables locales qui représentent les paramètres de cet événement. Vous devez mettre la Liste de paramètres (Visual Basic) entre parenthèses.
Implements	Facultatif. Indique que cet événement implémente un événement d'une interface.
implementslist	Requis si Implements est fourni. Liste des procédures Sub implémentées. Les procédures multiples sont séparées par des virgules : implementedprocedure [, implementedprocedure... ] Chaque implementedprocedure emploie la syntaxe et les paramètres suivants : interface.definedname ÉlémentDescription interface Obligatoire.Nom d'une interface que la classe ou la structure conteneur de cette procédure implémente. definedname Obligatoire.Nom par lequel la procédure est définie dans interface.Il ne doit pas être identique à name, le nom que cette procédure utilise pour implémenter la procédure définie.
Custom	Obligatoire. Les événements déclarés comme Custom doivent définir des accesseurs AddHandler, RemoveHandler et RaiseEvent personnalisés.
delegatename	Facultatif. Nom d'un délégué qui spécifie la signature du gestionnaire d'événements.
AddHandler	Obligatoire. Déclare un accesseur AddHandler, qui spécifie les instructions à exécuter lors de l'ajout d'un gestionnaire d'événements, soit explicitement à l'aide de l'instruction AddHandler soit implicitement à l'aide de la clause Handles.
End AddHandler	Obligatoire. Met fin au bloc AddHandler.
value	Obligatoire. Nom du paramètre.
RemoveHandler	Obligatoire. Déclare un accesseur RemoveHandler, qui spécifie les instructions à exécuter lors de la suppression d'un gestionnaire d'événements à l'aide de l'instruction RemoveHandler.
End RemoveHandler	Obligatoire. Met fin au bloc RemoveHandler.
RaiseEvent	Obligatoire. Déclare un accesseur RaiseEvent, qui spécifie les instructions à exécuter lors du déclenchement de l'événement à l'aide de l'instruction RaiseEvent. En général, il appelle une liste de délégués gérée par les accesseurs AddHandler et RemoveHandler.
End RaiseEvent	Obligatoire. Met fin au bloc RaiseEvent.
delegatesignature	Obligatoire. Liste des paramètres qui correspondent aux paramètres requis par le délégué delegatename. Vous devez mettre la Liste de paramètres (Visual Basic) entre parenthèses.
statements	Facultatif. Instructions qui contiennent les corps des méthodes AddHandler, RemoveHandler et RaiseEvent.
End Event	Obligatoire. Met fin au bloc Event.

Notes

Une fois l'événement déclaré, utilisez l'instruction RaiseEvent pour le déclencher. Les fragments de code suivants illustrent la déclaration et le déclenchement d'un événement type :

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

Notes

Vous pouvez déclarer des arguments d'événement de la même manière que pour les arguments de procédures, avec toutefois les exceptions suivantes : les événements ne peuvent pas avoir d'arguments nommés, d'arguments ParamArray ou d'arguments Optional. Les événements n'ont pas de valeurs de retour.

Pour gérer un événement, vous devez l'associer à une sous-routine du gestionnaire d'événements à l'aide de l'instruction Handles ou AddHandler. Les signatures de la sous-routine et de l'événement doivent correspondre. Pour gérer un événement partagé, vous devez utiliser l'instruction AddHandler.

Vous pouvez utiliser Event seulement au niveau du module. Cela signifie que le contexte de déclaration pour un événement doit être une classe, une structure, un module ou une interface, et ne peut pas être un fichier source, un espace de noms, une procédure ou un bloc. Pour plus d'informations, consultez Contextes de déclaration et niveaux d'accès par défaut (Visual Basic).

Dans la plupart des cas, vous pouvez utiliser la première syntaxe présente dans la section Syntaxe de cette rubrique pour déclarer des événements. Toutefois, certains scénarios nécessitent un plus grand contrôle sur le comportement détaillé de l'événement. La dernière syntaxe présente dans la section Syntaxe de cette rubrique, qui utilise le mot clé Custom, fournit ce contrôle en vous permettant de définir des événements personnalisés. Dans un événement personnalisé, vous spécifiez exactement ce qui se passe lorsque le code ajoute ou supprime un gestionnaire d'événements de l'événement ou lorsque le code déclenche ce dernier. Pour obtenir des exemples, consultez Comment : déclarer des événements personnalisés pour économiser la mémoire (Visual Basic) et Comment : déclarer des événements personnalisés pour éviter les blocages (Visual Basic).

Exemple

L'exemple suivant utilise des événements pour compter les secondes de 10 à 0. Le code illustre plusieurs méthodes, propriétés et instructions liées à des événements. Cela inclut l'instruction RaiseEvent.

La classe qui déclenche un événement est la source de l'événement, et les méthodes qui traitent l'événement sont les gestionnaires d'événements. Une source d'événement peut avoir des gestionnaires multiples pour les événements qu'elle génère. Lorsque la classe génère l'événement, celui-ci se produit pour chaque classe ayant choisi de gérer les événements pour cette instance de l'objet.

Cet exemple utilise aussi un formulaire (Form1) comportant un bouton (Button1) et une zone de texte (TextBox1). Lorsque vous cliquez sur le bouton, la première zone affiche un compte à rebours de 10 à 0 secondes. Lorsque la durée totale (10 secondes) s'est écoulée, la première zone de texte affiche « Terminé ».

Le code correspondant à Form1 indique les états de début et de fin du formulaire. Il contient également le code exécuté lors du déclenchement des événements.

Pour utiliser cet exemple, ouvrez un nouveau projet Windows Forms. Ajoutez ensuite un bouton nommé Button1 et une zone de texte nommée TextBox1 au formulaire principal nommé Form1. Cliquez ensuite avec le bouton droit sur le formulaire, puis cliquez sur Afficher le code pour ouvrir l'éditeur de code.

Ajoutez une variable WithEvents à la section des déclarations de la classe Form1 :

Private WithEvents mText As TimerState

Ajoutez le code suivant au code pour Form1. Remplacez toute procédure en double éventuelle, telle que Form_Load ou 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

Appuyez sur F5 pour exécuter l'exemple précédent, puis cliquez sur le bouton Démarrer. La première zone de texte commence le compte à rebours des secondes. Lorsque la durée totale (10 secondes) s'est écoulée, la première zone de texte affiche « Terminé ».

Notes

La méthode My.Application.DoEvents ne traite pas les événements exactement de la même manière que le formulaire. Pour permettre au formulaire de gérer les événements directement, vous pouvez utiliser le multithreading. Pour plus d'informations, consultez Threads (C# et Visual Basic).

Voir aussi

Event, instruction

Éléments

Notes

Exemple

Voir aussi

Tâches

Référence

Autres ressources

Ressources supplémentaires