com.jme.input
Class InputHandler

java.lang.Object
  extended by com.jme.input.InputHandler
Direct Known Subclasses:
ChaseCamera, FirstPersonHandler, KeyboardLookHandler, MouseLookHandler, NodeHandler, ThirdPersonHandler

public class InputHandler
extends java.lang.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 4371 2009-05-29 04:28:03Z christoph.luder@gmail.com $
Author:
Mark Powell, Jack Lindamood - (javadoc only), Irrisor - revamp

Field Summary
(package private)  ActionTrigger activeTriggers
          Stores first active trigger that is invoked upon next update.
(package private)  java.util.ArrayList<ActionTrigger> allTriggers
          list of all ActionTriggers of this input handler (triggers add themselves).
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 java.lang.String DEVICE_ALL
          Wildcard device name for all devices.
static java.lang.String DEVICE_KEYBOARD
          Device name of the keyboard.
static java.lang.String DEVICE_MOUSE
          Device name of the mouse.
protected  InputActionEvent event
          event that will be used to call each action this frame.
protected  Mouse mouse
          Not used any more.
 
Constructor Summary
InputHandler()
          Creates a new input handler.
 
Method Summary
 void addAction(InputActionInterface inputAction, java.lang.String triggerCommand, boolean allowRepeats)
          Adds an input action to be invoked by this handler during update.
 void addAction(InputActionInterface inputAction, java.lang.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, java.lang.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(java.util.Map<java.lang.String,java.lang.Object> props, java.lang.String key, boolean defaultVal)
           
static java.util.Collection<InputHandlerDevice> getDevices()
           
static float getFloatProp(java.util.Map<java.lang.String,java.lang.Object> props, java.lang.String key, float defaultVal)
           
 InputHandler getFromAttachedHandlers(int index)
          Get an element from the attachedHandlers association.
static int getIntProp(java.util.Map<java.lang.String,java.lang.Object> props, java.lang.String key, int defaultVal)
           
static java.lang.Object getObjectProp(java.util.Map<java.lang.String,java.lang.Object> props, java.lang.String key, java.lang.Object defaultVal)
           
 InputHandler getParent()
          Query parent handler.
 boolean isEnabled()
           
protected  void processTriggers(float time)
          Process triggers and call ActionTrigger.performAction(com.jme.input.action.InputActionEvent) if appropriate.
 void removeAction(InputActionInterface inputAction)
          Removes a keyboard input action from the list of keyActions that are polled during update.
 void removeAction(java.lang.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, java.lang.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.
protected  boolean setParent(InputHandler value)
           
 int sizeOfAttachedHandlers()
           
 void update(float time)
          Checks all actions to see if they should be invoked.
protected  void updateAttachedHandlers(float time)
          Update attached handlers.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

activeTriggers

ActionTrigger activeTriggers
Stores first active trigger that is invoked upon next update. Other active triggers are reachable via ActionTrigger.getNext() (linked list).


allTriggers

java.util.ArrayList<ActionTrigger> allTriggers
list of all ActionTriggers of this input handler (triggers add themselves).


DEVICE_MOUSE

public static final java.lang.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 java.lang.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 java.lang.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

mouse

protected Mouse mouse
Not used any more.


event

protected InputActionEvent event
event that will be used to call each action this frame.

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,
                           java.lang.String trigger)

addAction

public void addAction(InputActionInterface inputAction,
                      java.lang.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,
                      java.lang.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 java.util.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,
                      java.lang.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(java.lang.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)

processTriggers

protected void processTriggers(float time)
Process triggers and call ActionTrigger.performAction(com.jme.input.action.InputActionEvent) if appropriate.

Parameters:
time - The time to pass to every trigger that is called.

updateAttachedHandlers

protected void updateAttachedHandlers(float time)
Update attached handlers.

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

getFloatProp

public static float getFloatProp(java.util.Map<java.lang.String,java.lang.Object> props,
                                 java.lang.String key,
                                 float defaultVal)

getIntProp

public static int getIntProp(java.util.Map<java.lang.String,java.lang.Object> props,
                             java.lang.String key,
                             int defaultVal)

getBooleanProp

public static boolean getBooleanProp(java.util.Map<java.lang.String,java.lang.Object> props,
                                     java.lang.String key,
                                     boolean defaultVal)

getObjectProp

public static java.lang.Object getObjectProp(java.util.Map<java.lang.String,java.lang.Object> props,
                                             java.lang.String key,
                                             java.lang.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

setParent

protected boolean setParent(InputHandler value)
Parameters:
value - new value for field parent
Returns:
true if parent was changed