Class XRInputButtonReader

Serializable typed input button reader that can read the current button's state from an input source. Behaviors can declare a field of this type to allow them to read input from an input action or any other source.

Inheritance
object
XRInputButtonReader
Implements
Inherited Members
Namespace: UnityEngine.XR.Interaction.Toolkit.Inputs.Readers
Assembly: Unity.XR.Interaction.Toolkit.dll
Syntax
[Serializable]
public class XRInputButtonReader : IXRInputButtonReader, IXRInputValueReader<float>, IXRInputValueReader

Constructors

XRInputButtonReader()

Initializes and returns an instance of XRInputButtonReader.

Declaration
public XRInputButtonReader()

XRInputButtonReader(string, string, bool, InputSourceMode)

Initializes and returns an instance of XRInputButtonReader.

Declaration
public XRInputButtonReader(string name = null, string valueName = null, bool wantsInitialStateCheck = false, XRInputButtonReader.InputSourceMode inputSourceMode = InputSourceMode.InputActionReference)
Parameters
Type Name Description
string name

The name of the directly serialized embedded input action for performed.
string valueName

The name of the directly serialized embedded input action for the scalar value. Based off of name if left null.
bool wantsInitialStateCheck

Whether the action should start performing if already actuated when the action is enabled.
XRInputButtonReader.InputSourceMode inputSourceMode

The initial input source mode.

Properties

bypass

A runtime bypass that can be used to override the button input state returned by this class.

Declaration
public IXRInputButtonReader bypass { get; set; }
Property Value
Type Description
IXRInputButtonReader

inputActionPerformed

The directly serialized embedded input action that is read to determine whether the button is down when the mode is set to InputAction.

Declaration
public InputAction inputActionPerformed { get; set; }
Property Value
Type Description
InputAction
Remarks

Must have a button-like interaction where phase equals performed when down. This is the case with an input action whose Action Type is Button or whose Action Type is Value with an interaction like Press or Sector.

inputActionReferencePerformed

The reference to an input action that is read to determine whether the button is down when the mode is set to InputActionReference.

Declaration
public InputActionReference inputActionReferencePerformed { get; set; }
Property Value
Type Description
InputActionReference
Remarks

Must have a button-like interaction where phase equals performed when down. This is the case with an input action whose Action Type is Button or whose Action Type is Value with an interaction like Press or Sector.

inputActionReferenceValue

The reference to an input action that is read to determine the scalar value that varies from 0 to 1 when the mode is set to InputActionReference.

Declaration
public InputActionReference inputActionReferenceValue { get; set; }
Property Value
Type Description
InputActionReference

inputActionValue

The directly serialized embedded input action that is read to determine the scalar value that varies from 0 to 1 when the mode is set to InputAction.

Declaration
public InputAction inputActionValue { get; set; }
Property Value
Type Description
InputAction

inputSourceMode

The mode that determines from which input source the button's state is read from. By default this is set to InputActionReference to read from an input action defined in the project.

Declaration
public XRInputButtonReader.InputSourceMode inputSourceMode { get; set; }
Property Value
Type Description
XRInputButtonReader.InputSourceMode
See Also

manualFrameCompleted

The frame that the manual performed state was set to false when the mode is set to ManualValue.

Declaration
public int manualFrameCompleted { get; set; }
Property Value
Type Description
int
See Also

manualFramePerformed

The frame that the manual performed state was set to true when the mode is set to ManualValue.

Declaration
public int manualFramePerformed { get; set; }
Property Value
Type Description
int
See Also

manualPerformed

The manually set performed state that is returned when the mode is set to ManualValue.

Declaration
public bool manualPerformed { get; set; }
Property Value
Type Description
bool
See Also

manualValue

The manually set scalar value that varies from 0 to 1 that is returned when the mode is set to ManualValue.

Declaration
public float manualValue { get; set; }
Property Value
Type Description
float

Methods

DisableDirectActionIfModeUsed()

Disable the directly serialized embedded input action if the mode is set to InputAction.

Declaration
public void DisableDirectActionIfModeUsed()
See Also

EnableDirectActionIfModeUsed()

Enable the directly serialized embedded input action if the mode is set to InputAction.

Declaration
public void EnableDirectActionIfModeUsed()
See Also

GetObjectReference()

Gets the object reference that is used as the input source when the mode is set to ObjectReference.

Declaration
public IXRInputButtonReader GetObjectReference()
Returns
Type Description
IXRInputButtonReader

Returns the object reference, which may be null.

QueueManualState(bool, float)

Queue a manual state to be effective on the next frame. This method automatically determines whether the button should be considered as newly performed that frame based on the current state.

Declaration
public void QueueManualState(bool performed, float value)
Parameters
Type Name Description
bool performed

The manual button performed state that should be returned next frame.
float value

The manual scalar value that varies from 0 to 1 that should be returned next frame.

QueueManualState(bool, float, bool, bool)

Queue a manual state to be effective on the next frame.

Declaration
public void QueueManualState(bool performed, float value, bool performedThisFrame, bool completedThisFrame)
Parameters
Type Name Description
bool performed

The manual button performed state that should be returned next frame.
float value

The manual scalar value that varies from 0 to 1 that should be returned next frame.
bool performedThisFrame

Whether the manual button should be considered as performed that frame on the next frame.
bool completedThisFrame

Whether the manual button should be considered as completed that frame on the next frame.

ReadIsPerformed()

Read whether the button is currently performed, which typically means whether the button is being pressed. This is typically true for multiple frames.

Declaration
public bool ReadIsPerformed()
Returns
Type Description
bool

Returns true if the button is performed. Otherwise, returns false.
Remarks

For input actions, this depends directly on the interaction(s) driving the action (including the default interaction if no specific interaction has been added to the action or binding).

ReadValue()

Read the current value from the input source.

Declaration
public float ReadValue()
Returns
Type Description
float

Returns the current value from the input source. May return default(TValue) if unused or no source is set.

ReadWasCompletedThisFrame()

Read whether the button completed this frame, which typically means whether the button stopped being pressed during this frame. This is typically only true for one single frame.

Declaration
public bool ReadWasCompletedThisFrame()
Returns
Type Description
bool

Returns true if the button completed this frame. Otherwise, returns false.
Remarks

For input actions, this depends directly on the interaction(s) driving the action (including the default interaction if no specific interaction has been added to the action or binding).

ReadWasPerformedThisFrame()

Read whether the button performed this frame, which typically means whether the button started being pressed during this frame. This is typically only true for one single frame.

Declaration
public bool ReadWasPerformedThisFrame()
Returns
Type Description
bool

Returns true if the button performed this frame. Otherwise, returns false.
Remarks

For input actions, this depends directly on the interaction(s) driving the action (including the default interaction if no specific interaction has been added to the action or binding).

SetObjectReference(IXRInputButtonReader)

Sets the object reference that is used as the input source when the mode is set to ObjectReference.

Declaration
public void SetObjectReference(IXRInputButtonReader value)
Parameters
Type Name Description
IXRInputButtonReader value

The object reference.
Remarks

If the argument is to be serialized, it must be a Unity Object type.

TryReadValue(out float)

Try to read the current value from the input source.

Declaration
public bool TryReadValue(out float value)
Parameters
Type Name Description
float value

When this method returns, contains the current value from the input source. May return default(TValue) if unused or no source is set.
Returns
Type Description
bool

Returns true if the current value was able to be read (and for actions, also if in progress).
Remarks

You can use the return value of this method instead of only using ReadValue() in order to avoid doing any work when the input action is not in progress, such as when the control is not actuated. This can be useful for performance reasons.
If an input processor on an input action returns a different value from the default float when the input action is not in progress, the outvalue returned by this method may not be default(TValue) as is typically the case for Try- methods. If you need to support processors that return a different value from the default when the control is not actuated, you should use ReadValue() instead of using the return value of this method to skip input handling.

Implements