com.badlogic.gdx
Interface Input

All Known Implementing Classes:

RemoteInput

public interface Input

Interface to the input facilities. This allows polling the state of the keyboard, the touch screen and the accelerometer. On some backends (desktop, gwt, etc) the touch screen is replaced by mouse input. The accelerometer is of course not available on all backends.

Instead of polling for events, one can process all input events with an InputProcessor. You can set the InputProcessor via the setInputProcessor(InputProcessor) method. It will be called before the ApplicationListener.render() method in each frame.

Keyboard keys are translated to the constants in Input.Keys transparently on all systems. Do not use system specific key constants.

The class also offers methods to use (and test for the presence of) other input systems like vibration, compass, on-screen keyboards, and cursor capture. Support for simple input dialogs is also provided.

Author:

mzechner

Nested Class Summary

static class	Input.Buttons Mouse buttons.
static class	Input.Keys Keys.
static class	Input.Orientation
static class	Input.Peripheral Enumeration of potentially available peripherals.
static interface	Input.TextInputListener Callback interface for getTextInput(TextInputListener, String, String)

Method Summary

void	cancelVibrate() Stops the vibrator
float	getAccelerometerX()
float	getAccelerometerY()
float	getAccelerometerZ()
float	getAzimuth() The azimuth is the angle of the device's orientation around the z-axis.
long	getCurrentEventTime()
int	getDeltaX()
int	getDeltaX(int pointer)
int	getDeltaY()
int	getDeltaY(int pointer)
InputProcessor	getInputProcessor()
Input.Orientation	getNativeOrientation()
float	getPitch() The pitch is the angle of the device's orientation around the x-axis.
void	getPlaceholderTextInput(Input.TextInputListener listener, String title, String placeholder) System dependent method to input a string of text.
float	getRoll() The roll is the angle of the device's orientation around the y-axis.
int	getRotation()
void	getRotationMatrix(float[] matrix) Returns the rotation matrix describing the devices rotation as per SensorManager#getRotationMatrix(float[], float[], float[], float[]).
void	getTextInput(Input.TextInputListener listener, String title, String text) System dependent method to input a string of text.
int	getX()
int	getX(int pointer) Returns the x coordinate in screen coordinates of the given pointer.
int	getY()
int	getY(int pointer) Returns the y coordinate in screen coordinates of the given pointer.
boolean	isButtonPressed(int button) Whether a given button is pressed or not.
boolean	isCursorCatched()
boolean	isKeyPressed(int key) Returns whether the key is pressed.
boolean	isPeripheralAvailable(Input.Peripheral peripheral) Queries whether a Input.Peripheral is currently available.
boolean	isTouched()
boolean	isTouched(int pointer) Whether the screen is currently touched by the pointer with the given index.
boolean	justTouched()
void	setCatchBackKey(boolean catchBack) Sets whether the BACK button on Android should be caught.
void	setCatchMenuKey(boolean catchMenu) Sets whether the MENU button on Android should be caught.
void	setCursorCatched(boolean catched) Only viable on the desktop.
void	setCursorImage(Pixmap pixmap, int xHotspot, int yHotspot) Only viable on the desktop.
void	setCursorPosition(int x, int y) Only viable on the desktop.
void	setInputProcessor(InputProcessor processor) Sets the InputProcessor that will receive all touch and key input events.
void	setOnscreenKeyboardVisible(boolean visible) Sets the on-screen keyboard visible if available.
void	vibrate(int milliseconds) Vibrates for the given amount of time.
void	vibrate(long[] pattern, int repeat) Vibrate with a given pattern.

Method Detail

getAccelerometerX

float getAccelerometerX()

Returns:

The value of the accelerometer on its x-axis. ranges between [-10,10].

getAccelerometerY

float getAccelerometerY()

Returns:

The value of the accelerometer on its y-axis. ranges between [-10,10].

getAccelerometerZ

float getAccelerometerZ()

Returns:

The value of the accelerometer on its y-axis. ranges between [-10,10].

getX

int getX()

Returns:

The x coordinate of the last touch on touch screen devices and the current mouse position on desktop for the first pointer in screen coordinates. The screen origin is the top left corner.

getX

int getX(int pointer)

Returns the x coordinate in screen coordinates of the given pointer. Pointers are indexed from 0 to n. The pointer id identifies the order in which the fingers went down on the screen, e.g. 0 is the first finger, 1 is the second and so on. When two fingers are touched down and the first one is lifted the second one keeps its index. If another finger is placed on the touch screen the first free index will be used.

Parameters:

pointer - the pointer id.

Returns:

the x coordinate

getDeltaX

int getDeltaX()

Returns:

the different between the current pointer location and the last pointer location on the x-axis.

getDeltaX

int getDeltaX(int pointer)

Returns:

the different between the current pointer location and the last pointer location on the x-axis.

getY

int getY()

Returns:

The y coordinate of the last touch on touch screen devices and the current mouse position on desktop for the first pointer in screen coordinates. The screen origin is the top left corner.

getY

int getY(int pointer)

Returns the y coordinate in screen coordinates of the given pointer. Pointers are indexed from 0 to n. The pointer id identifies the order in which the fingers went down on the screen, e.g. 0 is the first finger, 1 is the second and so on. When two fingers are touched down and the first one is lifted the second one keeps its index. If another finger is placed on the touch screen the first free index will be used.

Parameters:

pointer - the pointer id.

Returns:

the y coordinate

getDeltaY

int getDeltaY()

Returns:

the different between the current pointer location and the last pointer location on the y-axis.

getDeltaY

int getDeltaY(int pointer)

Returns:

the different between the current pointer location and the last pointer location on the y-axis.

isTouched

boolean isTouched()

Returns:

whether the screen is currently touched.

justTouched

boolean justTouched()

Returns:

whether a new touch down event just occurred.

isTouched

boolean isTouched(int pointer)

Whether the screen is currently touched by the pointer with the given index. Pointers are indexed from 0 to n. The pointer id identifies the order in which the fingers went down on the screen, e.g. 0 is the first finger, 1 is the second and so on. When two fingers are touched down and the first one is lifted the second one keeps its index. If another finger is placed on the touch screen the first free index will be used.

Parameters:

pointer - the pointer

Returns:

whether the screen is touched by the pointer

isButtonPressed

boolean isButtonPressed(int button)

Whether a given button is pressed or not. Button constants can be found in Input.Buttons. On Android only the Button#LEFT constant is meaningful.

Parameters:

button - the button to check.

Returns:

whether the button is down or not.

isKeyPressed

boolean isKeyPressed(int key)

Returns whether the key is pressed.

Parameters:

key - The key code as found in Input.Keys.

Returns:

true or false.

getTextInput

void getTextInput(Input.TextInputListener listener,
                  String title,
                  String text)

System dependent method to input a string of text. A dialog box will be created with the given title and the given text as a message for the user. Once the dialog has been closed the provided Input.TextInputListener will be called on the rendering thread.

Parameters:

listener - The TextInputListener.

title - The title of the text input dialog.

text - The message presented to the user.

getPlaceholderTextInput

void getPlaceholderTextInput(Input.TextInputListener listener,
                             String title,
                             String placeholder)

System dependent method to input a string of text. A dialog box will be created with the given title and the given text as a hint message for the user. Once the dialog has been closed the provided Input.TextInputListener will be called on the rendering thread.

Parameters:

listener - The TextInputListener.

title - The title of the text input dialog.

placeholder - The placeholder text presented to the user.

setOnscreenKeyboardVisible

void setOnscreenKeyboardVisible(boolean visible)

Sets the on-screen keyboard visible if available.

Parameters:

visible - visible or not

vibrate

void vibrate(int milliseconds)

Vibrates for the given amount of time. Note that you'll need the permission in your manifest file in order for this to work.

Parameters:

milliseconds - the number of milliseconds to vibrate.

vibrate

void vibrate(long[] pattern,
             int repeat)

Vibrate with a given pattern. Pass in an array of ints that are the times at which to turn on or off the vibrator. The first one is how long to wait before turning it on, and then after that it alternates. If you want to repeat, pass the index into the pattern at which to start the repeat.

Parameters:

pattern - an array of longs of times to turn the vibrator on or off.

repeat - the index into pattern at which to repeat, or -1 if you don't want to repeat.

cancelVibrate

void cancelVibrate()

Stops the vibrator

getAzimuth

float getAzimuth()

The azimuth is the angle of the device's orientation around the z-axis. The positive z-axis points towards the earths center.

Returns:

the azimuth in degrees

See Also:

http://developer.android.com/reference/android/hardware/SensorManager.html#getRotationMatrix(float[], float[], float[], float[])

getPitch

float getPitch()

The pitch is the angle of the device's orientation around the x-axis. The positive x-axis roughly points to the west and is orthogonal to the z- and y-axis.

Returns:

the pitch in degrees

See Also:

http://developer.android.com/reference/android/hardware/SensorManager.html#getRotationMatrix(float[], float[], float[], float[])

getRoll

float getRoll()

The roll is the angle of the device's orientation around the y-axis. The positive y-axis points to the magnetic north pole of the earth.

Returns:

the roll in degrees

See Also:

http://developer.android.com/reference/android/hardware/SensorManager.html#getRotationMatrix(float[], float[], float[], float[])

getRotationMatrix

void getRotationMatrix(float[] matrix)

Returns the rotation matrix describing the devices rotation as per SensorManager#getRotationMatrix(float[], float[], float[], float[]). Does not manipulate the matrix if the platform does not have an accelerometer.

Parameters:

matrix -

getCurrentEventTime

long getCurrentEventTime()

Returns:

the time of the event currently reported to the InputProcessor.

setCatchBackKey

void setCatchBackKey(boolean catchBack)

Sets whether the BACK button on Android should be caught. This will prevent the app from being paused. Will have no effect on the desktop.

Parameters:

catchBack - whether to catch the back button

setCatchMenuKey

void setCatchMenuKey(boolean catchMenu)

Sets whether the MENU button on Android should be caught. This will prevent the onscreen keyboard to show up. Will have no effect on the desktop.

Parameters:

catchMenu - whether to catch the back button

setInputProcessor

void setInputProcessor(InputProcessor processor)

Sets the InputProcessor that will receive all touch and key input events. It will be called before the ApplicationListener.render() method each frame.

Parameters:

processor - the InputProcessor

getInputProcessor

InputProcessor getInputProcessor()

Returns:

the currently set InputProcessor or null.

isPeripheralAvailable

boolean isPeripheralAvailable(Input.Peripheral peripheral)

Queries whether a Input.Peripheral is currently available. In case of Android and the Input.Peripheral.HardwareKeyboard this returns the whether the keyboard is currently slid out or not.

Parameters:

peripheral - the Input.Peripheral

Returns:

whether the peripheral is available or not.

getRotation

int getRotation()

Returns:

the rotation of the device with respect to its native orientation.

getNativeOrientation

Input.Orientation getNativeOrientation()

Returns:

the native orientation of the device.

setCursorCatched

void setCursorCatched(boolean catched)

Only viable on the desktop. Will confine the mouse cursor location to the window and hide the mouse cursor.

Parameters:

catched - whether to catch or not to catch the mouse cursor

isCursorCatched

boolean isCursorCatched()

Returns:

whether the mouse cursor is catched.

setCursorPosition

void setCursorPosition(int x,
                       int y)

Only viable on the desktop. Will set the mouse cursor location to the given window coordinates (origin top-left corner).

Parameters:

x - the x-position

y - the y-position

setCursorImage

void setCursorImage(Pixmap pixmap,
                    int xHotspot,
                    int yHotspot)

Only viable on the desktop. Will set the mouse cursor image to the image represented by the Pixmap. The Pixmap must be in RGBA8888 format, width & height must be powers-of-two greater than zero (not necessarily equal), and alpha transparency must be single-bit (i.e., 0x00 or 0xFF only). To revert to the default operating system cursor, pass in a null Pixmap; xHotspot & yHotspot are ignored in this case.

Parameters:

pixmap - the mouse cursor image as a Pixmap, or null to revert to the default operating system cursor

xHotspot - the x location of the hotspot pixel within the cursor image (origin top-left corner)

yHotspot - the y location of the hotspot pixel within the cursor image (origin top-left corner)