quicktime.app.spaces
Class SimpleSpace

java.lang.Object
  |
  +--quicktime.app.spaces.SimpleSpace
All Implemented Interfaces:
Collection, DynamicCollection, Listener, Space, Ticklish
Direct Known Subclasses:
GroupDrawable, SWCompositor

public abstract class SimpleSpace
extends java.lang.Object
implements Space

SimpleSpace provides a default reference implementation of the Space interface. The following actions are taken by the SimpleSpace class when members or controllers are added to the Space.

The SimpleSpace can be used in different settings - ie. it has no predefined application for managing display (presentation) or model contexts. The QTJava library provides DisplaySpaces as extensions and concrete classes of the SimpleSpace. However applications can also use SimpleSpace as a parent class for other kinds of Spaces, such as model spaces.

The SimpleSpace has no knowledge or implementation of the type of collection that is used to hold the collection of members. It is a delegated responsibility of the subclass to implement the Collection methods. There are two protected methods that the subclass should call after they have successfully added or removed a member - memberAdded and memberRemoved respectively. These methods ensure the behaviour of members as outlined.

See Also:
quicktime.app.display.SWCompositor, GroupDrawable

Field Summary
protected  java.util.Vector containedSpaces
          This vector is used to collect any Spaces that are added as members to this Space
protected  java.util.Vector controllersVec
          This vector is used to collect the Controllers that are added to the Space
protected  TickleList ticklers
          This TickleList is used to collect any ticklish controllers that are added to the Space
protected  <>Timer timer
          This is the Timer that both provides a TimeBase for the Space and tickles the Space based on the scale and period of the Timer
 
Fields inherited from interface quicktime.app.time.Ticklish
kScale
 
Constructor Summary
protected SimpleSpace(Protocol protocols)
          Called by classes that extend the SimpleSpace.
protected SimpleSpace(Protocol protocols, int scale, int period)
          Called by classes that extend the SimpleSpace.
 
Method Summary
 void addController(Controller c)
          This method is used by the application to add a Controller to the Space.
 void addedTo(java.lang.Object interest)
          This method is called by some kind of container object when the Listener is added to the object that is the source of the interest.
abstract  boolean addMember(java.lang.Object member)
          Adds an object to the collection.
 java.util.Enumeration controllers()
          Returns an Enumeration of all Controllers that are currently attached to the Space.
protected  void finalize()
           
 Protocol getProtocol()
          Returns the Protocol object that defines if a member is an appropriate member of the Space.
 java.lang.Object getSource()
          This object is the source for all of the members and controllers of the Space that implement the Listener interface.
 <>Timer getTimer()
          Returns the Timer of the Space.
 boolean hasMember(java.lang.Object object)
          Returns true if the specified QTDrawable is a member of this Group.
 boolean isAppropriate(java.lang.Object object)
          Returns true if the Object object is an appropriate member of the Space.
protected  void memberAdded(java.lang.Object member)
          When the sub-class defines the addMember method and has added the member to its collection it should call memberAdded to ensure that the member roles as defined within the Space are correctly established.
protected  void memberRemoved(java.lang.Object member)
          When the sub-class defines the removeMember method and has removed the member from its collection it should call memberRemoved to ensure that the member roles as defined within the Space are correctly maintained.
 void removeAllControllers()
          This method will remove all of the controllers that are currently attached to the Space.
 void removeAllMembers()
          This method will remove all of the members that are currently contained by the space.
 void removeController(Controller c)
          Removes a controller that was previously added to the Space.
 void removedFrom(java.lang.Object interest)
          This method is called by the specified object when the Listener object is removed from the object that is the source of the interest.
abstract  void removeMember(java.lang.Object member)
          If the object is a member of the collection it is removed.
 boolean tickle(float er, int time)
          The Timer invokes the tickle method when the invocation constraints of the Timer are reached.
 java.util.Enumeration tickleList()
          Returns an Enumeration of all of the Controllers that implement the Ticklish interface (TicklishControllers) that have been added to the Space.
 void timeChanged(int newTime)
          Invoked by the timer when a time condition of its time base has changed.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface quicktime.app.spaces.Collection
isEmpty, members, size
 

Field Detail

controllersVec

protected java.util.Vector controllersVec
This vector is used to collect the Controllers that are added to the Space

containedSpaces

protected java.util.Vector containedSpaces
This vector is used to collect any Spaces that are added as members to this Space

ticklers

protected TickleList ticklers
This TickleList is used to collect any ticklish controllers that are added to the Space

timer

protected <>Timer timer
This is the Timer that both provides a TimeBase for the Space and tickles the Space based on the scale and period of the Timer
Constructor Detail

SimpleSpace

protected SimpleSpace(Protocol protocols)
               throws QTException
Called by classes that extend the SimpleSpace. The sub class must pass in a Protocol object that defines the protocol (ie. the Class type of member objects) that the sub-class Space knows how to deal with. This ensure that members of a Space meet some minimal functionality.

This constructor does not create a Timer, the subclass must create a Timer in its constructor. This is provided so that subclasses can customise the Timer.

Parameters:
protocols - the Protocol that is enforced on candidate member objects of this space.
See Also:
Protocol, Timer

SimpleSpace

protected SimpleSpace(Protocol protocols,
                      int scale,
                      int period)
               throws QTException
Called by classes that extend the SimpleSpace. The sub class must pass in a Protocol object that defines the protocol (ie. the Class type of member objects) that the sub-class Space knows how to deal with. This ensure that members of a Space meet some minimal functionality. The constructor also provides a scale and period for the construction of the Space's Timer. This scale and period can be reset at any time using appropriate methods on the Timer class.
Parameters:
protocols - the Protocol that is enforced on candidate member objects of this space.
scale - the scale of the Space's Timer - this may NOT be zero.
period - the period of the Space's Timer.
See Also:
Protocol, Timer
Method Detail

timeChanged

public void timeChanged(int newTime)
                 throws QTException
Invoked by the timer when a time condition of its time base has changed.
Specified by:
timeChanged in interface Ticklish
Parameters:
the - newTime of the time base resulting from the changed time line of the timer

tickle

public boolean tickle(float er,
                      int time)
               throws QTException
The Timer invokes the tickle method when the invocation constraints of the Timer are reached. If the sub-class Space has its own tickle requirements then it should overide the tickle method, however to ensure that any ticklish controllers are tickled the overiding implementation should first call super.tickle.
Specified by:
tickle in interface Ticklish
Parameters:
er - the effective rate of the Timer when the time condition matches
time - the time that the Timer invoked the tickle method.
Returns:
true if the Ticklish object should receive a consequent tickle, or false if the Ticklish object should not be tickled again.

tickleList

public java.util.Enumeration tickleList()
Returns an Enumeration of all of the Controllers that implement the Ticklish interface (TicklishControllers) that have been added to the Space. These controllers are tickled each time the Space itself is tickled by its Timer.
Specified by:
tickleList in interface Space
Returns:
an Enumeration of Ticklish objects

getSource

public java.lang.Object getSource()
This object is the source for all of the members and controllers of the Space that implement the Listener interface. All such members and controllers will have the same source as the parent space when it is addedTo a Listener source. If the parent Space has not been added to a Listener source this returns null.
Specified by:
getSource in interface Space
Returns:
the Listener source object

getProtocol

public Protocol getProtocol()
Returns the Protocol object that defines if a member is an appropriate member of the Space.
Specified by:
getProtocol in interface DynamicCollection
Returns:
a Protocol object.

isAppropriate

public boolean isAppropriate(java.lang.Object object)
Returns true if the Object object is an appropriate member of the Space. To be an appropriate member the object must pass the passProtocol method of the Protocol object of the Space.
Specified by:
isAppropriate in interface Collection
Parameters:
object - the Object to test
Returns:
true if the object passes the current protocol of the Protocol object of the Space.

hasMember

public boolean hasMember(java.lang.Object object)
Returns true if the specified QTDrawable is a member of this Group.
Specified by:
hasMember in interface Collection
Returns:
a boolean

addedTo

public void addedTo(java.lang.Object interest)
This method is called by some kind of container object when the Listener is added to the object that is the source of the interest.
Specified by:
addedTo in interface Listener
Parameters:
source - the object that is to be the source of interest for the the Listener object.

removedFrom

public void removedFrom(java.lang.Object interest)
This method is called by the specified object when the Listener object is removed from the object that is the source of the interest.
Specified by:
removedFrom in interface Listener
Parameters:
source - the object that is to be the source of interest for the the Listener object.

addController

public void addController(Controller c)
                   throws QTException
This method is used by the application to add a Controller to the Space. A Controller will control members of a Space.
Specified by:
addController in interface Space
Parameters:
c - the Controller to add to the Space.

removeController

public void removeController(Controller c)
                      throws QTException
Removes a controller that was previously added to the Space.
Specified by:
removeController in interface Space
Parameters:
c - the Controller to remove from the Space.

controllers

public java.util.Enumeration controllers()
Returns an Enumeration of all Controllers that are currently attached to the Space.
Specified by:
controllers in interface Space
Returns:
an Enumeration

getTimer

public <>Timer getTimer()
Returns the Timer of the Space. This Timer provids a TimeBase for the Space and if active will tickle and send timeChanged calls to the TicklishControllers that are attached to the Space.
Specified by:
getTimer in interface Space
Returns:
a Timer

addMember

public abstract boolean addMember(java.lang.Object member)
                           throws QTException
Adds an object to the collection. Returns true if the object is appropriate member of the collection (and thus added) and false if not.
Specified by:
addMember in interface Collection
Parameters:
member - the object that should be added as a member to the collection
Returns:
a boolean.

removeMember

public abstract void removeMember(java.lang.Object member)
                           throws QTException
If the object is a member of the collection it is removed.
Specified by:
removeMember in interface Collection
Parameters:
member - the object to remove from the collection

memberAdded

protected void memberAdded(java.lang.Object member)
                    throws QTException
When the sub-class defines the addMember method and has added the member to its collection it should call memberAdded to ensure that the member roles as defined within the Space are correctly established.
Parameters:
member - the object that has been added to the Space.

memberRemoved

protected void memberRemoved(java.lang.Object member)
                      throws QTException
When the sub-class defines the removeMember method and has removed the member from its collection it should call memberRemoved to ensure that the member roles as defined within the Space are correctly maintained.
Parameters:
member - the object that has been added to the Space.

removeAllControllers

public void removeAllControllers()
                          throws QTException
This method will remove all of the controllers that are currently attached to the Space.

removeAllMembers

public void removeAllMembers()
                      throws QTException
This method will remove all of the members that are currently contained by the space.

finalize

protected void finalize()
                 throws java.lang.Throwable
Overrides:
finalize in class java.lang.Object