Class InputActionRebindingExtensions.RebindingOperation

An ongoing rebinding operation.

Inheritance

Object

InputActionRebindingExtensions.RebindingOperation

Namespace: UnityEngine.InputSystem

Syntax

public sealed class RebindingOperation : IDisposable

Remarks

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.

var rebind = new RebindingOperation()
    .WithAction(myAction)
    .WithBindingGroup("Gamepad")
    .WithCancelingThrough("<Keyboard>/escape");

rebind.Start();

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

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

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

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.

See Also

AddCandidate(InputControl, Single, Single)

RemoveCandidate(InputControl)

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

expectedControlType

Declaration

public string expectedControlType { get; }

Property Value

Type	Description
String

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

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

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)

Declaration

public void AddCandidate(InputControl control, float score, float magnitude = -1F)

Parameters

Type	Name	Description
InputControl	control
Single	score
Single	magnitude

Cancel()

Declaration

public void Cancel()

Complete()

Manually complete the rebinding operation.

Declaration

public void Complete()

Dispose()

Declaration

public void Dispose()

Implements

IDisposable.Dispose()

Finalize()

Declaration

protected void Finalize()

OnApplyBinding(Action<InputActionRebindingExtensions.RebindingOperation, String>)

Declaration

public InputActionRebindingExtensions.RebindingOperation OnApplyBinding(Action<InputActionRebindingExtensions.RebindingOperation, string> callback)

Parameters

Type	Name	Description
Action<InputActionRebindingExtensions.RebindingOperation, String>	callback

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

OnCancel(Action<InputActionRebindingExtensions.RebindingOperation>)

Declaration

public InputActionRebindingExtensions.RebindingOperation OnCancel(Action<InputActionRebindingExtensions.RebindingOperation> callback)

Parameters

Type	Name	Description
Action<InputActionRebindingExtensions.RebindingOperation>	callback

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

OnComplete(Action<InputActionRebindingExtensions.RebindingOperation>)

Declaration

public InputActionRebindingExtensions.RebindingOperation OnComplete(Action<InputActionRebindingExtensions.RebindingOperation> callback)

Parameters

Type	Name	Description
Action<InputActionRebindingExtensions.RebindingOperation>	callback

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

OnComputeScore(Func<InputControl, InputEventPtr, Single>)

Declaration

public InputActionRebindingExtensions.RebindingOperation OnComputeScore(Func<InputControl, InputEventPtr, float> callback)

Parameters

Type	Name	Description
Func<InputControl, InputEventPtr, Single>	callback

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

OnGeneratePath(Func<InputControl, String>)

Set function to call when generating the final binding 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

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

OnMatchWaitForAnother(Single)

Declaration

public InputActionRebindingExtensions.RebindingOperation OnMatchWaitForAnother(float seconds)

Parameters

Type	Name	Description
Single	seconds

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

OnPotentialMatch(Action<InputActionRebindingExtensions.RebindingOperation>)

Declaration

public InputActionRebindingExtensions.RebindingOperation OnPotentialMatch(Action<InputActionRebindingExtensions.RebindingOperation> callback)

Parameters

Type	Name	Description
Action<InputActionRebindingExtensions.RebindingOperation>	callback

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

RemoveCandidate(InputControl)

Declaration

public void RemoveCandidate(InputControl control)

Parameters

Type	Name	Description
InputControl	control

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

Declaration

public InputActionRebindingExtensions.RebindingOperation Start()

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

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.

See Also

PerformInteractiveRebinding(InputAction, Int32)

WithBindingGroup(String)

Declaration

public InputActionRebindingExtensions.RebindingOperation WithBindingGroup(string group)

Parameters

Type	Name	Description
String	group

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

WithBindingMask(Nullable<InputBinding>)

Declaration

public InputActionRebindingExtensions.RebindingOperation WithBindingMask(InputBinding? bindingMask)

Parameters

Type	Name	Description
Nullable<InputBinding>	bindingMask

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

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.

See Also

overridePath

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)

Declaration

public InputActionRebindingExtensions.RebindingOperation WithRebindAddingNewBinding(string group = null)

Parameters

Type	Name	Description
String	group

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

WithTargetBinding(Int32)

Declaration

public InputActionRebindingExtensions.RebindingOperation WithTargetBinding(int bindingIndex)

Parameters

Type	Name	Description
Int32	bindingIndex

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

WithTimeout(Single)

Declaration

public InputActionRebindingExtensions.RebindingOperation WithTimeout(float timeInSeconds)

Parameters

Type	Name	Description
Single	timeInSeconds

Returns

Type	Description
InputActionRebindingExtensions.RebindingOperation

See Also

PerformInteractiveRebinding(InputAction, Int32)