NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Providing Event Functionality

Event functionality is provided by several interrelated pieces: the event data, a delegate for the event, methods in your class that attach and remove event handlers, and a method to raise the event.

To provide event functionality

  1. Define a class that defines data for the event. This class must derive from System.EventArgs, which is the base class for event data.
    Note: This step is not needed if an event data class already exists for the event your class wants to raise, or if data is not generated by your event.
    [C#]   
    public class AlarmEventArgs : EventArgs {
          private readonly int nrings = 0;
          private readonly bool snoozePressed = false;
    //properties
          public string AlarmText{   }
          public int NumRings{...}
          public bool SnoozePressed{...}
    ...
         }
  2. Declare a delegate to handle the event.
    Note: You do not have to declare a custom delegate if the event does not generate data. In that situation, the base event handler System.ComponentModel.Eventhandler is adequate.
    [C#]
    public delegate void AlarmEventHandler(object sender, AlarmEventArgs e);
  3. Provide public methods (event hooks) in your class that attach (or remove) event handler delegates. If you want your components to work in the designer, in the PDC Technology Preview release of Visual Studio 7.0, these methods must be named AddOn<EventName> and RemoveOn<EventName>. The code example at the end of this topic shows an implementation of these methods.
    Note for C# and Visual Basic users In a future release, the AddOn and RemoveOn methods will be replaced by a simpler syntax for adding or removing event handlers. For details of the event syntax, see the C# or VB language documentation.
    [C#]   
    public class Alarm : Component {
    //other class members 
       
    //Attaches an event handler for the alarm event
       public void AddOnAlarm(AlarmEventHandler) {...}
    
    //Removes an event handler for the alarm event
       public void RemoveOnAlarm(AlarmEventHandler) {...}
       
    }
  4. Provide a protected method in your class that raises the event. This method must be named On<EventName>. The On<EventName> raises the event by invoking the delegates. The code example at the end of this topic shows an implementation of the On<EventName> method.
    Note: The protected On<EventName>method also allows derived classes to override the event without attaching a delegate to it. A subclass must always call the On<EventName> method of the base class, to ensure that registered delegates receive the event.
    [C#]   
    public class Alarm : Component {
       //other class members 
       public void AddOnAlarm(AlarmEventHandler) {...}
       public void RemoveOnAlarm(AlarmEventHandler) {...}
       protected virtual void OnAlarm(AlarmEvent e){…}
       }


A code example that includes all the elements described above is shown below. For a complete sample that implements and uses events, see the Event Delegate Mini-Sample.

[C#] 
//Step 1. Class that defines data for the event
//
public class AlarmEventArgs : EventArgs {
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);

//Component definition
//
public class Alarm : Component {
private AlarmEventHandler alarm = null;
// Step 3a. AddOnAlarm allows clients to attach an event handler. 
// The Combine method of the Delegate class adds a delegate to the 
// existing list of delegates.
//
public void AddOnAlarm(AlarmEventHandler handler) {
    alarm = (AlarmEventHandler)Delegate.Combine(alarm, handler);
        }
//Step 3b. RemoveOnAlarm allows clients to remove an event handler. The 
//Remove method of the Delegate class removes a delegate from the       
//existing list of delegates.
//
public void RemoveOnAlarm(AlarmEventHandler handler) {
     alarm = (AlarmEventHandler)Delegate.Remove(alarm, handler);
        }
//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) {
       alarm(this, e);//Invokes the delegates. 
          }
     }

See Also

Events and Delegates

Event Delegate Mini-Sample

Properties

Custom Metadata Using Attributes