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. since QTJava 6.1

Method Summary

void	addedTo(java.lang.Object interest) Deprecated. since QTJava 6.1
void	addedToSpace(Space s) Deprecated. since QTJava 6.1
boolean	addMember(java.lang.Object member) Deprecated. since QTJava 6.1
protected void	deactivateResponder() Deprecated. since QTJava 6.1
protected void	doDragTarget(java.awt.event.MouseEvent e) Deprecated.
protected MouseResponder	getResponder() Deprecated. since QTJava 6.1
protected abstract java.lang.Object	getSelected(java.awt.event.MouseEvent event) Deprecated. since QTJava 6.1
abstract Space	getSpace() Deprecated. since QTJava 6.1
boolean	hasMember(java.lang.Object object) Deprecated. since QTJava 6.1
boolean	isAppropriate(java.lang.Object object) Deprecated. since QTJava 6.1
boolean	isEmpty() Deprecated. since QTJava 6.1
boolean	isWholespace() Deprecated. since QTJava 6.1
java.util.Enumeration	members() Deprecated. since QTJava 6.1
void	mouseClicked(java.awt.event.MouseEvent e) Deprecated. since QTJava 6.1
void	mouseDragged(java.awt.event.MouseEvent e) Deprecated. since QTJava 6.1
void	mouseEntered(java.awt.event.MouseEvent e) Deprecated. since QTJava 6.1
void	mouseExited(java.awt.event.MouseEvent e) Deprecated. since QTJava 6.1
void	mouseMoved(java.awt.event.MouseEvent e) Deprecated. since QTJava 6.1
void	mousePressed(java.awt.event.MouseEvent e) Deprecated. since QTJava 6.1
void	mouseReleased(java.awt.event.MouseEvent e) Deprecated. since QTJava 6.1
void	removedFrom(java.lang.Object interest) Deprecated. since QTJava 6.1
void	removedFromSpace() Deprecated. since QTJava 6.1
void	removeMember(java.lang.Object member) Deprecated. since QTJava 6.1
protected void	responderActivated() Deprecated. since QTJava 6.1
protected abstract void	setTargetSpace(Space s) Deprecated. since QTJava 6.1
protected void	setTranslation() Deprecated. since QTJava 6.1
void	setWholespace(boolean flag) Deprecated. since QTJava 6.1
int	size() Deprecated. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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

Returns:

the current space.

addedToSpace

public final void addedToSpace(Space s)

Deprecated. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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

Returns:

a MouseResponder

setTargetSpace

protected abstract void setTargetSpace(Space s)

Deprecated. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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

QTException

isWholespace

public boolean isWholespace()

Deprecated. since QTJava 6.1

Returns the current setting of the wholespace flag.

Returns:

a boolean

setWholespace

public void setWholespace(boolean flag)

Deprecated. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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

See Also:

DynamicCollection, Protocol

removeMember

public void removeMember(java.lang.Object member)

Deprecated. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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

Parameters:

object - the object to test for membership

Returns:

a boolean

mouseEntered

public void mouseEntered(java.awt.event.MouseEvent e)

Deprecated. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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. since QTJava 6.1

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