com.jme3.input

Class InputManager

java.lang.Object

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

Constructors

Constructor and Description
InputManager(MouseInput mouse, KeyInput keys, JoyInput joystick, TouchInput touch) Initializes the InputManager.

Method Summary

Modifier and Type	Method and Description
boolean	addJoystickConnectionListener(JoystickConnectionListener listener) Add a listener that reports when a joystick has been added or removed.
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	clearJoystickConnectionListeners() Remove all joystick connection listeners.
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.
void	fireJoystickConnectedEvent(Joystick joystick) Called when a joystick has been connected.
void	fireJoystickDisconnectedEvent(Joystick joystick) Called when a joystick has been disconnected.
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() Deprecated. Use isSimulateMouse Returns state of simulation of mouse events. Used for touchscreen input only.
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.
boolean	isSimulateKeyboard() Returns state of simulation of key events.
boolean	isSimulateMouse() Returns state of simulation of mouse events.
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
boolean	removeJoystickConnectionListener(JoystickConnectionListener listener) Remove an existing listener.
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	setJoysticks(Joystick[] joysticks) Re-sets the joystick list when a joystick is added or removed.
void	setMouseCursor(JmeCursor jmeCursor) Sets the mouse cursor image or animation.
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 - (not null, alias created)

keys - (not null, alias created)

joystick - (may be null, alias created)

touch - (may be null, alias created)

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

Parameters:

evt - information about the event

onJoyButtonEvent

public void onJoyButtonEvent(JoyButtonEvent evt)

Callback from RawInputListener. Do not use.

Specified by:

onJoyButtonEvent in interface RawInputListener

Parameters:

evt - information about the event

setMouseCursor

public void setMouseCursor(JmeCursor jmeCursor)

Sets the mouse cursor image or animation. Set cursor to null to show default system cursor. To hide the cursor completely, use setCursorVisible(boolean).

Parameters:

jmeCursor - The cursor to set, or null to reset to system cursor.

See Also:

JmeCursor

onMouseMotionEvent

public void onMouseMotionEvent(MouseMotionEvent evt)

Callback from RawInputListener. Do not use.

Specified by:

onMouseMotionEvent in interface RawInputListener

Parameters:

evt - event to add to the input queue (not null)

onMouseButtonEvent

public void onMouseButtonEvent(MouseButtonEvent evt)

Callback from RawInputListener. Do not use.

Specified by:

onMouseButtonEvent in interface RawInputListener

Parameters:

evt - information about the event

onKeyEvent

public void onKeyEvent(KeyInputEvent evt)

Callback from RawInputListener. Do not use.

Specified by:

onKeyEvent in interface RawInputListener

Parameters:

evt - information about the event

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.

Returns:

true if the mapping is registered, otherwise false

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

@Deprecated
public boolean getSimulateMouse()

Deprecated. Use isSimulateMouse Returns state of simulation of mouse events. Used for touchscreen input only.

Returns:

true if a mouse is simulated, otherwise false

isSimulateMouse

public boolean isSimulateMouse()

Returns state of simulation of mouse events. Used for touchscreen input only.

Returns:

true if a mouse is simulated, otherwise false

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

isSimulateKeyboard

public boolean isSimulateKeyboard()

Returns state of simulation of key events. Used for touchscreen input only.

Returns:

true if a keyboard is simulated, otherwise false

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

Parameters:

evt - information about the event

setJoysticks

public void setJoysticks(Joystick[] joysticks)

Re-sets the joystick list when a joystick is added or removed. This should only be called internally.

Parameters:

joysticks - (alias created)

addJoystickConnectionListener

public boolean addJoystickConnectionListener(JoystickConnectionListener listener)

Add a listener that reports when a joystick has been added or removed. Currently only implemented in LWJGL3

Parameters:

listener - the listener

Returns:

true

removeJoystickConnectionListener

public boolean removeJoystickConnectionListener(JoystickConnectionListener listener)

Remove an existing listener.

Parameters:

listener - the listener to remove.

Returns:

true if this listener was removed, or false if it was not found.

clearJoystickConnectionListeners

public void clearJoystickConnectionListeners()

Remove all joystick connection listeners.

fireJoystickConnectedEvent

public void fireJoystickConnectedEvent(Joystick joystick)

Called when a joystick has been connected. This should only be called internally.

Parameters:

joystick - the joystick that has been connected.

fireJoystickDisconnectedEvent

public void fireJoystickDisconnectedEvent(Joystick joystick)

Called when a joystick has been disconnected. This should only be called internally.

Parameters:

joystick - the joystick that has been disconnected.