Class InputActionRebindingExtensions.RebindingOperation

An ongoing rebinding operation.

Inheritance

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 InvalidOperationException.

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 = 0.2F

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

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

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.

completed

Whether the rebind has been completed.

Declaration

public bool completed { get; }

Property Value

Type	Description
Boolean	True if the rebind has been completed.

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.

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.

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.

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.

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 = -1F)

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.

Exceptions

Type	Condition
ArgumentNullException	`control` is `null`.

Cancel()

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

Declaration

public void Cancel()

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()

Implements

IDisposable.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

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.

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.

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).

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.

Exceptions

Type	Condition
ArgumentNullException	`control` is `null`.

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.

Exceptions

Type	Condition
InvalidOperationException	The rebind has been configure incorrectly. For example, no action has been given but no OnApplyBinding(Action<InputActionRebindingExtensions.RebindingOperation, String>) callback has been installed either.

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).

Exceptions

Type	Condition
ArgumentNullException	`action` is `null`.
InvalidOperationException	`action` is currently enabled.

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.

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.

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().

Exceptions

Type	Condition
ArgumentNullException	`path` is `null` or empty.

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().

Exceptions

Type	Condition
ArgumentNullException	`path` is `null` or empty.

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.

Exceptions

Type	Condition
ArgumentException	`magnitude` is negative.

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.

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>).

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

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();

Exceptions

Type	Condition
ArgumentOutOfRangeException	`bindingIndex` is negative.

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.

Class InputActionRebindingExtensions.RebindingOperation

Inheritance

Namespace: UnityEngine.InputSystem

Syntax

Remarks

Fields

kDefaultMagnitudeThreshold

Declaration

Field Value

Properties

action

Declaration

Property Value

See Also

bindingMask

Declaration

Property Value

Remarks

canceled

Declaration

Property Value

See Also

candidates

Declaration

Property Value

Remarks

See Also

completed

Declaration

Property Value

See Also

expectedControlType

Declaration

Property Value

Remarks

See Also

magnitudes

Declaration

Property Value

Remarks

See Also

scores

Declaration

Property Value

Remarks

See Also

selectedControl

Declaration

Property Value

Remarks

started

Declaration

Property Value

Remarks

See Also

startTime

Declaration

Property Value

timeout

Declaration

Property Value

Methods

AddCandidate(InputControl, Single, Single)

Declaration

Parameters

Exceptions

See Also

Cancel()

Declaration

See Also

Complete()

Declaration

Dispose()

Declaration

Implements

Finalize()

Declaration

OnApplyBinding(Action<InputActionRebindingExtensions.RebindingOperation, String>)

Declaration

Parameters