quicktime.app.event
Class QTMouseTargetController

java.lang.Object
  |
  +--quicktime.app.event.QTMouseController
        |
        +--quicktime.app.event.QTMouseTargetController
All Implemented Interfaces:
Collection, Controller, Listener, ListenerController

public class QTMouseTargetController
extends QTMouseController
implements Collection

A QTMouseTargetController deals with mouse events in a space where the mouse event occurs over (or selects) a member of that space. Members are selected based on being the frontmost member of the space (or of the members explicitly added to the controller).

This controller is also a collection. It acts in two modes. If its wholespace variable is set to true then any of the members of the space can be selected. It wholespace is false then only those members of the space that are also members of the controller can be selected. Generally controllers represent a collection of members that will require the same kinds of mouse behaviours.

This class specialises the handling of the events of its superclass in that for the event to be dispatched to its listeners the controller must have a selected target. In these cases the target attribute of the mouse event is set and the mouse event is broadcast to the appropriate listeners. For instance, if the user clicks in an "empty" area of the space the mouse clicked event won't be broadcast. However, if the user clicks on a member of the space and either wholespace is true or the selected member is a member of the controller, then and only then will the event be broadcast. The exception to this rule is that MouseEnter and MouseExit events will be broadcast regardless. MouseDrag events are considered to be targeted to a target that was selected by a mouse press event and are broadcast until the user releases the mouse. MouseMove events will only be broadcast when they occur whilst over a selected target.

In addition to these events a listener can be registered with this controller which is interested in receiving notification of mouse move or drag events that enter and exit members of the space.

If members are added to the controller the controller will query the space it is attached to to see if those members are appropriate members for that space. This can only be done after the controller is attached to a space. If members are added to the controller before it is added to a space, this appropriateness test is performed. If a member is found to inappropriate it is removed without notification. The member must also be a member of the space.


Fields inherited from class quicktime.app.event.QTMouseController
space
 
Constructor Summary
QTMouseTargetController()
          Creates a QTMouseTargetController with a default setting of wholespace equals true.
QTMouseTargetController(boolean wholespace)
          Creates a QTMouseTargetController.
 
Method Summary
 void addedToSpace(Space s)
          This method is called by the space when a Controller is being addedTo the Space s.
protected  void addHandler()
          This method is called when a controller is added to its space and the controller needs to create its event handler
 boolean addMember(java.lang.Object member)
          If wholespace is set to false, then only objects that are explicitly added to the controller will be controlled by it.
 void addQTMouseListener(QTMouseListener l)
          Add a QTMouseListener for this controller.
protected  void doMouseClicked(QTMouseEvent e)
          This method dispatches the event to the appropriate listeners.
protected  void doMouseDragged(QTMouseEvent e)
          This method dispatches the event to the appropriate listeners.
protected  void doMouseEntered(QTMouseEvent e)
          This method dispatches the event to the appropriate listeners.
protected  void doMouseExited(QTMouseEvent e)
          This method dispatches the event to the appropriate listeners.
protected  void doMouseMoved(QTMouseEvent e, boolean isWithinItsSpace)
          This method dispatches the event to the appropriate listeners.
protected  void doMousePressed(QTMouseEvent e)
          This method dispatches the event to the appropriate listeners.
protected  void doMouseReleased(QTMouseEvent e, boolean isWithin)
          This method dispatches the event to the appropriate listeners.
protected  void doMouseTargetEnter(QTMouseEvent e)
          This method dispatches the event to the appropriate listeners.
protected  void doMouseTargetExit(QTMouseEvent e)
          This method dispatches the event to the appropriate listeners.
protected  java.lang.Object getHitTarget(int x, int y)
          Returns the frontmost object at the specified location that is a member of the space if wholespace is true, or the frontmost object in the controller's collection if wholespace is false.
 boolean hasMember(java.lang.Object object)
          Returns true if the member has been explicitly added to this controller.
 boolean isAppropriate(java.lang.Object object)
          Returns true if the provided object is an appropriate candidate for membership in a collection.
 boolean isEmpty()
          Returns true if the controller's collection of controllable objects is empty.
 boolean isWholespace()
          Returns the current setting of the wholespace flag.
 java.util.Enumeration members()
          Returns an enumeration of all members of this controller.
 void mouseDragged(QTMouseEvent e)
          If the QTMouseController has a MouseMoveListener(s) it will dispatch drag events that occur within its Space's area to those listeners.
 void mouseEntered(QTMouseEvent e)
          If the QTMouseController has a MouseEnterExitListener(s) it will dispatch a mouseEntered event when the mouse moves or is dragged into the space.
 void mouseExited(QTMouseEvent e)
          If the QTMouseController has a MouseEnterExitListener(s) it will dispatch a mouseExited event when the mouse moves or is dragged out of the space.
 void mouseReleased(QTMouseEvent e)
          If the QTMouseController has a MouseButtonListener(s) it will dispatch release events that occur within its Space's area to those listeners.
protected  void removeActiveHandler()
          This method is called when a controller is removed from its space and it had an active event handler
 void removeMember(java.lang.Object member)
          Removes a member from the collection of objects that the controller controls
 void removeQTMouseListener(QTMouseListener l)
          Remove a QTMouseListener for this controller.
 void setWholespace(boolean flag)
          Sets the new value of the wholespace flag.
 int size()
          Returns the number of members that have been explicitly added to the Controller.
 
Methods inherited from class quicktime.app.event.QTMouseController
addedTo, doMouseReleased, getSpace, mouseClicked, mouseMoved, mousePressed, removedFrom, removedFromSpace, translateAndIsWithin
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

QTMouseTargetController

public QTMouseTargetController()
Creates a QTMouseTargetController with a default setting of wholespace equals true.

QTMouseTargetController

public QTMouseTargetController(boolean wholespace)
Creates a QTMouseTargetController.
Parameters:
wholespace - the initial setting of the wholespace variable.
Method Detail

addedToSpace

public void addedToSpace(Space s)
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.

This method will also ensure that any members of the controller are both appropriate objects for the space and are also members of the space.

Overrides:
addedToSpace in class QTMouseController
Parameters:
s - the Space being added to
See Also:
setTargetSpace()

removeActiveHandler

protected void removeActiveHandler()
This method is called when a controller is removed from its space and it had an active event handler
Overrides:
removeActiveHandler in class QTMouseController

addHandler

protected void addHandler()
This method is called when a controller is added to its space and the controller needs to create its event handler
Overrides:
addHandler in class QTMouseController

isWholespace

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

setWholespace

public void setWholespace(boolean flag)
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)
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.
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)
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. This method will also return true if the Controller has not been addedTo a space, in which case when it is the appropriate test will be performed.

removeMember

public void removeMember(java.lang.Object member)
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()
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()
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()
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)
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

addQTMouseListener

public void addQTMouseListener(QTMouseListener l)
Add a QTMouseListener for this controller. The controller will take the appropriate action based on the known mouse listeners in the quicktime.app.event package.
Overrides:
addQTMouseListener in class QTMouseController
Parameters:
l - a new QTMouseListener

removeQTMouseListener

public void removeQTMouseListener(QTMouseListener l)
Remove a QTMouseListener for this controller.
Overrides:
removeQTMouseListener in class QTMouseController
Parameters:
l - a new QTMouseListener

doMousePressed

protected void doMousePressed(QTMouseEvent e)
This method dispatches the event to the appropriate listeners. Subclasses can overide this method to do any particular processing that is required for this type of mouse event.
Overrides:
doMousePressed in class QTMouseController
Parameters:
e - the translated mouse event

mouseReleased

public void mouseReleased(QTMouseEvent e)
If the QTMouseController has a MouseButtonListener(s) it will dispatch release events that occur within its Space's area to those listeners.
Overrides:
mouseReleased in class QTMouseController
Parameters:
e - the QTMouseEvent of this type.

doMouseReleased

protected void doMouseReleased(QTMouseEvent e,
                               boolean isWithin)
This method dispatches the event to the appropriate listeners. Subclasses can overide this method to do any particular processing that is required for this type of mouse event.
Parameters:
e - the translated mouse event

doMouseClicked

protected void doMouseClicked(QTMouseEvent e)
This method dispatches the event to the appropriate listeners. Subclasses can overide this method to do any particular processing that is required for this type of mouse event.
Overrides:
doMouseClicked in class QTMouseController
Parameters:
e - the translated mouse event

mouseDragged

public void mouseDragged(QTMouseEvent e)
If the QTMouseController has a MouseMoveListener(s) it will dispatch drag events that occur within its Space's area to those listeners. Mouse drag events will continue to be delivered to the controller and its listeners where the press occured and until the mouse button is released (regardless of whether the mouse is within the space or not).
Overrides:
mouseDragged in class QTMouseController
Parameters:
e - the QTMouseEvent of this type.

doMouseDragged

protected void doMouseDragged(QTMouseEvent e)
This method dispatches the event to the appropriate listeners. Subclasses can overide this method to do any particular processing that is required for this type of mouse event.
Overrides:
doMouseDragged in class QTMouseController
Parameters:
e - the translated mouse event

doMouseTargetExit

protected void doMouseTargetExit(QTMouseEvent e)
This method dispatches the event to the appropriate listeners. Subclasses can overide this method to do any particular processing that is required for this type of mouse event.
Parameters:
e - the translated mouse event

doMouseTargetEnter

protected void doMouseTargetEnter(QTMouseEvent e)
This method dispatches the event to the appropriate listeners. Subclasses can overide this method to do any particular processing that is required for this type of mouse event.
Parameters:
e - the translated mouse event

doMouseMoved

protected void doMouseMoved(QTMouseEvent e,
                            boolean isWithinItsSpace)
This method dispatches the event to the appropriate listeners. Subclasses can overide this method to do any particular processing that is required for this type of mouse event.
Overrides:
doMouseMoved in class QTMouseController
Parameters:
e - the translated mouse event
isWithinItsSpace - if true the mouse moved event is within the enclosing space. If false it isn't.

mouseEntered

public void mouseEntered(QTMouseEvent e)
If the QTMouseController has a MouseEnterExitListener(s) it will dispatch a mouseEntered event when the mouse moves or is dragged into the space.
Overrides:
mouseEntered in class QTMouseController
Parameters:
e - the QTMouseEvent of this type.

doMouseEntered

protected void doMouseEntered(QTMouseEvent e)
This method dispatches the event to the appropriate listeners. Subclasses can overide this method to do any particular processing that is required for this type of mouse event.
Overrides:
doMouseEntered in class QTMouseController
Parameters:
e - the translated mouse event

mouseExited

public void mouseExited(QTMouseEvent e)
If the QTMouseController has a MouseEnterExitListener(s) it will dispatch a mouseExited event when the mouse moves or is dragged out of the space.
Overrides:
mouseExited in class QTMouseController
Parameters:
e - the QTMouseEvent of this type.

doMouseExited

protected void doMouseExited(QTMouseEvent e)
This method dispatches the event to the appropriate listeners. Subclasses can overide this method to do any particular processing that is required for this type of mouse event.
Overrides:
doMouseExited in class QTMouseController
Parameters:
e - the translated mouse event

getHitTarget

protected java.lang.Object getHitTarget(int x,
                                        int y)
Returns the frontmost object at the specified location that is a member of the space if wholespace is true, or the frontmost object in the controller's collection if wholespace is false.
Parameters:
x - the x location in the local coordinates of the space.
y - the y location in the local coordinates of the space.