Package com.badlogic.gdx

Interface Input

  • All Known Implementing Classes:
    AbstractInput, 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.

    • Method Detail

      • getAccelerometerX

        float getAccelerometerX()
        Returns:
        The acceleration force in m/s^2 applied to the device in the X axis, including the force of gravity

      • getAccelerometerY

        float getAccelerometerY()
        Returns:
        The acceleration force in m/s^2 applied to the device in the Y axis, including the force of gravity

      • getAccelerometerZ

        float getAccelerometerZ()
        Returns:
        The acceleration force in m/s^2 applied to the device in the Z axis, including the force of gravity

      • getGyroscopeX

        float getGyroscopeX()
        Returns:
        The rate of rotation in rad/s around the X axis

      • getGyroscopeY

        float getGyroscopeY()
        Returns:
        The rate of rotation in rad/s around the Y axis

      • getGyroscopeZ

        float getGyroscopeZ()
        Returns:
        The rate of rotation in rad/s around the Z axis

      • getMaxPointers

        int getMaxPointers()
        Returns:
        The maximum number of pointers supported

      • 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

      • getPressure

        float getPressure()
        Returns:
        the pressure of the first pointer

      • getPressure

        float getPressure​(int pointer)
        Returns the pressure of the given pointer, where 0 is untouched. On Android it should be up to 1.0, but it can go above that slightly and its not consistent between devices. On iOS 1.0 is the normal touch and significantly more of hard touch. Check relevant manufacturer documentation for details. Check availability with isPeripheralAvailable(Peripheral). If not supported, returns 1.0 when touched.
        Parameters:
        pointer - the pointer id.
        Returns:
        the pressure

      • 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 Buttons#LEFT constant is meaningful before version 4.0.
        Parameters:
        button - the button to check.
        Returns:
        whether the button is down or not.

      • isButtonJustPressed

        boolean isButtonJustPressed​(int button)
        Returns whether a given button has just been pressed. Button constants can be found in Input.Buttons. On Android only the Buttons#LEFT constant is meaningful before version 4.0. On WebGL (GWT), only LEFT, RIGHT and MIDDLE buttons are supported.
        Parameters:
        button - the button to check.
        Returns:
        true or false.

      • 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.

      • isKeyJustPressed

        boolean isKeyJustPressed​(int key)
        Returns whether the key has just been pressed.
        Parameters:
        key - The key code as found in Input.Keys.
        Returns:
        true or false.

      • getTextInput

        void getTextInput​(Input.TextInputListener listener,
                  java.lang.String title,
                  java.lang.String text,
                  java.lang.String hint)
        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. Will use the Default keyboard type. 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.

      • getTextInput

        void getTextInput​(Input.TextInputListener listener,
                  java.lang.String title,
                  java.lang.String text,
                  java.lang.String hint,
                  Input.OnscreenKeyboardType type)
        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.
        type - which type of keyboard we wish to display

      • setOnscreenKeyboardVisible

        void setOnscreenKeyboardVisible​(boolean visible)
        Sets the on-screen keyboard visible if available. Will use the Default keyboard type.
        Parameters:
        visible - visible or not

      • setOnscreenKeyboardVisible

        void setOnscreenKeyboardVisible​(boolean visible,
                                Input.OnscreenKeyboardType type)
        Sets the on-screen keyboard visible if available.
        Parameters:
        visible - visible or not
        type - which type of keyboard we wish to display. Can be null when hiding

      • vibrate

        void vibrate​(int milliseconds)
        Generates a simple haptic effect of a given duration or a vibration effect on devices without haptic capabilities. Note that on Android backend you'll need the permission in your manifest file in order for this to work. On iOS backend you'll need to set useHaptics = true for devices with haptics capabilities to use them.
        Parameters:
        milliseconds - the number of milliseconds to vibrate.

      • vibrate

        void vibrate​(int milliseconds,
             boolean fallback)
        Generates a simple haptic effect of a given duration and default amplitude. Note that on Android backend you'll need the permission in your manifest file in order for this to work. On iOS backend you'll need to set useHaptics = true for devices with haptics capabilities to use them.
        Parameters:
        milliseconds - the duration of the haptics effect
        fallback - whether to use non-haptic vibrator on devices without haptics capabilities (or haptics disabled). Fallback non-haptic vibrations may ignore length parameter in some backends.

      • vibrate

        void vibrate​(int milliseconds,
             int amplitude,
             boolean fallback)
        Generates a simple haptic effect of a given duration and amplitude. Note that on Android backend you'll need the permission in your manifest file in order for this to work. On iOS backend you'll need to set useHaptics = true for devices with haptics capabilities to use them.
        Parameters:
        milliseconds - the duration of the haptics effect
        amplitude - the amplitude/strength of the haptics effect. Valid values in the range [0, 255].
        fallback - whether to use non-haptic vibrator on devices without haptics capabilities (or haptics disabled). Fallback non-haptic vibrations may ignore length and/or amplitude parameters in some backends.

      • vibrate

        void vibrate​(Input.VibrationType vibrationType)
        Generates a simple haptic effect of a type. VibrationTypes are length/amplitude haptic effect presets that depend on each device and are defined by manufacturers. Should give most consistent results across devices and OSs. Note that on Android backend you'll need the permission in your manifest file in order for this to work. On iOS backend you'll need to set useHaptics = true for devices with haptics capabilities to use them.
        Parameters:
        vibrationType - the type of vibration

      • getCurrentEventTime

        long getCurrentEventTime()
        Returns:
        the time of the event currently reported to the InputProcessor.

      • setCatchBackKey

        @Deprecated
void setCatchBackKey​(boolean catchBack)
        Deprecated.
        use setCatchKey(int keycode, boolean catchKey) instead 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

      • isCatchBackKey

        @Deprecated
boolean isCatchBackKey()
        Deprecated.
        use isCatchKey(int keycode) instead
        Returns:
        whether the back button is currently being caught

      • setCatchMenuKey

        @Deprecated
void setCatchMenuKey​(boolean catchMenu)
        Deprecated.
        use setCatchKey(int keycode, boolean catchKey) instead 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 menu button

      • isCatchMenuKey

        @Deprecated
boolean isCatchMenuKey()
        Deprecated.
        use isCatchKey(int keycode) instead
        Returns:
        whether the menu button is currently being caught

      • setCatchKey

        void setCatchKey​(int keycode,
                 boolean catchKey)
        Sets whether the given key on Android or GWT should be caught. No effect on other platforms. All keys that are not caught may be handled by other apps or background processes on Android, or may trigger default browser behaviour on GWT. For example, media or volume buttons are handled by background media players if present, or Space key triggers a scroll. All keys you need to control your game should be caught to prevent unintended behaviour.
        Parameters:
        keycode - keycode to catch
        catchKey - whether to catch the given keycode

      • isCatchKey

        boolean isCatchKey​(int keycode)
        Parameters:
        keycode - keycode to check if caught
        Returns:
        true if the given keycode is configured to be caught

      • 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. X and y coordinates are still reported as if the mouse was not catched.
        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