17.7 Events

An event is a member that enables an object or class to provide
notifications. Clients can attach executable code
for events by supplying event handlers.
Events are declared using event-declarations:
event-declaration:
attributesopt event-modifiersopt event type variable-declarators ;
attributesopt event-modifiersopt event type member-name {
event-accessor-declarations }
event-modifiers:
event-modifier
event-modifiers event-modifier
event-modifier:
new
public
protected
internal
private
static
virtual
sealed
override
abstract
extern
event-accessor-declarations:
add-accessor-declaration remove-accessor-declaration
remove-accessor-declaration add-accessor-declaration
add-accessor-declaration:
attributesopt add block
Chapter 17 Classes
247
remove-accessor-declaration:
attributesopt remove block
An event-declaration may include a set of attributes (§24) and a valid
combination of the four access modifiers
(§17.2.3), the new (§17.2.2), static (§17.5.2, §17.7.3), virtual (§17.5.
3, §17.7.4), override (§17.5.4,
§17.7.4), sealed (§17.5.5), abstract (§17.5.6, §17.7.4), and extern
modifiers.
Event declarations are subject to the same rules as method declarations (§17
.5) with regard to valid combinations
of modifiers.
The type of an event declaration must be a delegate-type (§11.2), and that
delegate-type must be at least as
accessible as the event itself (§10.5.4).
An event declaration may include event-accessor-declarations. However, if
it does not, for non-extern, nonabstract
events, the compiler shall supply them automatically (§17.7.1); for extern
events, the accessors are
provided externally.
An event declaration that omits event-accessor-declarations defines one or
more events?one for each of the
variable-declarators. The attributes and modifiers apply to all of the
members declared by such an eventdeclaration.
It is a compile-time error for an event-declaration to include both the
abstract modifier and brace-delimited
event-accessor-declarations.
When an event declaration includes an extern modifier, the event is said to
be an external event. Because an
external event declaration provides no actual implementation, it is an
error for it to include both the extern
modifier and event-accessor-declarations.
An event can be used as the left-hand operand of the += and -= operators (§1
4.13.3). These operators are used,
respectively, to attach event handlers to, or to remove event handlers from
an event, and the access modifiers of
the event control the contexts in which such operations are permitted.
Since += and ?= are the only operations that are permitted on an event
outside the type that declares the event,
external code can add and remove handlers for an event, but cannot in any
other way obtain or modify the
underlying list of event handlers.
In an operation of the form x += y or x ?= y, when x is an event and the
reference takes place outside the type
that contains the declaration of x, the result of the operation has type
void (as opposed to having the type of x,
with the value of x after the assignment). This rule prohibits external
code from indirectly examining the
underlying delegate of an event.
[Example: The following example shows how event handlers are attached to
instances of the Button class:
public delegate void EventHandler(object sender, EventArgs e);
public class Button: Control
{
public event EventHandler Click;
}
public class LoginDialog: Form
{
Button OkButton;
Button CancelButton;
public LoginDialog() {
OkButton = new Button(?);
OkButton.Click += new EventHandler(OkButtonClick);
CancelButton = new Button(?);
CancelButton.Click += new EventHandler(CancelButtonClick);
}
void OkButtonClick(object sender, EventArgs e) {
// Handle OkButton.Click event
}
C# LANGUAGE SPECIFICATION
248
void CancelButtonClick(object sender, EventArgs e) {
// Handle CancelButton.Click event
}
}
Here, the LoginDialog instance constructor creates two Button instances and
attaches event handlers to the
Click events. end example]