docs.unity.cn

Input System 1.3.0

    Show / Hide Table of Contents

    Class InputActionRebindingExtensions.RebindingOperation

    An ongoing rebinding operation.

    Inheritance
    Object
    InputActionRebindingExtensions.RebindingOperation
    Namespace: UnityEngine.InputSystem
    Syntax
    public sealed class RebindingOperation : IDisposable
    Remarks
    An example for how to use this class comes with the Input System package in the form of the "Rebinding UI" sample that can be installed from the Package Manager UI in the Unity editor. The sample comes with a reusable RebindActionUI component that also has a dedicated custom inspector.

    The most convenient way to use this class is by using PerformInteractiveRebinding(InputAction, Int32). This method sets up many default behaviors based on the information found in the given action.

    Note that instances of this class must be disposed of to not leak memory on the unmanaged heap.

    // A MonoBehaviour that can be hooked up to a UI.Button control.
    public class RebindButton : MonoBehaviour
    {
        public InputActionReference m_Action; // Reference to an action to rebind.
        public int m_BindingIndex; // Index into m_Action.bindings for binding to rebind.
        public Text m_DisplayText; // Text in UI that receives the binding display string.
    
        public void OnEnable()
        {
            UpdateDisplayText();
        }
    
        public void OnDisable()
        {
            m_Rebind?.Dispose();
        }
    
        public void OnClick()
        {
            var rebind = m_Action.PerformInteractiveRebinding()
                .WithTargetBinding(m_BindingIndex)
                .OnComplete(_ => UpdateDisplayText())
                .Start();
        }
    
        private void UpdateDisplayText()
        {
            m_DisplayText.text = m_Action.GetBindingDisplayString(m_BindingIndex);
        }
    
        private void RebindingOperation m_Rebind;
    }
    
    rebind.Start();

    The goal of a rebind is always to generate a control path (see InputControlPath) usable with a binding. By default, the generated path will be installed in overridePath. This is non-destructive as the original path is left intact in the form of path.

    This class acts as both a configuration interface for rebinds as well as a controller while the rebind is ongoing. An instance can be reused arbitrary many times. Doing so can avoid allocating additional GC memory (the class internally retains state that it can reuse for multiple rebinds).

    Note, however, that during rebinding it can be necessary to look at the InputControlLayout information registered in the system which means that layouts may have to be loaded. These will be cached for as long as the rebind operation is not disposed of.

    To reset the configuration of a rebind operation without releasing its memory, call Reset(). Note that changing configuration while a rebind is in progress in not allowed and will throw .

    Note that it is also possible to use this class for selecting controls interactively without also having an InputAction or even associated InputBindings. To set this up, configure the rebind accordingly with the respective methods (such as WithExpectedControlType<TControl>()) and use OnApplyBinding(Action<InputActionRebindingExtensions.RebindingOperation, String>) to intercept the binding override process and instead use custom logic to do something with the resulting path (or to even just use the control list found in candidates).

    Fields

    kDefaultMagnitudeThreshold

    Declaration
    public const float kDefaultMagnitudeThreshold = null
    Field Value
    Type Description
    Single

    Properties

    action

    The action that rebinding is being performed on.

    Declaration
    public InputAction action { get; }
    Property Value
    Type Description
    InputAction
    See Also
    WithAction(InputAction)

    bindingMask

    Optional mask to determine which bindings to apply overrides to.

    Declaration
    public InputBinding? bindingMask { get; }
    Property Value
    Type Description
    Nullable<InputBinding>
    Remarks

    If this is not null, all bindings that match this mask will have overrides applied to them.

    canceled

    Whether the rebind has been cancelled.

    Declaration
    public bool canceled { get; }
    Property Value
    Type Description
    Boolean
    See Also
    OnCancel(Action<InputActionRebindingExtensions.RebindingOperation>)

    candidates

    Controls that had input and were deemed potential matches to rebind to.

    Declaration
    public InputControlList<InputControl> candidates { get; }
    Property Value
    Type Description
    InputControlList<InputControl>
    Remarks

    Controls in the list should be ordered by priority with the first element in the list being considered the best match.

    See Also
    AddCandidate(InputControl, Single, Single)
    RemoveCandidate(InputControl)
    scores
    magnitudes

    completed

    Whether the rebind has been completed.

    Declaration
    public bool completed { get; }
    Property Value
    Type Description
    Boolean

    True if the rebind has been completed.

    See Also
    OnComplete(Action<InputActionRebindingExtensions.RebindingOperation>)
    OnComplete(Action<InputActionRebindingExtensions.RebindingOperation>)

    expectedControlType

    Name of the control layout that the rebind is looking for.

    Declaration
    public string expectedControlType { get; }
    Property Value
    Type Description
    String
    Remarks

    This is optional but in general, rebinds will be more successful when the operation knows what kind of input it is looking for.

    If an action is supplied with WithAction(InputAction) (automatically done by PerformInteractiveRebinding(InputAction, Int32)), the expected control type is automatically set to expectedControlType or, if that is not set, to "Button" in case the action has type Button.

    If a binding is supplied with WithTargetBinding(Int32) and the binding is a part binding (see isPartOfComposite), the expected control type is automatically set to that expected by the respective part of the composite.

    If this is set, any input on controls that are not of the expected type is ignored. If this is not set, any control that matches all of the other criteria is considered for rebinding.

    See Also
    layout
    expectedControlType

    magnitudes

    The matching control actuation level (see EvaluateMagnitude() for each control in candidates.

    Declaration
    public ReadOnlyArray<float> magnitudes { get; }
    Property Value
    Type Description
    ReadOnlyArray<Single>

    EvaluateMagnitude() result for each InputControl in candidates.

    Remarks

    This array mirrors candidates, i.e. each entry corresponds to the entry in candidates at the same index.

    See Also
    EvaluateMagnitude()
    candidates
    scores

    scores

    The matching score for each control in candidates.

    Declaration
    public ReadOnlyArray<float> scores { get; }
    Property Value
    Type Description
    ReadOnlyArray<Single>

    A relative floating-point score for each control in candidates.

    Remarks

    Candidates are ranked and sorted by their score. By default, a score is computed for each candidate control automatically. However, this can be overridden using OnComputeScore(Func<InputControl, InputEventPtr, Single>).

    Default scores are directly based on magnitudes (see EvaluateMagnitude()). The greater the magnitude of actuation, the greater the score associated with the control. This means, for example, that if both X and Y are actuated on a gamepad stick, the axis with the greater amount of actuation will get scored higher and thus be more likely to get picked.

    In addition, 1 is added to each default score if the respective control is non-synthetic (see synthetic). This will give controls that correspond to actual controls present on the device precedence over those added internally. For example, if both are actuated, the synthetic up button on stick controls will be ranked lower than the buttonSouth which is an actual button on the device.

    See Also
    OnComputeScore(Func<InputControl, InputEventPtr, Single>)
    candidates
    magnitudes

    selectedControl

    The control currently deemed the best candidate.

    Declaration
    public InputControl selectedControl { get; }
    Property Value
    Type Description
    InputControl

    Primary candidate control at this point.

    Remarks

    If there are no candidates yet, this returns null. If there are candidates, it returns the first element of candidates which is always the control with the highest matching score.

    started

    Whether the rebind is currently in progress.

    Declaration
    public bool started { get; }
    Property Value
    Type Description
    Boolean

    Whether rebind is in progress.

    Remarks

    This is true after calling Start() and set to false when OnComplete(Action<InputActionRebindingExtensions.RebindingOperation>) or OnCancel(Action<InputActionRebindingExtensions.RebindingOperation>) is called.

    See Also
    Start()
    completed
    canceled

    startTime

    Declaration
    public double startTime { get; }
    Property Value
    Type Description
    Double

    timeout

    Declaration
    public float timeout { get; }
    Property Value
    Type Description
    Single

    Methods

    AddCandidate(InputControl, Single, Single)

    Add a candidate to candidates. This will also add values to scores and magnitudes. If the control has already been added, it's values are simply updated based on the given arguments.

    Declaration
    public void AddCandidate(InputControl control, float score, float magnitude = null)
    Parameters
    Type Name Description
    InputControl control

    A control that is meant to be considered as a candidate for the rebind.

    Single score

    The score to associate with the control (see scores). By default, the control with the highest score will be picked by the rebind.

    Single magnitude

    Actuation level of the control to enter into magnitudes.

    See Also
    RemoveCandidate(InputControl)

    Cancel()

    Cancel an ongoing rebind. This will invoke the callback supplied by OnCancel(Action<InputActionRebindingExtensions.RebindingOperation>) (if any).

    Declaration
    public void Cancel()
    See Also
    Start()

    Complete()

    Manually complete the rebinding operation.

    Declaration
    public void Complete()

    Dispose()

    Release all memory held by the option, especially unmanaged memory which will not otherwise be freed.

    Declaration
    public void Dispose()

    Finalize()

    Declaration
    protected void Finalize()

    OnApplyBinding(Action<InputActionRebindingExtensions.RebindingOperation, String>)

    Apply a generated binding path as the final step to complete a rebind.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation OnApplyBinding(Action<InputActionRebindingExtensions.RebindingOperation, string> callback)
    Parameters
    Type Name Description
    Action<InputActionRebindingExtensions.RebindingOperation, String> callback

    Delegate to invoke in order to the apply the generated binding path.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    Once a binding path has been generated (see OnGeneratePath(Func<InputControl, String>)) from a candidate control, the last step is to apply the path. The default logic will take the supplied action (see WithAction(InputAction)) and apply the path as an overridePath on all bindings that have been selected for rebinding with WithTargetBinding(Int32), WithBindingMask(Nullable<InputBinding>), or WithBindingGroup(String).

    To customize this process, you can supply a custom delegate via this method. If you do so, the default logic is bypassed and the step left entirely to the delegate. This also makes it possible to use rebind operations without even having an action or even InputBindings.

    OnCancel(Action<InputActionRebindingExtensions.RebindingOperation>)

    Delegate to invoke when the rebind is cancelled instead of completing. This happens when either an input is received from a control explicitly set up to trigger cancellation (see WithCancelingThrough(String) and WithCancelingThrough(InputControl)) or when Cancel() is called explicitly.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation OnCancel(Action<InputActionRebindingExtensions.RebindingOperation> callback)
    Parameters
    Type Name Description
    Action<InputActionRebindingExtensions.RebindingOperation> callback

    Delegate to invoke when the rebind is cancelled.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation
    See Also
    WithCancelingThrough(String)
    Cancel()
    canceled

    OnComplete(Action<InputActionRebindingExtensions.RebindingOperation>)

    Delegate to invoke when the rebind completes successfully.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation OnComplete(Action<InputActionRebindingExtensions.RebindingOperation> callback)
    Parameters
    Type Name Description
    Action<InputActionRebindingExtensions.RebindingOperation> callback

    A delegate to invoke when the rebind is completed.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    Note that by the time this is invoked, the rebind has been fully applied, that is OnApplyBinding(Action<InputActionRebindingExtensions.RebindingOperation, String>) has been executed.

    OnComputeScore(Func<InputControl, InputEventPtr, Single>)

    Delegate to invoke for compute the matching score for a candidate control.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation OnComputeScore(Func<InputControl, InputEventPtr, float> callback)
    Parameters
    Type Name Description
    Func<InputControl, InputEventPtr, Single> callback

    A delegate that computes matching scores.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    By default, the actuation level of a control is used as its matching score. For a StickControl, for example, the vector magnitude of the control will be its score. So, a stick that is actuated just a little will have a lower score than a stick that is actuated to maximum extent in one direction.

    The control with the highest score will be the one appearing at index 0 in candidates and thus will be the control picked by the rebind as the top candidate.

    By installing a custom delegate, it is possible to customize the scoring and apply custom logic to boost or lower scores of controls.

    The first argument to the delegate is the control that is being added to candidates and the second argument is a pointer to the input event that contains an input on the control.

    See Also
    scores
    candidates

    OnGeneratePath(Func<InputControl, String>)

    Set function to call when generating the final binding path (see path) for a control that has been selected.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation OnGeneratePath(Func<InputControl, string> callback)
    Parameters
    Type Name Description
    Func<InputControl, String> callback

    Delegate to call for when to generate a binding path.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    A rebind will by default create a path that it deems most useful for the purpose of rebinding. However, this logic may be undesirable for your use case. By supplying a custom callback you can bypass this logic and thus replace it.

    When a matching control is singled out, the default logic will look for the device that introduces the given control. For example, if the A button is pressed on an Xbox gamepad, the resulting path will be "<Gamepad>/buttonSouth" as it is the Gamepad device that introduces the south face button on gamepads. Thus, the binding will work with any other gamepad, not just the Xbox controller.

    If the delegate returns a null or empty string, the default logic will be re-engaged.

    See Also
    path
    WithoutGeneralizingPathOfSelectedControl()

    OnMatchWaitForAnother(Single)

    If a successful match has been found, wait for the given time for a better match to appear before committing to the match.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation OnMatchWaitForAnother(float seconds)
    Parameters
    Type Name Description
    Single seconds

    Time in seconds to wait until committing to a match.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    While this adds a certain amount of lag to the operation, the lag is not really perceptible if the timeout is kept short.

    What this helps with is controls such as sticks where, when moved out of the deadzone, the initial direction that the user presses may not be the one actually intended. For example, the user may be pressing slightly more in the X direction before finally very clearly going more strongly in the Y direction. If the rebind does not wait for a bit but instead takes the first actuation as is, the rebind may appear overly brittle.

    An alternative to timeouts is to set higher magnitude thresholds with WithMagnitudeHavingToBeGreaterThan(Single). The default threshold is 0.2f. By setting it to 0.6f or even higher, timeouts may be unnecessary.

    OnPotentialMatch(Action<InputActionRebindingExtensions.RebindingOperation>)

    Delegate to invoke when the rebind has found one or more controls that it considers potential matches. This allows modifying priority of matches or adding or removing matches altogether.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation OnPotentialMatch(Action<InputActionRebindingExtensions.RebindingOperation> callback)
    Parameters
    Type Name Description
    Action<InputActionRebindingExtensions.RebindingOperation> callback

    Callback to invoke when one or more suitable controls have been found.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    The matches will be contained in candidates. In the callback, you can, for example, alter the contents of the list in order to customize the selection process. You can remove candidates with AddCandidate(InputControl, Single, Single) and/or remove candidates with RemoveCandidate(InputControl).

    See Also
    candidates

    RemoveCandidate(InputControl)

    Remove a control from the list of candidates. This also removes its entries from scores and magnitudes.

    Declaration
    public void RemoveCandidate(InputControl control)
    Parameters
    Type Name Description
    InputControl control

    Control to remove from candidates.

    See Also
    AddCandidate(InputControl, Single, Single)

    Reset()

    Reset the configuration on the rebind.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation Reset()
    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    Call this method to reset the effects of calling methods such as WithAction(InputAction), WithBindingGroup(String), etc. but retain other data that the rebind operation may have allocated already. If you are reusing the same RebindingOperation multiple times, a good strategy is to reset and reconfigure the operation before starting it again.

    Start()

    Start the rebinding. This should be invoked after the rebind operation has been fully configured.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation Start()
    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    See Also
    Cancel()
    Dispose()

    WithAction(InputAction)

    Perform rebinding on the bindings of the given action.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithAction(InputAction action)
    Parameters
    Type Name Description
    InputAction action

    Action to perform rebinding on.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    Note that by default, a rebind does not have a binding mask or any other setting that constrains which binding the rebind is applied to. This means that if the action has multiple bindings, all of them will have overrides applied to them.

    To target specific bindings, either set a binding index with WithTargetBinding(Int32), or set a binding mask with WithBindingMask(Nullable<InputBinding>) or WithBindingGroup(String).

    If the action has an associated expectedControlType set, it will automatically be passed to WithExpectedControlType(String).

    See Also
    PerformInteractiveRebinding(InputAction, Int32)

    WithBindingGroup(String)

    Apply the rebinding to all bindings of the action given by WithAction(InputAction) which are associated with the given binding group (see groups).

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithBindingGroup(string group)
    Parameters
    Type Name Description
    String group

    A binding group. See groups. A binding matches if any of its group associates matches.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    See Also
    WithBindingMask(Nullable<InputBinding>)
    WithTargetBinding(Int32)

    WithBindingMask(Nullable<InputBinding>)

    Apply the rebinding to all bindings of the action given by WithAction(InputAction) which are match the given binding mask (see Matches(InputBinding)).

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithBindingMask(InputBinding? bindingMask)
    Parameters
    Type Name Description
    Nullable<InputBinding> bindingMask

    A binding mask. See Matches(InputBinding).

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    See Also
    WithBindingGroup(String)
    WithTargetBinding(Int32)

    WithCancelingThrough(String)

    Set the control path that is matched against actuated controls.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithCancelingThrough(string binding)
    Parameters
    Type Name Description
    String binding

    A control path (see InputControlPath) such as "<Keyboard>/escape".

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    Note that every rebind operation has only one such path. Calling this method repeatedly will overwrite the path set from prior calls.

    var rebind = new RebindingOperation();
    
    // Cancel from keyboard escape key.
    rebind
        .WithCancelingThrough("<Keyboard>/escape");
    
    // Cancel from any control with "Cancel" usage.
    // NOTE: This can be dangerous. The control that the wants to bind to may have the "Cancel"
    //       usage assigned to it, thus making it impossible for the user to bind to the control.
    rebind
        .WithCancelingThrough("*/{Cancel}");

    WithCancelingThrough(InputControl)

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithCancelingThrough(InputControl control)
    Parameters
    Type Name Description
    InputControl control
    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    WithControlsExcluding(String)

    Prevent specific controls from being considered as candidate controls.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithControlsExcluding(string path)
    Parameters
    Type Name Description
    String path

    A control path. See InputControlPath.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    Some controls can be undesirable to include in the candidate selection process even though they constitute valid, non-noise user input. For example, in a desktop application, the mouse will usually be used to navigate the UI including a rebinding UI that makes use of RebindingOperation. It can thus be advisable to exclude specific pointer controls like so:

    rebind
        .WithControlsExcluding("<Pointer>/position") // Don't bind to mouse position
        .WithControlsExcluding("<Pointer>/delta") // Don't bind to mouse movement deltas
        .WithControlsExcluding("<Pointer>/{PrimaryAction}") // don't bind to controls such as leftButton and taps.

    This method can be called repeatedly to add multiple exclusions. To reset the list, call Reset().

    See Also
    Matches(String, InputControl)

    WithControlsHavingToMatchPath(String)

    Restrict candidate controls using a control path (see InputControlPath).

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithControlsHavingToMatchPath(string path)
    Parameters
    Type Name Description
    String path

    A control path. See InputControlPath.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    This method is most useful to, for example, restrict controls to specific types of devices. If, say, you want to let the player only bind to gamepads, you can do so using

    rebind.WithControlsHavingToMatchPath("<Gamepad>");

    This method can be called repeatedly to add multiple paths. The effect is that candidates are accepted if any of the given paths matches. To reset the list, call Reset().

    See Also
    Matches(String, InputControl)

    WithExpectedControlType(String)

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithExpectedControlType(string layoutName)
    Parameters
    Type Name Description
    String layoutName
    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    WithExpectedControlType(Type)

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithExpectedControlType(Type type)
    Parameters
    Type Name Description
    Type type
    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    WithExpectedControlType<TControl>()

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithExpectedControlType<TControl>()
        where TControl : InputControl
    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation
    Type Parameters
    Name Description
    TControl

    WithMagnitudeHavingToBeGreaterThan(Single)

    Require actuation of controls to exceed a certain level.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithMagnitudeHavingToBeGreaterThan(float magnitude)
    Parameters
    Type Name Description
    Single magnitude

    Minimum magnitude threshold that has to be reached on a control for it to be considered a candidate. See EvaluateMagnitude() for details about magnitude evaluations.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    Rebind operations use a default threshold of 0.2. This means that the actuation level of any control as returned by EvaluateMagnitude() must be equal or greater than 0.2 for it to be considered a potential candidate. This helps filter out controls that are actuated incidentally as part of actuating other controls.

    For example, if the player wants to bind an action to the X axis of the gamepad's right stick, the player will almost unavoidably also actuate the Y axis to a certain degree. However, if actuation of the Y axis stays under 2.0, it will automatically get filtered out.

    Note that the magnitude threshold is not the only mechanism that helps trying to find the most actuated control. In fact, all controls will eventually be sorted by magnitude of actuation so even if both X and Y of a stick make it into the candidate list, if X is actuated more strongly than Y, it will be favored.

    Note that you can also use this method to lower the default threshold of 0.2 in case you want more controls to make it through the matching process.

    See Also
    magnitudes
    EvaluateMagnitude()

    WithMatchingEventsBeingSuppressed(Boolean)

    Prevent all input events that have input matching the rebind operation's configuration from reaching its targeted InputDevices and thus taking effect.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithMatchingEventsBeingSuppressed(bool value = true)
    Parameters
    Type Name Description
    Boolean value
    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    While rebinding interactively, it is usually for the most part undesirable for input to actually have an effect. For example, when rebind gamepad input, pressing the "A" button should not lead to a "submit" action in the UI. For this reason, a rebind can be configured to automatically swallow any input event except the ones having input on controls matching WithControlsExcluding(String).

    Not at all input necessarily should be suppressed. For example, it can be desirable to have UI that allows the user to cancel an ongoing rebind by clicking with the mouse. This means that mouse position and click input should come through. For this reason, input from controls matching WithControlsExcluding(String) is still let through.

    WithoutGeneralizingPathOfSelectedControl()

    Disable the default behavior of automatically generalizing the path of a selected control.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithoutGeneralizingPathOfSelectedControl()
    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    At runtime, every InputControl has a unique path in the system (path). However, when performing rebinds, we are not generally interested in the specific runtime path of the control -- which may depend on the number and types of devices present. In fact, most of the time we are not even interested in what particular brand of device the user is rebinding to but rather want to just bind based on the device's broad category.

    For example, if the user has a DualShock controller and performs an interactive rebind, we usually do not want to generate override paths that reflects that the input specifically came from a DualShock controller. Rather, we're usually interested in the fact that it came from a gamepad.

    See Also
    overridePath
    OnGeneratePath(Func<InputControl, String>)

    WithoutIgnoringNoisyControls()

    Do not ignore input from noisy controls.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithoutIgnoringNoisyControls()
    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    By default, noisy controls are ignored for rebinds. This means that, for example, a gyro inside a gamepad will not be considered as a potential candidate control as it is hard to tell valid user interaction on the control apart from random jittering that occurs on noisy controls.

    By calling this method, this behavior can be disabled. This is usually only useful when implementing custom candidate selection through OnPotentialMatch(Action<InputActionRebindingExtensions.RebindingOperation>).

    See Also
    noisy

    WithRebindAddingNewBinding(String)

    Instead of applying the generated path as an overridePath, create a new binding on the given action (see WithAction(InputAction)).

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithRebindAddingNewBinding(string group = null)
    Parameters
    Type Name Description
    String group

    Binding group (see groups) to apply to the new binding. This determines, for example, which control scheme (if any) the binding is associated with.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation
    See Also
    OnApplyBinding(Action<InputActionRebindingExtensions.RebindingOperation, String>)

    WithTargetBinding(Int32)

    Rebinding a specific InputBinding on an InputAction as identified by the given index into bindings.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithTargetBinding(int bindingIndex)
    Parameters
    Type Name Description
    Int32 bindingIndex

    Index into bindings of the action supplied by WithAction(InputAction).

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    Note that if the given binding is a part binding of a composite (see isPartOfComposite), then the expected control type (see WithExpectedControlType(String)) is implicitly changed to match the type of control expected by the given part. If, for example, the composite the part belongs to is a Vector2Composite, then the expected control type is implicitly changed to ButtonControl.

    // Create an action with a WASD setup.
    var moveAction = new InputAction(expectedControlType: "Vector2");
    moveAction.AddCompositeBinding("2DVector")
        .With("Up", "<Keyboard>/w")
        .With("Down", "<Keyboard>/s")
        .With("Left", "<Keyboard>/a")
        .With("Right", "<Keyboard>/d");
    
    // Start a rebind of the "Up" binding.
    moveAction.PerformInteractiveRebinding()
        .WithTargetBinding(1)
        .Start();
    See Also
    WithAction(InputAction)
    bindings
    WithBindingMask(Nullable<InputBinding>)
    WithBindingGroup(String)

    WithTimeout(Single)

    If no match materializes with timeInSeconds, cancel the rebind automatically.

    Declaration
    public InputActionRebindingExtensions.RebindingOperation WithTimeout(float timeInSeconds)
    Parameters
    Type Name Description
    Single timeInSeconds

    Time in seconds to wait for a successful rebind. Disabled if timeout is less than or equal to 0.

    Returns
    Type Description
    InputActionRebindingExtensions.RebindingOperation

    The same RebindingOperation instance.

    Remarks

    Limiting rebinds by time can be useful in situations where a rebind may potentially put the user in a situation where there is no other way to escape the rebind. For example, if WithMatchingEventsBeingSuppressed(Boolean) is engaged, input may be consumed by the rebind and thus not reach the UI if WithControlsExcluding(String) has not also been configured accordingly.

    By default, no timeout is set.

    See Also
    timeout

    See Also

    PerformInteractiveRebinding(InputAction, Int32)
    In This Article
    • Fields
      • kDefaultMagnitudeThreshold
    • Properties
      • action
      • bindingMask
      • canceled
      • candidates
      • completed
      • expectedControlType
      • magnitudes
      • scores
      • selectedControl
      • started
      • startTime
      • timeout
    • Methods
      • AddCandidate(InputControl, Single, Single)
      • Cancel()
      • Complete()
      • Dispose()
      • Finalize()
      • OnApplyBinding(Action<InputActionRebindingExtensions.RebindingOperation, String>)
      • OnCancel(Action<InputActionRebindingExtensions.RebindingOperation>)
      • OnComplete(Action<InputActionRebindingExtensions.RebindingOperation>)
      • OnComputeScore(Func<InputControl, InputEventPtr, Single>)
      • OnGeneratePath(Func<InputControl, String>)
      • OnMatchWaitForAnother(Single)
      • OnPotentialMatch(Action<InputActionRebindingExtensions.RebindingOperation>)
      • RemoveCandidate(InputControl)
      • Reset()
      • Start()
      • WithAction(InputAction)
      • WithBindingGroup(String)
      • WithBindingMask(Nullable<InputBinding>)
      • WithCancelingThrough(String)
      • WithCancelingThrough(InputControl)
      • WithControlsExcluding(String)
      • WithControlsHavingToMatchPath(String)
      • WithExpectedControlType(String)
      • WithExpectedControlType(Type)
      • WithExpectedControlType<TControl>()
      • WithMagnitudeHavingToBeGreaterThan(Single)
      • WithMatchingEventsBeingSuppressed(Boolean)
      • WithoutGeneralizingPathOfSelectedControl()
      • WithoutIgnoringNoisyControls()
      • WithRebindAddingNewBinding(String)
      • WithTargetBinding(Int32)
      • WithTimeout(Single)
    • See Also
    Back to top Copyright © 2022 Unity Technologies
    Generated by DocFX
    on Wednesday, January 5, 2022
    Terms of use