com.transmote.nest.events
Class EventDispatcher

java.lang.Object
  java.util.Observable
      com.transmote.nest.events.EventDispatcher

All Implemented Interfaces:

Observer

Direct Known Subclasses:

NestSprite

public class EventDispatcher
extends Observable
implements Observer

EventDispatcher instances wrap Java's Observable implementation of the Observer interface. EventDispatcher is modeled on ActionScript's EventDispatcher class, and offers much of the same functionality. Event instances flow through EventDispatcher instances in what is referred to as 'the event flow'.

The Nest event flow is modeled on the event flow implemented by Adobe ActionScript 3.0. Input events enter into the event flow through NestSpriteContainer, at the top of the display list. Each input event then proceeds down through the display list, in the 'capture' phase. The event ultimately reaches the 'target' phase, at the NestSprite instance farthest down the display list within whose bounds the event was generated. Once the event reaches its target, it moves back up the display list in the 'bubbling' phase.

how to use: addObserver, dispatchEvent, override handleEvent.

wraps Observable, to allow use via composition instead of inheritance.

Author:

Eric Socolofsky

See Also:

Event

+Example

/*
 * MouseEvents_Simple
 * 
 * NestSprite provides a simple API for handling mouse events.
 * Subclasses can override the following NestSprite methods
 * to handle mouse events:
 * - mouseClicked()
 * - mouseClickedOutside()
 * - mouseEntered()
 * - mouseExited()
 * - mousePressed()
 * - mousePressedOutside()
 * - mouseReleased()
 * - mouseReleasedOutside()
 * - mouseDown()
 * - mouseUp()
 * - mouseDragged()
 * - mouseMoved()
 * 
 * A NestSprite instance will only receive mouse events if it is
 * currently on the display list, so be sure to addChild() it
 * to NestSpriteContainer or to an other NestSprite that is already
 * on the display list before attempting to handle mouse events.
 * 
 * Many mouse events are only handled if they are within the bounds
 * of the NestSprite instance.  See the MouseEvents_Bounds example for
 * a more in-depth explanation of NestSprite.bounds().
 */

import com.transmote.nest.*;
import com.transmote.nest.events.*;

NestSpriteContainer spriteContainer;

void setup () {
  size(400, 400);
  setupSprites();
}

void draw () {
  background(0);
  spriteContainer.updateDisplayList();
}

void setupSprites () {
  // create a NestSpriteContainer to hold all other NestSprites
  spriteContainer = new NestSpriteContainer(this);
  
  // attach ButtonSprite instances to the SpriteContainer
  ButtonSprite spriteLeft = new ButtonSprite();
  spriteLeft.x = 50;
  spriteLeft.y = 150;
  spriteContainer.addChild(spriteLeft);
  ButtonSprite spriteRight = new ButtonSprite();
  spriteRight.x = 250;
  spriteRight.y = 150;
  spriteContainer.addChild(spriteRight);
  
  // set each ButtonSprite up to handle
  // events generated by the other ButtonSprite
  spriteLeft.addObserver(spriteRight);
  spriteRight.addObserver(spriteLeft);
}

Constructor Summary

EventDispatcher()

EventDispatcher(Object owner)

Method Summary

void	addObserver(Observer o) Add an Observer to be notified asynchronously of events (which can be defined as either Objects or Events).
void	deleteObserver(Observer o) Remove an Observer from the event notification list of this EventDispatcher instance.
void	dispatchEvent(Event evt) Dispatch a Nest Event to all registered Observers.
void	dispatchEvent(Object arg) Dispatch a generic Object to all registered Observers.
void	dispose() Clean up all references within this EventDispatcher instance, to prepare for garbage collection.
Object	owner() A reference to an object that contains this EventDispatcher instance.
void	update(Observable o, Object arg)

Methods inherited from class java.util.Observable

countObservers, deleteObservers, hasChanged, notifyObservers, notifyObservers

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EventDispatcher

public EventDispatcher()

EventDispatcher

public EventDispatcher(Object owner)

Method Detail

owner

public Object owner()

A reference to an object that contains this EventDispatcher instance. Useful when using EventDispatcher with composition rather than inheritance. Set this property via the constructor. If this property is not set, it returns a reference to this EventDispatcher instance.

addObserver

public void addObserver(Observer o)

Add an Observer to be notified asynchronously of events (which can be defined as either Objects or Events).

Overrides:

addObserver in class Observable

Parameters:

o - The Observer instance that will be notified. If the Observer is an EventDispatcher, the Event will be handled by either handleEvent(Event) or handleEvent(Observable, Object).

See Also:

handleEvent(Event), handleEvent(Observable, Object)

deleteObserver

public void deleteObserver(Observer o)

Remove an Observer from the event notification list of this EventDispatcher instance.

Overrides:

deleteObserver in class Observable

Parameters:

o - The Observer instance that will no longer be notified.

dispatchEvent

public void dispatchEvent(Event evt)

Dispatch a Nest Event to all registered Observers. Dispatching an event via this method will store a reference to the owner of this EventDispatcher instance in the event, as Event.target. This is the preferred method for event-based communication within the NestSprite framework. However, since this method is wrapping the Java Observable pattern, a generic Object can be dispatched instead.

Parameters:

evt - The Event to dispatch to all Observers.

See Also:

Event.target(), owner(), handleEvent(Event), dispatchEvent(Object)

dispatchEvent

public void dispatchEvent(Object arg)

Dispatch a generic Object to all registered Observers. The preferred method for event-based communication within the NestSprite framework is dispatchEvent(Event). However, since this method is wrapping the Java Observable pattern, an Object can be dispatched instead.

Parameters:

arg - The Object to dispatch to all Observers.

See Also:

dispatchEvent(Event), handleEvent(Observable, Object)

dispose

public void dispose()

Clean up all references within this EventDispatcher instance, to prepare for garbage collection.

update

public final void update(Observable o,
                         Object arg)

Specified by:

update in interface Observer