All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class quicktime.app.actions.MouseController

java.lang.Object
   |
   +----quicktime.app.actions.MouseController

public abstract class MouseController

extends Object

implements ListenerController, Collection, MouseListener, MouseMotionListener

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:

MouseResponder, SWController

xLocationOffset

yLocationOffset

MouseController(MouseResponder, boolean)

Creates a mouse controller with its responder.

addedTo(Object)

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.

addedToSpace(Space)

This method is called by the space when a Controller is being addedTo the Space s.

addMember(Object)

If wholespace is set to false, then only objects that are explicitly added to the controller will be controlled by it.

deactivateResponder()

A method that is called whenever the MouseController deactivates its responder.

doDragTarget(MouseEvent)

getResponder()

This method returns the MouseResponder that is attached to the MouseController.

getSelected(MouseEvent)

This method is called when a MouseController has received a mouse press, click, drag, event in its space.

getSpace()

This method returns the Space which the MouseController has been attached to.

hasMember(Object)

Returns true if the member has been explicitly added to this controller.

isAppropriate(Object)

Returns true if the provided object is an appropriate candidate for membership in a collection.

isEmpty()

Returns true if the controller's collection of controllable objects is empty.

isWholespace()

Returns the current setting of the wholespace flag.

members()

Returns an enumeration of all members of this controller.

mouseClicked(MouseEvent)

If the responder is interested in mouseClick events it will be activated when the user clicks.

mouseDragged(MouseEvent)

If the responder is interested in mouseDragged events it will be activated when the user drags the mouse within the display space.

mouseEntered(MouseEvent)

If the responder is interested in mouseEntered events it will be activated when the user's mouse enters the QTCanvas space.

mouseExited(MouseEvent)

If the responder is interested in mouseExited events it will be deactivated after the user's mouse exits the QTCanvas space.

mouseMoved(MouseEvent)

If the responder is interested in mouseMoved events it will be activated when the user's mouse moves within the display space.

mousePressed(MouseEvent)

If the responder is interested in mousePressed events it will be activated when the user presses the mouse within the display space.

mouseReleased(MouseEvent)

If the responder is interested in mouseReleased events it will be activated when the user releases the mouse within the display space.

removedFrom(Object)

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.

removedFromSpace()

Called by the Space when a Controller is being removed from a Space.

removeMember(Object)

Removes a member from the collection of objects that the controller controls

responderActivated()

A notification method that is called whenever the MouseController activates its responder.

setTargetSpace(Space)

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.

setTranslation()

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.

setWholespace(boolean)

Sets the new value of the wholespace flag.

size()

Returns the number of members that have been explicitly added to the Controller.

 protected int xLocationOffset

 protected int yLocationOffset

 protected MouseController(MouseResponder mr,
                           boolean wholespace)

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

 public abstract Space getSpace()

This method returns the Space which the MouseController has been attached to.

Returns:

the current space.

 public final 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.

Parameters:

s - the Space being added to

See Also:

setTargetSpace

 public void removedFromSpace()

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.

 protected MouseResponder getResponder()

This method returns the MouseResponder that is attached to the MouseController.

Returns:

a MouseResponder

 protected abstract void setTargetSpace(Space s)

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.

 public void addedTo(Object interest)

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.

Parameters:

interest - the object that is to be the source of interest for the the object that implements this interface.

 public void removedFrom(Object interest)

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.

Parameters:

interest - the object that was the source of interest for the the object that implements this interface.

 protected abstract Object getSelected(MouseEvent event) throws QTException

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

 public boolean isWholespace()

Returns the current setting of the wholespace flag.

Returns:

a boolean

 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.

 public boolean addMember(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. It the candidate is not an appropriate member for the controller to be controlled it will not be added and false is returned.

Parameters:

member - the new member object that will be controlled.

Returns:

a boolean indicating whether the object was added or not.

 public boolean isAppropriate(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.

Parameters:

object - the object to test

Returns:

true if the supplied object is appropriate for this collection, or false if not

 public void removeMember(Object member)

Removes a member from the collection of objects that the controller controls

Parameters:

member - the object that will be removed from the controller.

 public 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.

Returns:

an Enumeration

 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.

Returns:

a boolean

 public int size()

Returns the number of members that have been explicitly added to the Controller.

Returns:

an int

 public boolean hasMember(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.

 public void mouseEntered(MouseEvent e)

If the responder is interested in mouseEntered events it will be activated when the user's mouse enters the QTCanvas space.

Parameters:

e - the mouse event

 public void mouseExited(MouseEvent e)

If the responder is interested in mouseExited events it will be deactivated after the user's mouse exits the QTCanvas space.

Parameters:

e - the mouse event

 protected void setTranslation()

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.

 public void mousePressed(MouseEvent e)

If the responder is interested in mousePressed events it will be activated when the user presses the mouse within the display space.

Parameters:

e - the mouse event

 public void mouseReleased(MouseEvent e)

If the responder is interested in mouseReleased events it will be activated when the user releases the mouse within the display space.

Parameters:

e - the mouse event

 public void mouseClicked(MouseEvent e)

If the responder is interested in mouseClick events it will be activated when the user clicks.

Parameters:

e - the mouse event

 public void mouseMoved(MouseEvent e)

If the responder is interested in mouseMoved events it will be activated when the user's mouse moves within the display space.

Parameters:

e - the mouse event

 public void mouseDragged(MouseEvent e)

If the responder is interested in mouseDragged events it will be activated when the user drags the mouse within the display space.

Parameters:

e - the mouse event

 protected void doDragTarget(MouseEvent e)

 protected void deactivateResponder()

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.

 protected void responderActivated()

A notification method that is called whenever the MouseController activates its responder.

All Packages  Class Hierarchy  This Package  Previous  Next  Index