File size: 6,916 Bytes
18a519f | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 | using UnityEngine.InputSystem.Interactions;
////REVIEW: this goes beyond just actions; is there a better name? just InputPhase?
////REVIEW: what about opening up phases completely to interactions and allow them to come up with whatever custom phases?
namespace UnityEngine.InputSystem
{
/// <summary>
/// Trigger phase of an <see cref="InputAction"/>.
/// </summary>
/// <remarks>
/// Actions can be triggered in steps. For example, a <see cref="SlowTapInteraction">
/// 'slow tap'</see> will put an action into <see cref="Started"/> phase when a button
/// the action is bound to is pressed. At that point, however, the action still
/// has to wait for the expiration of a timer in order to make it a 'slow tap'. If
/// the button is release before the timer expires, the action will be <see cref="Canceled"/>
/// whereas if the button is held long enough, the action will be <see cref="Performed"/>.
/// </remarks>
/// <seealso cref="InputAction.phase"/>
/// <seealso cref="InputAction.CallbackContext.phase"/>
/// <seealso cref="InputAction.started"/>
/// <seealso cref="InputAction.performed"/>
/// <seealso cref="InputAction.canceled"/>
public enum InputActionPhase
{
/// <summary>
/// The action is not enabled.
/// </summary>
Disabled,
/// <summary>
/// The action is enabled and waiting for input on its associated controls.
///
/// This is the phase that an action goes back to once it has been <see cref="Performed"/>
/// or <see cref="Canceled"/>.
/// </summary>
Waiting,
/// <summary>
/// An associated control has been actuated such that it may lead to the action
/// being triggered. Will lead to <see cref="InputAction.started"/> getting called.
///
/// This phase will only be invoked if there are interactions on the respective control
/// binding. Without any interactions, an action will go straight from <see cref="Waiting"/>
/// into <see cref="Performed"/> and back into <see cref="Waiting"/> whenever an associated
/// control changes value.
///
/// An example of an interaction that uses the <see cref="Started"/> phase is <see cref="SlowTapInteraction"/>.
/// When the button it is bound to is pressed, the associated action goes into the <see cref="Started"/>
/// phase. At this point, the interaction does not yet know whether the button press will result in just
/// a tap or will indeed result in slow tap. If the button is released before the time it takes to
/// recognize a slow tap, then the action will go to <see cref="Canceled"/> and then back to <see cref="Waiting"/>.
/// If, however, the button is held long enough for it to qualify as a slow tap, the action will progress
/// to <see cref="Performed"/> and then go back to <see cref="Waiting"/>.
///
/// <see cref="Started"/> can be useful for UI feedback. For example, in a game where the weapon can be charged,
/// UI feedback can be initiated when the action is <see cref="Started"/>.
///
/// <example>
/// <code>
/// fireAction.started +=
/// ctx =>
/// {
/// if (ctx.interaction is SlowTapInteraction)
/// {
/// weaponCharging = true;
/// weaponChargeStartTime = ctx.time;
/// }
/// }
/// fireAction.canceled +=
/// ctx =>
/// {
/// weaponCharging = false;
/// }
/// fireAction.performed +=
/// ctx =>
/// {
/// Fire();
/// weaponCharging = false;
/// }
/// </code>
/// </example>
///
/// By default, an action is started as soon as a control moves away from its default value. This is
/// the case for both <see cref="InputActionType.Button"/> actions (which, however, does not yet have to mean
/// that the button press threshold has been reached; see <see cref="InputSettings.defaultButtonPressPoint"/>)
/// and <see cref="InputActionType.Value"/> actions. <see cref="InputActionType.PassThrough"/> does not use
/// the <c>Started</c> phase and instead goes straight to <see cref="Performed"/>.
///
/// For <see cref="InputActionType.Value"/> actions, <c>Started</c> will immediately be followed by <see cref="Performed"/>.
///
/// Note that interactions (see <see cref="IInputInteraction"/>) can alter how an action does or does not progress through
/// the phases.
/// </summary>
Started,
/// <summary>
/// The action has been performed. Leads to <see cref="InputAction.performed"/> getting called.
///
/// By default, a <see cref="InputActionType.Button"/> action performs when a control crosses the button
/// press threshold (see <see cref="InputSettings.defaultButtonPressPoint"/>), a <see cref="InputActionType.Value"/>
/// action performs on any value change that isn't the default value, and a <see cref="InputActionType.PassThrough"/>
/// action performs on any value change including going back to the default value.
///
/// Note that interactions (see <see cref="IInputInteraction"/>) can alter how an action does or does not progress through
/// the phases.
///
/// For a given action, finding out whether it was performed in the current frame can be done with <see cref="InputAction.WasPerformedThisFrame"/>.
///
/// <example>
/// <code>
/// action.WasPerformedThisFrame();
/// </code>
/// </example>
/// </summary>
Performed,
/// <summary>
/// The action has stopped. Leads to <see cref="InputAction.canceled"/> getting called.
///
/// By default, a <see cref="InputActionType.Button"/> action cancels when a control falls back below the button
/// press threshold (see <see cref="InputSettings.defaultButtonPressPoint"/>) and a <see cref="InputActionType.Value"/>
/// action cancels when a control moves back to its default value. A <see cref="InputActionType.PassThrough"/> action
/// does not generally cancel based on input on its controls.
///
/// An action will also get canceled when it is disabled while in progress (see <see cref="InputAction.Disable"/>).
/// Also, when an <see cref="InputDevice"/> that is
///
/// Note that interactions (see <see cref="IInputInteraction"/>) can alter how an action does or does not progress through
/// the phases.
/// </summary>
Canceled
}
}
|