Oberon || Library || Module Index || Search Engine || Definition || Module


Ulm's Oberon Library:
RelatedEvents


NAME

RelatedEvents - relate events to objects

SYNOPSIS

TYPE Object = Disciplines.Object;
TYPE Event = POINTER TO EventRec;
TYPE EventRec =
   RECORD
      (Events.EventRec)
      object: Object;
      event: Events.Event;
   END;
TYPE Queue = POINTER TO QueueRec;
TYPE QueueRec =
   RECORD
      (Objects.ObjectRec)
      event: Events.Event;
      next: Queue;
   END;


VAR null: Object;

PROCEDURE GetEventType(object: Object; VAR eventType: Events.EventType); PROCEDURE Forward(from, to: Object); PROCEDURE QueueEvents(object: Object); PROCEDURE Reset(object: Object); PROCEDURE Save(object: Object); PROCEDURE Restore(object: Object); PROCEDURE GetQueue(object: Object; VAR queue: Queue); PROCEDURE EventsPending(object: Object) : BOOLEAN; PROCEDURE AppendQueue(object: Object; queue: Queue); PROCEDURE Raise(object: Object; event: Events.Event);

DESCRIPTION

Many events are not to be handled globally but are to be considered in the context of an abstract data type. RelatedEvents implements object centered event handling, i.e. the handling of events does not primarily depend on the global event handlers of Events but on the object it is related to.

RelatedEvents supports four reaction types for related events. Different reactions may be active at the same time. GetEventType returns an event type for the given object and causes all events related to object also to be passed (in form of an indirect event of type Event) to Events.Raise with this event type. Initially, the priority of eventType equals Priorities.liberrors + 1.

Forward requests all incoming events of from to be forwarded to to. QueueEvents puts all events for object in a queue which can be examined later by GetQueue. Reset undoes previous calls of GetEventType, Forward and QueueEvents and causes all subsequent events of object to be processed by Events.

Save and Restore allow to save and restore the reaction state of the given object and may be nested. The reaction state includes all settings and the event queue. Save puts like Reset the object into the default state.

GetQueue removes and returns the event queue of object. EventsPending returns TRUE if there are any events in the queue of object. GetQueue and EventsPending allow object to be NIL. AppendQueue forwards all events of queue to object.

By default (or if object equals NIL), Raise passes event to Events.Raise for usual event handling. If GetEventType, Forward, or QueueEvents have been called for object, object related event handling will take place as described above.

The object null acts as a null device like Streams.null: It causes all related events and all operations of RelatedEvents to be ignored.

RelatedEvents supports Forwarders by creating a backward chain which forwards events from objects which are depended on to dependants, i.e. Forwarders.Forward causes events to be forwarded from to to from. This allows to react on events independently from the knowledge of forward chains created by Forwarders. Note that this backward chain does not lead to reference cycles due to Forward calls which usually forward events from dependants to objects which are depended on.

SEE ALSO

Conclusions
formatted output of event queues
Events
global event handling
Forwarders
general forwarding operation
Priorities
event priority system

BUGS

Forward is not protected against reference cycles. If Forward points into the same direction as an implicitly created backward link by Forwarders.Forward, then events may be delivered twice.
Edited by: borchert, last change: 2003/07/10, revision: 1.7, converted to HTML: 2003/07/10

Oberon || Library || Module Index || Search Engine || Definition || Module