Urho.Input Class

Input subsystem. Converts operating system window messages to input state and events.

See Also: Input

Syntax

public class Input : UrhoObject

Remarks

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 Input.SetMouseVisible.

You can subscribe to these events by using one of the SubscribeToXxx methods in UrhoObject:

  • MouseButtonUp: a mouse button was released.
  • MouseButtonDown: a mouse button was pressed.
  • MouseMove: the mouse moved.
  • MouseWheel: the mouse wheel moved.
  • KeyUp: a key was released.
  • KeyDown: a key was pressed.
  • TextInput: a string of translated text input in UTF8 format. May contain a single character or several.
  • JoystickConnected: a joystick was plugged in.
  • JoystickDisconnected: a joystick was disconnected.
  • JoystickButtonDown: a joystick button was pressed.
  • JoystickButtonUp: a joystick button was released.
  • JoystickAxisMove: a joystick axis was moved.
  • JoystickHatMove: a joystick POV hat was moved.
  • TouchBegin: a finger touched the screen.
  • TouchEnd: a finger was lifted from the screen.
  • TouchMove: a finger moved on the screen.
  • GestureRecorded : recording a touch gesture is complete.
  • GestureInput : a touch gesture was recognized.
  • MultiGesture : a multi-finger pinch/rotation touch gesture is underway.
  • DropFile : a file was drag-dropped on the application window.
  • InputFocus : application input focus or window minimization state changed.
  • MouseVisibleChanged : the visibility of the operating system mouse cursor was changed.
  • ExitRequested : application exit was requested (eg. with the window close button.)

Keyboard and Mouse Input

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.  Input.GetKeyPress and Input.GetMouseButtonPress return true only for one frame (the initiation) while Input.GetKeyDown and Input.GetMouseButtonDown return true as long as the key or button is held down. To check whether keys are down or pressed by scancode, use Input.GetScancodeDown and Input.GetScancodePress. Functions also exist for converting keycodes to scancodes or vice versa, or getting key names. See for example Input.GetKeyName and Input.GetKeyFromScancode.

Mouse motion since the last frame can be accessed with Input.GetMouseMove. The cursor position within the window can be queried with Input.GetMousePosition.

Mouse modes

The operating system mouse cursor can be used in four modes which can be switched with Input.MouseMode:

  • Absolute: is the default behaviour, allowing the toggling of operating system cursor visibility and allowing the cursor to escape the window when visible. When the operating system cursor is invisible in absolute mouse mode, the mouse is confined to the window. If the operating system and UI cursors are both invisible, interaction with the user interface will be limited (for example, drag move and drag end events will not trigger).    Setting this value to Absolute will call SetMouseGrabbed(false).
  • Relative: sets the operating system cursor to invisible and confines the cursor to the window. The operating system cursor cannot be set to be visible in this mode via SetMouseVisible(), however changes are tracked and will be restored when another mouse mode is set. When the virtual cursor is also invisible, UI interaction will still function as normal (eg: drag events will trigger). Setting this will call SetMouseGrabbed(true).

  • Wrap: grabs the mouse from the operating system and confines the operating system cursor to the window, wrapping the cursor when it is near the edges. Setting this will call SetMouseGrabbed(true).
  • Free: does not grab/confine the mouse cursor even when it is hidden. This can be used for cases where the cursor should render using the operating system outside the window, and perform custom rendering (with SetMouseVisible(false)) inside.

Joystick input

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 Input.GetJoystick to retrieve the joystick state by ID. In case you do not have the ID, you can also use Input.GetJoystickByIndex which uses a zero-based index; see Input.NumJoystick 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 .() to distinguish between a game controller and an unrecognized joystick.

On platforms that support the accelerometer, it will appear as a "virtual" joystick.

Touch input

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: Input.NumTouches and Urho.Input.GetTouch.

Touch gestures can be recorded using SDL's inbuilt $1 gesture recognition system. Use Input.RecordGesture to start recording. The following finger movements will be recorded until the finger is lifted, at which point the recording ends and the 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.

Whenever a recognized gesture is entered by the user, the 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: Input.RemoveGesture to selectively clear a gesture by its ID and Input.RemoveAllGestures to clear them all.

Touch input can also emulate a virtual joystick by displaying on-screen buttons. See the function Input.AddScreenJoystick.

Touch emulation can be used to test mobile applications on a desktop machine without a touch screen. See Input.TouchEmulation. 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.

Platform-specific details

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 .etScreenKeyboardVisible. The UI subsystem can also automatically show the virtual keyboard when a line editing 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.

Requirements

Namespace: Urho
Assembly: Urho (in Urho.dll)
Assembly Versions: 1.0.0.0

The members of Urho.Input are listed below.

See Also: UrhoObject

Public Constructors

Constructs a new instance of Urho.Input which is tied to the Application.CurrentContext.
Constructs a new instance of Urho.Input, given a raw pointer to an unmanaged object
Constructs a new instance of Urho.Input linked to a specific Context.

Protected Constructors

Empty constructor, chain to this constructor when you provide your own constructor that sets the handle field.

Public Properties

EnabledBoolean. Controls whether input is enabled or disabled.
[read-only]
MinimizedBoolean. Return whether application window is minimized.
[read-only]
MouseGrabbedBoolean. Return whether the mouse is currently being grabbed by an operation.
[read-only]
MouseLockedBoolean. Return whether the mouse is locked to the window
[read-only]
MouseModeMouseMode. Return the mouse mode. Or Set the mouse mode. 
[read-only]
MouseMoveIntVector2. Return mouse movement since last frame.
[read-only]
MouseMoveWheelInt32. Return mouse wheel movement since last frame.
[read-only]
MouseMoveXInt32. Return horizontal mouse movement since last frame.
[read-only]
MouseMoveYInt32. Return vertical mouse movement since last frame.
[read-only]
MousePositionIntVector2. Return mouse position within window. Should only be used with a visible mouse cursor.
[read-only]
MouseVisibleBoolean. Return whether the operating system mouse cursor is visible.
[read-only]
NumJoysticksUInt32. Return number of connected joysticks.
[read-only]
NumTouchesUInt32. Return number of active finger touches.
[read-only]
QualifiersInt32. Return the currently held down qualifiers.
[read-only]
ScreenKeyboardSupportBoolean. Return whether on-screen keyboard is supported.
ScreenKeyboardVisibleBoolean. Return whether on-screen keyboard is being shown; On platform that support it, setting this property displays the on-screen keyboard.
ToggleFullscreenBoolean. Return whether fullscreen toggle is enabled. Or Set whether ALT-ENTER fullscreen toggle is enabled.
TouchEmulationBoolean. Return whether touch emulation is enabled. Or Set touch emulation by mouse. Only available on desktop platforms. When enabled, actual mouse events are no longer sent and the mouse cursor is forced visible.
[read-only]
override
TypeStringHash. Urho's type system type.
[read-only]
override
TypeNameString. Urho's low-level type name.
[read-only]
static
TypeNameStaticString. Urho's low-level type name, accessible as a static method.
[read-only]
static
TypeStaticStringHash. Urho's low-level type, accessible as a static method.

Public Methods

AddScreenJoystick(XmlFile, XmlFile) : Int32
CenterMousePosition()
Center the mouse position.
GetJoystick(Int32) : JoystickState*
Return joystick state by ID, or null if does not exist.
GetJoystickByIndex(UInt32) : JoystickState*
Return joystick state by index, or null if does not exist. 0 = first connected joystick.
GetJoystickByName(String) : JoystickState*
GetKeyDown(Key) : Boolean
Check if a key is held down.
GetKeyFromName(String) : Int32
Return keycode from key name.
GetKeyFromScancode(Int32) : Int32
Return keycode from scancode.
GetKeyName(Key) : String
Return name of key from keycode.
GetKeyPress(Key) : Boolean
Check if a key has been pressed on this frame.
GetMouseButtonDown(MouseButton) : Boolean
Check if a mouse button is held down.
GetMouseButtonPress(MouseButton) : Boolean
Check if a mouse button has been pressed on this frame.
GetQualifierDown(Int32) : Boolean
Check if a qualifier key is held down.
GetQualifierPress(Int32) : Boolean
Check if a qualifier key has been pressed on this frame.
GetScancodeDown(Int32) : Boolean
Check if a key is held down by scancode.
GetScancodeFromKey(Key) : Int32
Return scancode from keycode.
GetScancodeFromName(String) : Int32
Return scancode from key name.
GetScancodeName(Int32) : String
Return name of key from scancode.
GetScancodePress(Int32) : Boolean
Check if a key has been pressed on this frame by scancode.
GetTouch(UInt32) : TouchState
Return active finger touch by index.
HasFocus() : Boolean
Return whether application window has input focus.
IsScreenJoystickVisible(Int32) : Boolean
Return whether a virtual joystick is visible.
LoadGestures(File) : UInt32
LoadGestures(MemoryBuffer) : UInt32
RecordGesture() : Boolean
Begin recording a touch gesture. Return true if successful. The E_GESTURERECORDED event (which contains the ID for the new gesture) will be sent when recording finishes.
RemoveAllGestures()
Remove all in-memory gestures.
RemoveGesture(UInt32) : Boolean
Remove an in-memory gesture by ID. Return true if was found.
RemoveScreenJoystick(Int32) : Boolean
Remove screen joystick by instance ID. Return true if successful. This method should only be called in main thread.
ResetMouseGrabbed()
Reset the mouse grabbed to the last unsuppressed SetMouseGrabbed call
ResetMouseMode()
Reset the last mouse mode that wasn't suppressed in SetMouseMode
ResetMouseVisible()
Reset last mouse visibility that was not suppressed in SetMouseVisible.
SaveGesture(File, UInt32) : Boolean
SaveGesture(MemoryBuffer, UInt32) : Boolean
SaveGestures(File) : Boolean
SaveGestures(MemoryBuffer) : Boolean
SetMouseGrabbed(Boolean, Boolean)
SetMouseMode(MouseMode, Boolean)
SetMousePosition(IntVector2)
SetMouseVisible(Boolean, Boolean)
Set whether the operating system mouse cursor is visible. When not visible (default), is kept centered to prevent leaving the window. Mouse visibility event can be suppressed-- this also recalls any unsuppressed SetMouseVisible which can be returned by ResetMouseVisible().
SetScreenJoystickVisible(Int32, Boolean)
Set whether the virtual joystick is visible.
SubscribeToDropFile(Action<DropFileEventArgs>) : Subscription
Subscribes to the DropFile event raised by the Input.
SubscribeToExitRequested(Action<ExitRequestedEventArgs>) : Subscription
Subscribes to the ExitRequested event raised by the Input.
SubscribeToGestureInput(Action<GestureInputEventArgs>) : Subscription
Subscribes to the GestureInput event raised by the Input.
SubscribeToGestureRecorded(Action<GestureRecordedEventArgs>) : Subscription
Subscribes to the GestureRecorded event raised by the Input.
SubscribeToInputFocus(Action<InputFocusEventArgs>) : Subscription
Subscribes to the InputFocus event raised by the Input.
SubscribeToJoystickAxisMove(Action<JoystickAxisMoveEventArgs>) : Subscription
Subscribes to the JoystickAxisMove event raised by the Input.
SubscribeToJoystickButtonDown(Action<JoystickButtonDownEventArgs>) : Subscription
Subscribes to the JoystickButtonDown event raised by the Input.
SubscribeToJoystickButtonUp(Action<JoystickButtonUpEventArgs>) : Subscription
Subscribes to the JoystickButtonUp event raised by the Input.
SubscribeToJoystickConnected(Action<JoystickConnectedEventArgs>) : Subscription
Subscribes to the JoystickConnected event raised by the Input.
SubscribeToJoystickDisconnected(Action<JoystickDisconnectedEventArgs>) : Subscription
Subscribes to the JoystickDisconnected event raised by the Input.
SubscribeToJoystickHatMove(Action<JoystickHatMoveEventArgs>) : Subscription
Subscribes to the JoystickHatMove event raised by the Input.
SubscribeToKeyDown(Action<KeyDownEventArgs>) : Subscription
Subscribes to the KeyDown event raised by the Input.
SubscribeToKeyUp(Action<KeyUpEventArgs>) : Subscription
Subscribes to the KeyUp event raised by the Input.
SubscribeToMouseButtonDown(Action<MouseButtonDownEventArgs>) : Subscription
Subscribes to the MouseButtonDown event raised by the Input.
SubscribeToMouseButtonUp(Action<MouseButtonUpEventArgs>) : Subscription
Subscribes to the MouseButtonUp event raised by the Input.
SubscribeToMouseModeChanged(Action<MouseModeChangedEventArgs>) : Subscription
Subscribes to the MouseModeChanged event raised by the Input.
SubscribeToMouseMoved(Action<MouseMovedEventArgs>) : Subscription
Subscribes to the MouseMoved event raised by the Input.
SubscribeToMouseVisibleChanged(Action<MouseVisibleChangedEventArgs>) : Subscription
Subscribes to the MouseVisibleChanged event raised by the Input.
SubscribeToMouseWheel(Action<MouseWheelEventArgs>) : Subscription
Subscribes to the MouseWheel event raised by the Input.
SubscribeToMultiGesture(Action<MultiGestureEventArgs>) : Subscription
Subscribes to the MultiGesture event raised by the Input.
SubscribeToTextInput(Action<TextInputEventArgs>) : Subscription
Subscribes to the TextInput event raised by the Input.
SubscribeToTouchBegin(Action<TouchBeginEventArgs>) : Subscription
Subscribes to the TouchBegin event raised by the Input.
SubscribeToTouchEnd(Action<TouchEndEventArgs>) : Subscription
Subscribes to the TouchEnd event raised by the Input.
SubscribeToTouchMove(Action<TouchMoveEventArgs>) : Subscription
Subscribes to the TouchMove event raised by the Input.
TryGetJoystickState(UInt32, out JoystickState) : Boolean
Update()
Poll for window messages. Called by HandleBeginFrame().

Public Events