Partager via

Propagation d'un événement

  • Article

L'infrastructure de page ASP.NET fournit une technique appelée propagation d'événements qui permet à un contrôle enfant de propager des événements jusqu'au somment de sa hiérarchie des relations contenant-contenu. La propagation d'événements permet aux événements d'être déclenchés à partir d'un emplacement mieux adapté dans la hiérarchie des contrôles et autorise l'attachement de gestionnaires d'événements au contrôle d'origine ainsi qu'au contrôle qui expose l'événement propagé.

La propagation d'événements est utilisée par les contrôles dépendants (Repeater, DataList et DataGrid) pour exposer des événements de command déclenchés par des contrôles enfants (au sein de modèles d'élément) sous la forme d'événements de niveau supérieur. Alors que les contrôles serveur ASP.NET du .NET Framework utilisent la propagation d'événements pour les événements de commande (événements dont la classe de données d'événement dérive de CommandEventArgs), tout événement défini sur un contrôle serveur peut être propagé.

Un contrôle peut participer à la propagation d'événements à l'aide de deux méthodes qu'il hérite de la classe de base System.Web.UI.Control. Ces méthodes sont OnBubbleEvent et RaiseBubbleEvent. Le code suivant montre les signatures de ces méthodes.

protected virtual bool OnBubbleEvent(
   object source,
   EventArgs args
);
protected void RaiseBubbleEvent(
   object source,
   EventArgs args 
);
[Visual Basic]
Overridable Protected Function OnBubbleEvent( _
   ByVal source As Object, _
   ByVal args As EventArgs _
) As Boolean
Protected Sub RaiseBubbleEvent( _
   ByVal source As Object, _
   ByVal args As EventArgs _
)

L'implémentation de RaiseBubbleEvent est fournie par Control et ne peut pas être substituée. RaiseBubbleEvent envoie les données d'événement vers le sommet de la hiérarchie jusqu'au parent du contrôle. Pour gérer ou déclencher l'événement propagé, un contrôle doit substituer la méthode OnBubbleEvent.

Un contrôle auquel un événement est propagé effectue l'une des trois actions suivantes.

  • Il ne fait rien, l'événement est donc automatiquement propagé jusqu'à son parent.

  • Il effectue un certain traitement et continue à propager l'événement. Dans ce but, un contrôle doit substituer OnBubbleEvent et appeler RaiseBubbleEvent à partir de OnBubbleEvent. Le fragment de code suivant (provenant de la section Exemple de contrôle dépendant basé sur un modèle) propage un événement après avoir vérifié le type de ses arguments.

    protected override bool OnBubbleEvent(object source, EventArgs e) {
            if (e is CommandEventArgs) {
                // Adds information about an Item to the  
                // CommandEvent.
                TemplatedListCommandEventArgs args =
                    new TemplatedListCommandEventArgs(this, source, (CommandEventArgs)e);
                RaiseBubbleEvent(this, args);
                return true;
            }
            return false;
        }
[Visual Basic]
Protected Overrides Function OnBubbleEvent(source As Object, e As EventArgs) As Boolean
   If TypeOf e Is CommandEventArgs Then
      ' Adds information about an Item to the  
      ' CommandEvent.
      Dim args As New TemplatedListCommandEventArgs(Me, source, CType(e, CommandEventArgs))
      RaiseBubbleEvent(Me, args)
      Return True
   End If
   Return False
End Function

  • Il arrête de propager l'événement et le déclenche et/ou le gère. Le déclenchement d'un événement nécessite l'appel de la méthode qui distribue l'événement aux écouteurs. Pour déclencher l'événement propagé, un contrôle doit substituer OnBubbleEvent pour appeler la méthode OnNomÉvénemente qui déclenche l'événement propagé. Un contrôle qui déclenche un événement propagé l'expose généralement sous la forme d'un événement de niveau supérieur. Le fragment de code suivant (provenant de la section Exemple de contrôle dépendant basé sur un modèle) déclenche un événement propagé.

    protected override bool OnBubbleEvent(object source, EventArgs e) {
    bool handled = false;

    if (e is TemplatedListCommandEventArgs) {
        TemplatedListCommandEventArgs ce = (TemplatedListCommandEventArgs)e;

        OnItemCommand(ce);
        handled = true;
    }
    return handled;
}
[Visual Basic]
Protected Overrides Function OnBubbleEvent(source As Object, e As EventArgs) As Boolean
   Dim handled As Boolean = False

   If TypeOf e Is TemplatedListCommandEventArgs Then
      Dim ce As TemplatedListCommandEventArgs = CType(e, TemplatedListCommandEventArgs)

      OnItemCommand(ce)
      handled = True
   End If
   Return handled
End Function

Pour obtenir des exemples illustrant la propagation d'événements, consultez Exemple de contrôle de propagation d'événements et Exemple de contrôle dépendant basé sur un modèle.

Remarque   Alors que la méthode qui permet la propagation d'événements, OnBubbleEvent, respecter le modèle d'attribution d'un nom .NET Framework standard pour les méthodes déclenchant des événements, il n'existe aucun événement appelé BubbleEvent. L'événement propagé est exposé sous la forme d'un événement de niveau supérieur dans le contrôle qui arrête la propagation d'événements. Par exemple, le contrôle DataList expose les événements Command de contrôles dans son modèle en tant qu'événements ItemCommand. Remarquez également que la signature standard des méthodes OnNomÉvénement dans le .NET Framework possède un argument (protected void OnEventName (EventArgs e)). Cependant, OnBubbleEvent possède deux arguments, car l'événement provient de l'extérieur du contrôle. Le deuxième argument fournit la source.

Jusqu'ici, vous avez appris comment un contrôle peut répondre à un événement qui lui est propagé. La section suivante explique comment créer un contrôle qui définit un événement propagé.

Définition d'un événement propagé

Si vous souhaitez que votre contrôle permette la propagation d'événements pour un événement qu'il définit, il doit appeler RaiseBubbleEvent à partir de la méthode OnNomÉvénement qui déclenche l'événement. Aucun travail supplémentaire n'est nécessaire au sein du contrôle. Le fragment de code suivant illustre un contrôle qui définit un événement Command permettant la propagation.

protected virtual void OnCommand(CommandEventArgs e) {
            CommandEventHandler handler = (CommandEventHandler)Events[EventCommand];
            if (handler != null)
                handler(this,e);

            // The Command event is bubbled up the control hierarchy.
            RaiseBubbleEvent(this, e);
        } 
[Visual Basic]
Protected Overridable Sub OnCommand(e As CommandEventArgs)
   Dim handler As CommandEventHandler = CType(Events(EventCommand), CommandEventHandler)
   If Not (handler Is Nothing) Then
      handler(Me, e)
   End If 
   ' The Command event is bubbled up the control hierarchy.
   RaiseBubbleEvent(Me, e)
End Sub

Remarque   La propagation d'événements n'est pas limitée aux événements de commande. Vous pouvez utiliser le mécanisme décrit ici pour propager n'importe quel événement.

Voir aussi

Exemple de contrôle de propagation d'événements | Exemple de contrôle dépendant basé sur un modèle