quicktime.app.actions
Class MouseController

java.lang.Object
  |
  +--quicktime.app.actions.MouseController
All Implemented Interfaces:
Collection, Controller, java.util.EventListener, Listener, ListenerController, java.awt.event.MouseListener, java.awt.event.MouseMotionListener
Direct Known Subclasses:
GroupController, SWController

Deprecated. since QTJava 4.0

public abstract class MouseController
extends java.lang.Object
implements ListenerController, Collection, java.awt.event.MouseListener, java.awt.event.MouseMotionListener

The MouseController marshals mouse events that occur within the space it is attached to and activates its MouseResponder if the received events are of interest to that responder. Thus the MouseController delegates the response to a mouse event to its MouseResponder.

The test to see if an object is a valid candidate is controlled through the setting of the wholespace variable. If wholespace is true then any object that is in the Controller's space is a candidate for response. If wholespace is false then the object must be a member of the controllers list of objects.

Subclasses define specialised controllers that deal with some kind of Space know how to extract objects that are from that Space if the usage of the MouseController requires the selection of a target object. If the MouseController selects an object it hands it off to its MouseResponder which must be able to deal with the kind of object that is selected. However, neither the MouseController or MouseResponder as such have any requirement about the types of spaces, members, etc. that they deal with. The particular controllers and responders decide these issues for themselves.

The two QTDisplaySpaces in the current release both provide MouseController subclasses for extracting an object the user clicks on. SWController for SWCompositor and GroupController for GroupDrawable. The type of object these Controllers returned are documented in those classes. The Responders that can deal with these members can be defined by the application - a Dragger responder is provided that drags a Transformable selection within a QTDrawable space.

In the MouseControllers addedTo and removedFrom methods it registers its interest in the Mouse events that are generated by that java.awt.Component which is the source of that event. Typically the top level Space will be addedTo some kind of Component and the Space itself propogates this to its contained members and controllers so the application will generally have no need to call these methods explicitly.

See Also:
QTMouseController

Field Summary
protected  int xLocationOffset
          Deprecated.  
protected  int yLocationOffset
          Deprecated.  
 
Constructor Summary
protected MouseController(MouseResponder mr, boolean wholespace)
          Deprecated. Creates a mouse controller with its responder.
 
Method Summary
 void addedTo(java.lang.Object interest)
          Deprecated. This method is called by the specified object when the instance of the class that implements this interface is added to the object that is the source of the interest.
 void addedToSpace(Space s)
          Deprecated. This method is called by the space when a Controller is being addedTo the Space s.
 boolean addMember(java.lang.Object member)
          Deprecated. If wholespace is set to false, then only objects that are explicitly added to the controller will be controlled by it.
protected  void deactivateResponder()
          Deprecated. A method that is called whenever the MouseController deactivates its responder.
protected  void doDragTarget(java.awt.event.MouseEvent e)
          Deprecated.  
protected  MouseResponder getResponder()
          Deprecated. This method returns the MouseResponder that is attached to the MouseController.
protected abstract  java.lang.Object getSelected(java.awt.event.MouseEvent event)
          Deprecated. This method is called when a MouseController has received a mouse press, click, drag, event in its space.
abstract  Space getSpace()
          Deprecated. This method returns the Space which the MouseController has been attached to.
 boolean hasMember(java.lang.Object object)
          Deprecated. Returns true if the member has been explicitly added to this controller.
 boolean isAppropriate(java.lang.Object object)
          Deprecated. Returns true if the provided object is an appropriate candidate for membership in a collection.
 boolean isEmpty()
          Deprecated. Returns true if the controller's collection of controllable objects is empty.
 boolean isWholespace()
          Deprecated. Returns the current setting of the wholespace flag.
 java.util.Enumeration members()
          Deprecated. Returns an enumeration of all members of this controller.
 void mouseClicked(java.awt.event.MouseEvent e)
          Deprecated. If the responder is interested in mouseClick events it will be activated when the user clicks.
 void mouseDragged(java.awt.event.MouseEvent e)
          Deprecated. If the responder is interested in mouseDragged events it will be activated when the user drags the mouse within the display space.
 void mouseEntered(java.awt.event.MouseEvent e)
          Deprecated. If the responder is interested in mouseEntered events it will be activated when the user's mouse enters the QTCanvas space.
 void mouseExited(java.awt.event.MouseEvent e)
          Deprecated. If the responder is interested in mouseExited events it will be deactivated after the user's mouse exits the QTCanvas space.
 void mouseMoved(java.awt.event.MouseEvent e)
          Deprecated. If the responder is interested in mouseMoved events it will be activated when the user's mouse moves within the display space.
 void mousePressed(java.awt.event.MouseEvent e)
          Deprecated. If the responder is interested in mousePressed events it will be activated when the user presses the mouse within the display space.
 void mouseReleased(java.awt.event.MouseEvent e)
          Deprecated. If the responder is interested in mouseReleased events it will be activated when the user releases the mouse within the display space.
 void removedFrom(java.lang.Object interest)
          Deprecated. This method is called by the specified object when the instance of the class that implements this interface is removed from the object that is the source of the interest.
 void removedFromSpace()
          Deprecated. Called by the Space when a Controller is being removed from a Space.
 void removeMember(java.lang.Object member)
          Deprecated. Removes a member from the collection of objects that the controller controls
protected  void responderActivated()
          Deprecated. A notification method that is called whenever the MouseController activates its responder.
protected abstract  void setTargetSpace(Space s)
          Deprecated. This method is defined by the subclass to ensure that the incoming Space is an appropriate kind of space for the MouseController to be attached too.
protected  void setTranslation()
          Deprecated. This method is used to setup translation values for x and y of an event to translate the event into the local coordinate space of a member's display Space.
 void setWholespace(boolean flag)
          Deprecated. Sets the new value of the wholespace flag.
 int size()
          Deprecated. Returns the number of members that have been explicitly added to the Controller.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

xLocationOffset

protected int xLocationOffset
Deprecated. 

yLocationOffset

protected int yLocationOffset
Deprecated. 
Constructor Detail

MouseController

protected MouseController(MouseResponder mr,
                          boolean wholespace)
Deprecated. 
Creates a mouse controller with its responder.
Parameters:
mr - the responder that will become active to respond to mouse events
wholespace - sets the value of the wholespace flag
Method Detail

getSpace

public abstract Space getSpace()
Deprecated. 
This method returns the Space which the MouseController has been attached to.
Returns:
the current space.

addedToSpace

public final void addedToSpace(Space s)
Deprecated. 
This method is called by the space when a Controller is being addedTo the Space s. If the Controller is not an appropriate controller for that kind of Space this method can throw an exception and the controller won't be added to the Space.
Specified by:
addedToSpace in interface Controller
Parameters:
s - the Space being added to
See Also:
setTargetSpace()

removedFromSpace

public void removedFromSpace()
Deprecated. 
Called by the Space when a Controller is being removed from a Space. This is only called by the Space on controllers that have previously been added, thus the space they are being removed from is the space they were added to. Sets the targetSpace to null.
Specified by:
removedFromSpace in interface Controller

getResponder

protected MouseResponder getResponder()
Deprecated. 
This method returns the MouseResponder that is attached to the MouseController.
Returns:
a MouseResponder

setTargetSpace

protected abstract void setTargetSpace(Space s)
Deprecated. 
This method is defined by the subclass to ensure that the incoming Space is an appropriate kind of space for the MouseController to be attached too. If not a ClassCastException is generally thrown, and the MouseController will not be attached to the Space.
Parameters:
s -  

addedTo

public void addedTo(java.lang.Object interest)
Deprecated. 
This method is called by the specified object when the instance of the class that implements this interface is added to the object that is the source of the interest. The MouseController expects that the incoming object is some kind of java.awt.Component - in which case it registers its interest in mouse events from that Component source. If the incoming object is not some kind of Component then nothing is done.
Specified by:
addedTo in interface Listener
Parameters:
interest - the object that is to be the source of interest for the the object that implements this interface.

removedFrom

public void removedFrom(java.lang.Object interest)
Deprecated. 
This method is called by the specified object when the instance of the class that implements this interface is removed from the object that is the source of the interest. The MouseController expects that the incoming object is some kind of java.awt.Component - in which case it removes its interest in mouse events from that Component source. If the incoming object is not some kind of Component then nothing is done.
Specified by:
removedFrom in interface Listener
Parameters:
interest - the object that was the source of interest for the the object that implements this interface.

getSelected

protected abstract java.lang.Object getSelected(java.awt.event.MouseEvent event)
                                         throws QTException
Deprecated. 
This method is called when a MouseController has received a mouse press, click, drag, event in its space. This method returns a Transformable object if it finds such an object at the location of the event.
Parameters:
event - a mouse down event
Returns:
a transformable object that is located at the event coordinates or null

isWholespace

public boolean isWholespace()
Deprecated. 
Returns the current setting of the wholespace flag.
Returns:
a boolean

setWholespace

public void setWholespace(boolean flag)
Deprecated. 
Sets the new value of the wholespace flag.
Parameters:
flag - if true all objects in the controller's space are potentially controllable.

addMember

public boolean addMember(java.lang.Object member)
Deprecated. 
If wholespace is set to false, then only objects that are explicitly added to the controller will be controlled by it. Use this method to add these objects to the controller. It the candidate is not an appropriate member for the controller to be controlled it will not be added and false is returned.
Specified by:
addMember in interface Collection
Parameters:
member - the new member object that will be controlled.
Returns:
a boolean indicating whether the object was added or not.

isAppropriate

public boolean isAppropriate(java.lang.Object object)
Deprecated. 
Returns true if the provided object is an appropriate candidate for membership in a collection. The provided QTJava collections use this method to ensure a minimal requirement of Class or Interface instanceof tests to ensure the type of object that can be added to a collection. Some collections can have a protocol that allows an application to further refine and tighten the type of object that is allowed within an individual collection.
Specified by:
isAppropriate in interface Collection
Parameters:
object - the object to test
Returns:
true if the supplied object is appropriate for this collection, or false if not

removeMember

public void removeMember(java.lang.Object member)
Deprecated. 
Removes a member from the collection of objects that the controller controls
Specified by:
removeMember in interface Collection
Parameters:
member - the object that will be removed from the controller.

members

public java.util.Enumeration members()
Deprecated. 
Returns an enumeration of all members of this controller. If wholespace is set to true then this Enumeration may return an empty collection as the default behaviour of the MouseController is that if wholespace is true any object in the space is controllable and thus there is no requirement to explicitly add members to this Controller.
Specified by:
members in interface Collection
Returns:
an Enumeration

isEmpty

public boolean isEmpty()
Deprecated. 
Returns true if the controller's collection of controllable objects is empty. If wholespace is true this does not mean that the controller is not capable of controlling object in its Space as the default behaviour of the MouseController is that if wholespace is true any object in the space is controllable and thus there is no requirement to explicitly add members to this Controller.
Specified by:
isEmpty in interface Collection
Returns:
a boolean

size

public int size()
Deprecated. 
Returns the number of members that have been explicitly added to the Controller.
Specified by:
size in interface Collection
Returns:
an int

hasMember

public boolean hasMember(java.lang.Object object)
Deprecated. 
Returns true if the member has been explicitly added to this controller. As the default behaviour of the MouseController is that if wholespace is true any object in the space is controllable and thus there is no requirement to explicitly add members to this Controller. Consequently this may return false, but if the object is a member of the controller's space it may still be controllable by this controller iff wholespace is set to true.
Specified by:
hasMember in interface Collection
Following copied from interface: quicktime.app.spaces.Collection
Parameters:
member - the object to test for membership
Returns:
a boolean

mouseEntered

public void mouseEntered(java.awt.event.MouseEvent e)
Deprecated. 
If the responder is interested in mouseEntered events it will be activated when the user's mouse enters the QTCanvas space.
Specified by:
mouseEntered in interface java.awt.event.MouseListener
Parameters:
e - the mouse event

mouseExited

public void mouseExited(java.awt.event.MouseEvent e)
Deprecated. 
If the responder is interested in mouseExited events it will be deactivated after the user's mouse exits the QTCanvas space.
Specified by:
mouseExited in interface java.awt.event.MouseListener
Parameters:
e - the mouse event

setTranslation

protected void setTranslation()
Deprecated. 
This method is used to setup translation values for x and y of an event to translate the event into the local coordinate space of a member's display Space. In the case of a DirectGroup the translation is (0, 0), in the case of a Compositor member (which can be embedded n-deep) the translation is the sum of the locations of the space's parents.

The method sets the value of the protected instance variables xLocationOffset and yLocation offset.


mousePressed

public void mousePressed(java.awt.event.MouseEvent e)
Deprecated. 
If the responder is interested in mousePressed events it will be activated when the user presses the mouse within the display space.
Specified by:
mousePressed in interface java.awt.event.MouseListener
Parameters:
e - the mouse event

mouseReleased

public void mouseReleased(java.awt.event.MouseEvent e)
Deprecated. 
If the responder is interested in mouseReleased events it will be activated when the user releases the mouse within the display space.
Specified by:
mouseReleased in interface java.awt.event.MouseListener
Parameters:
e - the mouse event

mouseClicked

public void mouseClicked(java.awt.event.MouseEvent e)
Deprecated. 
If the responder is interested in mouseClick events it will be activated when the user clicks.
Specified by:
mouseClicked in interface java.awt.event.MouseListener
Parameters:
e - the mouse event

mouseMoved

public void mouseMoved(java.awt.event.MouseEvent e)
Deprecated. 
If the responder is interested in mouseMoved events it will be activated when the user's mouse moves within the display space.
Specified by:
mouseMoved in interface java.awt.event.MouseMotionListener
Parameters:
e - the mouse event

mouseDragged

public void mouseDragged(java.awt.event.MouseEvent e)
Deprecated. 
If the responder is interested in mouseDragged events it will be activated when the user drags the mouse within the display space.
Specified by:
mouseDragged in interface java.awt.event.MouseMotionListener
Parameters:
e - the mouse event

doDragTarget

protected void doDragTarget(java.awt.event.MouseEvent e)
Deprecated. 

deactivateResponder

protected void deactivateResponder()
Deprecated. 
A method that is called whenever the MouseController deactivates its responder. A subclass should use this method to deactivate a responder (either explicitly or calling super.deactivateResponder). For example a user may have dragged a member out of a group, so the drag action's target is no longer valid and the Responder has no target to act upon.

responderActivated

protected void responderActivated()
Deprecated. 
A notification method that is called whenever the MouseController activates its responder.