Class ButtonControl

An axis that has a trigger point beyond which it is considered to be pressed.

Inheritance
object
InputControl
InputControl<float>
AxisControl
ButtonControl
AnyKeyControl
DiscreteButtonControl
KeyControl
TouchPressControl
Inherited Members
AxisControl.clamp
AxisControl.clampMin
AxisControl.clampMax
AxisControl.clampConstant
AxisControl.invert
Namespace: UnityEngine.InputSystem.Controls
Assembly: Unity.InputSystem.dll
Syntax
public class ButtonControl : AxisControl
Remarks

By default stored as a single bit. In that format, buttons will only yield 0 and 1 as values. However, buttons return are AxisControls and yield full floating-point values and may thus have a range of values. See pressPoint for how button presses on such buttons are handled.

Constructors

ButtonControl()

Default-initialize the control.

Declaration
public ButtonControl()
Remarks

The default format for the control is FormatBit. The control's minimum value is set to 0 and the maximum value to 1.

Fields

pressPoint

The minimum value the button has to reach for it to be considered pressed.

Declaration
public float pressPoint
Field Value
Type Description
float

Button press threshold.
Remarks

The button is considered pressed, if it has a value equal to or greater than this value.

By default, this property is set to -1. If the value of the property is negative, defaultButtonPressPoint is used.

The value can be configured as a parameter in a layout.

public class MyDevice : InputDevice
{
    [InputControl(parameters = "pressPoint=0.234")]
    public ButtonControl button { get; private set; }
//...

}
See Also

Properties

isPressed

Whether the button is currently pressed.

Declaration
public bool isPressed { get; }
Property Value
Type Description
bool

True if button is currently pressed.
Remarks

A button is considered pressed if its value is equal to or greater than its button press threshold (pressPointOrDefault).

Examples

You can use this to read whether specific keys are currently pressed by using isPressed on keys, as shown in the following examples:

// Using KeyControl property directly.
Keyboard.current.spaceKey.isPressed
Keyboard.current.aKey.isPressed // etc.
// Using Key enum.
Keyboard.current[Key.Space].isPressed
// Using key name.
((KeyControl)Keyboard.current["space"]).isPressed

Note: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use displayName.

You can also use this to read mouse buttons, as shown in the following examples:

bool leftPressed = Mouse.current.leftButton.isPressed;
bool rightPressed = Mouse.current.rightButton.isPressed;
bool middlePressed = Mouse.current.middleButton.isPressed;

You can also check through all numbered buttons on the mouse: (this example does not cause allocations)

var controls = Mouse.current.allControls;
for (var i = 0; i < controls.Count; ++i)
{
    var button = controls[i] as ButtonControl;
    if (button != null && button.isPressed)
    {
        // respond to mouse button press here...
    }
}

Or you can look up controls by name, like this:

bool leftPressed = ((ButtonControl)Mouse.current["leftButton"]).isPressed;
See Also

pressPointOrDefault

Return pressPoint if set, otherwise return defaultButtonPressPoint.

Declaration
public float pressPointOrDefault { get; }
Property Value
Type Description
float

Effective value to use for press point thresholds.
See Also

wasPressedThisFrame

Whether the press started this frame.

Declaration
public bool wasPressedThisFrame { get; }
Property Value
Type Description
bool

True if the current press of the button started this frame.
Remarks

The first time this function - or wasReleasedThisFrame - are called, it's possible that extremely fast inputs (or very slow frame update times) will result in presses/releases being missed. Following the next input system update after either have been called, and from then on until the device is destroyed, this ceases to be an issue. 

// An example showing the use of this property on a gamepad button and a keyboard key.

using UnityEngine;
using UnityEngine.InputSystem;

public class ExampleScript : MonoBehaviour
{
    void Update()
    {
        bool buttonPressed = Gamepad.current.aButton.wasPressedThisFrame;
        bool spaceKeyPressed = Keyboard.current.spaceKey.wasPressedThisFrame;
    }
}
_Note_: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use displayName.

You can also use this property to read mouse buttons. For example:

Mouse.current.leftButton.wasPressedThisFrame
Mouse.current.rightButton.wasPressedThisFrame
Mouse.current.middleButton.wasPressedThisFrame

wasReleasedThisFrame

Whether the press ended this frame.

Declaration
public bool wasReleasedThisFrame { get; }
Property Value
Type Description
bool

True if the current press of the button ended this frame.
Remarks

Note: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use displayName.

Examples

An example showing the use of this property on a gamepad button and a keyboard key:

using UnityEngine;
using UnityEngine.InputSystem;
public class ExampleScript : MonoBehaviour
{
void Update()
{
bool buttonPressed = Gamepad.current.aButton.wasReleasedThisFrame;
bool spaceKeyPressed = Keyboard.current.spaceKey.wasReleasedThisFrame;
}
}

Methods

IsValueConsideredPressed(float)

Whether the given value would be considered pressed for this button.

Declaration
public bool IsValueConsideredPressed(float value)
Parameters
Type Name Description
float value

Value for the button.
Returns
Type Description
bool

True if value crosses the threshold to be considered pressed.
See Also

Extension Methods

Did you find this page useful? Please give it a rating: