Compartilhar via


Consumindo eventos

Para consumir um evento em um aplicativo você deve fornecer um manipulador de eventos (um método de manipulação de eventos) que executa lógica de programa em resposta ao evento e registra o manipulador de eventos junto a origem do evento. Este processo é conhecido como conexão de evento. Os designers visuais para Windows Forms e Web Forms fornecem ferramentas de desenvolvimento rápido de aplicativos (RAD) que simplificam ou ocultam os detalhes da conexão de evento.

Este tópico descreve o padrão geral de manipulação de eventos. Para obter uma visão geral do modelo de eventos na .NET Framework, consulte Eventos e Representantes. Para obter mais informações sobre o modelo de eventos nos Windows Forms, consulte Como: consumir eventos em um aplicativo do Windows Forms. Para obter mais informações sobre o modelo de eventos nos Web Forms, consulte Como: consumir eventos em um aplicativo de formulários da Web.

O Padrão de Evento

Os detalhes da conexão de evento diferem em Windows Forms e Web Forms por causa dos diferentes níveis de suporte fornecido por diferentes ferramentas RAD. No entanto, ambos os cenários seguem o mesmo padrão de evento, que possui as seguintes características:

  • Uma classe que gera um evento chamado EventName possui o membro a seguir:
Public Event EventName As EventNameEventHandler
public event EventNameEventHandler EventName;
public:
    event EventNameEventHandler^ EventName;
  • O representante de evento para o evento EventName é EventName EventHandler , com a assinatura a seguir:
Public Delegate Sub EventNameEventHandler(sender As Object, e As EventNameEventArgs)
public delegate void EventNameEventHandler(object sender, EventNameEventArgs e);
delegate void EventNameEventHandler(Object^ sender, EventNameEventArgs^ e);

Para consumir o evento EventName, o manipulador de eventos deve ter a mesma assinatura do representante de evento:

Sub EventHandler(sender As Object, e As EventNameEventArgs)
End Sub
void EventHandler(object sender, EventNameEventArgs e) {}
void EventHandler(Object^ sender, EventNameEventArgs^ e) {}

Dica

Um representante de evento na .NET Framework é denominado EventNameEventHandler, enquanto o termo manipulador de eventos, na documentação, refere-se a um método de manipulação de eventos.A lógica por trás o esquema de nomeação é que uma EventNameEventHandler delegar aponta para o manipulador de eventos (método) que realmente manipula o evento.

Quando um evento não possui nenhum dado associado, a classe que está lançando o evento utiliza System.EventHandler como o representante e System.EventArgs como os dados do evento. Os eventos que associaram dados usam classes que derivam de EventArgs para o tipo de dados do evento e o tipo de representante de evento correspondente. Por exemplo, se você desejar manipular um evento MouseUp em um aplicativo Windows Forms , a classe de dados do evento é MouseEventArgs e o representante de evento é MouseEventHandler. Observe que vários eventos de mouse usam uma classe comum para dados do evento e um representante de eventos comum, de tal forma que o esquema de nomeação não coincida exatamente com a convenção descrita acima. Para os eventos de mouse, o manipulador de eventos deve ter a seguinte assinatura:

Sub Mouse_Moved(sender As Object, e As MouseEventArgs)
End Sub
void Mouse_Moved(object sender, MouseEventArgs e){}
void Mouse_Moved(Object^ sender, MouseEventArgs^ e){}

Os parâmetros do remetente e do argumento de evento fornecem detalhes adicionais sobre o evento de mouse para o manipulador de eventos. O objeto remetente indica o quê lançou o evento. O parâmetro MouseEventArgs fornece detalhes sobre o movimento do mouse que gerou o evento. Várias origens de eventos fornecem dados adicionais para o evento, e vários manipuladores de eventos usam os dados específicos do evento no processamento do evento. Para obter um exemplo que demonstra o lançamento e a manipulação de eventos com dados específicos de eventos, consulte Como: Lançar e Consumir Eventos.

Dica

Eventos também surgem fora do contexto de interfaces de usuário (UIs), e, na verdade, a .NET Framework inclui várias classes não UI que geram eventos.No entanto, todos os eventos seguem o padrão descrito aqui.

Para obter informações sobre como lançar eventos a partir de uma classe, consulte Lançando um Evento.

Estática e dinâmicos eventos

O .NET Framework permite que os assinantes registrar para notificações de evento estaticamente ou dinamicamente. Manipuladores de eventos estáticos estão em vigor para toda a vida da classe cujos eventos eles manipulam. Este é o método mais comum de manipulação de eventos. Manipuladores de eventos dinâmicos estão explicitamente ativados e desativados durante a execução do programa, geralmente em resposta a alguma lógica condicional do programa. Por exemplo, eles podem ser usados se as notificações de evento são necessários somente sob certas condições ou se um aplicativo fornece vários manipuladores de eventos e condições de tempo de execução definem apropriado utilizar um deles.

O EventInfo.AddEventHandler método adiciona manipuladores de eventos dinâmicos e a EventInfo.RemoveEventHandler método desativa-los. Os idiomas individuais também fornecem seus próprios recursos para manipular eventos dinamicamente. O exemplo a seguir define uma TemperatureMonitor classe que gera um TemperatureTheshold evento sempre que a temperatura atinge um limite predefinido. Em seguida, um manipulador de eventos que assina esse evento é ativado e desativado durante a execução do programa.

public class TemperatureEventArgs : Inherits EventArgs
   Private oldTemp As Decimal
   Private newTemp As Decimal

   Public ReadOnly Property OldTemperature As Decimal
      Get
         Return Me.oldTemp
      End Get   
   End Property

   Public ReadOnly Property NewTemperature As Decimal
      Get
         Return Me.newTemp
      End Get
   End Property

   Public Sub New(oldTemp As Decimal, newTemp As Decimal)
      Me.oldTemp = oldTemp
      Me.newTemp = newTemp   
   End Sub
End Class

Public Delegate Sub TemperatureEventHandler(sender As Object, _
                                            ev As TemperatureEventArgs)

Public Class TemperatureMonitor
   Private currentTemperature As Decimal
   Private threshholdTemperature As Decimal

   Public Event TemperatureThreshold As TemperatureEventHandler 

   Public Sub New(threshHold As Decimal)
      Me.threshholdTemperature = threshHold
   End Sub

   Public Sub SetTemperature(newTemperature As Decimal)
      If (Me.currentTemperature > threshholdTemperature And _
         newTemperature <= Me.threshholdTemperature) Or _
         (Me.CurrentTemperature < Me.threshholdTemperature And _
             newTemperature >= Me.threshholdTemperature) Then
         OnRaiseTemperatureEvent(newTemperature)
      End If
      Me.currentTemperature = newTemperature
   End Sub

   Public Function GetTemperature() As Decimal
      Return Me.currentTemperature
   End Function

   Protected Overridable Sub OnRaiseTemperatureEvent(newTemperature As Decimal)
      RaiseEvent TemperatureThreshold(Me, New TemperatureEventArgs(Me.currentTemperature, _ 
                                       newTemperature))
   End Sub                                       
End Class

Public Module Example
   Public Sub Main()
      Dim tempMon As New TemperatureMonitor(32d)
      tempMon.SetTemperature(33)
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", _
                        tempMon.GetTemperature())
      tempMon.SetTemperature(32)
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", _
                        tempMon.GetTemperature())

      ' Add event handler dynamically using Visual Basic syntax.
      AddHandler tempMon.TemperatureThreshold, AddressOf TempMonitor

      tempMon.SetTemperature(33)
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", _
                        tempMon.GetTemperature())
      tempMon.SetTemperature(34)
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", _
                        tempMon.GetTemperature())
      tempMon.SetTemperature(32)
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", _
                        tempMon.GetTemperature())

      ' Remove event handler dynamically using Visual Basic syntax.
      RemoveHandler tempMon.TemperatureThreshold, AddressOf TempMonitor

      tempMon.SetTemperature(31)
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", _ 
                        tempMon.GetTemperature())
      tempMon.SetTemperature(35)
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", _ 
                        tempMon.GetTemperature())
   End Sub

   Private Sub TempMonitor(sender As Object, e As TemperatureEventArgs)
      Console.WriteLine("   ***Warning: Temperature is changing from {0} to {1}.", _ 
                        e.OldTemperature, e.NewTemperature)
   End Sub 
End Module
' The example displays the following output:
'       Current temperature is 33 degrees Fahrenheit.
'       Current temperature is 32 degrees Fahrenheit.
'       Current temperature is 33 degrees Fahrenheit.
'       Current temperature is 34 degrees Fahrenheit.
'          ***Warning: Temperature is changing from 34 to 32.
'       Current temperature is 32 degrees Fahrenheit.
'       Current temperature is 31 degrees Fahrenheit.
'       Current temperature is 35 degrees Fahrenheit.
using System;

public class TemperatureEventArgs : EventArgs
{
   private decimal oldTemp;
   private decimal newTemp;

   public decimal OldTemperature
   {
      get { return this.oldTemp; }
   }

   public decimal NewTemperature
   {
      get { return this.newTemp; }
   }

   public TemperatureEventArgs(decimal oldTemp, decimal newTemp)
   {
      this.oldTemp = oldTemp;
      this.newTemp = newTemp;   
   }
}

public delegate void TemperatureEventHandler(object sender, TemperatureEventArgs ev);

public class TemperatureMonitor
{
   private decimal currentTemperature;
   private decimal threshholdTemperature;

   public event TemperatureEventHandler TemperatureThreshold; 

   public TemperatureMonitor(decimal threshhold)
   {
      this.threshholdTemperature = threshhold;
   }

   public void SetTemperature(decimal newTemperature)
   {
      if ( (this.currentTemperature > this.threshholdTemperature && 
           newTemperature <= this.threshholdTemperature) ||
           (this.currentTemperature < this.threshholdTemperature &&
           newTemperature >= this.threshholdTemperature) )
         OnRaiseTemperatureEvent(newTemperature);
      this.currentTemperature = newTemperature;
   }

   public decimal GetTemperature()
   {
      return this.currentTemperature;
   }

   protected virtual void OnRaiseTemperatureEvent(decimal newTemperature)
   {
      // Raise the event if it has subscribers.
      if (TemperatureThreshold != null)
         TemperatureThreshold(this, new TemperatureEventArgs(this.currentTemperature, 
                               newTemperature));
   }
}

public class Example
{
   public static void Main()
   {
      Example ex = new Example();
      ex.MonitorTemperatures();
   }

   public void MonitorTemperatures()
   {
      TemperatureMonitor tempMon = new TemperatureMonitor(32);
      tempMon.SetTemperature(33);
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", 
                        tempMon.GetTemperature());
      tempMon.SetTemperature(32);
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.",
                        tempMon.GetTemperature());

      // Add event handler dynamically using C# syntax.
      tempMon.TemperatureThreshold += this.TempMonitor;

      tempMon.SetTemperature(33);
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", 
                        tempMon.GetTemperature());
      tempMon.SetTemperature(34);
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", 
                        tempMon.GetTemperature());
      tempMon.SetTemperature(32);
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.",
                        tempMon.GetTemperature());

      // Remove event handler dynamically using C# syntax.
      tempMon.TemperatureThreshold -= this.TempMonitor;

      tempMon.SetTemperature(31);
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", 
                        tempMon.GetTemperature());
      tempMon.SetTemperature(35);
      Console.WriteLine("Current temperature is {0} degrees Fahrenheit.", 
                        tempMon.GetTemperature());
   }

   private void TempMonitor(object sender, TemperatureEventArgs e)
   {
      Console.WriteLine("   ***Warning: Temperature is changing from {0} to {1}.", 
                        e.OldTemperature, e.NewTemperature);
   } 
}
// The example displays the following output:
//       Current temperature is 33 degrees Fahrenheit.
//       Current temperature is 32 degrees Fahrenheit.
//       Current temperature is 33 degrees Fahrenheit.
//       Current temperature is 34 degrees Fahrenheit.
//          ***Warning: Temperature is changing from 34 to 32.
//       Current temperature is 32 degrees Fahrenheit.
//       Current temperature is 31 degrees Fahrenheit.
//       Current temperature is 35 degrees Fahrenheit.

Consulte também

Tarefas

Como: consumir eventos em um aplicativo de formulários da Web

Como: consumir eventos em um aplicativo do Windows Forms

Conceitos

Delegados e eventos

Disparar um evento

Outros recursos

Tratamento e disparada de eventos