Class OneModifierComposite

A binding with an additional modifier. The bound controls only trigger when the modifier is pressed.

Inheritance

object

InputBindingComposite

OneModifierComposite

Inherited Members

InputBindingComposite.GetExpectedControlLayoutName(string, string)

Namespace: UnityEngine.InputSystem.Composites

Assembly: Unity.InputSystem.dll

Syntax

[DisplayStringFormat("{modifier}+{binding}")]
public class OneModifierComposite : InputBindingComposite

Remarks

This composite can be used to require a button to be held in order to "activate" another binding. This is most commonly used on keyboards to require one of the modifier keys (shift, ctrl, or alt) to be held in combination with another control, e.g. "CTRL+1".

// Create a button action that triggers when CTRL+1
// is pressed on the keyboard.
var action = new InputAction(type: InputActionType.Button);
action.AddCompositeBinding("OneModifier")
    .With("Modifier", "<Keyboard>/ctrl")
    .With("Binding", "<Keyboard>/1")

However, this can also be used to "gate" other types of controls. For example, a "look" action could be bound to mouse delta such that the altKey on the keyboard has to be pressed in order for the player to be able to look around.

lookAction.AddCompositeBinding("OneModifier")
    .With("Modifier", "<Keyboard>/alt")
    .With("Binding", "<Mouse>/delta")

Fields

binding

Binding for the control that is gated by the modifier. The composite will assume the value of this control while the modifier is considered pressed (that is, has a magnitude equal to or greater than the button press point).

Declaration

public int binding

Field Value

Type	Description
int	Part index to use with ReadValue<TValue>(int).

Remarks

This property is automatically assigned by the input system.

See Also

TwoModifiersComposite

modifier

Binding for the button that acts as a modifier, e.g. <Keyboard/ctrl.

Declaration

public int modifier

Field Value

Type	Description
int	Part index to use with ReadValue<TValue>(int).

Remarks

This property is automatically assigned by the input system.

See Also

TwoModifiersComposite

modifiersOrder

If set to Ordered or Unordered, the built-in logic to determine if modifiers need to be pressed first is overridden.

Declaration

[Tooltip("By default it follows the Input Consumption setting to determine if the modifers keys need to be pressed first.")]
public OneModifierComposite.ModifiersOrder modifiersOrder

Field Value

Type	Description
OneModifierComposite.ModifiersOrder

Remarks

By default, if the setting shortcutKeysConsumeInput is enabled, if binding is bound to only ButtonControls, then the composite requires modifier to be pressed before pressing binding. This means that binding to, for example, Ctrl+B, the ctrl keys have to be pressed before pressing the B key. This is the behavior usually expected with keyboard shortcuts.

If the setting shortcutKeysConsumeInput is disabled, modifiers can be pressed after the button and the composite will still trigger.

However, when binding, for example, Ctrl+MouseDelta, it should be possible to press ctrl at any time. The default logic will automatically detect the difference between this binding and the button binding in the example above and behave accordingly.

This field allows you to explicitly override this default inference and make the order mandatory or make it so that regardless of what binding is bound to, any press sequence is acceptable. For the example binding to Ctrl+B, it would mean that pressing B and only then pressing Ctrl will still trigger the binding.

See Also

TwoModifiersComposite

Properties

valueSizeInBytes

Size of the largest value that may be read from the controls bound to binding.

Declaration

public override int valueSizeInBytes { get; }

Property Value

Type	Description
int

Overrides

InputBindingComposite.valueSizeInBytes

See Also

TwoModifiersComposite

valueType

Type of values read from controls bound to binding.

Declaration

public override Type valueType { get; }

Property Value

Type	Description
Type

Overrides

InputBindingComposite.valueType

See Also

TwoModifiersComposite

Methods

EvaluateMagnitude(ref InputBindingCompositeContext)

Determine the current level of actuation of the composite.

Declaration

public override float EvaluateMagnitude(ref InputBindingCompositeContext context)

Parameters

Type	Name	Description
InputBindingCompositeContext	context	Callback context for the binding composite. Use this to access the values supplied by part bindings.

Returns

Type	Description
float

Overrides

InputBindingComposite.EvaluateMagnitude(ref InputBindingCompositeContext)

Remarks

This method by default returns -1, meaning that the composite does not support magnitudes. You can override the method to add support for magnitudes.

See EvaluateMagnitude() for details of how magnitudes work.

See Also

EvaluateMagnitude()

FinishSetup(ref InputBindingCompositeContext)

Called after binding resolution for an InputActionMap is complete.

Declaration

protected override void FinishSetup(ref InputBindingCompositeContext context)

Parameters

Type	Name	Description
InputBindingCompositeContext	context

Overrides

InputBindingComposite.FinishSetup(ref InputBindingCompositeContext)

Remarks

Some composites do not have predetermine value types. Two examples of this are OneModifierComposite and TwoModifiersComposite, which both have a "binding" part that can be bound to arbitrary controls. This means that the value type of these bindings can only be determined at runtime.

Overriding this method allows accessing the actual controls bound to each part at runtime.

[InputControl] public int binding;

     protected override void FinishSetup(ref InputBindingContext context)
     {
         // Get all controls bound to the 'binding' part.
         var controls = context.controls
             .Where(x => x.part == binding)
             .Select(x => x.control);
     }</code></pre></example>


See Also

TwoModifiersComposite

ReadValue(ref InputBindingCompositeContext, void*, int)

Read a value from the composite without having to know the value type (unlike ReadValue(ref InputBindingCompositeContext) and without allocating GC heap memory (unlike ReadValueAsObject(ref InputBindingCompositeContext)).

Declaration

public override void ReadValue(ref InputBindingCompositeContext context, void* buffer, int bufferSize)

Parameters

Type	Name	Description
InputBindingCompositeContext	context	Callback context for the binding composite. Use this to access the values supplied by part bindings.
void*	buffer	Buffer that receives the value read for the composite.
int	bufferSize	Size of the buffer allocated at buffer.

Overrides

InputBindingComposite.ReadValue(ref InputBindingCompositeContext, void*, int)

Remarks

This API will be used if someone calls ReadValue(void*, int) with the action leading to the composite.

By deriving from InputBindingComposite<TValue>, this will automatically be implemented for you.

Exceptions

Type	Condition
ArgumentException	bufferSize is smaller than valueSizeInBytes.
ArgumentNullException	buffer is null.

See Also

ReadValue(void*, int)

ReadValueAsObject(ref InputBindingCompositeContext)

Read the value of the composite as a boxed object. This allows reading the value without having to know the value type and without having to deal with raw byte buffers.

Declaration

public override object ReadValueAsObject(ref InputBindingCompositeContext context)

Parameters

Type	Name	Description
InputBindingCompositeContext	context	Callback context for the binding composite. Use this to access the values supplied by part bindings.

Returns

Type	Description
object	The current value of the composite according to the state passed in through context.

Overrides

InputBindingComposite.ReadValueAsObject(ref InputBindingCompositeContext)

Remarks

This API will be used if someone calls ReadValueAsObject() with the action leading to the composite.

By deriving from InputBindingComposite<TValue>, this will automatically be implemented for you.

See Also

TwoModifiersComposite

See Also

TwoModifiersComposite