docs/ecma334/8.7.5.xml

   1 <?xml version="1.0"?>
   2 <clause number="8.7.5" title="Events" informative="true">
   3   <paragraph>An event is a member that enables an object or class to provide notifications. A class defines an event by providing an event declaration (which resembles a field declaration, though with an added event keyword) and an optional set of event accessors. The type of this declaration must be a delegate type. </paragraph>
   4   <paragraph>An instance of a delegate type encapsulates one or more callable entities. For instance methods, a callable entity consists of an instance and a method on that instance. For static methods, a callable entity consists of just a method. Given a delegate instance and an appropriate set of arguments, one can invoke all of that delegate instance's methods with that set of arguments. </paragraph>
   5   <paragraph>In the example <code_example><![CDATA[
   6 public delegate void EventHandler(object sender, System.EventArgs e);
   7 public class Button
   8 {
   9    public event EventHandler Click;
  10    public void Reset() {
  11       Click = null;
  12    }
  13 }
  14 ]]></code_example>the Button class defines a Click event of type EventHandler. Inside the Button class, the Click member is exactly like a private field of type EventHandler. However, outside the Button class, the Click member can only be used on the left-hand side of the += and -= operators. The += operator adds a handler for the event, and the -= operator removes a handler for the event. The example <code_example><![CDATA[
  15 using System;
  16 public class Form1
  17 {
  18    public Form1() {
  19       // Add Button1_Click as an event handler for Button1's Click event
  20       Button1.Click += new EventHandler(Button1_Click);
  21    }
  22    Button Button1 = new Button();
  23    void Button1_Click(object sender, EventArgs e) {
  24       Console.WriteLine("Button1 was clicked!");
  25    }
  26    public void Disconnect() {
  27       Button1.Click -= new EventHandler(Button1_Click);
  28    }
  29 }
  30 ]]></code_example>shows a Form1 class that adds Button1_Click as an event handler for Button1's Click event. In the Disconnect method, that event handler is removed. </paragraph>
  31   <paragraph>For a simple event declaration such as <code_example><![CDATA[
  32 public event EventHandler Click;
  33 ]]></code_example>the compiler automatically provides the implementation underlying the += and -= operators. </paragraph>
  34   <paragraph>An implementer who wants more control can get it by explicitly providing add and remove accessors. For example, the Button class could be rewritten as follows: <code_example><![CDATA[
  35 public class Button
  36 {
  37    private EventHandler handler;
  38    public event EventHandler Click {
  39       add { handler += value; }
  40
  41       remove { handler -= value; }
  42    }
  43 }
  44 ]]></code_example></paragraph>
  45   <paragraph>This change has no effect on client code, but allows the Button class more implementation flexibility. For example, the event handler for Click need not be represented by a field. </paragraph>
  46 </clause>