Class InputHandler

Namespace

MLEM.Input

Assembly

MLEM.dll

An input handler is a more advanced wrapper around MonoGame's default input system. It includes keyboard, mouse, gamepad and touch handling through the GenericInput wrapper, as well as a new "pressed" state for inputs, the ability for keyboard and gamepad repeat events, and the ability to track down, up and press times for inputs.

public class InputHandler : GameComponent, IGameComponent, IUpdateable, IDisposable

Inheritance

object

GameComponent

InputHandler

Implements

IGameComponent

IUpdateable

IDisposable

Inherited Members

GameComponent.Initialize()

GameComponent.OnUpdateOrderChanged(object, EventArgs)

GameComponent.OnEnabledChanged(object, EventArgs)

GameComponent.Dispose(bool)

GameComponent.Dispose()

GameComponent.Game

GameComponent.Enabled

GameComponent.UpdateOrder

GameComponent.EnabledChanged

GameComponent.UpdateOrderChanged

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Constructors

InputHandler(Game, bool, bool, bool, bool, bool)

Creates a new input handler with optional initial values.

public InputHandler(Game game, bool handleKeyboard = true, bool handleMouse = true, bool handleGamepads = true, bool handleTouch = true, bool externalGestureHandling = false)

Parameters

game Game

The game instance that this input handler belongs to.

handleKeyboard bool

The initial value for HandleKeyboard, which determines whether this input handler handles keyboard inputs.

handleMouse bool

The initial value for HandleMouse, which determines whether this input handler handles mouse inputs.

handleGamepads bool

The initial value for HandleGamepads, which determines whether this input handler handles gamepad inputs.

handleTouch bool

The initial value for HandleTouch, which determines whether this input handler handles touch inputs.

externalGestureHandling bool

The initial value for ExternalGestureHandling, which determines whether gestures will be supplied using AddExternalGesture(GestureSample) (or this input handler should handle gestures itself).

Fields

AllButtons

All values of the Microsoft.Xna.Framework.Input.Buttons enum.

public static readonly Buttons[] AllButtons

Field Value

Buttons[]

AllKeys

All values of the Microsoft.Xna.Framework.Input.Keys enum.

public static readonly Keys[] AllKeys

Field Value

Keys[]

ExternalGestureHandling

If your project already handles the processing of MonoGame's gestures elsewhere, you can set this field to true to ensure that this input handler's gesture handling does not override your own, since Microsoft.Xna.Framework.Input.Touch.GestureSample objects can only be retrieved once and are then removed from the Microsoft.Xna.Framework.Input.Touch.TouchPanel's queue. If this value is set to true, but you still want to be able to use Gestures, GetGesture(GestureType, out GestureSample), and GetViewportGesture(GestureType, out GestureSample), you can make this input handler aware of a gesture for the duration of the update frame that you added it on by using AddExternalGesture(GestureSample). For more info, see https://mlem.ellpeck.de/articles/input.html#external-gesture-handling.

public bool ExternalGestureHandling

Field Value

bool

GamepadButtonDeadzone

This field represents the deadzone that gamepad Microsoft.Xna.Framework.Input.Buttons have when input is queried for them using this input handler. A deadzone is the percentage (between 0 and 1) that an analog value has to exceed for it to be considered down (IsDown(GenericInput, int)) or pressed (IsPressed(GenericInput, int)). Querying of analog values is done using GetAnalogValue(GamePadState, Buttons).

public float GamepadButtonDeadzone

Field Value

float

Gestures

Contains all of the gestures that have finished during the last update call. To easily query these gestures, use GetGesture(GestureType, out GestureSample) or GetViewportGesture(GestureType, out GestureSample).

public readonly ReadOnlyCollection<GestureSample> Gestures

Field Value

ReadOnlyCollection<GestureSample>

HandleGamepadRepeats

Set this field to false to disable gamepad repeat event handling.

public bool HandleGamepadRepeats

Field Value

bool

HandleGamepads

Set this field to false to disable keyboard handling for this input handler.

public bool HandleGamepads

Field Value

bool

HandleKeyboard

Set this field to false to disable keyboard handling for this input handler.

public bool HandleKeyboard

Field Value

bool

HandleKeyboardRepeats

Set this field to false to disable keyboard repeat event handling.

public bool HandleKeyboardRepeats

Field Value

bool

HandleMouse

Set this field to false to disable mouse handling for this input handler.

public bool HandleMouse

Field Value

bool

HandleTouch

Set this field to false to disable touch handling for this input handler.

public bool HandleTouch

Field Value

bool

InvertPressBehavior

Set this field to true to invert the press behavior of IsPressed(GenericInput, int). Inverted behavior means that, instead of an input counting as pressed when it was up in the last frame and is now down, it will be counted as pressed when it was down in the last frame and is now up.

public bool InvertPressBehavior

Field Value

bool

KeyRepeatDelay

This is the amount of time that has to pass before the first keyboard repeat event is triggered. KeyRepeatRate

public TimeSpan KeyRepeatDelay

Field Value

TimeSpan

KeyRepeatRate

This is the amount of time that has to pass between keyboard repeat events. KeyRepeatDelay

public TimeSpan KeyRepeatRate

Field Value

TimeSpan

Properties

ConnectedGamepads

Contains the amount of gamepads that are currently connected. Note that this value will be set to 0 if HandleGamepads is false. This field is automatically updated in Update().

public int ConnectedGamepads { get; }

Property Value

int

InputsDown

An array of all Microsoft.Xna.Framework.Input.Keys, Microsoft.Xna.Framework.Input.Buttons and MouseButton values that are currently down. Additionally, TryGetDownTime(GenericInput, out TimeSpan, int) or GetDownTime(GenericInput, int) can be used to determine the amount of time that a given input has been down for.

public GenericInput[] InputsDown { get; }

Property Value

GenericInput[]

InputsPressed

An array of all Microsoft.Xna.Framework.Input.Keys, Microsoft.Xna.Framework.Input.Buttons and MouseButton that are currently considered pressed. An input is considered pressed if it was up in the last update, and is up in the current one.

public GenericInput[] InputsPressed { get; }

Property Value

GenericInput[]

KeyboardState

Contains the current keyboard state

public KeyboardState KeyboardState { get; }

Property Value

KeyboardState

LastKeyboardState

Contains the keyboard state from the last update call

public KeyboardState LastKeyboardState { get; }

Property Value

KeyboardState

LastMousePosition

Contains the position of the mouse from the last update call, extracted from LastMouseState

public Point LastMousePosition { get; }

Property Value

Point

LastMouseState

Contains the mouse state from the last update call

public MouseState LastMouseState { get; }

Property Value

MouseState

LastScrollWheel

Contains the scroll wheel value from the last update call, in increments of 120

public int LastScrollWheel { get; }

Property Value

int

LastTouchState

Contains the touch state from the last update call

public TouchCollection LastTouchState { get; }

Property Value

TouchCollection

LastViewportMousePosition

Contains the LastMousePosition, but with the Microsoft.Xna.Framework.Graphics.GraphicsDevice.Viewport taken into account.

public Point LastViewportMousePosition { get; }

Property Value

Point

LastViewportTouchState

Contains the LastTouchState, but with the Microsoft.Xna.Framework.Graphics.GraphicsDevice.Viewport taken into account.

public IList<TouchLocation> LastViewportTouchState { get; }

Property Value

IList<TouchLocation>

MousePosition

Contains the current position of the mouse, extracted from MouseState

public Point MousePosition { get; }

Property Value

Point

MouseState

Contains the current mouse state

public MouseState MouseState { get; }

Property Value

MouseState

ScrollWheel

Contains the current scroll wheel value, in increments of 120

public int ScrollWheel { get; }

Property Value

int

TouchState

Contains the current touch state

public TouchCollection TouchState { get; }

Property Value

TouchCollection

ViewportMousePosition

Contains the MousePosition, but with the Microsoft.Xna.Framework.Graphics.GraphicsDevice.Viewport taken into account.

public Point ViewportMousePosition { get; }

Property Value

Point

ViewportTouchState

Contains the TouchState, but with the Microsoft.Xna.Framework.Graphics.GraphicsDevice.Viewport taken into account.

public IList<TouchLocation> ViewportTouchState { get; }

Property Value

IList<TouchLocation>

Methods

AddExternalGesture(GestureSample)

Adds a gesture to the Gestures collection and allows it to be queried using GetGesture(GestureType, out GestureSample) and GetViewportGesture(GestureType, out GestureSample) for the duration of the update frame that it was added on. This method should be used when ExternalGestureHandling is set to true, but GetGesture(GestureType, out GestureSample) and GetViewportGesture(GestureType, out GestureSample) should still be available. For more info, see https://mlem.ellpeck.de/articles/input.html#external-gesture-handling.

public void AddExternalGesture(GestureSample sample)

Parameters

sample GestureSample

The gesture sample to add.

Exceptions

InvalidOperationException

Thrown if ExternalGestureHandling is false.

DisableGestures(params GestureType[])

Helper function to disable gestures for a Microsoft.Xna.Framework.Input.Touch.TouchPanel easily.

public static void DisableGestures(params GestureType[] gestures)

Parameters

gestures GestureType[]

The gestures to disable

EnableGestures(params GestureType[])

Helper function to enable gestures for a Microsoft.Xna.Framework.Input.Touch.TouchPanel easily. Note that, if other gestures were previously enabled, they will not get overridden.

public static void EnableGestures(params GestureType[] gestures)

Parameters

gestures GestureType[]

The gestures to enable

GetDownTime(GenericInput, int)

Returns the current or last amount of time that a given GenericInput has been held down for. If this input isn't currently down and has not been down previously, this method returns Zero.

public TimeSpan GetDownTime(GenericInput input, int index = -1)

Parameters

input GenericInput

The input whose down time to query.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

TimeSpan

The resulting down time, or Zero if the input is not being held.

GetGamepadState(int)

Returns the current state of the indexth gamepad

public GamePadState GetGamepadState(int index)

Parameters

index int

The zero-based gamepad index

Returns

GamePadState

The current state of the gamepad

GetGesture(GestureType, out GestureSample)

Queries for a gesture of a given type that finished during the current update call.

public bool GetGesture(GestureType type, out GestureSample sample)

Parameters

type GestureType

The type of gesture to query for

sample GestureSample

The resulting gesture sample, or default if there isn't one

Returns

bool

True if a gesture of the type was found, otherwise false

GetLastGamepadState(int)

Returns the state of the indexth gamepad from the last update call

public GamePadState GetLastGamepadState(int index)

Parameters

index int

The zero-based gamepad index

Returns

GamePadState

The state of the gamepad last update

GetTimeSincePress(GenericInput, int)

Returns the amount of time that has passed since a given GenericInput last counted as pressed. If this input hasn't been pressed previously, this method returns Zero.

public TimeSpan GetTimeSincePress(GenericInput input, int index = -1)

Parameters

input GenericInput

The input whose up time to query.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

TimeSpan

The resulting up time, or Zero if the input has never been pressed, or is currently pressed.

GetUpTime(GenericInput, int)

Returns the amount of time that a given GenericInput has last been up for since the last time it was down. If this input hasn't been down previously, this method returns Zero.

public TimeSpan GetUpTime(GenericInput input, int index = -1)

Parameters

input GenericInput

The input whose up time to query.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

TimeSpan

The resulting up time, or Zero if the input is being held.

GetViewportGesture(GestureType, out GestureSample)

Queries for a gesture of the given type that finished during the current update call. Unlike GetGesture(GestureType, out GestureSample), the return value of this method takes the Microsoft.Xna.Framework.Graphics.GraphicsDevice.Viewport into account.

public bool GetViewportGesture(GestureType type, out GestureSample sample)

Parameters

type GestureType

The type of gesture to query for

sample GestureSample

The resulting gesture sample with the Microsoft.Xna.Framework.Graphics.GraphicsDevice.Viewport taken into account, or default if there isn't one

Returns

bool

True if a gesture of the type was found, otherwise false

IsAnyDown(params GenericInput[])

Returns if a given control of any kind is down. This is a helper function that can be passed a Microsoft.Xna.Framework.Input.Keys, Microsoft.Xna.Framework.Input.Buttons or MouseButton.

public bool IsAnyDown(params GenericInput[] controls)

Parameters

controls GenericInput[]

Returns

bool

Whether the given control is down

IsAnyPressed(params GenericInput[])

Returns if a given control of any kind is pressed. If HandleKeyboardRepeats or HandleGamepadRepeats are true, this method will also return true to signify a key or gamepad button repeat. An input is considered pressed if it was not down the last update call, but is down the current update call. If InvertPressBehavior is true, this behavior is inverted.

public bool IsAnyPressed(params GenericInput[] controls)

Parameters

controls GenericInput[]

Returns

bool

Whether the given control is pressed.

IsAnyPressedAvailable(params GenericInput[])

Returns if a given control of any kind is pressed, and if the press has not been consumed yet using TryConsumePressed(GenericInput, int).

public bool IsAnyPressedAvailable(params GenericInput[] controls)

Parameters

controls GenericInput[]

Returns

bool

Whether the given control is pressed and the press is not consumed yet.

IsAnyUp(params GenericInput[])

Returns if a given control of any kind is up. This is a helper function that can be passed a Microsoft.Xna.Framework.Input.Keys, Microsoft.Xna.Framework.Input.Buttons or MouseButton.

public bool IsAnyUp(params GenericInput[] controls)

Parameters

controls GenericInput[]

Returns

bool

Whether the given control is up.

IsDown(GenericInput, int)

Returns if a given control of any kind is down. This is a helper function that can be passed a Microsoft.Xna.Framework.Input.Keys, Microsoft.Xna.Framework.Input.Buttons or MouseButton.

public bool IsDown(GenericInput control, int index = -1)

Parameters

control GenericInput

The control whose down state to query

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad

Returns

bool

Whether the given control is down

IsModifierKeyDown(ModifierKey)

Returns whether the given modifier key is down.

public bool IsModifierKeyDown(ModifierKey modifier)

Parameters

modifier ModifierKey

The modifier key

Returns

bool

If the modifier key is down

IsPressConsumed(GenericInput, int)

Returns whether the given GenericInput's press state has been consumed using TryConsumePressed(GenericInput, int). If an input has been consumed, IsPressedAvailable(GenericInput, int) and TryConsumePressed(GenericInput, int) will always return false for that input.

public bool IsPressConsumed(GenericInput input, int index = -1)

Parameters

input GenericInput

The input to query.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

bool

Whether a press has been consumed for the given input.

IsPressed(GenericInput, int)

Returns if a given control of any kind is pressed. If HandleKeyboardRepeats or HandleGamepadRepeats are true, this method will also return true to signify a key or gamepad button repeat. An input is considered pressed if it was not down the last update call, but is down the current update call. If InvertPressBehavior is true, this behavior is inverted.

public bool IsPressed(GenericInput control, int index = -1)

Parameters

control GenericInput

The control whose pressed state to query

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad

Returns

bool

Whether the given control is pressed.

IsPressedAvailable(GenericInput, int)

Returns if a given control of any kind is pressed, and if the press has not been consumed yet using TryConsumePressed(GenericInput, int).

public bool IsPressedAvailable(GenericInput control, int index = -1)

Parameters

control GenericInput

The control whose pressed state to query.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

bool

Whether the given control is pressed and the press is not consumed yet.

IsPressedIgnoreRepeats(GenericInput, int)

An input is considered pressed if it was not down the last update call, but is down the current update call. If InvertPressBehavior is true, this behavior is inverted. This has the same behavior as IsPressed(GenericInput, int), but ignores keyboard and gamepad repeat events. If HandleKeyboardRepeats and HandleGamepadRepeats are false, this method does the same as IsPressed(GenericInput, int).

public bool IsPressedIgnoreRepeats(GenericInput control, int index = -1)

Parameters

control GenericInput

The control whose pressed state to query

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad

Returns

bool

Whether the given control is pressed, ignoring repeat events.

IsUp(GenericInput, int)

Returns if a given control of any kind is up. This is a helper function that can be passed a Microsoft.Xna.Framework.Input.Keys, Microsoft.Xna.Framework.Input.Buttons or MouseButton.

public bool IsUp(GenericInput control, int index = -1)

Parameters

control GenericInput

The control whose up state to query

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad

Returns

bool

Whether the given control is up.

SetGesturesEnabled(bool, params GestureType[])

Helper function to enable or disable the given gestures for a Microsoft.Xna.Framework.Input.Touch.TouchPanel easily. This method is equivalent to calling EnableGestures(params GestureType[]) if the enabled value is true and calling DisableGestures(params GestureType[]) if it is false. Note that, if other gestures were previously enabled, they will not get overridden.

public static void SetGesturesEnabled(bool enabled, params GestureType[] gestures)

Parameters

enabled bool

Whether to enable or disable the gestures

gestures GestureType[]

The gestures to enable or disable

TryConsumePressed(GenericInput, int)

Returns if a given control of any kind is pressed and available, and marks the press as consumed if it is. This is a helper function that can be passed a Microsoft.Xna.Framework.Input.Keys, Microsoft.Xna.Framework.Input.Buttons or MouseButton.

public bool TryConsumePressed(GenericInput control, int index = -1)

Parameters

control GenericInput

The control whose pressed state to query.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

bool

Whether the given control is pressed and the press is not consumed yet.

TryConsumePressedForLess(GenericInput, TimeSpan, int)

Returns if a given control of any kind was just let go this frame, and had been down for less than the given time before that, and if the press has not been consumed yet using TryConsumePressedForLess(GenericInput, TimeSpan, int), and marks the press as consumed if it is. Essentially, this action signifies a short press action.

public bool TryConsumePressedForLess(GenericInput control, TimeSpan time, int index = -1)

Parameters

control GenericInput

The control whose pressed state to query.

time TimeSpan

The maximum time that the control should have been down for.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

bool

Whether the given control was pressed for less than the given time, and the press was successfully consumed.

TryGetDownTime(GenericInput, out TimeSpan, int)

Tries to retrieve the amount of time that a given GenericInput has been held down for. If the input is currently down or has been down previously, this method returns true and the amount of time that it has currently or last been down for is stored in downTime.

public bool TryGetDownTime(GenericInput input, out TimeSpan downTime, int index = -1)

Parameters

input GenericInput

The input whose down time to query.

downTime TimeSpan

The resulting down time, or Zero if the input is not being held.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

bool

Whether the input is currently being held.

TryGetTimeSincePress(GenericInput, out TimeSpan, int)

Tries to retrieve the amount of time that has passed since a given GenericInput last counted as pressed. If the input has previously been pressed, or is currently pressed, this method returns true and the amount of time that has passed since it was last pressed is stored in lastPressTime.

public bool TryGetTimeSincePress(GenericInput input, out TimeSpan lastPressTime, int index = -1)

Parameters

input GenericInput

The input whose last press time to query.

lastPressTime TimeSpan

The resulting up time, or Zero if the input was never pressed or is currently pressed.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

bool

true if the input has previously been pressed or is currently pressed, false otherwise.

TryGetUpTime(GenericInput, out TimeSpan, int)

Tries to retrieve the amount of time that a given GenericInput has been up for since the last time it was down. If the input has previously been down, this method returns true and the amount of time that it has been up for is stored in upTime.

public bool TryGetUpTime(GenericInput input, out TimeSpan upTime, int index = -1)

Parameters

input GenericInput

The input whose up time to query.

upTime TimeSpan

The resulting up time, or Zero if the input is being held.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

bool

Whether the input is currently up.

Update()

Updates this input handler, querying pressed and released keys and calculating repeat events. Call this in your Microsoft.Xna.Framework.Game.Update(Microsoft.Xna.Framework.GameTime) method.

public void Update()

Update(GameTime)

Updates this input handler, querying pressed and released keys and calculating repeat events. Call this in your Microsoft.Xna.Framework.Game.Update(Microsoft.Xna.Framework.GameTime) method.

public override void Update(GameTime gameTime)

Parameters

gameTime GameTime

WasDown(GenericInput, int)

Returns if a given control of any kind was down in the last update call. This is a helper function that can be passed a Microsoft.Xna.Framework.Input.Keys, Microsoft.Xna.Framework.Input.Buttons or MouseButton.

public bool WasDown(GenericInput control, int index = -1)

Parameters

control GenericInput

The control whose down state to query

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad

Returns

bool

Whether the given control was down

WasPressedForLess(GenericInput, TimeSpan, int)

Returns if a given control of any kind was just let go this frame, and had been down for less than the given time before that. Essentially, this action signifies a short press action.

public bool WasPressedForLess(GenericInput control, TimeSpan time, int index = -1)

Parameters

control GenericInput

The control whose pressed state to query.

time TimeSpan

The maximum time that the control should have been down for.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

bool

Whether the given control was pressed for less than the given time.

WasPressedForLessAvailable(GenericInput, TimeSpan, int)

Returns if a given control of any kind was just let go this frame, and had been down for less than the given time before that, and if the press has not been consumed yet using TryConsumePressedForLess(GenericInput, TimeSpan, int). Essentially, this action signifies a short press action.

public bool WasPressedForLessAvailable(GenericInput control, TimeSpan time, int index = -1)

Parameters

control GenericInput

The control whose pressed state to query.

time TimeSpan

The maximum time that the control should have been down for.

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad.

Returns

bool

Whether the given control was pressed for less than the given time, and the press has not been consumed yet.

WasUp(GenericInput, int)

Returns if a given control of any kind was up in the last update call. This is a helper function that can be passed a Microsoft.Xna.Framework.Input.Keys, Microsoft.Xna.Framework.Input.Buttons or MouseButton.

public bool WasUp(GenericInput control, int index = -1)

Parameters

control GenericInput

The control whose up state to query

index int

The index of the gamepad to query (if applicable), or -1 for any gamepad

Returns

bool

Whether the given control was up.