de.sciss.app
Class BasicEvent

java.lang.Object
  java.util.EventObject
      de.sciss.app.BasicEvent

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

NodeEvent, NumberEvent, ServerEvent

public abstract class BasicEvent
extends EventObject

BasicEvent is the superclass of all events to be processed through EventManagers. It subclases java.util.EventObject and thus inherits an event source object.

The source is usually the object that caused the event to be dispatched, see the Timeline's setPosition for an example of the source usage. This allows objects which both dispatch and receive events to recognize if the event was fired by themselves, in which case they might optimize graphical updates or simply ignore the event, or by other objects.

Furthermore, a time tag (getWhen()) can be read to find out when the event was generated.

If events are dispatched at a heavy frequency, the incorporate method can help to shrink the queue by fusing events of the same type.

Version:

0.62, 17-Oct-06

Author:

Hanns Holger Rutz

See Also:

EventManager, Serialized Form

Field Summary

Fields inherited from class java.util.EventObject

source

Constructor Summary

BasicEvent(Object source, int id, long when)
Constructs a new BasicEvent.

Method Summary

int	getID() Requests an identifier specifying the exact type of action that was performed.
long	getWhen() State whens the event has been generated, a timestamp specifying system time millisecs as returned by System.currentTimeMillis().
abstract boolean	incorporate(BasicEvent oldEvent) Asks the event to incorporate the action described by another (older) event.

Methods inherited from class java.util.EventObject

getSource, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BasicEvent

public BasicEvent(Object source,
                  int id,
                  long when)

Constructs a new BasicEvent.

Parameters:

source - Since BasicEvent is a subclass of java.util.EventObject, the given 'source' is directly passed to the superclass and can be queried with getSource(). The source describes the object that originated an action.

id - type of action depending on the concrete subclass. Generally the id is used to distinguish between different method calls on the registered listeners, hence will be usually ignored by the listeners themselves.

when - When the event was generated. See getWhen().

Method Detail

getID

public int getID()

Requests an identifier specifying the exact type of action that was performed.

Returns:

a subclass specific identifier

getWhen

public long getWhen()

State whens the event has been generated, a timestamp specifying system time millisecs as returned by System.currentTimeMillis().

Returns:

time when the event was generated

incorporate

public abstract boolean incorporate(BasicEvent oldEvent)

Asks the event to incorporate the action described by another (older) event. This method has been created to reduce overhead; when many events are added to the event queue of an ELM, this allows to fuse two adjectant events. The idea is mainly based on the replaceEdit() method of the javax.swing.undo.UndoableEdit interface; a pendant of a symmetric addEdit() like method is not provided because it seems to be unnecessary.

Implementation notes : the oldEvent should generally only be incorporated if it refers to the same source object (getSource()) and has the same ID (getD()). the timestamp of the current event should not be modified.

Parameters:

oldEvent - the most recent event in the queue which might be incorporated by this new event.

Returns:

true if this object was able to incorporate the older event. in this case the oldEvent is removed from the event queue. false states that the oldEvent was incompatible and should remain in the queue.

See Also:

UndoableEdit