Class OneModifierComposite

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

Inheritance
object
InputBindingComposite
OneModifierComposite
Inherited Members
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

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

overrideModifiersNeedToBePressedFirst

If set to true, the built-in logic to determine if modifiers need to be pressed first is overridden. Default value is false.

Declaration
public bool overrideModifiersNeedToBePressedFirst
Field Value
Type Description
bool
Remarks

By default, 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.

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

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
See Also

valueType

Type of values read from controls bound to binding.

Declaration
public override Type valueType { get; }
Property Value
Type Description
Type
Overrides
See Also

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

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

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

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

See Also