Events (Oxygene)

From RemObjects Software

This is a Oxygene Language Feature topic
Feel free to add your notes to this topic below.

An event is a type member that consumers of the class can use to add, remove and optionally (version 3) raise event handlers.

Events are always delegate types. From within the class, the event can be used like a plain delegate variable, but from the outside a consumer can only add or remove a handler it knows about.

Oxygene 3.0 introduces an additional "raise" method that makes it possible to invoke an event externally.

By default, a variable and the accessor methods are compiler generated. Optionally, the member or add/remove/raise accessors can be stated explicitly.

Syntax

type
  MyDelegate = delegate (Sender: Object; Args: EventArgs);
  MyInterface = interface
    event MyEvent: MyDelegate;
    event MyRaiseEvent: MyDelegate add remove raise;
  end;

  MyClass = class(MyInterface)
  private
    fMember: MyDelegate;
    method AddExplicitEvent(param: MyDelegate);
    method RemoveExplicitEvent(param: MyDelegate);
    method RaiseExplicitEvent(sender: Object; Args: EventArgs);
  public
    event MyEvent: MyDelegate delegate fMember;
    event MyRaiseEvent: MyDelegate add remove raise;
    event ExplcitEvent: MyDelegate add AddExplicitEvent remove RemoveExplicitEvent raise RaiseExplicitEvent;
  end;

Adding/Removing Delegates

In cases where you want to provide your own logic for adding/removing delegates to and from the event, the following extended syntax can be used:

type
  TMyClass = class(…)
  private
    fMyEvent: EventHandler;
    method AddMyEvent(aValue: EventHandler);
    method RemoveMyEvent(aValue: EventHandler);
  public
    event MyEvent: EventHandler add AddMyEvent remove RemoveMyEvent;
  end;

With this syntax, the two specified add and remove methods must conform to the syntax above, they must be procedures and take only one parameter, the matching delegate type. If either provided, both "add" and "remove" must be specified.

Raise

the raise keyword on an event can be used to allow external classes to invoke the event handler. If present, it creates an internal method called fire_EventHandlerName with the signature of the delegate. Inside this method, code is generated to check if the event is assigned and - if yes - invokes it.

It's also possible to provide a custom raise method implementation.

When the raise keyword is set on an event, all calls to the events inside the class will use the raise method. (if raise is not specified, as is the default, the Invoke method on the fMyEvent woukd be called inline). Because of this, there's no need to check for nil when there is a raise keyword involved.

Like the add/remove accessors, it's possible to change the visiblity of the raise method, for example making it protected so only subclasses can call it.

Syntax Examples:

type
  MyEventTest = class
  private
    var f: EventHandler;
    method add_Event(e: EventHandler);
    method remove_Event(e: EventHandler);;
    method raise_Event(o: Object; e: EventArgs);
  public
    event ev1: EventHandler;
    event ev2: EventHandler raise;
    event ev2: EventHandler protected raise;  // descendants can raise
    event ev3: EventHandler delegate f;
    event ev4: EventHandler delegate f raise;
    event ev5: EventHandler add add_event remove remove_event raise raise_event; // custom methods
  end;

When a non-private raise method is defined, the event can be invoked from outside of the class, according to the visibility, through its name:

MyObject.MyEvent();

When consuming classes from languages that don't support using raise event invoking (such as C# and VB), the internal fire_myevent() method can be called directly.

See Also

• Delegates

Product: RemObjects Oxygene (formerly known as Chrome)
Current version: 3.0 Previous Versions: 'Joyride' (2.0), 'Floorshow' (1.5), 'Adrenochrome' (1.0)

Glossary — Keywords — Language Features — Platform Features — Samples — Articles — How To — Issues