Urho3D::Input Class Reference

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

#include <Urho3D/Input/Input.h>

Inheritance diagram for Urho3D::Input:

Public Member Functions
	Input (Context *context)
	Construct.
	~Input () override
	Destruct.
void	Update ()
	Poll for window messages. Called by HandleBeginFrame().
void	SetToggleFullscreen (bool enable)
void	SetMouseVisible (bool enable, bool suppressEvent=false)
	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().
void	ResetMouseVisible ()
	Reset last mouse visibility that was not suppressed in SetMouseVisible.
void	SetMouseGrabbed (bool grab, bool suppressEvent=false)
	Set whether the mouse is currently being grabbed by an operation.
void	ResetMouseGrabbed ()
	Reset the mouse grabbed to the last unsuppressed SetMouseGrabbed call.
void	SetMouseMode (MouseMode mode, bool suppressEvent=false)
	Set the mouse mode.
void	ResetMouseMode ()
	Reset the last mouse mode that wasn't suppressed in SetMouseMode.
SDL_JoystickID	AddScreenJoystick (XMLFile *layoutFile=nullptr, XMLFile *styleFile=nullptr)
	Add screen joystick.
bool	RemoveScreenJoystick (SDL_JoystickID id)
	Remove screen joystick by instance ID.
void	SetScreenJoystickVisible (SDL_JoystickID id, bool enable)
void	SetScreenKeyboardVisible (bool enable)
void	SetTouchEmulation (bool enable)
void	SetExplicitWindowRect (const IntRect &rect)
	Set explicit window rectangle in system coordinates explicitly.
void	ResetExplicitWindowRect ()
	Disable explicit window rectangle.
bool	RecordGesture ()
	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.
bool	SaveGestures (Serializer &dest)
	Save all in-memory touch gestures. Return true if successful.
bool	SaveGesture (Serializer &dest, unsigned gestureID)
	Save a specific in-memory touch gesture to a file. Return true if successful.
unsigned	LoadGestures (Deserializer &source)
	Load touch gestures from a file. Return number of loaded gestures, or 0 on failure.
bool	RemoveGesture (unsigned gestureID)
	Remove an in-memory gesture by ID. Return true if was found.
void	RemoveAllGestures ()
	Remove all in-memory gestures.
void	SetMousePosition (const IntVector2 &position)
void	CenterMousePosition ()
	Center the mouse position.
bool	GetKeyDown (Key key) const
bool	GetKeyPress (Key key) const
bool	GetScancodeDown (Scancode scancode) const
bool	GetScancodePress (Scancode scancode) const
bool	GetMouseButtonDown (MouseButtonFlags button) const
bool	GetMouseButtonPress (MouseButtonFlags button) const
bool	GetMouseButtonClick (MouseButtonFlags button) const
	Check if a mouse button was pressed and released without moving within a short duration of time.
bool	GetQualifierDown (Qualifier qualifier) const
bool	GetQualifierPress (Qualifier qualifier) const
QualifierFlags	GetQualifiers () const
IntVector2	GetMousePosition () const
Vector2	GetRelativeMousePosition () const
	Return relative mouse position in range [0, 1].
IntVector2	GetMouseMove () const
int	GetMouseMoveX () const
int	GetMouseMoveY () const
int	GetMouseMoveWheel () const
Vector2	GetSystemToBackbufferScale () const
IntVector2	SystemToBackbuffer (const IntVector2 &value) const
	Convert system position or delta to backbuffer one.
IntVector2	BackbufferToSystem (const IntVector2 &value) const
	Convert backbuffer position or delta to system one.
unsigned	GetNumTouches () const
TouchState *	GetTouch (unsigned index) const
TouchState *	GetTouchById (int touchId) const
	Return active finger touch by touch id.
unsigned	GetNumJoysticks () const
JoystickState *	GetJoystick (SDL_JoystickID id)
JoystickState *	GetJoystickByIndex (unsigned index)
JoystickState *	GetJoystickByName (const ea::string &name)
	Return joystick state by joystick id, or null if does not exist.
SDL_JoystickID	FindAccelerometerJoystickId () const
	Return joystick id that provides readings from accelerometer sensor. Return -1 if accelerometer not found.
bool	GetToggleFullscreen () const
bool	IsScreenJoystickVisible (SDL_JoystickID id) const
bool	GetScreenKeyboardSupport () const
bool	IsScreenKeyboardVisible () const
bool	GetTouchEmulation () const
bool	IsMouseVisible () const
bool	IsMouseGrabbed () const
bool	IsMouseLocked () const
MouseMode	GetMouseMode () const
bool	HasFocus ()
bool	IsMinimized () const
void	SetEnabled (bool enabled)
	Enable input reporting. When disabled, only E_SDLRAWINPUT event will be sent sent.
bool	GetEnabled () const
	Return true if input reporting is enabled.
IntVector2	GetGlobalWindowPosition () const
IntVector2	GetGlobalWindowSize () const
IntVector2	GetBackbufferSize () const
Public Member Functions inherited from Urho3D::Object
	Object (Context *context)
	Construct.
	~Object () override
	Destruct. Clean up self from event sender & receiver structures.
virtual StringHash	GetType () const =0
virtual const ea::string &	GetTypeName () const =0
virtual const TypeInfo *	GetTypeInfo () const =0
	Return type info.
virtual bool	IsInstanceOf (StringHash type) const =0
	Check whether current instance implements specified type.
virtual void	OnEvent (Object *sender, StringHash eventType, VariantMap &eventData)
	Handle event.
virtual void	SerializeInBlock (Archive &archive)
	Serialize content from/to archive. May throw ArchiveException.
template<typename T >
bool	IsInstanceOf () const
	Check current instance is type of specified class.
template<typename T >
T *	Cast ()
	Cast the object to specified most derived class.
template<typename T >
const T *	Cast () const
	Cast the object to specified most derived class.
void	SubscribeToEventManual (StringHash eventType, EventHandler *handler)
	Subscribe to an event that can be sent by any sender.
void	SubscribeToEventManual (Object *sender, StringHash eventType, EventHandler *handler)
	Subscribe to a specific sender's event.
template<class T >
void	SubscribeToEvent (StringHash eventType, T handler)
	Subscribe to an event that can be sent by any sender.
template<class T >
void	SubscribeToEvent (Object *sender, StringHash eventType, T handler)
	Subscribe to a specific sender's event.
void	UnsubscribeFromEvent (StringHash eventType)
	Unsubscribe from an event.
void	UnsubscribeFromEvent (Object *sender, StringHash eventType)
	Unsubscribe from a specific sender's event.
void	UnsubscribeFromEvents (Object *sender)
	Unsubscribe from a specific sender's events.
void	UnsubscribeFromAllEvents ()
	Unsubscribe from all events.
void	UnsubscribeFromAllEventsExcept (const ea::vector< StringHash > &exceptions)
	Unsubscribe from all events except those listed.
void	UnsubscribeFromAllEventsExcept (const ea::vector< Object * > &exceptions)
	Unsubscribe from all events except those with listed senders.
void	SendEvent (StringHash eventType)
	Send event to all subscribers.
void	SendEvent (StringHash eventType, VariantMap &eventData)
	Send event with parameters to all subscribers.
VariantMap &	GetEventDataMap () const
	Return a preallocated map for event data. Used for optimization to avoid constant re-allocation of event data maps.
template<typename... Args>
void	SendEvent (StringHash eventType, const Args &... args)
	Send event with variadic parameter pairs to all subscribers. The parameters are (paramID, paramValue) pairs.
Context *	GetContext () const
	Return execution context.
const Variant &	GetGlobalVar (StringHash key) const
const VariantMap &	GetGlobalVars () const
void	SetGlobalVar (StringHash key, const Variant &value)
Object *	GetSubsystem (StringHash type) const
	Return subsystem by type.
Object *	GetEventSender () const
	Return active event sender. Null outside event handling.
EventHandler *	GetEventHandler () const
	Return active event handler. Null outside event handling.
bool	HasSubscribedToEvent (StringHash eventType) const
	Return whether has subscribed to an event without specific sender.
bool	HasSubscribedToEvent (Object *sender, StringHash eventType) const
	Return whether has subscribed to a specific sender's event.
bool	HasEventHandlers () const
	Return whether has subscribed to any event.
template<class T >
T *	GetSubsystem () const
	Template version of returning a subsystem.
const ea::string &	GetCategory () const
void	SendEvent (StringHash eventType, const VariantMap &eventData)
	Send event with parameters to all subscribers.
void	SetBlockEvents (bool block)
	Block object from sending and receiving events.
bool	GetBlockEvents () const
	Return sending and receiving events blocking status.
Public Member Functions inherited from Urho3D::RefCounted
	RefCounted ()
	Construct. Allocate the reference count structure and set an initial self weak reference.
virtual	~RefCounted ()
	Destruct. Mark as expired and also delete the reference count structure if no outside weak references exist.
	RefCounted (const RefCounted &rhs)=delete
	Prevent copy construction.
RefCounted &	operator= (const RefCounted &rhs)=delete
	Prevent assignment.
int	AddRef ()
int	ReleaseRef ()
int	Refs () const
int	WeakRefs () const
RefCount *	RefCountPtr () const
	Return pointer to the reference count structure.
bool	HasScriptObject () const
	Return true if script runtime object wrapping this native object exists.
bool	IsScriptStrongRef () const
	Return true if script reference is strong.

Static Public Member Functions
static Key	GetKeyFromName (const ea::string &name)
	Return keycode from key name.
static Key	GetKeyFromScancode (Scancode scancode)
	Return keycode from scancode.
static ea::string	GetKeyName (Key key)
	Return name of key from keycode.
static Scancode	GetScancodeFromKey (Key key)
	Return scancode from keycode.
static Scancode	GetScancodeFromName (const ea::string &name)
	Return scancode from key name.
static ea::string	GetScancodeName (Scancode scancode)
	Return name of key from scancode.
static ea::string	GetMouseButtonName (MouseButton button)
	Return name of mouse button from code.
Static Public Member Functions inherited from Urho3D::Object
static const TypeInfo *	GetTypeInfoStatic ()
	Return type info static.

Public Attributes
PrioritySignal< void(SDL_Event &evt, bool &consumed), RawInputPriority >	OnRawInput
	Low-level input sink. User is responsible for checking "consumed" flag.

Private Member Functions
	URHO3D_OBJECT (Input, Object)
void	Initialize ()
	Initialize when screen mode initially set.
SDL_JoystickID	OpenJoystick (unsigned index)
	Open a joystick and return its ID. Return -1 if no joystick.
void	ResetJoysticks ()
	Setup internal joystick structures.
void	GainFocus ()
	Prepare input state for application gaining input focus.
void	LoseFocus ()
	Prepare input state for application losing input focus.
void	ResetState ()
	Clear input state.
void	ResetTouches ()
	Clear touch states and send touch end events.
void	ResetInputAccumulation ()
	Reset input accumulation.
unsigned	GetTouchIndexFromID (int touchID)
	Get the index of a touch based on the touch ID.
unsigned	PopTouchIndex ()
	Used internally to return and remove the next available touch index.
void	PushTouchIndex (int touchID)
	Push a touch index back into the list of available when finished with it.
void	SendInputFocusEvent ()
	Send an input focus or window minimization change event.
void	SetMouseButton (MouseButton button, bool newState, int clicks)
	Handle a mouse button change.
void	SetKey (Key key, Scancode scancode, bool newState)
	Handle a key change.
void	SetMouseWheel (int delta)
	Handle mouse wheel change.
void	SuppressNextMouseMove ()
	Suppress next mouse movement.
void	UnsuppressMouseMove ()
	Unsuppress mouse movement.
void	HandleScreenMode (StringHash eventType, VariantMap &eventData)
	Handle screen mode event.
void	HandleBeginFrame (StringHash eventType, VariantMap &eventData)
	Handle frame start event.
void	HandleScreenJoystickTouch (StringHash eventType, VariantMap &eventData)
	Handle touch events from the controls of screen joystick(s).
void	HandleSDLEvent (void *sdlEvent)
	Handle SDL event.
void	OnSDLRawInput (SDL_Event &evt, bool &consumed)
	Send SDLRawInput event.
void	SetMouseModeRelative (SDL_bool enable)
	Set SDL mouse mode relative.
void	SetMouseModeAbsolute (SDL_bool enable)
	Set SDL mouse mode absolute.

Private Attributes
WeakPtr< Graphics >	graphics_
	Graphics subsystem.
ea::hash_set< int >	keyDown_
	Key down state.
ea::hash_set< int >	keyPress_
	Key pressed state.
ea::hash_set< int >	scancodeDown_
	Key down state by scancode.
ea::hash_set< int >	scancodePress_
	Key pressed state by scancode.
ea::unordered_map< int, TouchState >	touches_
	Active finger touches.
ea::list< int >	availableTouchIDs_
	List that maps between event touch IDs and normalised touch IDs.
ea::unordered_map< int, int >	touchIDMap_
	Mapping of touch indices.
ea::string	textInput_
	String for text input.
ea::unordered_map< SDL_JoystickID, JoystickState >	joysticks_
	Opened joysticks.
MouseButtonFlags	mouseButtonDown_
	Mouse buttons' down state.
MouseButtonFlags	mouseButtonPress_
	Mouse buttons' pressed state.
MouseButtonFlags	mouseButtonClick_
	Mouse buttons' clicked state.
IntVector2	mousePressPosition_
	Position when last mouse button was pressed.
Timer	mousePressTimer_
	Time since last mouse press.
IntVector2	lastMousePosition_
	Last mouse position for calculating movement.
IntVector2	lastVisibleMousePosition_
	Last mouse position before being set to not visible.
IntVector2	mouseMove_
	Mouse movement since last frame.
int	mouseMoveWheel_
	Mouse wheel movement since last frame.
Vector2	systemToBackbufferScale_
	Input coordinate scaling. Non-unity when window and backbuffer have different sizes (e.g. Retina display).
unsigned	windowID_
	SDL window ID.
bool	toggleFullscreen_
	Fullscreen toggle flag.
bool	mouseVisible_
	Operating system mouse cursor visible flag.
bool	lastMouseVisible_
	The last operating system mouse cursor visible flag set by end use call to SetMouseVisible.
bool	mouseGrabbed_
	Flag to indicate the mouse is being grabbed by an operation. Subsystems like UI that uses mouse should temporarily ignore the mouse hover or click events.
bool	lastMouseGrabbed_
	The last mouse grabbed set by SetMouseGrabbed.
MouseMode	mouseMode_
	Determines the mode of mouse behaviour.
MouseMode	lastMouseMode_
	The last mouse mode set by SetMouseMode.
bool	sdlMouseRelative_
	Flag to determine whether SDL mouse relative was used.
bool	touchEmulation_
	Touch emulation mode flag.
bool	inputFocus_
	Input focus flag.
bool	minimized_
	Minimized flag.
bool	focusedThisFrame_
	Gained focus on this frame flag.
bool	suppressNextMouseMove_
	Next mouse move suppress flag.
bool	mouseMoveScaled_
	Whether mouse move is accumulated in backbuffer scale or not (when using events directly).
bool	initialized_
	Initialized flag.
bool	enabled_ = true
	Flag indicating that input subsystem is reporting events.
ea::optional< IntRect >	explicitWindowRect_
	Explicitly specified window rectangle.

Additional Inherited Members
Static Public Attributes inherited from Urho3D::Object
static constexpr ea::array< StringHash, 0 >	TypeHierarchy {}
Protected Attributes inherited from Urho3D::Object
WeakPtr< Context >	context_
	Execution context.

Detailed Description

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

Member Function Documentation

AddScreenJoystick()

SDL_JoystickID Urho3D::Input::AddScreenJoystick	(	XMLFile *	layoutFile = nullptr,
		XMLFile *	styleFile = nullptr
	)

Add screen joystick.

Return the joystick instance ID when successful or negative on error. If layout file is not given, use the default screen joystick layout. If style file is not given, use the default style file from root UI element.

This method should only be called in main thread.

GetGlobalWindowPosition()

IntVector2 Urho3D::Input::GetGlobalWindowPosition

(

)

const

Helpers to handle global mouse position.

GetJoystick()

JoystickState * Urho3D::Input::GetJoystick

(

SDL_JoystickID

id

)

Return joystick state by ID, or null if does not exist.

GetJoystickByIndex()

JoystickState * Urho3D::Input::GetJoystickByIndex

(

unsigned

index

)

Return joystick state by index, or null if does not exist. 0 = first connected joystick.

GetKeyDown()

bool Urho3D::Input::GetKeyDown

(

Key

key

)

const

Check if a key is held down.

GetKeyPress()

bool Urho3D::Input::GetKeyPress

(

Key

key

)

const

Check if a key has been pressed on this frame.

GetMouseButtonDown()

bool Urho3D::Input::GetMouseButtonDown

(

MouseButtonFlags

button

)

const

Check if a mouse button is held down.

GetMouseButtonPress()

bool Urho3D::Input::GetMouseButtonPress

(

MouseButtonFlags

button

)

const

Check if a mouse button has been pressed on this frame.

GetMouseMode()

MouseMode Urho3D::Input::GetMouseMode ( ) const

inline

Return the mouse mode.

GetMouseMove()

IntVector2 Urho3D::Input::GetMouseMove

(

)

const

Return mouse movement since last frame.

GetMouseMoveWheel()

int Urho3D::Input::GetMouseMoveWheel ( ) const

inline

Return mouse wheel movement since last frame.

GetMouseMoveX()

int Urho3D::Input::GetMouseMoveX

(

)

const

Return horizontal mouse movement since last frame.

GetMouseMoveY()

int Urho3D::Input::GetMouseMoveY

(

)

const

Return vertical mouse movement since last frame.

GetMousePosition()

IntVector2 Urho3D::Input::GetMousePosition

(

)

const

Return mouse position within window. Should only be used with a visible mouse cursor. Uses the backbuffer (Graphics width/height) coordinates.

GetNumJoysticks()

unsigned Urho3D::Input::GetNumJoysticks ( ) const

inline

Return number of connected joysticks.

GetNumTouches()

unsigned Urho3D::Input::GetNumTouches ( ) const

inline

Return number of active finger touches.

GetQualifierDown()

bool Urho3D::Input::GetQualifierDown

(

Qualifier

qualifier

)

const

Check if a qualifier key is held down.

GetQualifierPress()

bool Urho3D::Input::GetQualifierPress

(

Qualifier

qualifier

)

const

Check if a qualifier key has been pressed on this frame.

GetQualifiers()

QualifierFlags Urho3D::Input::GetQualifiers

(

)

const

Return the currently held down qualifiers.

GetScancodeDown()

bool Urho3D::Input::GetScancodeDown

(

Scancode

scancode

)

const

Check if a key is held down by scancode.

GetScancodePress()

bool Urho3D::Input::GetScancodePress

(

Scancode

scancode

)

const

Check if a key has been pressed on this frame by scancode.

GetScreenKeyboardSupport()

bool Urho3D::Input::GetScreenKeyboardSupport

(

)

const

Return whether on-screen keyboard is supported.

GetSystemToBackbufferScale()

Vector2 Urho3D::Input::GetSystemToBackbufferScale ( ) const

inline

Return input coordinate scaling. Should return non-unity on High DPI display.

GetToggleFullscreen()

bool Urho3D::Input::GetToggleFullscreen ( ) const

inline

Return whether fullscreen toggle is enabled.

GetTouch()

TouchState * Urho3D::Input::GetTouch

(

unsigned

index

)

const

Return active finger touch by index.

GetTouchEmulation()

bool Urho3D::Input::GetTouchEmulation ( ) const

inline

Return whether touch emulation is enabled.

HasFocus()

bool Urho3D::Input::HasFocus ( )

inline

Return whether application window has input focus.

IsMinimized()

bool Urho3D::Input::IsMinimized

(

)

const

Return whether application window is minimized.

IsMouseGrabbed()

bool Urho3D::Input::IsMouseGrabbed ( ) const

inline

Return whether the mouse is currently being grabbed by an operation.

IsMouseLocked()

bool Urho3D::Input::IsMouseLocked

(

)

const

Return whether the mouse is locked to the window.

IsMouseVisible()

bool Urho3D::Input::IsMouseVisible ( ) const

inline

Return whether the operating system mouse cursor is visible.

IsScreenJoystickVisible()

bool Urho3D::Input::IsScreenJoystickVisible

(

SDL_JoystickID

id

)

const

Return whether a virtual joystick is visible.

IsScreenKeyboardVisible()

bool Urho3D::Input::IsScreenKeyboardVisible

(

)

const

Return whether on-screen keyboard is being shown.

RemoveScreenJoystick()

bool Urho3D::Input::RemoveScreenJoystick

(

SDL_JoystickID

id

)

Remove screen joystick by instance ID.

Return true if successful.

This method should only be called in main thread.

ResetState()

void Urho3D::Input::ResetState ( )

private

Clear input state.

SetMouseMode()

void Urho3D::Input::SetMouseMode	(	MouseMode	mode,
		bool	suppressEvent = false
	)

Set the mouse mode.

Set the mouse mode behaviour. MM_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 Urho UI will be limited (eg: drag move / drag end events will not trigger). SetMouseMode(MM_ABSOLUTE) will call SetMouseGrabbed(false).

MM_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). SetMouseMode(MM_RELATIVE) will call SetMouseGrabbed(true).

MM_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. SetMouseMode(MM_WRAP) will call SetMouseGrabbed(true).

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

SetMousePosition()

void Urho3D::Input::SetMousePosition

(

const IntVector2 &

position

)

Set the mouse cursor position. Uses the backbuffer (Graphics width/height) coordinates.

SetScreenJoystickVisible()

void Urho3D::Input::SetScreenJoystickVisible	(	SDL_JoystickID	id,
		bool	enable
	)

Set whether the virtual joystick is visible.

SetScreenKeyboardVisible()

void Urho3D::Input::SetScreenKeyboardVisible

(

bool

enable

)

Show or hide on-screen keyboard on platforms that support it. When shown, keypresses from it are delivered as key events.

SetToggleFullscreen()

void Urho3D::Input::SetToggleFullscreen

(

bool

enable

)

Set whether ALT-ENTER fullscreen toggle is enabled.

SetTouchEmulation()

void Urho3D::Input::SetTouchEmulation

(

bool

enable

)

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.

---

The documentation for this class was generated from the following files:

• Urho3D/Input/Input.h
• Urho3D/Input/Input.cpp