Package com.simsilica.lemur.input

Class InputMapper

java.lang.Object

com.simsilica.lemur.input.InputMapper

public class InputMapper
extends Object

Wraps the normal InputManager to provide enhanced function mapping that completely decouples the registration of input from the listeners that are executed. Inputs can be dynamically registered to trigger certain logical "functions" based on a FunctionId. Separately, analog and state change listeners can be registered for specific FunctionIds. In addition to decoupling, any number of inputs can be registered to a particular FunctionId at any time. This is different than the default InputManager which will throw an exception if new inputs are added to an existing trigger mapping.

The design of InputMapper is setup to better handle the case where an application wants to allow the user to configure their own input mappings through a GUI... and specifically where the application may allow multiple separately configured inputs to trigger the same set of functions. For example, an application may map a joystick axis, the mouse wheel, and/or one or two keys to a specific function.

Also, any logical FunctionId can be treated as both an analog input or a trinary state input. Key inputs can trigger analog functions and analog axes can trigger Positive, Off, Negative state transitions. For example, the key 'A' can be mapped to a "move" function and 'S' can be mapped to the "move" function as being inverted. 'A' and 'S' will then trigger analog values of 1.0 and -1.0 respectively. The "move" function can then also be mapped to an analog joystick axis and the code remains the same. On the other end, if a StateFunctionListener is registered with to a logical FunctionId being fed by an analog Axis then it will see Positive, Negative, and Off as the axis transitions from greater than 0, less than 0, and 0, respectively. (A small neutrality threshold is effected to make extremely small analog values operate as 0.)

When registering inputs, a series of combinations can be included that must all be present to invoke the function. As an example, "mouse wheel" and "ctrl + mouse wheel" can be treated as two separate function triggers.

Entire groups of logical functions can be enabled and disabled by their groups. Multiple groups can be active at any given time and only active groups are elegible to receive input.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected class	InputMapper.FunctionListeners
protected class	InputMapper.InputObserver
static interface	InputMapper.Mapping	Represents a specific control mapping such that it can be reconfigured.
protected class	InputMapper.StateGroup
protected class	InputMapper.StateGroupIndex

Constructor Summary

Constructors

Constructor	Description
InputMapper(InputManager inputManager)

Method Summary

Modifier and Type	Method	Description
protected void	activate(InputMapper.StateGroup g)
void	activateGroup(String group)	Activates the specified function group, allowing those function IDs to receive input.
void	addAnalogListener(AnalogFunctionListener l, FunctionId... functions)
void	addDelegate(FunctionId func, Object target, String methodName)
void	addDelegate(FunctionId func, Object target, String methodName, boolean passArgument)
void	addInputConfigListener(InputConfigListener l)	Adds a listener that will be notified when input mappings are added, changed, or removed.
protected InputMapper.Mapping	addMapping(FunctionId function, double scale, Object primary, Object... modifiers)
void	addStateListener(StateFunctionListener l, FunctionId... functions)
protected void	deactivate(InputMapper.StateGroup g)
void	deactivateGroup(String group)	Deactivates the specified function group, preventing those function IDs from receiving input.
protected InputMapper.StateGroup	findMapping(FunctionId function, Object primary, Object... modifiers)
protected void	fireMappingAdded(InputMapper.Mapping m)
protected void	fireMappingChanged(InputMapper.Mapping m)
protected void	fireMappingRemoved(InputMapper.Mapping m)
Set<FunctionId>	getFunctionIds()	Returns a list of all FunctionIds that have listeners registered or inputs mapped.
protected InputMapper.FunctionListeners	getFunctionListeners(FunctionId f, boolean create)
protected InputMapper.StateGroupIndex	getIndex(Object state, boolean create)
InputMapper.Mapping	getMapping(FunctionId function, Object primary, Object... modifiers)
Set<InputMapper.Mapping>	getMappings(FunctionId function)	Returns all of the different input mappings for a particular function ID.
boolean	hasMappings(FunctionId function)	Returns true if the specified function has any input mappings.
InputMapper.Mapping	map(FunctionId function, int mainKeyCode, Object... pressed)
InputMapper.Mapping	map(FunctionId function, Axis axis, Object... pressed)
InputMapper.Mapping	map(FunctionId function, Button button, Object... pressed)
InputMapper.Mapping	map(FunctionId function, InputState bias, int mainKeyCode, Object... pressed)
InputMapper.Mapping	map(FunctionId function, InputState bias, Axis axis, Object... pressed)
InputMapper.Mapping	map(FunctionId function, InputState bias, Button button, Object... pressed)
protected void	mapGamepad(InputDevice device, Joystick j)
protected void	mapJoystick(Joystick j)
protected void	notifyStateChanged(FunctionId function, InputState value)
protected void	notifyValueActive(FunctionId function, double value)
void	registerProvider(InputProvider provider)	Registers an alternate InputProvider that can be used to supply events to this InputMapper and call its addRawInputListener() method.
void	release()
void	removeAnalogListener(AnalogFunctionListener l, FunctionId... functions)
void	removeDelegate(FunctionId func, Object target, String methodName)
void	removeInputConfigListener(InputConfigListener l)	Removes a previously registered input config listener.
void	removeMapping(FunctionId function, Object primary, Object... modifiers)
void	removeMapping(InputMapper.Mapping mapping)
void	removeStateListener(StateFunctionListener l, FunctionId... functions)
void	unregisterProvider(InputProvider provider)	Removes a previously registered alternate InputProvider and calls its removeRawInputListener() method.
void	update()
protected InputState	valueToState(double val)

Methods inherited from class java.lang.Object

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

Constructor Details

InputMapper

public InputMapper(InputManager inputManager)

Method Details

registerProvider

public void registerProvider(InputProvider provider)

Registers an alternate InputProvider that can be used to supply events to this InputMapper and call its addRawInputListener() method. If the provider is still registered when InputMapper is released then InputMapper will remove its listener during release().

unregisterProvider

public void unregisterProvider(InputProvider provider)

Removes a previously registered alternate InputProvider and calls its removeRawInputListener() method.

activateGroup

public void activateGroup(String group)

Activates the specified function group, allowing those function IDs to receive input.

deactivateGroup

public void deactivateGroup(String group)

Deactivates the specified function group, preventing those function IDs from receiving input.

release

public void release()

mapJoystick

protected void mapJoystick(Joystick j)

mapGamepad

protected void mapGamepad(InputDevice device,
 Joystick j)

getIndex

protected InputMapper.StateGroupIndex getIndex(Object state,
 boolean create)

getFunctionListeners

protected InputMapper.FunctionListeners getFunctionListeners(FunctionId f,
 boolean create)

map

public InputMapper.Mapping map(FunctionId function,
 Axis axis,
 Object... pressed)

map

public InputMapper.Mapping map(FunctionId function,
 InputState bias,
 Axis axis,
 Object... pressed)

map

public InputMapper.Mapping map(FunctionId function,
 Button button,
 Object... pressed)

map

public InputMapper.Mapping map(FunctionId function,
 InputState bias,
 Button button,
 Object... pressed)

map

public InputMapper.Mapping map(FunctionId function,
 int mainKeyCode,
 Object... pressed)

map

public InputMapper.Mapping map(FunctionId function,
 InputState bias,
 int mainKeyCode,
 Object... pressed)

addMapping

protected InputMapper.Mapping addMapping(FunctionId function,
 double scale,
 Object primary,
 Object... modifiers)

findMapping

protected InputMapper.StateGroup findMapping(FunctionId function,
 Object primary,
 Object... modifiers)

getMapping

public InputMapper.Mapping getMapping(FunctionId function,
 Object primary,
 Object... modifiers)

removeMapping

public void removeMapping(FunctionId function,
 Object primary,
 Object... modifiers)

removeMapping

public void removeMapping(InputMapper.Mapping mapping)

hasMappings

public boolean hasMappings(FunctionId function)

Returns true if the specified function has any input mappings.

getFunctionIds

public Set<FunctionId> getFunctionIds()

Returns a list of all FunctionIds that have listeners registered or inputs mapped.

getMappings

public Set<InputMapper.Mapping> getMappings(FunctionId function)

Returns all of the different input mappings for a particular function ID.

addStateListener

public void addStateListener(StateFunctionListener l,
 FunctionId... functions)

removeStateListener

public void removeStateListener(StateFunctionListener l,
 FunctionId... functions)

addAnalogListener

public void addAnalogListener(AnalogFunctionListener l,
 FunctionId... functions)

removeAnalogListener

public void removeAnalogListener(AnalogFunctionListener l,
 FunctionId... functions)

addDelegate

public void addDelegate(FunctionId func,
 Object target,
 String methodName)

addDelegate

public void addDelegate(FunctionId func,
 Object target,
 String methodName,
 boolean passArgument)

removeDelegate

public void removeDelegate(FunctionId func,
 Object target,
 String methodName)

activate

protected void activate(InputMapper.StateGroup g)

deactivate

protected void deactivate(InputMapper.StateGroup g)

update

public void update()

notifyStateChanged

protected void notifyStateChanged(FunctionId function,
 InputState value)

notifyValueActive

protected void notifyValueActive(FunctionId function,
 double value)

valueToState

protected InputState valueToState(double val)

addInputConfigListener

public void addInputConfigListener(InputConfigListener l)

Adds a listener that will be notified when input mappings are added, changed, or removed.

removeInputConfigListener

public void removeInputConfigListener(InputConfigListener l)

Removes a previously registered input config listener.

fireMappingAdded

protected void fireMappingAdded(InputMapper.Mapping m)

fireMappingRemoved

protected void fireMappingRemoved(InputMapper.Mapping m)

fireMappingChanged

protected void fireMappingChanged(InputMapper.Mapping m)