org.jdesktop.wonderland.client.input
Interface EventListener

All Known Implementing Classes:
EnterExitEvent3DLogger, EventClassFocusListener, EventClassListener, EventListenerBaseImpl, KeyEvent3DLogger, MouseEvent3DLogger, SpinObjectEventListener

public interface EventListener

A listener for events which are delivered by the input system to entities. An event listener can be added to an entity via addToEntity(). Multiple listeners can be added to a single entity. A particular listener can be only added once to a particular entity. Subsequent attempts to add the listener to the same entity will be ignored.

When an entity receives an event it will invoke methods for all enabled event listeners. An event listener can be enabled or disabled via setEnabled(). For each enabled listener the following methods will be called for the event:

1. consumesEvent: The listener should return true if it wishes to receive the given event.

2. propagatesToParent: The listener should return true if the parent of the event entity should be given a chance to receive the given event.

3. computeEvent: Called if the previous call to consumesEvent returned true. This method should determine how to change the world based on the event.

4. commitEvent: Called if computeEvent was previously called. This method should apply to the world the changes which were determined by computeEvent.

Note: commitEvent is called in the mtgame render loop thread and therefore should be kept short.

In general, the programmer should not make any assumptions about the order in which methods of different event listeners are called for a single event. Nor should the programmer make any assumptions about the order or number of times methods are called for a single event listener for a single event. One guarantee which is provided is that for a given event an enabled listener's computeEvent will be called once (if consumesEvent returned true) and, sometime later, the commitEvent routine will be called. Also, another guarantee is that all registered, enabled event listeners (both global and per-entity) will be tried for a given event before any event listeners are tried for subsequent events.

If an entity which has no attached listeners receives an event that entity will be treated as if it has an enabled listener whose consumesEvent method returns true and whose propagatesToParent method returns true.

computeEvent should propagate information to commitEvent by storing data in instance data members of the event listener. The system makes the guaranteed that a call to commitEvent is always preceded by a call to computeEvent for each newly received event.

Author:
deronj

Method Summary
 void addToEntity(org.jdesktop.mtgame.Entity entity)
          Add this event listener to the given entity.
 void commitEvent(Event event)
          Called after computeEvent has been called for this event listener.
 void computeEvent(Event event)
          The implementation of this method should determine how to change the world based on the given event.
 boolean consumesEvent(Event event)
          Returns whether this event listener currently wishes to receive the given event.
 boolean isEnabled()
          Returns whether this event listener is currently enabled.
 boolean isListeningForEntity(org.jdesktop.mtgame.Entity entity)
          Returns true if this listener is currently attached to the given entity.
 void postEvent(Event event)
          INTERNAL ONLY.
 boolean propagatesToParent(Event event)
          Returns whether the event should also be propagated to the event entity's parent for possible delivery.
 void removeFromEntity(org.jdesktop.mtgame.Entity entity)
          Remove this event listener from the given entity.
 void setEnabled(boolean enable)
          Enable or disable this event listener.
 

Method Detail

isEnabled

boolean isEnabled()
Returns whether this event listener is currently enabled.


setEnabled

void setEnabled(boolean enable)
Enable or disable this event listener.

Note: Disabling the listener deletes any pending posted events which have not yet been delivered to the listeners.

Parameters:
enable - Whether the event listener should be enabled.

consumesEvent

boolean consumesEvent(Event event)
Returns whether this event listener currently wishes to receive the given event. Here is where the decision to receive different types of events occurs. The input system calls this method only if the listener is enabled. Computations in this method should be kept reasonably short as they occur in AWT Event Dispatch thread.

Example Usage: User interface buttons with rounded edges can use a simple quad for its geometry and use a transparent texture to achieve the rounded appearance. In order to make sure that the portions of the quad which are transparent are not input sensitive we could define consumesEvent to lookup the hit texel in the texture and not consume the event if the hit texel is transparent.

Parameters:
event - The event in question.

propagatesToParent

boolean propagatesToParent(Event event)
Returns whether the event should also be propagated to the event entity's parent for possible delivery. If any listener on an entity prevents propagation to parents, the event will not be delivered to the entity's parents or to any global listeners. Note that other listeners on the same entity will receive the event.

This method is only called if consumesEvent() returns true for the given event

Computations in this method should be kept reasonably short as they occur in the AWT Event Dispatch thread. This method is only called for entity-attached event listeners.

Parameters:
event - The event in question.

computeEvent

void computeEvent(Event event)
The implementation of this method should determine how to change the world based on the given event.

Note: It is guaranteed that when computeEvent is called for a particular event that commitEvent will be called sometime after.

Parameters:
event - The event in question.

commitEvent

void commitEvent(Event event)
Called after computeEvent has been called for this event listener. The implementation of this method should apply to the world those changes which were determined in computeEvent.

Note: It is guaranteed that a call to commitEvent for an event is always preceded by a call to commitEvent for that event.

Parameters:
event - The event which was computed.

addToEntity

void addToEntity(org.jdesktop.mtgame.Entity entity)
Add this event listener to the given entity. An given event listener instance may be only be added once to an entity. Once an event listener instance has been added to an entity, subsequent attempts to add the entity will be ignored. However, a given event listener instance may be added to multiple entities.

Note: It is not a good idea to call this from inside EventListener.computeEvent function. However, it is okay to call this from inside EventListener.commitEvent function if necessary.

Parameters:
entity - The entity to which to attach this event listener.

removeFromEntity

void removeFromEntity(org.jdesktop.mtgame.Entity entity)
Remove this event listener from the given entity.

Note: It is not a good idea to call this from inside EventListener.computeEvent function. However, it is okay to call this from inside EventListener.commitEvent function if necessary.

Parameters:
entity - The entity to which to attach this event listener.

isListeningForEntity

boolean isListeningForEntity(org.jdesktop.mtgame.Entity entity)
Returns true if this listener is currently attached to the given entity.

Parameters:
entity - The entity to which to attach this event listener.

postEvent

void postEvent(Event event)
INTERNAL ONLY.
Deliver the given event to this collection. This is only ever called by the EventDeliverer.



Open Wonderland - http://openwonderland.org