ezEngine  Milestone 7
ezInputManager Class Reference

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

#include <InputManager.h>

Classes

struct  ezActionData
 The data that is stored for each action. More...
 
struct  ezInputSlot
 Stores the current state for one input slot. More...
 
struct  InputEventData
 The data that is broadcast when certain events occur. More...
 
struct  InternalData
 The internal data of the ezInputManager. Not allocated until it is actually required. More...
 

Public Types

typedef ezEvent< const
InputEventData & > 
ezEventInput
 

Static Public Member Functions

static void Update (ezTime tTimeDifference)
 Updates the state of the input manager. This should be called exactly once each frame. More...
 
static void SetInputSlotDisplayName (const char *szInputSlot, const char *szDefaultDisplayName)
 Changes the display name of an input slot.
 
static const char * GetInputSlotDisplayName (const char *szInputSlot)
 Returns the display name that was assigned to the given input slot.
 
static void SetInputSlotDeadZone (const char *szInputSlot, 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 (const char *szInputSlot)
 Returns the dead zone value for the given input slot.
 
static ezBitflags
< ezInputSlotFlags
GetInputSlotFlags (const char *szInputSlot)
 Returns the flags for the given input slot.
 
static ezKeyState::Enum GetInputSlotState (const char *szInputSlot, float *pValue=nullptr)
 Returns the current key state of the given input slot and optionally also returns its full value. More...
 
static void RetrieveAllKnownInputSlots (ezDynamicArray< const char * > &out_InputSlots)
 Returns an array that contains all the names of all currently known input slots.
 
static ezUInt32 RetrieveLastCharacter (bool bResetCurrent=true)
 Returns the last typed character as the OS has reported it. Thus supports Unicode etc. More...
 
static void PollHardware ()
 Makes sure that hardware input is processed at this moment, which allows to do this more often than Update() is called. More...
 
static void ClearInputMapping (const char *szInputSet, const char *szInputSlot)
 If szInputSlot is used in any action in szInputSet, it will be removed from all of them. More...
 
static void SetInputActionConfig (const char *szInputSet, const char *szAction, const ezInputActionConfig &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. More...
 
static ezInputActionConfig GetInputActionConfig (const char *szInputSet, const char *szAction)
 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 (const char *szInputSet, const char *szAction)
 Deletes all state associated with the given input action. More...
 
static ezKeyState::Enum GetInputActionState (const char *szInputSet, const char *szAction, float *pValue=nullptr, ezInt8 *iTriggeredSlot=nullptr)
 Returns the current state and value of the given input action. More...
 
static void SetActionDisplayName (const char *szAction, const char *szDisplayName)
 Sets the display name for the given action.
 
static const char * GetActionDisplayName (const char *szAction)
 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 (const char *szInputSetName, ezDynamicArray< ezString > &out_InputActions)
 Returns the names of all input actions in the given input set.
 
static void InjectInputSlotValue (const char *szInputSlot, float fValue)
 This function allows to 'inject' input state for one frame. More...
 
static const char * GetPressedInputSlot (ezInputSlotFlags::Enum MustHaveFlags, ezInputSlotFlags::Enum MustNotHaveFlags)
 Checks whether any input slot has been triggered in this frame, which has all MustHaveFlags and has none of the MustNotHaveFlags. More...
 
static const char * 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 void 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.
 

Private Types

typedef ezMap< ezString,
ezActionData
ezActionMap
 Maps input action names to their data.
 
typedef ezMap< ezString,
ezActionMap
ezInputSetMap
 Maps input set names to their data.
 
typedef ezMap< ezString,
ezInputSlot
ezInputSlotsMap
 Maps input slot names to their data.
 

Private Member Functions

 EZ_MAKE_SUBSYSTEM_STARTUP_FRIEND (Core, InputManager)
 

Static Private Member Functions

static void RegisterInputSlot (const char *szName, const char *szDefaultDisplayName, ezBitflags< ezInputSlotFlags > SlotFlags)
 Registers an input slot with the given name and a default display name. More...
 
static void ResetInputSlotValues ()
 Resets all input slot value to zero.
 
static void GatherDeviceInputSlotValues ()
 Queries all known devices for their input slot values and stores the maximum values inside the input manager.
 
static void UpdateInputSlotStates ()
 Uses the previously queried input slot values to update their overall state.
 
static void UpdateInputActions (ezTime tTimeDifference)
 Uses the previously queried input slot values to update the state (and value) of all input actions.
 
static void UpdateInputActions (const char *szInputSet, ezActionMap &Actions, ezTime tTimeDifference)
 Updates the state of all input actions in the given input set.
 
static ezActionMap::Iterator GetBestAction (ezActionMap &Actions, const ezString &sSlot, const ezActionMap::Iterator &itFirst)
 Returns an iterator to the (next) action that should get triggered by the given slot. More...
 
static void DeallocateInternals ()
 
static InternalDataGetInternals ()
 

Static Private Attributes

static ezUInt32 s_LastCharacter = '\0'
 The last (Unicode) character that was typed by the user, as reported by the OS (on Windows: WM_CHAR).
 
static bool s_bInputSlotResetRequired = true
 
static ezEventInput s_InputEvents
 
static InternalDatas_pData = nullptr
 

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.


Class Documentation

struct ezInputManager::InternalData

The internal data of the ezInputManager. Not allocated until it is actually required.

Class Members
ezMap< ezString, ezString > s_ActionDisplayNames Stores a display name for each input action.
ezInputSetMap s_ActionMapping Maps input set names to their data.
ezMap< ezString, float > s_InjectedInputSlots
ezInputSlotsMap s_InputSlots Maps input slot names to their data.

Member Function Documentation

void ezInputManager::ClearInputMapping ( const char *  szInputSet,
const char *  szInputSlot 
)
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.

ezInputManager::ezActionMap::Iterator ezInputManager::GetBestAction ( ezActionMap Actions,
const ezString sSlot,
const ezActionMap::Iterator itFirst 
)
staticprivate

Returns an iterator to the (next) action that should get triggered by the given slot.

This may return several actions (when called repeatedly) when their are several actions with the same priority.

ezKeyState::Enum ezInputManager::GetInputActionState ( const char *  szInputSet,
const char *  szAction,
float *  pValue = nullptr,
ezInt8 *  iTriggeredSlot = 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).

ezKeyState::Enum ezInputManager::GetInputSlotState ( const char *  szInputSlot,
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.

const char * 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.

void ezInputManager::InjectInputSlotValue ( const char *  szInputSlot,
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.

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.

void ezInputManager::RegisterInputSlot ( const char *  szName,
const char *  szDefaultDisplayName,
ezBitflags< ezInputSlotFlags SlotFlags 
)
staticprivate

Registers an input slot with the given name and a default display name.

If the input slot was already registered before, the display name is only changed, it the previous registration did not specify a display name different from the input slot name.

void ezInputManager::RemoveInputAction ( const char *  szInputSet,
const char *  szAction 
)
static

Deletes all state associated with the given input action.

It is not necessary to call this function for cleanup.

ezUInt32 ezInputManager::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.

void ezInputManager::SetInputActionConfig ( const char *  szInputSet,
const char *  szAction,
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.
szActionThe 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.
ConfigThis 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.
bClearPreviousInputMappingsIf 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.
void ezInputManager::Update ( ezTime  tTimeDifference)
static

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

Parameters
tTimeDifferenceThe 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: