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

#include <InputManager.h>

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

Public Types
using	plEventInput = plEvent<const InputEventData&>

Static Public Member Functions
static void	Update (plTime timeDifference)
	Updates the state of the input manager. This should be called exactly once each frame.

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

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

static plStringView	GetInputSlotDisplayName (plStringView sInputSet, plStringView sAction, plInt32 iTrigger=-1)
	A shortcut to get the display name of the input slot bound to a given action.

static void	SetInputSlotDeadZone (plStringView sInputSlot, float fDeadZone)
	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.

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

static plBitflags< plInputSlotFlags >	GetInputSlotFlags (plStringView sInputSlot)
	Returns the flags for the given input slot.

static plKeyState::Enum	GetInputSlotState (plStringView sInputSlot, float *pValue=nullptr)
	Returns the current key state of the given input slot and optionally also returns its full value.

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

static plUInt32	RetrieveLastCharacter (bool bResetCurrent=true)
	Returns the last typed character as the OS has reported it. Thus supports Unicode etc.

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

static void	ClearInputMapping (plStringView sInputSet, plStringView sInputSlot)
	If szInputSlot is used in any action in szInputSet, it will be removed from all of them.

static void	SetInputActionConfig (plStringView sInputSet, plStringView sAction, const plInputActionConfig &config, bool bClearPreviousInputMappings)
	This is the one function to set up which input actions are available and by which input slots (keys) they are triggered.

static plInputActionConfig	GetInputActionConfig (plStringView sInputSet, plStringView sAction)
	Returns the configuration for the given input action in the given input set. Returns a default configuration, if the action does not exist.

static void	RemoveInputAction (plStringView sInputSet, plStringView sAction)
	Deletes all state associated with the given input action.

static plKeyState::Enum	GetInputActionState (plStringView sInputSet, plStringView sAction, float pValue=nullptr, plInt8 pTriggeredSlot=nullptr)
	Returns the current state and value of the given input action.

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

static const plString	GetActionDisplayName (plStringView 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 (plDynamicArray< plString > &out_inputSetNames)
	Returns the names of all currently registered input sets.

static void	GetAllInputActions (plStringView sInputSetName, plDynamicArray< plString > &out_inputActions)
	Returns the names of all input actions in the given input set.

static void	SetExclusiveInputSet (plStringView sExclusiveSet)
	This can be used to pass input exclusively to this input set and no others.

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

static void	InjectInputSlotValue (plStringView sInputSlot, float fValue)
	This function allows to 'inject' input state for one frame.

static plStringView	GetPressedInputSlot (plInputSlotFlags::Enum mustHaveFlags, plInputSlotFlags::Enum mustNotHaveFlags)
	Checks whether any input slot has been triggered in this frame, which has all MustHaveFlags and has none of the MustNotHaveFlags.

static plStringView	ConvertScanCodeToEngineName (plUInt8 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 plStringView	GetInputSlotTouchPoint (plUInt32 uiIndex)
	Helper for retrieving the input slot string for touch point with a given index.

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

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

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

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

static void	RemoveEventHandler (plEventSubscriptionID id)

Friends
class	plInputDevice

Detailed Description

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

The plInputManager 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 plInputManager::ClearInputMapping	(	plStringView	sInputSet,
		plStringView	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.

◆ GetInputActionState()

plKeyState::Enum plInputManager::GetInputActionState	(	plStringView	sInputSet,
		plStringView	sAction,
		float *	pValue = nullptr,
		plInt8 *	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).

◆ GetInputSlotDisplayName()

plStringView plInputManager::GetInputSlotDisplayName	(	plStringView	sInputSet,
		plStringView	sAction,
		plInt32	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 .. plInputActionConfig::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()

plKeyState::Enum plInputManager::GetInputSlotState	(	plStringView	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.

◆ GetPressedInputSlot()

plStringView plInputManager::GetPressedInputSlot	(	plInputSlotFlags::Enum	mustHaveFlags,
		plInputSlotFlags::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 plInputManager::InjectInputSlotValue	(	plStringView	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 plInputManager::Update was called, its effect will be delayed by one frame.

◆ PollHardware()

void plInputManager::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.

◆ RemoveInputAction()

void plInputManager::RemoveInputAction	(	plStringView	sInputSet,
		plStringView	sAction )

static

Deletes all state associated with the given input action.

It is not necessary to call this function for cleanup.

◆ RetrieveLastCharacter()

plUInt32 plInputManager::RetrieveLastCharacter ( bool bResetCurrent = true )

static

Returns the last typed character as the OS has reported it. Thus supports Unicode etc.

If bResetCurrent is true, the internal last character will be reset to '\0'. 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.

◆ SetExclusiveInputSet()

static void plInputManager::SetExclusiveInputSet ( plStringView 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 plInputManager::SetInputActionConfig	(	plStringView	sInputSet,
		plStringView	sAction,
		const plInputActionConfig &	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 plInputManager 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.

◆ Update()

void plInputManager::Update ( plTime 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:

Code/Engine/Core/Input/InputManager.h
Code/Engine/Core/Input/Implementation/Action.cpp
Code/Engine/Core/Input/Implementation/InputManager.cpp
Code/Engine/Core/Input/Implementation/ScancodeTable.cpp

Classes

Public Types

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ ClearInputMapping()

◆ GetInputActionState()

◆ GetInputSlotDisplayName()

◆ GetInputSlotState()

◆ GetPressedInputSlot()

◆ InjectInputSlotValue()

◆ PollHardware()

◆ RemoveInputAction()

◆ RetrieveLastCharacter()

◆ SetExclusiveInputSet()

◆ SetInputActionConfig()

◆ Update()