#include <InputManager.h>

Classes
struct	InputEventData
	The data that is broadcast when certain events occur. More...

Public Types
using	ezEventInput = ezEvent< const InputEventData & >

Static Public Member Functions
static void	Update (ezTime timeDifference)

static void	SetInputSlotDisplayName (ezStringView sInputSlot, ezStringView sDefaultDisplayName)
	Changes the display name of an input slot.

static ezStringView	GetInputSlotDisplayName (ezStringView sInputSlot)
	Returns the display name that was assigned to the given input slot.

static ezStringView	GetInputSlotDisplayName (ezStringView sInputSet, ezStringView sAction, ezInt32 iTrigger=-1)

static void	SetInputSlotDeadZone (ezStringView sInputSlot, float fDeadZone)

static float	GetInputSlotDeadZone (ezStringView sInputSlot)
	Returns the dead zone value for the given input slot.

static ezBitflags< ezInputSlotFlags >	GetInputSlotFlags (ezStringView sInputSlot)
	Returns the flags for the given input slot.

static ezKeyState::Enum	GetInputSlotState (ezStringView sInputSlot, float *pValue=nullptr)

static void	RetrieveAllKnownInputSlots (ezDynamicArray< ezStringView > &out_inputSlots)
	Returns an array that contains all the names of all currently known input slots.

static ezString	RetrieveLastCharacters (bool bResetCurrent=true)

static void	PollHardware ()

static void	ClearInputMapping (ezStringView sInputSet, ezStringView sInputSlot)

static void	SetInputActionConfig (ezStringView sInputSet, ezStringView sAction, const ezInputActionConfig &config, bool bClearPreviousInputMappings)

static ezInputActionConfig	GetInputActionConfig (ezStringView sInputSet, ezStringView sAction)

static void	RemoveInputAction (ezStringView sInputSet, ezStringView sAction)

static ezKeyState::Enum	GetInputActionState (ezStringView sInputSet, ezStringView sAction, float pValue=nullptr, ezInt8 pTriggeredSlot=nullptr)

static void	SetActionDisplayName (ezStringView sAction, ezStringView sDisplayName)
	Sets the display name for the given action.

static const ezString	GetActionDisplayName (ezStringView sAction)
	Returns the display name for the given action, or the action name itself, if no special display name was specified yet.

static void	GetAllInputSets (ezDynamicArray< ezString > &out_inputSetNames)
	Returns the names of all currently registered input sets.

static void	GetAllInputActions (ezStringView sInputSetName, ezDynamicArray< ezString > &out_inputActions)
	Returns the names of all input actions in the given input set.

static void	SetExclusiveInputSet (ezStringView sExclusiveSet)

static ezStringView	GetExclusiveInputSet ()
	Returns whether any input set gets input exclusively.

static void	SetMouseCursor (const ezMouseCursorDesc &desc)

static const ezMouseCursorDesc &	GetMouseCursor ()
	Returns the description of the custom mouse cursor that shall currently be displayed.

static void	ClearMouseCursor ()
	Shortcut for SetMouseCursor(ezMouseCursorDesc()), disables the custom mouse cursor.

static ezUInt32	GetMouseCursorChangeCounter ()
	Incremented every time any value of the custom mouse cursor description changed.

static ezUInt32	GetHardwareCursorSize ()

static ezUInt32	GetMouseCursorIdentifierChangeCounter ()

static ezUInt32	PushMouseCursorOverride (const ezMouseCursorOverrideDesc &desc)

static void	PopMouseCursorOverride (ezUInt32 uiOverrideId)

static ezMouseCursorOverrideDesc	GetActiveMouseCursorOverride ()

static bool	IsCustomMouseCursorActive ()

static void	InjectInputSlotValue (ezStringView sInputSlot, float fValue)

static ezStringView	GetPressedInputSlot (ezInputSlotFlags::Enum mustHaveFlags, ezInputSlotFlags::Enum mustNotHaveFlags)

static ezStringView	ConvertScanCodeToEngineName (ezUInt8 uiScanCode, bool bIsExtendedKey)
	Mostly for internal use. Converts a scan-code value to the string that is used inside the engine for that key.

static ezStringView	GetInputSlotTouchPoint (ezUInt32 uiIndex)
	Helper for retrieving the input slot string for touch point with a given index.

static ezStringView	GetInputSlotTouchPointPositionX (ezUInt32 uiIndex)
	Helper for retrieving the input slot string for touch point x position with a given index.

static ezStringView	GetInputSlotTouchPointPositionY (ezUInt32 uiIndex)
	Helper for retrieving the input slot string for touch point y position with a given index.

static ezEventSubscriptionID	AddEventHandler (ezEventInput::Handler handler)
	Adds an event handler that is called for input events.

static void	RemoveEventHandler (ezEventInput::Handler handler)
	Removes a previously added event handler.

static void	RemoveEventHandler (ezEventSubscriptionID id)

template<typename TYPE >
static TYPE *	GetInputDeviceOfType ()

template<typename TYPE >
static void	GetInputDevicesOfType (ezDynamicArray< TYPE * > &out_devices)
	Fills the array with all ezInputDevice instances of the given base type.

static void	GetInputDevicesOfType (const ezRTTI pRtti, ezDynamicArray< ezInputDevice > &out_devices)
	Fills the array with all ezInputDevice instances of the given base type.

Friends
class	ezInputDevice

Detailed Description

The central class to set up and query the state of all input.

The ezInputManager is the central hub through which you can configure which keys will trigger which actions. You can query in which state an action is (inactive (up), active (down), just recently activated (pressed) or just recently deactivated (released)). You can query their values (e.g. how much a thumb-stick or the mouse was moved). Additionally you can localize buttons and actions. The internal data will always use English names and the US keyboard layout, but what with which names those keys are presented to the user can be changed. Although the input manager allows to query the state of each key, button, axis, etc. directly, this is not advised. Instead the user should set up 'actions' and define which keys will trigger those actions. At runtime the user should only query the state of actions. In the best case, an application allows the player to change the mapping which keys are used to trigger which actions.

Member Function Documentation

◆ ClearInputMapping()

void ezInputManager::ClearInputMapping	(	ezStringView	sInputSet,
		ezStringView	sInputSlot
	)

static

If szInputSlot is used in any action in szInputSet, it will be removed from all of them.

This should be used to reset the usage of an input slot before it is bound to another input action.

◆ GetActiveMouseCursorOverride()

ezMouseCursorOverrideDesc ezInputManager::GetActiveMouseCursorOverride ( )

static

Returns the override that is currently in effect, ie. the one that was pushed last.

If no override is registered, this returns ezMouseCursorOverride::None with m_bForceNoClip set to false, ie. 'don't change anything', which is not the same as a default constructed ezMouseCursorOverrideDesc.

◆ GetHardwareCursorSize()

ezUInt32 ezInputManager::GetHardwareCursorSize ( )

static

Returns the edge length of the operating system's mouse cursor, in pixels.

Use this to render a custom cursor at the size that the user expects, independent of the screen resolution, the window size and which monitor the window is on. It accounts for both DPI scaling and the user's mouse pointer size setting.

Falls back to 32 pixels if no mouse device exists or the platform can't report a size.

Querying the value involves system calls, so it is cached and only re-queried every few hundred calls to Update(). A change of the DPI scaling (e.g. by moving the window to another monitor) therefore takes a moment to be picked up.

◆ GetInputActionConfig()

ezInputActionConfig ezInputManager::GetInputActionConfig	(	ezStringView	sInputSet,
		ezStringView	sAction
	)

static

Returns the configuration for the given input action in the given input set. Returns a default configuration, if the action does not exist.

◆ GetInputActionState()

ezKeyState::Enum ezInputManager::GetInputActionState	(	ezStringView	sInputSet,
		ezStringView	sAction,
		float *	pValue = `nullptr`,
		ezInt8 *	pTriggeredSlot = `nullptr`
	)

static

Returns the current state and value of the given input action.

This is the one function that is called repeatedly at runtime to figure out which actions are active and thus which game-play functions to execute. You can (and should) use the /a pValue to scale game play features (e.g. how fast to drive).

◆ GetInputDeviceOfType()

template<typename TYPE >

static TYPE * ezInputManager::GetInputDeviceOfType ( )

inlinestatic

Returns the first input device of the requested type (or nullptr).

Convenience function for the case that it is known that only one device exists (or will be used).

◆ GetInputSlotDisplayName()

ezStringView ezInputManager::GetInputSlotDisplayName	(	ezStringView	sInputSet,
		ezStringView	sAction,
		ezInt32	iTrigger = `-1`
	)

static

A shortcut to get the display name of the input slot bound to a given action

If iTrigger is set, the name of that trigger (0 .. ezInputActionConfig::MaxInputSlotAlternatives) will be used. If iTrigger is less than 0, the first valid trigger is used. If iTrigger is outside the valid range or no valid trigger is bound, nullptr is returned.

Test:: This is new

◆ GetInputSlotState()

ezKeyState::Enum ezInputManager::GetInputSlotState	(	ezStringView	sInputSlot,
		float *	pValue = `nullptr`
	)

static

Returns the current key state of the given input slot and optionally also returns its full value.

Do not use this function, unless you really, really need the value of exactly this key. Prefer to map your key to an action and then use GetInputActionState(). That method is more robust and extensible.

◆ GetMouseCursorIdentifierChangeCounter()

static ezUInt32 ezInputManager::GetMouseCursorIdentifierChangeCounter ( )

inlinestatic

Incremented only when ezMouseCursorDesc::m_sCursor changed.

Use this to detect when the (potentially expensive) resolving of the cursor identifier to an actual resource has to be redone.

◆ GetPressedInputSlot()

ezStringView ezInputManager::GetPressedInputSlot	(	ezInputSlotFlags::Enum	mustHaveFlags,
		ezInputSlotFlags::Enum	mustNotHaveFlags
	)

static

Checks whether any input slot has been triggered in this frame, which has all MustHaveFlags and has none of the MustNotHaveFlags.

This function can be used in a UI to wait for user input and then assign that input to a certain action.

◆ InjectInputSlotValue()

void ezInputManager::InjectInputSlotValue	(	ezStringView	sInputSlot,
		float	fValue
	)

static

This function allows to 'inject' input state for one frame.

This can be useful to emulate certain keys, e.g. for virtual devices. Note that it usually makes more sense to actually have another input device, however this can be used to get data into the system quickly for when a full blown input device might be overkill. The injected input state is cleared immediately after it has been processed, so to keep a virtual input slot active, the input needs to be injected every frame.

Note that when the input is injected after ezInputManager::Update was called, its effect will be delayed by one frame.

◆ IsCustomMouseCursorActive()

bool ezInputManager::IsCustomMouseCursorActive ( )

static

Whether a custom cursor is set and is not suppressed by an override.

While this is true, the OS cursor is hidden (but not captured) and the system that renders custom cursors is expected to draw one.

◆ PollHardware()

void ezInputManager::PollHardware ( )

static

Makes sure that hardware input is processed at this moment, which allows to do this more often than Update() is called.

When you have a game where you are doing relatively few game updates (including processing input), for example only 20 times per second, it is possible to 'miss' input. PollHardware() allows to introduce sampling the hardware state more often to prevent this. E.g. when your renderer renders at 60 Hz, you can poll input also at 60 Hz, even though you really only process it at 20 Hz. In typical usage scenarios this is not required to do and can be ignored. Note that you can call PollHardware() as often as you like and at irregular intervals, it will not have a negative effect on the input states.

◆ PopMouseCursorOverride()

void ezInputManager::PopMouseCursorOverride ( ezUInt32 uiOverrideId )

static

Removes an override that was registered with PushMouseCursorOverride().

Overrides may be removed in any order. Passing zero does nothing. May only be called from the main thread.

◆ PushMouseCursorOverride()

ezUInt32 ezInputManager::PushMouseCursorOverride ( const ezMouseCursorOverrideDesc & desc )

static

Registers an override that temporarily changes the mouse cursor state, without the application having to know about it.

Use this from overlay UI (the in-game console, debug UIs, editor overlays) that needs the OS cursor, even while the application hid it or displays a custom cursor. The most recently pushed override wins, so multiple overlays can be active at the same time without stomping each other.

Returns an ID that has to be passed to PopMouseCursorOverride(). Never returns zero. Prefer using ezMouseCursorOverrideRequest instead.

May only be called from the main thread.

◆ RemoveInputAction()

void ezInputManager::RemoveInputAction	(	ezStringView	sInputSet,
		ezStringView	sAction
	)

static

Deletes all state associated with the given input action.

It is not necessary to call this function for cleanup.

◆ RetrieveLastCharacters()

ezString ezInputManager::RetrieveLastCharacters ( bool bResetCurrent = true )

static

Returns everything typed since the last reset, as the OS has reported it, in order, as one UTF-8 string. Supports Unicode etc.

If bResetCurrent is true, the internal buffer will be cleared. If it is false, the internal state will not be changed. This should only be used if the calling code does not do anything meaningful with the value - a second caller peeking with bResetCurrent == false still sees whatever a later reset call already consumed.

◆ SetExclusiveInputSet()

static void ezInputManager::SetExclusiveInputSet ( ezStringView sExclusiveSet )

inlinestatic

This can be used to pass input exclusively to this input set and no others.

Querying input from other input sets will always return 'key up'.

◆ SetInputActionConfig()

void ezInputManager::SetInputActionConfig	(	ezStringView	sInputSet,
		ezStringView	sAction,
		const ezInputActionConfig &	config,
		bool	bClearPreviousInputMappings
	)

static

This is the one function to set up which input actions are available and by which input slots (keys) they are triggered.

Parameters

szInputSet	'Input Sets' are sets of actions that are disjunct from each other. That means the same input slot (key, mouse button, etc.) can trigger multiple different actions from different input sets. For example In the input set 'Game' the left mouse button may trigger the action 'Shoot', but in the input set 'UI' the left mouse button may trigger the action 'Click'. All input sets are always evaluated and update their state simultaneously. The user only has to decide which actions to react to, ie. whether the game is currently running and thus the 'Game' input set is queried or whether a menu is shown and thus the 'UI' input set is queried.
szAction	The action that is supposed to be triggered. The same action name may be reused in multiple input sets, they will have nothing in common. The action name should describe WHAT is to be done, not which key the user pressed. For example an action could be 'player_forwards'. Which key is set to trigger that action should be irrelevant at run-time.
Config	This struct defines exactly which input slots (keys, buttons etc.) will trigger this action. The configuration allows to scale key values by the frame time, to get smooth movement when the frame-rate varies. It allows to only accept input from a slot if two other slots have certain values. This makes it possible to react to mouse or touch input only if that input is done inside a certain input area. The action can be triggered by multiple keys, if desired. In the most common cases, one will only set one or two input slots as triggers (Config.m_sInputSlotTrigger) and possibly decide whether frame time scaling is required. It makes sense to let the ezInputManager do the frame time scaling, because it should not be applied to all input, e.g. mouse delta values should never be scaled by the frame time.
bClearPreviousInputMappings	If set to true it is ensured that all the input slots that are used by this action are not mapped to any other action. That means no other action can be triggered by this key within this input set. For most actions this should be set to true. However, if you have several actions that can be triggered by the same slot (for example touch input) but only in different areas of the screen, this should be set to false.

◆ SetInputSlotDeadZone()

void ezInputManager::SetInputSlotDeadZone	(	ezStringView	sInputSlot,
		float	fDeadZone
	)

static

Sets the dead zone for the given input slot. As long as the hardware reports values lower than this, the input slot will report a value of zero.

◆ SetMouseCursor()

void ezInputManager::SetMouseCursor ( const ezMouseCursorDesc & desc )

static

Sets which custom ('software') mouse cursor shall be displayed.

Set desc.m_sCursor to an empty string (or call ClearMouseCursor()) to display no custom cursor.

◆ Update()

void ezInputManager::Update ( ezTime timeDifference )

static

Updates the state of the input manager. This should be called exactly once each frame.

Parameters

tTimeDifference The time elapsed since the last update. This will affect the value scaling of actions that use frame time scaling and is necessary to update controller vibration tracks.

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

/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/Input/InputManager.h
/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/Input/Implementation/Action.cpp
/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/Input/Implementation/InputManager.cpp
/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/Input/Implementation/ScancodeTable.cpp

Classes

Public Types

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ ClearInputMapping()

◆ GetActiveMouseCursorOverride()

◆ GetHardwareCursorSize()

◆ GetInputActionConfig()

◆ GetInputActionState()

◆ GetInputDeviceOfType()

◆ GetInputSlotDisplayName()

◆ GetInputSlotState()

◆ GetMouseCursorIdentifierChangeCounter()

◆ GetPressedInputSlot()

◆ InjectInputSlotValue()

◆ IsCustomMouseCursorActive()

◆ PollHardware()

◆ PopMouseCursorOverride()

◆ PushMouseCursorOverride()

◆ RemoveInputAction()

◆ RetrieveLastCharacters()

◆ SetExclusiveInputSet()

◆ SetInputActionConfig()

◆ SetInputSlotDeadZone()

◆ SetMouseCursor()

◆ Update()