com.jme3.input
Class InputManager

java.lang.Object
  extended by com.jme3.input.InputManager
All Implemented Interfaces:
RawInputListener

public class InputManager
extends java.lang.Object
implements RawInputListener

The InputManager is responsible for converting input events received from the Key, Mouse and Joy Input implementations into an abstract, input device independent representation that user code can use.

By default an InputManager is included with every Application instance for use in user code to query input, unless the Application is created as headless or with input explicitly disabled.

The input manager has two concepts, a Trigger and a mapping. A trigger represents a specific input trigger, such as a key button, or a mouse axis. A mapping represents a link onto one or several triggers, when the appropriate trigger is activated (e.g. a key is pressed), the mapping will be invoked. Any listeners registered to receive an event from the mapping will have an event raised.

There are two types of events that input listeners can receive, one is action events and another is analog events.

onAction events are raised when the specific input activates or deactivates. For a digital input such as key press, the onAction() event will be raised with the isPressed argument equal to true, when the key is released, onAction is called again but this time with the isPressed argument set to false. For analog inputs, the onAction method will be called any time the input is non-zero, however an exception to this is for joystick axis inputs, which are only called when the input is above the dead zone.

onAnalog events are raised every frame while the input is activated. For digital inputs, every frame that the input is active will cause the onAnalog method to be called, the argument value argument will equal to the frame's time per frame (TPF) value but only for digital inputs. For analog inputs however, the value argument will equal the actual analog value.


Constructor Summary
InputManager(MouseInput mouse, KeyInput keys, JoyInput joystick, TouchInput touch)
          Initializes the InputManager.
 
Method Summary
 void addListener(InputListener listener, java.lang.String... mappingNames)
          Adds a new listener to receive events on the given mappings.
 void addMapping(java.lang.String mappingName, Trigger... triggers)
          Create a new mapping to the given triggers.
 void addRawInputListener(RawInputListener listener)
          Adds a RawInputListener to receive raw input events.
 void beginInput()
          Callback from RawInputListener.
 void clearMappings()
          Clears all the input mappings from this InputManager.
 void clearRawInputListeners()
          Clears all RawInputListeners.
 void deleteMapping(java.lang.String mappingName)
          Deletes a mapping from receiving trigger events.
 void deleteTrigger(java.lang.String mappingName, Trigger trigger)
          Deletes a specific trigger registered to a mapping.
 void endInput()
          Callback from RawInputListener.
 float getAxisDeadZone()
          Returns the deadzone for joystick axes.
 Vector2f getCursorPosition()
          Returns the current cursor position.
 Joystick[] getJoysticks()
          Returns an array of all joysticks installed on the system.
 boolean getSimulateMouse()
          Returns state of simulation of mouse events.
 boolean hasMapping(java.lang.String mappingName)
          Returns true if this InputManager has a mapping registered for the given mappingName.
 boolean isCursorVisible()
          Returns whether the mouse cursor is visible or not.
 void onJoyAxisEvent(JoyAxisEvent evt)
          Callback from RawInputListener.
 void onJoyButtonEvent(JoyButtonEvent evt)
          Callback from RawInputListener.
 void onKeyEvent(KeyInputEvent evt)
          Callback from RawInputListener.
 void onMouseButtonEvent(MouseButtonEvent evt)
          Callback from RawInputListener.
 void onMouseMotionEvent(MouseMotionEvent evt)
          Callback from RawInputListener.
 void onTouchEvent(TouchEvent evt)
          Callback from RawInputListener.
 void onTouchEventQueued(TouchEvent evt)
          Dispatches touch events to touch listeners
 void removeListener(InputListener listener)
          Removes a listener from receiving events.
 void removeRawInputListener(RawInputListener listener)
          Removes a RawInputListener so that it no longer receives raw input events.
 void reset()
          Do not use.
 void setAxisDeadZone(float deadZone)
          Set the deadzone for joystick axes.
 void setCursorVisible(boolean visible)
          Set whether the mouse cursor should be visible or not.
 void setMouseCursor(JmeCursor jmeCursor)
           
 void setSimulateKeyboard(boolean value)
          Enable simulation of keyboard events.
 void setSimulateMouse(boolean value)
          Enable simulation of mouse events.
 void update(float tpf)
          Updates the InputManager.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

InputManager

public InputManager(MouseInput mouse,
                    KeyInput keys,
                    JoyInput joystick,
                    TouchInput touch)
Initializes the InputManager.

This should only be called internally in Application.

Parameters:
mouse -
keys -
joystick -
touch -
Throws:
java.lang.IllegalArgumentException - If either mouseInput or keyInput are null.
Method Detail

beginInput

public void beginInput()
Callback from RawInputListener. Do not use.

Specified by:
beginInput in interface RawInputListener

endInput

public void endInput()
Callback from RawInputListener. Do not use.

Specified by:
endInput in interface RawInputListener

onJoyAxisEvent

public void onJoyAxisEvent(JoyAxisEvent evt)
Callback from RawInputListener. Do not use.

Specified by:
onJoyAxisEvent in interface RawInputListener

onJoyButtonEvent

public void onJoyButtonEvent(JoyButtonEvent evt)
Callback from RawInputListener. Do not use.

Specified by:
onJoyButtonEvent in interface RawInputListener

setMouseCursor

public void setMouseCursor(JmeCursor jmeCursor)

onMouseMotionEvent

public void onMouseMotionEvent(MouseMotionEvent evt)
Callback from RawInputListener. Do not use.

Specified by:
onMouseMotionEvent in interface RawInputListener

onMouseButtonEvent

public void onMouseButtonEvent(MouseButtonEvent evt)
Callback from RawInputListener. Do not use.

Specified by:
onMouseButtonEvent in interface RawInputListener

onKeyEvent

public void onKeyEvent(KeyInputEvent evt)
Callback from RawInputListener. Do not use.

Specified by:
onKeyEvent in interface RawInputListener

setAxisDeadZone

public void setAxisDeadZone(float deadZone)
Set the deadzone for joystick axes.

ActionListener.onAction(java.lang.String, boolean, float) events will only be raised if the joystick axis value is greater than the deadZone.

Parameters:
deadZone - the deadzone for joystick axes.

getAxisDeadZone

public float getAxisDeadZone()
Returns the deadzone for joystick axes.

Returns:
the deadzone for joystick axes.

addListener

public void addListener(InputListener listener,
                        java.lang.String... mappingNames)
Adds a new listener to receive events on the given mappings.

The given InputListener will be registered to receive events on the specified mapping names. When a mapping raises an event, the listener will have its appropriate method invoked, either ActionListener.onAction(java.lang.String, boolean, float) or AnalogListener.onAnalog(java.lang.String, float, float) depending on which interface the listener implements. If the listener implements both interfaces, then it will receive the appropriate event for each method.

Parameters:
listener - The listener to register to receive input events.
mappingNames - The mapping names which the listener will receive events from.
See Also:
removeListener(com.jme3.input.controls.InputListener)

removeListener

public void removeListener(InputListener listener)
Removes a listener from receiving events.

This will unregister the listener from any mappings that it was previously registered with via addListener(com.jme3.input.controls.InputListener, java.lang.String[]).

Parameters:
listener - The listener to unregister.
See Also:
addListener(com.jme3.input.controls.InputListener, java.lang.String[])

addMapping

public void addMapping(java.lang.String mappingName,
                       Trigger... triggers)
Create a new mapping to the given triggers.

The given mapping will be assigned to the given triggers, when any of the triggers given raise an event, the listeners registered to the mappings will receive appropriate events.

Parameters:
mappingName - The mapping name to assign.
triggers - The triggers to which the mapping is to be registered.
See Also:
deleteMapping(java.lang.String)

hasMapping

public boolean hasMapping(java.lang.String mappingName)
Returns true if this InputManager has a mapping registered for the given mappingName.

Parameters:
mappingName - The mapping name to check.
See Also:
addMapping(java.lang.String, com.jme3.input.controls.Trigger[]), deleteMapping(java.lang.String)

deleteMapping

public void deleteMapping(java.lang.String mappingName)
Deletes a mapping from receiving trigger events.

The given mapping will no longer be assigned to receive trigger events.

Parameters:
mappingName - The mapping name to unregister.
See Also:
addMapping(java.lang.String, com.jme3.input.controls.Trigger[])

deleteTrigger

public void deleteTrigger(java.lang.String mappingName,
                          Trigger trigger)
Deletes a specific trigger registered to a mapping.

The given mapping will no longer receive events raised by the trigger.

Parameters:
mappingName - The mapping name to cease receiving events from the trigger.
trigger - The trigger to no longer invoke events on the mapping.

clearMappings

public void clearMappings()
Clears all the input mappings from this InputManager. Consequently, also clears all of the InputListeners as well.


reset

public void reset()
Do not use. Called to reset pressed keys or buttons when focus is restored.


isCursorVisible

public boolean isCursorVisible()
Returns whether the mouse cursor is visible or not.

By default the cursor is visible.

Returns:
whether the mouse cursor is visible or not.
See Also:
setCursorVisible(boolean)

setCursorVisible

public void setCursorVisible(boolean visible)
Set whether the mouse cursor should be visible or not.

Parameters:
visible - whether the mouse cursor should be visible or not.

getCursorPosition

public Vector2f getCursorPosition()
Returns the current cursor position. The position is relative to the bottom-left of the screen and is in pixels.

Returns:
the current cursor position

getJoysticks

public Joystick[] getJoysticks()
Returns an array of all joysticks installed on the system.

Returns:
an array of all joysticks installed on the system.

addRawInputListener

public void addRawInputListener(RawInputListener listener)
Adds a RawInputListener to receive raw input events.

Any raw input listeners registered to this InputManager will receive raw input events first, before they get handled by the InputManager itself. The listeners are each processed in the order they were added, e.g. FIFO.

If a raw input listener has handled the event and does not wish other listeners down the list to process the event, it may set the consumed flag to indicate the event was consumed and shouldn't be processed any further. The listener may do this either at each of the event callbacks or at the RawInputListener.endInput() method.

Parameters:
listener - A listener to receive raw input events.
See Also:
RawInputListener

removeRawInputListener

public void removeRawInputListener(RawInputListener listener)
Removes a RawInputListener so that it no longer receives raw input events.

Parameters:
listener - The listener to cease receiving raw input events.
See Also:
addRawInputListener(com.jme3.input.RawInputListener)

clearRawInputListeners

public void clearRawInputListeners()
Clears all RawInputListeners.

See Also:
addRawInputListener(com.jme3.input.RawInputListener)

setSimulateMouse

public void setSimulateMouse(boolean value)
Enable simulation of mouse events. Used for touchscreen input only.

Parameters:
value - True to enable simulation of mouse events

getSimulateMouse

public boolean getSimulateMouse()
Returns state of simulation of mouse events. Used for touchscreen input only.


setSimulateKeyboard

public void setSimulateKeyboard(boolean value)
Enable simulation of keyboard events. Used for touchscreen input only.

Parameters:
value - True to enable simulation of keyboard events

update

public void update(float tpf)
Updates the InputManager. This will query current input devices and send appropriate events to registered listeners.

Parameters:
tpf - Time per frame value.

onTouchEventQueued

public void onTouchEventQueued(TouchEvent evt)
Dispatches touch events to touch listeners

Parameters:
evt - The touch event to be dispatched to all onTouch listeners

onTouchEvent

public void onTouchEvent(TouchEvent evt)
Callback from RawInputListener. Do not use.

Specified by:
onTouchEvent in interface RawInputListener