Raising an Event

Event functionality is provided by three interrelated elements: a class that provides event data, an event delegate, and the class that raises the event. The .NET Framework has a convention for naming classes and methods related to events. If you want your class to raise an event named EventName, you need the following elements.

• A class that holds event data, named EventNameEventArgs. This class must derive from System.EventArgs.
• A delegate for the event, named EventNameEventHandler.
• A class that raises the event. This class must provide:

  1. An event declaration.

     public event EventNameEventHandler EventName;
     [Visual Basic]
     Public Event EventName As EventNameEventHandler
     

  2. A method named OnEventName that raises the event.

The event data class and the event delegate class might already be defined in the .NET Framework class library or in a third-party class library. In that case, you do not have to define those classes.

If you are not familiar with the delegate model for events in the .NET Framework, see Events and Delegates.

To provide event functionality

1. Define a class that provides data for the event. This class must derive from System.EventArgs, which is the base class for event data. An example follows.

   Note This step is not needed if an event data class already exists for the event or if there is no data associated with your event. If there is no event data, use the base class System.EventArgs.

   public class AlarmEventArgs : EventArgs {
      private readonly int nrings = 0;
      private readonly bool snoozePressed = false;
   
      //Properties.
      public string AlarmText {  
         ...
      }
      public int NumRings {
         ...
      }
      public bool SnoozePressed{
         ...
      }
      ...
   }
   [Visual Basic]
   Public Class AlarmEventArgs
      Inherits EventArgs
      Private nrings As Integer = 0
      Private _snoozePressed As Boolean = False
   
      'Properties.
      Public ReadOnly Property AlarmText() As String
         ...
      End Property 
   
      Public ReadOnly Property NumRings() As Integer
         ...
      End Property 
   
      Public ReadOnly Property SnoozePressed() As Boolean
         ...
      End Property
      ...
   End Class
   

2. Declare a delegate for the event, as in the following example.

   Note You do not have to declare a custom delegate if the event does not generate data. In that case, use the base event handler System.ComponentModel.EventHandler.

   public delegate void AlarmEventHandler(object sender, AlarmEventArgs e);
   [Visual Basic]
   Public Delegate Sub AlarmEventHandler(sender As Object, e As AlarmEventArgs)
   

3. Define a public event member in your class using the event keyword whose type is an event delegate, as in the following example.

   public class AlarmClock 
   {
    ...
    public event AlarmEventHandler Alarm;   
   }
   [Visual Basic]
   Public Class AlarmClock
      ...
      Public Event Alarm As AlarmEventHandler
   End Class
   

   In the AlarmClock class the Alarm event is a delegate of type AlarmEventHandler. When the compiler encounters an event keyword, it creates a private member such as

   private AlarmEventHandler al = null;
   

   and the two public methods add_Alarm and remove_Alarm. These methods are event hooks that allow delegates to be combined or removed from the event delegate al. The details are hidden from the programmer.

   Note In languages other than C# and Visual Basic .NET, the compiler might not automatically generate the code corresponding to an event member, and you might have to explicitly define the event hooks and the private delegate field.

4. Provide a protected method in your class that raises the event. This method must be named OnEventName. The ** OnEventName method ** raises the event by invoking the delegates. The code example at the end of this topic shows an implementation of OnEventName.

   Note   The protected OnEventName method also allows derived classes to override the event without attaching a delegate to it. A derived class must always call the OnEventName method of the base class to ensure that registered delegates receive the event.

   public class AlarmClock 
      {
      ...
      public event AlarmHandler Alarm;
      protected virtual void OnAlarm(AlarmEvent e){...}
      }
   [Visual Basic]
   Public Class AlarmClock
      ...
      Public Event Alarm As AlarmEventHandler
      Protected Overridable Sub OnAlarm(e As AlarmEventArgs)
         ...
      End Sub
   End Class
   

The following code fragment puts together all of the elements discussed in this section. For a complete sample that implements and uses events, see Event Sample.

//Step 1. Class that defines data for the event
//
public class AlarmEventArgs : EventArgs 
   {   
      private readonly bool snoozePressed = false;
      private readonly int nrings = 0;
      // Constructor.
      public AlarmEventArgs(bool snoozePressed, int nrings) {...}
      // Properties.
      public int NumRings{ get { return nrings;}}
      public bool SnoozePressed { get { return snoozePressed;}}    
      public string AlarmText { get {...}}

   }
   
//Step 2. Delegate declaration.
//
public delegate void AlarmEventHandler(object sender, AlarmEventArgs e);

// Class definition.
//
public class AlarmClock 
{
//Step 3. The Alarm event is defined using the event keyword.
//The type of Alarm is AlarmEventHandler.
  public event AlarmEventHandler Alarm;
//
//Step 4. The protected OnAlarm method raises the event by invoking 
//the delegates. The sender is always this, the current instance of 
//the class.
//   
protected virtual void OnAlarm(AlarmEventArgs e) 
   {
    if (Alarm != null) 
     {
       //Invokes the delegates.
       Alarm(this, e); 
      }
   }
}
[Visual Basic]
'Step 1. Class that defines data for the event
'
Public Class AlarmEventArgs
   Inherits EventArgs
   Private _snoozePressed As Boolean = False
   Private nrings As Integer = 0
   
   ' Constructor.
   Public Sub New(snoozePressed As Boolean, nrings As Integer)
      ...
   End Sub

   ' Properties.
   Public ReadOnly Property NumRings() As Integer
      Get
         Return nrings
      End Get
   End Property
   
   Public ReadOnly Property SnoozePressed() As Boolean
      Get
         Return _snoozePressed
      End Get
   End Property
   
   Public ReadOnly Property AlarmText() As String
      Get
         ...
      End Get 
   End Property
End Class

'Step 2. Delegate declaration.
'
Public Delegate Sub AlarmEventHandler(sender As Object, e As AlarmEventArgs)

' Class definition.
'
Public Class AlarmClock
   'Step 3. The Alarm event is defined using the event keyword.
   'The type of Alarm is AlarmEventHandler.
   Public Event Alarm As AlarmEventHandler
   
   '
   'Step 4. The protected OnAlarm method raises the event by invoking 
   'the delegates. The sender is always this, the current instance of 
   'the class.
   '   
   Protected Overridable Sub OnAlarm(e As AlarmEventArgs)
      'Invokes the delegates.
      RaiseEvent Alarm(Me, e)
   End Sub
End Class

See Also

Events and Delegates | Event Sample