Partager via

Event, instruction

  • Article

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

Syntaxe

[ <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 qui s'appliquent à cet événement. Les attributs multiples sont séparés par des virgules. Vous devez placer la liste d’attributs entre crochets («<» et «>»).
accessmodifier Optionnel. Spécifie le code pouvant accéder à l'événement. Il peut s'agir d'une des méthodes suivantes :

- Public : tout code pouvant accéder à l'élément qui le déclare peut y accéder.
- Protégé : seul le code de sa classe ou de classe dérivée peut y accéder.
- Ami : seul le code de le même assemblée peut y accéder.
- Privé : seul le code de l'élément qui le déclare peut y accéder.
- Ami-uniquement seul un code de la classe de l’événement, d’une classe dérivée ou de la même assemblée peut y accéder.
- Protégé privé seul un code de la classe de l’événement ou d’une classe dérivée dans la même assemblée peut y accéder.
Shared Optionnel. Spécifie que cet événement n'est pas associé à une instance spécifique d'une classe ou d'une structure.
Shadows Optionnel. Indique que cet élément redéclare et masque un élément de programmation du 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 la classe de base, le code qui n'est pas autorisé à accéder à l'élément Private accède à la place à l'élément de la classe de base.
eventname Obligatoire. Nom de l'événement. Ce nom respecte les conventions standard d'affectation de noms aux variables.
parameterlist Optionnel. Liste des variables locales qui représentent les paramètres de cet événement. Vous devez placer la liste des paramètres entre parenthèses.
Implements Optionnel. Indique que cet événement implémente un événement d'une interface.
implementslist Obligatoire si Implements est utilisé. Liste des procédures Sub en cours d'implémentation. Les procédures multiples sont séparées par des virgules :

implementedprocedure [ , implementedprocedure ... ]

Chaque implementedprocedure emploie la syntaxe et les éléments suivants :

interface.definedname

- interface - Requis. Nom d'une interface que la classe ou la structure qui contient cette procédure implémente.
- Definedname - Requis. 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 Optionnel. 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 quand un gestionnaire d’événements est ajouté, soit explicitement en utilisant l’instruction AddHandler, soit implicitement en utilisant 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 quand un gestionnaire d’événements est supprimé à 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 quand l’événement est déclenché à 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 correspondant aux paramètres requis par le délégué delegatename. Vous devez placer la liste des paramètres entre parenthèses.
statements Optionnel. Instructions qui contiennent les corps des méthodes AddHandler, RemoveHandler et RaiseEvent.
End Event Obligatoire. Met fin au bloc Event.

Notes

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

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 des arguments de procédures, avec les exceptions suivantes : les événements ne peuvent pas avoir d’arguments nommés, d’arguments ParamArray ni 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.

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 quand le code ajoute ou supprime un gestionnaire d'événements pour l'événement, ou quand le code déclenche l'événement. Pour obtenir des exemples, consultez Comment déclarer des événements personnalisés pour conserver la mémoire et Comment déclarer des événements personnalisés pour éviter le blocage.

Exemple

L'exemple suivant utilise des événements pour dé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 plusieurs gestionnaires pour les événements qu'elle génère. Quand la classe déclenche l'événement, celui-ci se produit pour chaque classe ayant choisi de gérer les événements pour cette instance de l'objet.

L'exemple utilise également un formulaire (Form1) avec un bouton (Button1) et une zone de texte (TextBox1). Quand vous cliquez sur le bouton, la première zone de texte affiche un compte à rebours de 10 à 0 secondes. Quand 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. Faites ensuite un clic droit sur le formulaire, et 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 à décompter les secondes. Quand 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 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 Modèles gérés.

Voir aussi