net.jinx.action.input
Class InputDevice

java.lang.Object
  net.jinx.action.input.InputDevice

public class InputDevice
extends java.lang.Object

Wrapper for net.java.games.input.Controller to make it simpler and easier to deal with. It does this by categorizing the Axis objects returned from the Controller and it's sub-controllers. It also allows you to control the dead zones and whether or not to negate values for each individual Axis. It will even take care of normalizing arbitrary axes for you. This class works by first getting all the Axes from all the sub-controllers. Then it categorizes them into fuzzy axes, POV hats, buttons, and mouse wheels. Fuzzy Axes are those whose values can be anything between negetive one and one (including those values). POV hats are digital direction pads with either four or eight directions. This class treats them almost exactly like a direction pad on a game pad, meaning that if the pad is pressed up-left, up, or up-right, isUp() will return true. This means the left-right and up-down directions are independant and can be used seperately if you desire. Buttons are boolean inputs that are either on or off. Mouse wheels can't be shoe-horned into any other category, so they're treated as a category of their own. The mouseWheelClicks() method can be used to get the direction and number of clicks on the wheel, if it exists.

API Stability: Beta.

Constructor Summary

InputDevice(net.java.games.input.Controller c)
Constructs a new InputDevice to wrap the given Controller.

Method Summary

boolean[]	buttonsPressed() Determines which buttons are currently pressed.
net.java.games.input.Axis[]	getAxes() Returns the array containing all of the axes for this InputDevice.
net.java.games.input.Axis	getButton(int button) Returns the button Axis indicated.
net.java.games.input.Axis[]	getButtons() Returns the array containing the button axes for this InputDevice.
net.java.games.input.Controller	getController() Returns the underlying JInput Controller that this InputDevice is wrapping.
float	getDeadZone(int axis) Returns the dead zone for the indicated fuzzy axis.
float	getDeadZoneValue(int axis) Returns the value of the indicated fuzzy axis, using the set dead zone to calculate the value.
java.lang.String	getDescription() Returns a best guess as to the type of this InputDevice.
static InputDevice[]	getDevices() Provides an array of InputDevice objects.
static InputDevice[]	getDevices(Hierarchy base) Provides an array of InputDevice objects.
static InputDevice[]	getDevices(InputDevice[] existingDevices) Provides an array of InputDevice objects.
static InputDevice[]	getDevices(InputDevice[] existingDevices, Hierarchy base) Provides an array of InputDevice objects.
net.java.games.input.Axis[]	getFuzzyAxes() Returns the array containing the fuzzy axes for this InputDevice.
net.java.games.input.Axis	getFuzzyAxis(int axis) Returns the fuzzy Axis indicated.
float	getFuzzyValue(int axis) Returns the value of the indicated fuzzy axis; dead zone data is ignored and the value is not necessarily normalized.
java.lang.String	getID() Returns a (hopefully) unique identifier String for this InputDevice to ease finding the same InputDevice from one run of a program to the next.
net.java.games.input.Axis	getMouseWheel() Returns the mouse wheel Axis, or null if this is not a mouse.
int	getMouseWheelClicks() Returns the direction and number of clicks that have occured on this mouse's wheel.
net.java.games.input.Axis	getMouseXAxis() Returns the X Axis for a mouse, or null if this is not a mouse.
net.java.games.input.Axis	getMouseYAxis() Returns the Y Axis for a mouse, or null if this is not a mouse.
java.lang.String	getName() Returns the name of this InputDevice.
float	getNormalDivider() Returns the normal divider.
float	getNormalValue(int axis) Returns the value of the indicated fuzzy axis; dead zone data is ignored, but the return value is guaranteed to be normalized from -1 to 1.
net.java.games.input.Axis	getPOVHat(int hat) Returns the POV Hat Axis indicated.
net.java.games.input.Axis[]	getPOVHats() Returns the array containing the POV hat axes for this InputDevice.
java.lang.StringBuffer	getReport() Gets a report of the current conditions of this InputDevice.
net.java.games.input.Rumbler	getRumbler(net.java.games.input.Axis.Identifier axid) Returns a Rumbler that matches the given identifier, or null if there isn't one.
net.java.games.input.Rumbler[]	getRumblers() Gets the array of all Rumblers attached to this InputDevice.
float	getThrottleValue(int axis) Returns the value of the indicated fuzzy axis, using the set dead zone to calculate the value.
boolean	isButtonPressed(int button) Determines if the indicated button is pressed.
boolean	isHeadTracker() Returns true if this InputDevice is a head tracker.
boolean	isKeyboard() Returns true if this InputDevice is a keyboard.
boolean	isKeypad() Returns true if this InputDevice is a keypad.
boolean	isMouse() Returns true if this InputDevice is a mouse.
boolean	isPOVCenter(int hat) Determines if the indicated POV hat is centered.
boolean	isPOVDown(int hat) Determines if the indicated POV hat is pointed in the down direction.
boolean	isPOVLeft(int hat) Determines if the indicated POV hat is pointed in the left direction.
boolean	isPOVRight(int hat) Determines if the indicated POV hat is pointed in the right direction.
boolean	isPOVUp(int hat) Determines if the indicated POV hat is pointed in the up direction.
boolean	isReverseFuzzy(int axis) Returns the value of the reverse flag for the indicated fuzzy axis.
boolean	isRudder() Returns true if this InputDevice is a rudder control.
boolean	isStick() Returns true if this InputDevice is a stick.
boolean	isUseless() Returns true if this InputDevice has no controls of any kind.
boolean	isWheel() Returns true if this InputDevice is a steering wheel.
void	load(Hierarchy h) Loads the configuration for this InputDevice from h.
static void	load(InputDevice[] devices, Hierarchy base) Calls load(base) on each InputDevice in the array of devices, using a sub-node named according to the device's unique ID (see the getID() method) and that device's order among those devices with an identical ID.
static InputDevice	matchDevice(java.lang.String id, InputDevice[] devices) Attempts to match an InputDevice to it's ID string.
boolean	poll() Polls this InputDevice for input.
void	rumble(net.java.games.input.Axis.Identifier axid, float intensity) Rumbles the Rumbler that matches the given identifier, if it exists.
void	rumble(float intensity) Rumbles all rumblers attached to this InputDevice at the same intensity.
void	rumble(float x, float y) This should produce a 2D directional rumble if the InputDevice supports it.
void	setDeadZone(int axis, float dz) Sets the dead zone for the indicated fuzzy axis.
void	setNormalDivider(float normalDivider) Sets the value used to normalize axes that are not normalized.
void	setReverseFuzzy(int axis, boolean reverse) Sets whether or not the indicated fuzzy axis should be reversed.
void	store(Hierarchy h) Stores the configuration for this InputDevice in h.
static void	store(InputDevice[] devices, Hierarchy base) Calls store(Hierarchy) on each InputDevice in the array of devices, using a sub-node named according to the device's unique ID (see the getID() method) and that device's order among those devices with an identical ID.
java.lang.String	toString() Returns the ID String for this InputDevice.

Methods inherited from class java.lang.Object

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

Constructor Detail

InputDevice

public InputDevice(net.java.games.input.Controller c)

Constructs a new InputDevice to wrap the given Controller.

Parameters:

c - the Controller.

Method Detail

getController

public net.java.games.input.Controller getController()

Returns the underlying JInput Controller that this InputDevice is wrapping.

Returns:

the Controller.

getName

public java.lang.String getName()

Returns the name of this InputDevice. This will not necessarily be the same as the underlying Controller's name, as this class makes some corrections to the name.

Returns:

the name as a String.

getDescription

public java.lang.String getDescription()

Returns a best guess as to the type of this InputDevice. This may not match what JInput claims, but it should be better for descriptive purposes. This is only for informational/display purposes.

Returns:

a String containing a single word.

getID

public java.lang.String getID()

Returns a (hopefully) unique identifier String for this InputDevice to ease finding the same InputDevice from one run of a program to the next. This won't allow you to distinguish between two devices that are exactly the same model, but it shouldn't matter in this case. For that, you can use the relative order of the duplicate devices, along with the results of this method.

Returns:

the ID String. This should function as a fingerprint for an InputDevice.

isMouse

public boolean isMouse()

Returns true if this InputDevice is a mouse.

Returns:

true if the above is true.

isKeyboard

public boolean isKeyboard()

Returns true if this InputDevice is a keyboard. IsKeypad() should return true if this does.

Returns:

true if the above is true.

isKeypad

public boolean isKeypad()

Returns true if this InputDevice is a keypad.

Returns:

true if the above is true.

isWheel

public boolean isWheel()

Returns true if this InputDevice is a steering wheel.

Returns:

true if the above is true.

isRudder

public boolean isRudder()

Returns true if this InputDevice is a rudder control.

Returns:

true if the above is true.

isHeadTracker

public boolean isHeadTracker()

Returns true if this InputDevice is a head tracker.

Returns:

true if the above is true.

isStick

public boolean isStick()

Returns true if this InputDevice is a stick.

Returns:

true if the above is true.

isUseless

public boolean isUseless()

Returns true if this InputDevice has no controls of any kind. You might think this is a pointless method to add, but I have seen devices with no controls show up in my lists of devices. I've got a keyboard that registers as something like eight devices, four of which have no controls. It's a very goofy keyboard and I can't figure out why DirectX and/or JInput don't filter them out.

Returns:

true if the device is useless.

getMouseXAxis

public net.java.games.input.Axis getMouseXAxis()

Returns the X Axis for a mouse, or null if this is not a mouse.

Returns:

the X Axis or null.

getMouseYAxis

public net.java.games.input.Axis getMouseYAxis()

Returns the Y Axis for a mouse, or null if this is not a mouse.

Returns:

the Y Axis or null.

getMouseWheel

public net.java.games.input.Axis getMouseWheel()

Returns the mouse wheel Axis, or null if this is not a mouse.

Returns:

the mouse wheel Axis.

getMouseWheelClicks

public int getMouseWheelClicks()

Returns the direction and number of clicks that have occured on this mouse's wheel. This will return zero if this is not a mouse or doesn't have a wheel.

Returns:

the number of clicks; the sign indicates direction.

getAxes

public net.java.games.input.Axis[] getAxes()

Returns the array containing all of the axes for this InputDevice.

Returns:

the array of all axes. Do not modify this array. Just use it to retrieve data.

getButtons

public net.java.games.input.Axis[] getButtons()

Returns the array containing the button axes for this InputDevice.

Returns:

the array of buttons. Do not modify this array. Just use it to retrieve data.

getButton

public net.java.games.input.Axis getButton(int button)

Returns the button Axis indicated.

Parameters:

button - the number of the button to return.

Returns:

the Axis.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if button is out of bounds.

getPOVHats

public net.java.games.input.Axis[] getPOVHats()

Returns the array containing the POV hat axes for this InputDevice.

Returns:

the array of POV hats. Do not modify this array. Just use it to retrieve data.

getPOVHat

public net.java.games.input.Axis getPOVHat(int hat)

Returns the POV Hat Axis indicated.

Parameters:

hat - the number of the hat to return.

Returns:

the Axis.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if hat is out of bounds.

isPOVCenter

public boolean isPOVCenter(int hat)

Determines if the indicated POV hat is centered.

Parameters:

hat - the index of the hat to query.

Returns:

true if the POV is centered.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if hat is out of bounds.

isPOVUp

public boolean isPOVUp(int hat)

Determines if the indicated POV hat is pointed in the up direction.

Parameters:

hat - the index of the hat to query.

Returns:

true if the POV is pointed up.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if hat is out of bounds.

isPOVDown

public boolean isPOVDown(int hat)

Determines if the indicated POV hat is pointed in the down direction.

Parameters:

hat - the index of the hat to query.

Returns:

true if the POV is pointed down.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if hat is out of bounds.

isPOVLeft

public boolean isPOVLeft(int hat)

Determines if the indicated POV hat is pointed in the left direction.

Parameters:

hat - the index of the hat to query.

Returns:

true if the POV is pointed left.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if hat is out of bounds.

isPOVRight

public boolean isPOVRight(int hat)

Determines if the indicated POV hat is pointed in the right direction.

Parameters:

hat - the index of the hat to query.

Returns:

true if the POV is pointed right.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if hat is out of bounds.

setDeadZone

public void setDeadZone(int axis,
                        float dz)

Sets the dead zone for the indicated fuzzy axis.

Parameters:

axis - the number of the fuzzy axis to set the dead zone for.

dz - the dead zone value.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if axis is out of bounds.

getDeadZone

public float getDeadZone(int axis)

Returns the dead zone for the indicated fuzzy axis.

Parameters:

axis - the number of the fuzzy axis to query.

Returns:

the dead zone for the axis.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if axis is out of bounds.

getFuzzyValue

public float getFuzzyValue(int axis)

Returns the value of the indicated fuzzy axis; dead zone data is ignored and the value is not necessarily normalized. The only processing this method does is to reverse the value based on the Axis' reverse flag.

Parameters:

axis - the number of the fuzzy axis to query.

Returns:

the axis' value.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if axis is out of bounds.

getNormalValue

public float getNormalValue(int axis)

Returns the value of the indicated fuzzy axis; dead zone data is ignored, but the return value is guaranteed to be normalized from -1 to 1.

Parameters:

axis - the number of the fuzzy axis to query.

Returns:

the axis' value.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if axis is out of bounds.

getDeadZoneValue

public float getDeadZoneValue(int axis)

Returns the value of the indicated fuzzy axis, using the set dead zone to calculate the value. The return value will be normally distributed from -1 to 1.

Parameters:

axis - the number of the fuzzy axis to query.

Returns:

the axis' value.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if axis is out of bounds.

getThrottleValue

public float getThrottleValue(int axis)

Returns the value of the indicated fuzzy axis, using the set dead zone to calculate the value. The return value will be normally distributed from 0 to 1. The dead zone data will be used at either extreme of the axis to ensure that both zero and one can be reached.

Parameters:

axis - the number of the fuzzy axis to query.

Returns:

the axis' value.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if axis is out of bounds.

setReverseFuzzy

public void setReverseFuzzy(int axis,
                            boolean reverse)

Sets whether or not the indicated fuzzy axis should be reversed. This affects the getDeadZoneValue(int) and getFuzzyValue(int) methods.

Parameters:

axis - the number of the fuzzy axis to configure.

reverse - true means the axis is reversed, false means it's not.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if axis is out of bounds.

isReverseFuzzy

public boolean isReverseFuzzy(int axis)

Returns the value of the reverse flag for the indicated fuzzy axis.

Parameters:

axis - the number of the fuzzy axis to configure.

Returns:

true if the indicated fuzzy axis should be reversed.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if axis is out of bounds.

getFuzzyAxes

public net.java.games.input.Axis[] getFuzzyAxes()

Returns the array containing the fuzzy axes for this InputDevice. These are the Axes that are neither buttons nor POV hats.

Returns:

the array of fuzzy axes. Do not modify this array. Just use it to retrieve data.

getFuzzyAxis

public net.java.games.input.Axis getFuzzyAxis(int axis)

Returns the fuzzy Axis indicated.

Parameters:

axis - the number of the fuzzy axis to return.

Returns:

the Axis.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if axis is out of bounds.

isButtonPressed

public boolean isButtonPressed(int button)

Determines if the indicated button is pressed.

Parameters:

button - the index of the button to query.

Returns:

true if the button is pressed

Throws:

java.lang.ArrayIndexOutOfBoundsException - if button is out of bounds.

buttonsPressed

public boolean[] buttonsPressed()

Determines which buttons are currently pressed.

Returns:

a boolean array corresponding to this InputDevice's buttons. Any particular value will be true if the button is pressed and false if it's not.

setNormalDivider

public void setNormalDivider(float normalDivider)

Sets the value used to normalize axes that are not normalized. The values of these axes are divided by this value and then clamped from -1 to 1.

Parameters:

normalDivider - the divider.

Throws:

java.lang.IllegalArgumentException - if normalDivider is less than one.

getNormalDivider

public float getNormalDivider()

Returns the normal divider. This will always be one or higher. This defaults to 1000, which works well for mouse axes.

Returns:

the divider.

poll

public boolean poll()

Polls this InputDevice for input.

Returns:

true if this InputDevice is still valid, false otherwise.

getRumblers

public net.java.games.input.Rumbler[] getRumblers()

Gets the array of all Rumblers attached to this InputDevice.

Returns:

the array. Do not modify this array.

getRumbler

public net.java.games.input.Rumbler getRumbler(net.java.games.input.Axis.Identifier axid)

Returns a Rumbler that matches the given identifier, or null if there isn't one.

Parameters:

axid - the identifier to match.

Returns:

the Rumbler.

rumble

public void rumble(net.java.games.input.Axis.Identifier axid,
                   float intensity)

Rumbles the Rumbler that matches the given identifier, if it exists.

Parameters:

axid - the identifier to match.

intensity - the strength of the rumble.

rumble

public void rumble(float intensity)

Rumbles all rumblers attached to this InputDevice at the same intensity.

Parameters:

intensity - the strength of the rumble.

rumble

public void rumble(float x,
                   float y)

This should produce a 2D directional rumble if the InputDevice supports it. If it isn't supported, rumble(float) will be called using the average of x and y.

Parameters:

x - the strength of the rumble in the x direction.

y - the strength of the rumble in the y direction.

getReport

public java.lang.StringBuffer getReport()

Gets a report of the current conditions of this InputDevice. This is suitable for dumping into a file, or displaying in a window. This is useful for building test programs without having to check each axis manually.

Returns:

a StringBuffer containing the report. This will be multiple lines and will vary in length.

store

public void store(Hierarchy h)

Stores the configuration for this InputDevice in h.

Parameters:

h - the Hierarchy to store this InputDevice's configuration in. If h is null, then nothing is done.

load

public void load(Hierarchy h)

Loads the configuration for this InputDevice from h.

Parameters:

h - the Hierarchy to search for this InputDevice's configuration in. If h is null then nothing is done.

toString

public java.lang.String toString()

Returns the ID String for this InputDevice.

Overrides:

toString in class java.lang.Object

Returns:

the ID String.

getDevices

public static InputDevice[] getDevices(InputDevice[] existingDevices)

Provides an array of InputDevice objects.

Parameters:

existingDevices - an InputDevice array for the devices that have already been configured. If one of these matches up to a device in the new array, it will replace it.

getDevices

public static InputDevice[] getDevices(InputDevice[] existingDevices,
                                       Hierarchy base)

Provides an array of InputDevice objects.

Parameters:

existingDevices - an InputDevice array for the devices that have already been configured. If one of these matches up to a device in the new array, it will replace it.

base - the Hierarchy to configure the new InputDevice objects from.

getDevices

public static InputDevice[] getDevices(Hierarchy base)

Provides an array of InputDevice objects. Useless ones with no controls and no Rumblers will have been removed from the array. This method can be called again later to check for new devices.

Parameters:

base - the Hierarchy to configure the new InputDevice array from.

Returns:

the array of InputDevices.

getDevices

public static InputDevice[] getDevices()

Provides an array of InputDevice objects. Useless ones with no controls and no Rumblers will have been removed from the array. This method can be called again later to check for new devices.

Returns:

the array of InputDevices.

matchDevice

public static InputDevice matchDevice(java.lang.String id,
                                      InputDevice[] devices)

Attempts to match an InputDevice to it's ID string.

Parameters:

id - the ID string to search for, as per the getID() method.

devices - the InputDevices to search.

Returns:

the InputDevice that matches or null if there was no match.

load

public static void load(InputDevice[] devices,
                        Hierarchy base)

Calls load(base) on each InputDevice in the array of devices, using a sub-node named according to the device's unique ID (see the getID() method) and that device's order among those devices with an identical ID.

Parameters:

devices - the array of InputDevice objects.

base - the Hierarchy to use to configure devices from.

store

public static void store(InputDevice[] devices,
                         Hierarchy base)

Calls store(Hierarchy) on each InputDevice in the array of devices, using a sub-node named according to the device's unique ID (see the getID() method) and that device's order among those devices with an identical ID.

Parameters:

devices - the array of InputDevice objects.

base - the Hierarchy to store configuration data for the devices in.