org.jdesktop.wonderland.client.input
Class InputManager

java.lang.Object
  extended by org.jdesktop.wonderland.client.input.InputManager
All Implemented Interfaces:
java.awt.dnd.DropTargetListener, java.awt.event.FocusListener, java.awt.event.KeyListener, java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.MouseWheelListener, java.util.EventListener
Direct Known Subclasses:
InputManager3D

public abstract class InputManager
extends java.lang.Object
implements java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.MouseWheelListener, java.awt.event.KeyListener, java.awt.event.FocusListener, java.awt.dnd.DropTargetListener

A singleton container for all of the processor objects in the Wonderland input subsystem.

The InputManager supports event listener (EventListener) objects. These listeners can be added to entities in the world in order to allow these entities to respond to events. These events can be generated as a result of user input or can be programmatically generated by other parts of the client.

The InputManager also supports a set of global event listeners. These are independent of any entities. The system always delivers all events to global event listeners which are willing to consume these events. Note: the return value of propagateToParent() for global listeners is ignored. Note: The pickDetails field of an event is null for events received by the global listeners.

In Wonderland Release 0.4, the Wonderland client provided the notion of an "event mode." The event mode could be either App or World. When the event mode was App, only event listeners which controlled the shared apps were to consume events. When the event mode was World, only event listeners which controlled the non-app parts of the scene (aka "world") were to consume events. This essentially provided a single focus for all input events, which had a binary value. The new Wonderland InputManager provides a more general model of focus.

The InputManager provides "focus sets" for different classes of events. Each distinct event class can have its own focus set. A focus set is a set of one or more entities that have focus for that class of event. For example, the KeyEvent3D class can have a focus set consisting of Entity1 and the MouseEvent3D class can have a focus set consisting of Entity2 and Entity3. Unlike Wonderland Release 0.4, each event class can have a different set of focussed entities. Notice also that there can be multiple focussed entities instead of just one. When an entity is handed to an event listener via an event listener method such as, consumesEvent etc., that method can determine the entity to which the event was distributed by calling Event.getEntity(). The method can determine if the entity has focus by calling Event.isFocussed(). (Note that isFocussed returns whether the entity had focus at the time the event was delivered to the listener).

Note that the concept of focus in this input system is merely advisory. Event listeners can be programmed to use the isFocussed flag or ignore it. For example, a shared app event listener could be written to ignore events when the entity of the shared app does not have focus. Or, a 3D "xeyes" type of app could be written to accept all mouse motion events, regardless of whether their entity has focus, and change the gaze of the eyes to follow the mouse pointer's location no matter where it moves on the screen.

It is intended that the Wonderland client provide one or more focus managers which change the focussed entities based on user input or some other stimuli. These focus managers will be the responsible for implementing the focus management policy--the InputManager merely provides the mechanism. The goal is to allow multiple and different focus managers to be experimented with over time.

Author:
deronj

Nested Class Summary
 class InputManager.FocusChange
          An object which indicates how to modify the focus set.
static class InputManager.FocusChangeAction
          The ways that a focus set can be changed.
static class InputManager.NondeliverableMouseEvent
          TODO: later: use for injecting a non-deliverable mouse event in order to implement programmatic (non-user-generated) enter/exit events.
static class InputManager.PickEventReturn
          The return type for pickMouseEventSwing.
static class InputManager.WindowSwingEventConsumer
          An entity component which allows us to figure out whether a WindowSwing should consume events.
static class InputManager.WindowSwingViewMarker
          An entity component which allows us to identify a pick hit entity as a view of a WindowSwing.
 
Field Summary
protected  java.awt.Canvas canvas
          The canvas from which this input manager should receive events.
protected  EventDistributor eventDistributor
          The singleton event distributor.
protected  org.jdesktop.mtgame.Entity globalFocusEntity
          The global focus wildcard entity
protected static InputManager inputManager
          The singleton input manager
protected  InputPicker inputPicker
          The singleton input picker.
 
Constructor Summary
protected InputManager()
          Create a new instance of InputManager.
 
Method Summary
 void addEventListener(EventListener listener, org.jdesktop.mtgame.Entity entity)
          Add an event listener to the specified entity
 void addFocus(java.lang.Class[] eventClasses, org.jdesktop.mtgame.Entity[] entities)
          A utility method.
 void addGlobalEventListener(EventListener listener)
          Register a global event listener with the input manager.
 void addKeyMouseFocus(org.jdesktop.mtgame.Entity entity)
          A utility method.
 void addKeyMouseFocus(org.jdesktop.mtgame.Entity[] entities)
          A utility method.
 void changeFocus(InputManager.FocusChange[] changes)
          The base changeFocus method.
 void dragEnter(java.awt.dnd.DropTargetDragEvent e)
          INTERNAL ONLY
 void dragExit(java.awt.dnd.DropTargetEvent e)
          INTERNAL ONLY
 void dragOver(java.awt.dnd.DropTargetDragEvent e)
          INTERNAL ONLY
 void drop(java.awt.dnd.DropTargetDropEvent e)
          INTERNAL ONLY
 void dropActionChanged(java.awt.dnd.DropTargetDragEvent e)
          INTERNAL ONLY
static void ensureKeyFocusInMainWindow()
          Make sure that the Wonderland client main (3D) window has key focus.
static boolean entityHasFocus(Event event, org.jdesktop.mtgame.Entity entity)
          Returns true if the given entity is marked as having focus.
static boolean entityHasFocus(java.util.EventObject event, org.jdesktop.mtgame.Entity entity)
          Returns true if the given entity is marked as having focus.
 void focusGained(java.awt.event.FocusEvent e)
          INTERNAL ONLY
 void focusLost(java.awt.event.FocusEvent e)
          INTERNAL ONLY
 org.jdesktop.mtgame.CameraComponent getCameraComponent()
          Returns the camera component that is used for picking.
 org.jdesktop.mtgame.Entity getGlobalFocusEntity()
          Returns the global focus entity.
 void initialize(java.awt.Canvas canvas)
          Initialize the input manager to receive input events from the given AWT canvas and start the input manager running.
 void initialize(java.awt.Canvas canvas, org.jdesktop.mtgame.CameraComponent cameraComp)
          Initialize the input manager to receive input events from the given AWT canvas and start the input manager running.
static InputManager inputManager()
          Return the input manager singleton.
 void keyPressed(java.awt.event.KeyEvent e)
          INTERNAL ONLY
 void keyReleased(java.awt.event.KeyEvent e)
          INTERNAL ONLY
 void keyTyped(java.awt.event.KeyEvent e)
          INTERNAL ONLY
 void mouseClicked(java.awt.event.MouseEvent e)
          INTERNAL ONLY
 void mouseDragged(java.awt.event.MouseEvent e)
          INTERNAL ONLY
 void mouseEntered(java.awt.event.MouseEvent e)
          INTERNAL ONLY
 void mouseExited(java.awt.event.MouseEvent e)
          INTERNAL ONLY
 void mouseMoved(java.awt.event.MouseEvent e)
          INTERNAL ONLY
 void mousePressed(java.awt.event.MouseEvent e)
          INTERNAL ONLY
 void mouseReleased(java.awt.event.MouseEvent e)
          INTERNAL ONLY
 void mouseWheelMoved(java.awt.event.MouseWheelEvent e)
          INTERNAL ONLY
 org.jdesktop.mtgame.PickInfo pick(int x, int y)
          Perform a pick using a ray which extends from the eye position through the given screen point.
 InputManager.PickEventReturn pickMouseEventSwing(java.awt.event.MouseEvent awtMouseEvent)
          FOR USE BY APP BASE ONLY.
 com.jme.math.Ray pickRayWorld(int x, int y)
          Calculate a pick ray from the current eye position into the given point in screen coordinates.
 void postEvent(Event event)
          Inject an event into the input system.
 void postEvent(Event event, org.jdesktop.mtgame.Entity entity)
          Inject an event, with an associated entity into the system
 void removeEventListener(EventListener listener, org.jdesktop.mtgame.Entity entity)
          Remove an event listener from the specified entity
 void removeFocus(java.lang.Class[] eventClasses, org.jdesktop.mtgame.Entity[] entities)
          A utility method.
 void removeGlobalEventListener(EventListener listener)
          Remove this global event listener.
 void removeKeyMouseFocus(org.jdesktop.mtgame.Entity entity)
          A utility method.
 void removeKeyMouseFocus(org.jdesktop.mtgame.Entity[] entities)
          A utility method.
 void replaceFocus(java.lang.Class[] eventClasses, org.jdesktop.mtgame.Entity[] entities)
          A utility method.
 void replaceKeyMouseFocus(org.jdesktop.mtgame.Entity entity)
          A utility method.
 void replaceKeyMouseFocus(org.jdesktop.mtgame.Entity[] entities)
          A utility method.
 void setCameraComponent(org.jdesktop.mtgame.CameraComponent cameraComp)
          Specify the camera component to be used for picking.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

inputManager

protected static InputManager inputManager
The singleton input manager


inputPicker

protected InputPicker inputPicker
The singleton input picker. (Used only in non-embedded swing case).


eventDistributor

protected EventDistributor eventDistributor
The singleton event distributor.


canvas

protected java.awt.Canvas canvas
The canvas from which this input manager should receive events.


globalFocusEntity

protected org.jdesktop.mtgame.Entity globalFocusEntity
The global focus wildcard entity

Constructor Detail

InputManager

protected InputManager()
Create a new instance of InputManager.

Method Detail

inputManager

public static InputManager inputManager()
Return the input manager singleton.
INTERNAL ONLY.


initialize

public void initialize(java.awt.Canvas canvas)
Initialize the input manager to receive input events from the given AWT canvas and start the input manager running. This method does not define a camera component, so picking on events will not start occuring until a camera component is specified with a subsequent call to setCameraComponent.

Parameters:
canvas - The AWT canvas which generates AWT user events.

initialize

public void initialize(java.awt.Canvas canvas,
                       org.jdesktop.mtgame.CameraComponent cameraComp)
Initialize the input manager to receive input events from the given AWT canvas and start the input manager running. The input manager will perform picks with the given camera. This routine can only be called once. To subsequently change the camera, use setCameraComponent. To subsequently change the focus manager, use setFocusManager.

Parameters:
canvas - The AWT canvas which generates AWT user events.
cameraComp - The mtgame camera component to use for picking operations.

getGlobalFocusEntity

public org.jdesktop.mtgame.Entity getGlobalFocusEntity()
Returns the global focus entity.


mouseClicked

public void mouseClicked(java.awt.event.MouseEvent e)
INTERNAL ONLY

Specified by:
mouseClicked in interface java.awt.event.MouseListener

mouseEntered

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

Specified by:
mouseEntered in interface java.awt.event.MouseListener

mouseExited

public void mouseExited(java.awt.event.MouseEvent e)
INTERNAL ONLY

Specified by:
mouseExited in interface java.awt.event.MouseListener

mousePressed

public void mousePressed(java.awt.event.MouseEvent e)
INTERNAL ONLY

Specified by:
mousePressed in interface java.awt.event.MouseListener

mouseReleased

public void mouseReleased(java.awt.event.MouseEvent e)
INTERNAL ONLY

Specified by:
mouseReleased in interface java.awt.event.MouseListener

mouseDragged

public void mouseDragged(java.awt.event.MouseEvent e)
INTERNAL ONLY

Specified by:
mouseDragged in interface java.awt.event.MouseMotionListener

mouseMoved

public void mouseMoved(java.awt.event.MouseEvent e)
INTERNAL ONLY

Specified by:
mouseMoved in interface java.awt.event.MouseMotionListener

mouseWheelMoved

public void mouseWheelMoved(java.awt.event.MouseWheelEvent e)
INTERNAL ONLY

Specified by:
mouseWheelMoved in interface java.awt.event.MouseWheelListener

keyPressed

public void keyPressed(java.awt.event.KeyEvent e)
INTERNAL ONLY

Specified by:
keyPressed in interface java.awt.event.KeyListener

keyReleased

public void keyReleased(java.awt.event.KeyEvent e)
INTERNAL ONLY

Specified by:
keyReleased in interface java.awt.event.KeyListener

keyTyped

public void keyTyped(java.awt.event.KeyEvent e)
INTERNAL ONLY

Specified by:
keyTyped in interface java.awt.event.KeyListener

focusGained

public void focusGained(java.awt.event.FocusEvent e)
INTERNAL ONLY

Specified by:
focusGained in interface java.awt.event.FocusListener

focusLost

public void focusLost(java.awt.event.FocusEvent e)
INTERNAL ONLY

Specified by:
focusLost in interface java.awt.event.FocusListener

dragEnter

public void dragEnter(java.awt.dnd.DropTargetDragEvent e)
INTERNAL ONLY

Specified by:
dragEnter in interface java.awt.dnd.DropTargetListener

dragExit

public void dragExit(java.awt.dnd.DropTargetEvent e)
INTERNAL ONLY

Specified by:
dragExit in interface java.awt.dnd.DropTargetListener

dragOver

public void dragOver(java.awt.dnd.DropTargetDragEvent e)
INTERNAL ONLY

Specified by:
dragOver in interface java.awt.dnd.DropTargetListener

drop

public void drop(java.awt.dnd.DropTargetDropEvent e)
INTERNAL ONLY

Specified by:
drop in interface java.awt.dnd.DropTargetListener

dropActionChanged

public void dropActionChanged(java.awt.dnd.DropTargetDragEvent e)
INTERNAL ONLY

Specified by:
dropActionChanged in interface java.awt.dnd.DropTargetListener

ensureKeyFocusInMainWindow

public static void ensureKeyFocusInMainWindow()
Make sure that the Wonderland client main (3D) window has key focus.


addGlobalEventListener

public void addGlobalEventListener(EventListener listener)
Register a global event listener with the input manager. If the listener has already been registered this action is a no-op. The input manager attempts to distribute newly arriving events to all registered global listeners. It calls the consumesEvent method of the listener. If this returns true then the computeEvent and commitEvent of the listener are called. Note: It is not a good idea to call addGlobalEventListener from inside the EventListener.computeEvent method. However, it is okay to call this from inside EventListener. commitEvent method if necessary.

Parameters:
listener - The global event listener to be added.

removeGlobalEventListener

public void removeGlobalEventListener(EventListener listener)
Remove this global event listener. Note: It is not a good idea to call this from inside EventListener.computeEvent function. However, it is okay to call this from inside EventListener.commitEvent function if necessary.

Parameters:
listener - The entity to which to attach this event listener.

addEventListener

public void addEventListener(EventListener listener,
                             org.jdesktop.mtgame.Entity entity)
Add an event listener to the specified entity

Parameters:
listener -
entity -

removeEventListener

public void removeEventListener(EventListener listener,
                                org.jdesktop.mtgame.Entity entity)
Remove an event listener from the specified entity

Parameters:
listener -
entity -

setCameraComponent

public void setCameraComponent(org.jdesktop.mtgame.CameraComponent cameraComp)
Specify the camera component to be used for picking.

Parameters:
cameraComp - The mtgame camera component to use for picking operations.

getCameraComponent

public org.jdesktop.mtgame.CameraComponent getCameraComponent()
Returns the camera component that is used for picking.


changeFocus

public void changeFocus(InputManager.FocusChange[] changes)
The base changeFocus method. Atomically changes the focus sets. The other focus utility methods call this method. This method is for use by the Wonderland client focus manager.

Parameters:
changes - An array of the changes to make to the focus sets.

addFocus

public void addFocus(java.lang.Class[] eventClasses,
                     org.jdesktop.mtgame.Entity[] entities)
A utility method. Atomically add the given entities to the focus sets of the given event classes. This method is for use by the Wonderland client focus manager.

Parameters:
eventClasses - The event classes whose focus sets are to be modified.
entities - The entities to add to the focus sets.
Throws:
java.lang.IllegalArgumentException - If any class in eventClasses are not the Wonderland base event class or one of its subclasses.

removeFocus

public void removeFocus(java.lang.Class[] eventClasses,
                        org.jdesktop.mtgame.Entity[] entities)
A utility method. Atomically remove the given entities from the focus sets of the given event classes. This method is for use by the Wonderland client focus manager.

Parameters:
eventClasses - The event classes whose focus sets are to be modified.
entities - The entities to add to the focus sets.
Throws:
java.lang.IllegalArgumentException - If any class in eventClasses are not the Wonderland base event class or one of its subclasses.

replaceFocus

public void replaceFocus(java.lang.Class[] eventClasses,
                         org.jdesktop.mtgame.Entity[] entities)
A utility method. Atomically replace the focus sets of the given event classes with the given entities. This method is for use by the Wonderland client focus manager.

Parameters:
eventClasses - The event classes whose focus sets are to be modified.
entities - The entities to add to the focus sets.
Throws:
java.lang.IllegalArgumentException - If any class in eventClasses are not the Wonderland base event class or one of its subclasses.

addKeyMouseFocus

public void addKeyMouseFocus(org.jdesktop.mtgame.Entity[] entities)
A utility method. Atomically add the given entities to the focus sets of the KeyEvent3D and MouseEvent3D event classes. This method is for use by the Wonderland client focus manager.

Parameters:
entities - The entities to add to the focus sets.

removeKeyMouseFocus

public void removeKeyMouseFocus(org.jdesktop.mtgame.Entity[] entities)
A utility method. Atomically remove the given entities from the focus sets of the KeyEvent3D and MouseEvent3D event classes. This method is for use by the Wonderland client focus manager.

Parameters:
entities - The entities to add to the focus sets.

replaceKeyMouseFocus

public void replaceKeyMouseFocus(org.jdesktop.mtgame.Entity[] entities)
A utility method. Atomically replace the focus sets of the KeyEvent3D and MouseEvent3D event classes with the given entities. This method is for use by the Wonderland client focus manager.

Parameters:
entities - The entities to add to the focus sets.

addKeyMouseFocus

public void addKeyMouseFocus(org.jdesktop.mtgame.Entity entity)
A utility method. Atomically add the given entity to the focus sets of the KeyEvent3D and MouseEvent3D event classes. This method is for use by the Wonderland client focus manager.

Parameters:
entity - The entity to add to the focus sets.

removeKeyMouseFocus

public void removeKeyMouseFocus(org.jdesktop.mtgame.Entity entity)
A utility method. Atomically remove the given entity from the focus sets of the KeyEvent3D and MouseEvent3D event classes. This method is for use by the Wonderland client focus manager.

Parameters:
entity - The entity to add to the focus sets.

replaceKeyMouseFocus

public void replaceKeyMouseFocus(org.jdesktop.mtgame.Entity entity)
A utility method. Atomically replace the focus sets of the KeyEvent3D and MouseEvent3D event classes with the given entity. This method is for use by the Wonderland client focus manager.

Parameters:
entity - The entity to add to the focus sets.

entityHasFocus

public static boolean entityHasFocus(Event event,
                                     org.jdesktop.mtgame.Entity entity)
Returns true if the given entity is marked as having focus.

Parameters:
event - The event to be delivered.
entity - The entity to check if it is in the focus set.

entityHasFocus

public static boolean entityHasFocus(java.util.EventObject event,
                                     org.jdesktop.mtgame.Entity entity)
Returns true if the given entity is marked as having focus.

Parameters:
event - The event to be delivered.
entity - The entity to check if it is in the focus set.

postEvent

public void postEvent(Event event)
Inject an event into the input system. The event doesn't have an associated entity. Therefore it will only be distributed to the global event listeners. NOTE: make sure that the class of the argument event implements clone.

Parameters:
event - The event to be distributed to enabled global event listeners.

postEvent

public void postEvent(Event event,
                      org.jdesktop.mtgame.Entity entity)
Inject an event, with an associated entity into the system

Parameters:
event -
entity -

pickMouseEventSwing

public InputManager.PickEventReturn pickMouseEventSwing(java.awt.event.MouseEvent awtMouseEvent)
FOR USE BY APP BASE ONLY.

Picker for mouse events for the Embedded Swing case. To be called by theEmbedded Swing toolkit createCoordinateHandler.

Returns non-null if window is a WindowSwing. If it is a WindowSwing then return the appropriate hit entity and the corresponding pick info.

Parameters:
awtEvent - The event whose entity and pickInfo need to be picked.
Returns:
An object of class PickEventReturn, which contains the return values entity and pickDetails.

pickRayWorld

public com.jme.math.Ray pickRayWorld(int x,
                                     int y)
Calculate a pick ray from the current eye position into the given point in screen coordinates.


pick

public org.jdesktop.mtgame.PickInfo pick(int x,
                                         int y)
Perform a pick using a ray which extends from the eye position through the given screen point. point in screen coordinates.



Open Wonderland - http://openwonderland.org