UserInputState
The UserInputState enum describes the state of an input that is currently or was recently performed.
Items 5
| History | Name | Value | Description | |
|---|---|---|---|---|
| 113 | Begin | 0 | Occurs when an InputObject starts to interact with the game. For example, a mouse button down, or a key down, or when a touch begins touching the screen. | |
| 113 | Change | 1 | Occurs each frame an InputObject has already begun interacting with the game and part of its state is changing. For example, a movement of the mouse position, a gamepad thumbstick, gamepad trigger button, or screen touch point. | |
| 113 | End | 2 | When an InputObject finishes interacting with the game. For example, a mouse button up, or a key up, or when a touch stops touching the screen. | |
| 194 | Cancel | 3 | A special circumstance state that indicates this input is no longer relevant, particularly with ContextActionService. For example, binding two action-handling functions will cause the first to Cancel if an input was already in-progress when the second was bound. | |
| 194 | None | 4 | A state that should never be seen in a game, essentially just marks the end of the enum. |
Description
The UserInputState enum describes the state of an input that is currently or was recently performed. It is used by the InputObject.UserInputState property of the same name, as well as various UserInputService and GuiObject events.
Depending on the UserInputType, input may follow states differently.
- Simple button and key presses generally follow a simple Begin →
End flow.
- Gamepad trigger buttons are similar to button presses, but will use Change as the state of the button changes.
- Mouse movement generally follows Begin (mouse-over) → Change
→ End (mouse-leave).
- Touch input behaves somewhat similarly to mouse movement. Begin and End occur when the user starts or ends touching the screen, respectively. The same InputObject is used for the same touch point.
- Gamepad thumbstick controls will cause Change to occur each frame the position changes.
Cancel
In the context of ContextActionService, binding action-handling functions using BindAction provides a UserInputState to the action handler when a relevant input is performed. If an in-progress input associated with a bound action is then unbound or becomes relevant to a different input, the Cancel UserInputState is passed, indicating that the input is no longer relevant to the action.