com.jme.input
Class InputHandler

java.lang.Object
  com.jme.input.InputHandler

Direct Known Subclasses:

ChaseCamera, FirstPersonHandler, KeyboardLookHandler, MouseLookHandler, NodeHandler, ThirdPersonHandler

public class InputHandler
extends Object

InputHandler handles mouse, key and other inputs. Actions can be subscribed for specific event triggers. InputActionInterface.performAction(InputActionEvent) is invoked within the update(float) method whenever the trigger criterias match. For a usage example see TestInputHandler. InputHandler is also used to decouple event occurence and action invocation (see ActionTrigger) - an event may occur in another thread (e.g. polling thread) but the action is still invoked in the thread that is calling the update(float) method.
You can add custom devices via the addDevice(InputHandlerDevice) method.

Version:

$Id: InputHandler.java,v 1.44 2007/08/02 22:55:27 nca Exp $

Author:

Mark Powell, Jack Lindamood - (javadoc only), Irrisor - revamp

Field Summary

static int	AXIS_ALL int value for representing all axes (wildcard).
static int	AXIS_NONE int value for representing no axis.
static int	BUTTON_ALL int value for representing all buttons/keys (wildcard).
static int	BUTTON_NONE int value for representing no button/key.
static String	DEVICE_ALL Wildcard device name for all devices.
static String	DEVICE_KEYBOARD Device name of the keyboard.
static String	DEVICE_MOUSE Device name of the mouse.

Constructor Summary

InputHandler()
Creates a new input handler.

Method Summary

void	addAction(InputActionInterface inputAction, String triggerCommand, boolean allowRepeats) Adds an input action to be invoked by this handler during update.
void	addAction(InputActionInterface inputAction, String triggerCommand, int keyCode, boolean allowRepeats) Registeres a single key as command in KeyBindingManager and adds an input action to be invoked by this handler during update.
void	addAction(InputActionInterface action, String deviceName, int button, int axis, boolean allowRepeats) Adds an input action to be invoked on deviceName button or axis events.
void	addAction(InputAction action, SyntheticAxis eventHandler, boolean allowRepeats) Adds an input action to be invoked on events for the given synthetic axis.
void	addAction(InputAction action, SyntheticButton eventHandler, boolean allowRepeats) Adds an input action to be invoked on events for the given synthetic button.
void	addAction(MouseInputAction mouseAction) Adds a mouse input action to be invoked each frame.
static void	addDevice(InputHandlerDevice device) Add a device to the InputHandlers.
boolean	addToAttachedHandlers(InputHandler value) Attach a handler which should be updated in this handlers update method.
void	clearActions() Clears all actions currently registered.
static boolean	getBooleanProp(HashMap<String,Object> props, String key, boolean defaultVal)
static Collection<InputHandlerDevice>	getDevices()
static float	getFloatProp(HashMap<String,Object> props, String key, float defaultVal)
InputHandler	getFromAttachedHandlers(int index) Get an element from the attachedHandlers association.
static int	getIntProp(HashMap<String,Object> props, String key, int defaultVal)
static Object	getObjectProp(HashMap<String,Object> props, String key, Object defaultVal)
InputHandler	getParent() Query parent handler.
boolean	isEnabled()
void	removeAction(InputActionInterface inputAction) Removes a keyboard input action from the list of keyActions that are polled during update.
void	removeAction(String triggerCommand) Removes a keyboard input action from the list of keyActions that are polled during update.
void	removeAllActions() Removes all actions and triggers from this handler.
void	removeAllFromAttachedHandlers()
boolean	removeFromAttachedHandlers(InputHandler value)
void	setActionSpeed(float speed) Sets the speed of all actions currently registered with this handler to the given value.
void	setActionSpeed(float speed, String trigger)
void	setEnabled(boolean value) Enable/disable the handler: disabled handler do not invoke actions and do not update attached handlers.
void	setEnabledOfAttachedHandlers(boolean enabled) enabled/disables all attached handlers but this handler keeps its status.
int	sizeOfAttachedHandlers()
void	update(float time) Checks all actions to see if they should be invoked.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEVICE_MOUSE

public static final String DEVICE_MOUSE

Device name of the mouse.

See Also:

addAction(com.jme.input.action.InputActionInterface,String,int,int,boolean), Constant Field Values

DEVICE_KEYBOARD

public static final String DEVICE_KEYBOARD

Device name of the keyboard.

See Also:

addAction(com.jme.input.action.InputActionInterface,String,int,int,boolean), Constant Field Values

DEVICE_ALL

public static final String DEVICE_ALL

Wildcard device name for all devices.

See Also:

addAction(com.jme.input.action.InputActionInterface,String,int,int,boolean), Constant Field Values

BUTTON_NONE

public static final int BUTTON_NONE

int value for representing no button/key.

See Also:

addAction(com.jme.input.action.InputActionInterface,String,int,int,boolean), Constant Field Values

BUTTON_ALL

public static final int BUTTON_ALL

int value for representing all buttons/keys (wildcard).

See Also:

addAction(com.jme.input.action.InputActionInterface,String,int,int,boolean), Constant Field Values

AXIS_NONE

public static final int AXIS_NONE

int value for representing no axis.

See Also:

addAction(com.jme.input.action.InputActionInterface,String,int,int,boolean), Constant Field Values

AXIS_ALL

public static final int AXIS_ALL

int value for representing all axes (wildcard).

See Also:

addAction(com.jme.input.action.InputActionInterface,String,int,int,boolean), Constant Field Values

Constructor Detail

InputHandler

public InputHandler()

Creates a new input handler. By default, there are no keyboard actions or mouse actions defined.

Method Detail

setActionSpeed

public void setActionSpeed(float speed)

Sets the speed of all actions currently registered with this handler to the given value.

Parameters:

speed - The new speed for all currently registered actions.

See Also:

InputAction.setSpeed(float)

setActionSpeed

public void setActionSpeed(float speed,
                           String trigger)

addAction

public void addAction(InputActionInterface inputAction,
                      String triggerCommand,
                      boolean allowRepeats)

Adds an input action to be invoked by this handler during update.

Parameters:

inputAction - the input action to be added

triggerCommand - the command to trigger this action (registered with KeyBindingManager), if null the action is invoked on each call of update(float)

allowRepeats - true to invoke the action every call of update the trigger is lit, false to invoke

addAction

public void addAction(InputActionInterface inputAction,
                      String triggerCommand,
                      int keyCode,
                      boolean allowRepeats)

Registeres a single key as command in KeyBindingManager and adds an input action to be invoked by this handler during update.

Parameters:

inputAction - the input action to be added

triggerCommand - the command to trigger this action, may not be null (unlike in addAction(com.jme.input.action.InputActionInterface,String,boolean))

keyCode - the keyCode to register at KeyBindingManager for the command

allowRepeats - true to invoke the action every call of update the trigger is lit, false to invoke

addAction

public void addAction(InputAction action,
                      SyntheticButton eventHandler,
                      boolean allowRepeats)

Adds an input action to be invoked on events for the given synthetic button. An event should occur on press and on release. The type of event can be distinguished by the InputActionEvent.getTrigger* methods.

Parameters:

action - the input action to be added

allowRepeats - false to invoke action once for each button down, true to invoke each frame while the

eventHandler - button

addAction

public void addAction(InputAction action,
                      SyntheticAxis eventHandler,
                      boolean allowRepeats)

Adds an input action to be invoked on events for the given synthetic axis. An event should occur each time the axis value changes. The type of event can be distinguished by the InputActionEvent.getTrigger* methods.

Parameters:

action - the input action to be added

allowRepeats - false to invoke action once for each button down, true to invoke each frame while the

eventHandler - axis

addAction

public void addAction(MouseInputAction mouseAction)

Adds a mouse input action to be invoked each frame. Use addAction(com.jme.input.action.InputActionInterface,String,int,int,boolean) to add actions that are invoked on mouse events.

Parameters:

mouseAction - The input action to be added

getDevices

public static Collection<InputHandlerDevice> getDevices()

addDevice

public static void addDevice(InputHandlerDevice device)

Add a device to the InputHandlers. Note: only newly added actions regard the added devices (actions added with DEVICE_ALL before device was added will not receive device events).

Parameters:

device - new device

See Also:

InputHandlerDevice

addAction

public void addAction(InputActionInterface action,
                      String deviceName,
                      int button,
                      int axis,
                      boolean allowRepeats)

Adds an input action to be invoked on deviceName button or axis events. For an axis an event should occur each time the axis value changes, for a button an event should occur on press and on release. The type of event can be distinguished by the InputActionEvent.getTrigger* methods.

Parameters:

action - the input action to be added

deviceName - name of the deviceName: DEVICE_MOUSE, DEVICE_KEYBOARD, a joystick name or DEVICE_ALL

button - index of the button that triggers this event, BUTTON_NONE for no button, BUTTON_ALL for all buttons. (for keyboad deviceName this is a key code). If DEVICE_ALL is specified button will not be interpreted as key code, thus keyboard input is only regarded if BUTTON_ALL is specified inthis case.

axis - index of the axis that triggers this event, AXIS_NONE for no axis, AXIS_ALL for all axes

allowRepeats - false to invoke action once for each button down, true to invoke each frame while the

removeAction

public void removeAction(InputActionInterface inputAction)

Removes a keyboard input action from the list of keyActions that are polled during update.

Parameters:

inputAction - The action to remove.

removeAction

public void removeAction(String triggerCommand)

Removes a keyboard input action from the list of keyActions that are polled during update.

Parameters:

triggerCommand - the command that should be removed

removeAllActions

public void removeAllActions()

Removes all actions and triggers from this handler. Commonly used to get the handler and the actions garbage collected.

clearActions

public void clearActions()

Clears all actions currently registered.

update

public void update(float time)

Checks all actions to see if they should be invoked. If so, InputActionInterface.performAction(InputActionEvent) is called on the action with the given time.
This method can be invoked while the handler is disabled. Thus the method should check isEnabled() and return immediately if it evaluates to false.
This method should normally not be overwritten by subclasses. If an InputHandler needs to execute something in each update register an action with triggerCommand = null. Exception to this is an InputHandler that checks additional input types, that cannot be handled via InputHandlerDevices.

Parameters:

time - The time to pass to every action that is active.

See Also:

addAction(com.jme.input.action.InputActionInterface,String,boolean)

getFloatProp

public static float getFloatProp(HashMap<String,Object> props,
                                 String key,
                                 float defaultVal)

getIntProp

public static int getIntProp(HashMap<String,Object> props,
                             String key,
                             int defaultVal)

getBooleanProp

public static boolean getBooleanProp(HashMap<String,Object> props,
                                     String key,
                                     boolean defaultVal)

getObjectProp

public static Object getObjectProp(HashMap<String,Object> props,
                                   String key,
                                   Object defaultVal)

isEnabled

public boolean isEnabled()

Returns:

true if this handler is currently enabled

setEnabled

public void setEnabled(boolean value)

Enable/disable the handler: disabled handler do not invoke actions and do not update attached handlers.

Parameters:

value - true to enable the handler, false to disable the handler

setEnabledOfAttachedHandlers

public void setEnabledOfAttachedHandlers(boolean enabled)

enabled/disables all attached handlers but this handler keeps its status.

Parameters:

enabled - true to enable all attached handlers, false to disable them

addToAttachedHandlers

public boolean addToAttachedHandlers(InputHandler value)

Attach a handler which should be updated in this handlers update method.

Parameters:

value - handler to attach

Returns:

true if handler was not attached before

getFromAttachedHandlers

public InputHandler getFromAttachedHandlers(int index)

Get an element from the attachedHandlers association.

Parameters:

index - index of element to be retrieved

Returns:

the element, null if index out of range

removeAllFromAttachedHandlers

public void removeAllFromAttachedHandlers()

removeFromAttachedHandlers

public boolean removeFromAttachedHandlers(InputHandler value)

sizeOfAttachedHandlers

public int sizeOfAttachedHandlers()

Returns:

number of attached handlers

getParent

public InputHandler getParent()

Query parent handler.

Returns:

current parent