|
Dry
|
The Input subsystem provides keyboard, mouse, joystick and touch input both via a polled interface and events. This subsystem is also used for querying whether the application window has input focus or is minimized.
The subsystem is always instantiated, even in headless mode, but is active only once the application window has been created. Once active, the subsystem takes over the operating system mouse cursor. It will be hidden by default, so the UI should be used to render a software cursor if necessary. For editor-like applications the operating system cursor can be made visible by calling SetMouseVisible().
The input events include:
Key events include both the symbolic keycode ("Key") that depends on the keyboard layout, the layout- and operating system-independent SDL scancode ("Scancode"), and the true operating system-specific raw keycode ("Raw").
The input polling API differentiates between the initiation of a key/mouse button press, and holding the key or button down. GetKeyPress() and GetMouseButtonPress() return true only for one frame (the initiation) while GetKeyDown() and GetMouseButtonDown() return true as long as the key or button is held down. To check whether keys are down or pressed by scancode, use GetScancodeDown() and GetScancodePress(). Functions also exist for converting keycodes to scancodes or vice versa, or getting key names. See for example GetKeyName() and GetKeyFromScancode().
Mouse motion since the last frame can be accessed with GetMouseMove(). The cursor position within the window can be queried with GetMousePosition().
In AngelScript, the polling API is accessed via properties: input.keyDown[], input.keyPress[], input.scancodeDown[], input.scancodePress[], input.mouseButtonDown[], input.mouseButtonPress[], input.mouseMove, input.mousePosition.
The operating system mouse cursor can be used in four modes which can be switched with SetMouseMode().
Plugged in joysticks will begin sending input events automatically. Each joystick will be assigned a joystick ID which will be used in subsequent joystick events, as well as for retrieving the joystick state. Use GetJoystick() to retrieve the joystick state by ID. In case you do not have the ID, you can also use GetJoystickByIndex() which uses a zero-based index; see GetNumJoysticks() for the number of currently connected joysticks. The ID, as well as the joystick name, can be looked up from the joystick state.
If the joystick model is recognized by SDL as a game controller the buttons and axes mappings utilize known constants such as CONTROLLER_BUTTON_A or CONTROLLER_AXIS_LEFTX without having to guess them. Use IsController() to distinguish between a game controller and an unrecognized joystick.
On platforms that support the accelerometer, it will appear as a "virtual" joystick.
On platforms where touch input is available, touch begin/end/move events will be sent, as well as multi-gesture events with pinch/rotation delta values when more than one finger is pressed down. The current finger touches can also be accessed via a polling API: GetNumTouches() and GetTouch().
Touch gestures can be recorded using SDL's inbuilt $1 gesture recognition system. Use RecordGesture() to start recording. The following finger movements will be recorded until the finger is lifted, at which point the recording ends and the E_GESTURERECORDED event is sent with the hash ID of the new gesture. The current in-memory gesture(s) can be saved or loaded as binary data using the SaveGestures(), SaveGesture(), LoadGestures() functions.
Whenever a recognized gesture is entered by the user, the E_GESTUREINPUT event will be sent. In addition to the ID of the best matched gesture, it contains the center position and an error metric (lower = better) to help filter out false gestures.
Note that all recorded (whether saved or not) and loaded gestures are held in-memory. Two additional functions are available to clear them: RemoveGesture() to selectively clear a gesture by its ID and RemoveAllGestures() to clear them all.
Touch input can also emulate a virtual joystick by displaying on-screen buttons. See the function AddScreenJoystick().
Touch emulation can be used to test mobile applications on a desktop machine without a touch screen. See SetTouchEmulation(). When touch emulation is enabled, actual mouse events are no longer sent and the operating system mouse cursor is forced visible. The left mouse button acts as a moving finger, while the rest of the mouse buttons act as stationary fingers for multi-finger gestures. For example pressing down both left and right mouse buttons, then dragging the mouse with the buttons still pressed would emulate a two-finger pinch zoom-in gesture.
On platforms that support it (such as Android) an on-screen virtual keyboard can be shown or hidden. When shown, keypresses from the virtual keyboard will be sent as text input events just as if typed from an actual keyboard. Show or hide it by calling SetScreenKeyboardVisible(). The UI subsystem can also automatically show the virtual keyboard when a LineEdit element is focused, and hide it when defocused. This behavior can be controlled by calling SetUseScreenKeyboard().
On Windows the user must first touch the screen once before touch input is activated. Trying to record or load touch gestures will fail before that.
1.8.13