Class InputControlPath

Functions for working with control path specs (like "/gamepad/*stick").

Inheritance

System.Object

InputControlPath

Namespace: UnityEngine.InputSystem

Syntax

public static class InputControlPath

Remarks

Control paths are a mini-language similar to regular expressions. They are used throughout the input system as string "addresses" of input controls. At runtime, they can be matched against the devices and controls present in the system to retrieve the actual endpoints to receive input from.

Like on a file system, a path is made up of components that are each separated by a forward slash (/). Each such component in turn is made up of a set of fields that are individually optional. However, one of the fields must be present (e.g. at least a name or a wildcard).

Field structure of each path component

<Layout>{Usage}#(DisplayName)Name

• Layout: The name of the layout that the control must be based on (either directly or indirectly).
• Usage: The usage that the control or device has to have, i.e. must be found in usages This field can be repeated several times to require multiple usages (e.g. "{LeftHand}{Vertical}").
• DisplayName: The name that displayName of the control or device must match.
• Name: The name that name or one of the entries in aliases must match. Alternatively, this can be a wildcard (*) to match any name.

Note that all matching is case-insensitive.

Various examples of control paths

// Matches all gamepads (also gamepads *based* on the Gamepad layout):
"<Gamepad>"

// Matches the "Submit" control on all devices:
"*/{Submit}"

// Matches the key that prints the "a" character on the current keyboard layout:
"<Keyboard>/#(a)"

// Matches the X axis of the left stick on a gamepad.
"<Gamepad>/leftStick/x"

// Matches the orientation control of the right-hand XR controller:
"<XRController>{RightHand}/orientation"

// Matches all buttons on a gamepad.
"<Gamepad>/<Button>"

The structure of the API of this class is similar in spirit to System.IO.Path, i.e. it offers a range of static methods that perform various operations on path strings.

To query controls on devices present in the system using control paths, use FindControls(String). Also, control paths can be used with Item[String] on every control. This makes it possible to do things like:

Find key that prints "t" on current keyboard:

Keyboard.current["#(t)"]

Fields

DoubleWildcard

Declaration

public const string DoubleWildcard = "**"

Field Value

Type	Description
System.String

Separator

Declaration

public const char Separator = '/'

Field Value

Type	Description
System.Char

Wildcard

Declaration

public const string Wildcard = "*"

Field Value

Type	Description
System.String

Methods

Combine(InputControl, String)

Declaration

public static string Combine(InputControl parent, string path)

Parameters

Type	Name	Description
InputControl	parent
System.String	path

Returns

Type	Description
System.String

Matches(String, InputControl)

Declaration

public static bool Matches(string expected, InputControl control)

Parameters

Type	Name	Description
System.String	expected
InputControl	control

Returns

Type	Description
System.Boolean

MatchesPrefix(String, InputControl)

Declaration

public static bool MatchesPrefix(string expected, InputControl control)

Parameters

Type	Name	Description
System.String	expected
InputControl	control

Returns

Type	Description
System.Boolean

ToHumanReadableString(String, InputControlPath.HumanReadableStringOptions)

Create a human readable string from the given control path.

Declaration

public static string ToHumanReadableString(string path, InputControlPath.HumanReadableStringOptions options = InputControlPath.HumanReadableStringOptions.None)

Parameters

Type	Name	Description
System.String	path	A control path such as "<XRController>{LeftHand}/position".
InputControlPath.HumanReadableStringOptions	options	Customize the resulting string.

Returns

Type	Description
System.String	A string such as "Left Stick/X [Gamepad]".

Remarks

This function is most useful for turning binding paths (see path) into strings that can be displayed in UIs (such as rebinding screens). It is used by the Unity editor itself to display binding paths in the UI.

The method uses display names (see displayName, displayName, and displayName) where possible. For example, "<XInputController>/buttonSouth" will be returned as "A [Xbox Controller]" as the display name of XInputController is "XBox Controller" and the display name of its "buttonSouth" control is "A".

Note that these lookups depend on the currently registered control layouts (see InputControlLayout) and different strings may thus be returned for the same control path depending on the layouts registered with the system.

InputControlPath.ToHumanReadableString("*/{PrimaryAction"); // -> "PrimaryAction [Any]"
InputControlPath.ToHumanReadableString("<Gamepad>/buttonSouth"); // -> "Button South [Gamepad]"
InputControlPath.ToHumanReadableString("<XInputController>/buttonSouth"); // -> "A [Xbox Controller]"
InputControlPath.ToHumanReadableString("<Gamepad>/leftStick/x"); // -> "Left Stick/X [Gamepad]"

See Also

path

TryFindChild(InputControl, String, Int32)

Declaration

public static InputControl TryFindChild(InputControl control, string path, int indexInPath = 0)

Parameters

Type	Name	Description
InputControl	control
System.String	path
System.Int32	indexInPath

Returns

Type	Description
InputControl

TryFindChild<TControl>(InputControl, String, Int32)

Declaration

public static TControl TryFindChild<TControl>(InputControl control, string path, int indexInPath = 0)
    where TControl : InputControl

Parameters

Type	Name	Description
InputControl	control
System.String	path
System.Int32	indexInPath

Returns

Type	Description
TControl

Type Parameters

Name	Description
TControl

TryFindControl(InputControl, String, Int32)

Declaration

public static InputControl TryFindControl(InputControl control, string path, int indexInPath = 0)

Parameters

Type	Name	Description
InputControl	control
System.String	path
System.Int32	indexInPath

Returns

Type	Description
InputControl

TryFindControl<TControl>(InputControl, String, Int32)

Return the first control that matches the given path.

Declaration

public static TControl TryFindControl<TControl>(InputControl control, string path, int indexInPath = 0)
    where TControl : InputControl

Parameters

Type	Name	Description
InputControl	control
System.String	path
System.Int32	indexInPath

Returns

Type	Description
TControl

Type Parameters

Name	Description
TControl

Remarks

Does not allocate.

Exceptions

Type	Condition
System.ArgumentNullException

TryFindControls(InputControl, String, Int32)

Declaration

public static InputControl[] TryFindControls(InputControl control, string path, int indexInPath = 0)

Parameters

Type	Name	Description
InputControl	control
System.String	path
System.Int32	indexInPath

Returns

Type	Description
InputControl[]

TryFindControls(InputControl, String, ref InputControlList<InputControl>, Int32)

Declaration

public static int TryFindControls(InputControl control, string path, ref InputControlList<InputControl> matches, int indexInPath = 0)

Parameters

Type	Name	Description
InputControl	control
System.String	path
InputControlList<InputControl>	matches
System.Int32	indexInPath

Returns

Type	Description
System.Int32

TryFindControls<TControl>(InputControl, String, Int32, ref InputControlList<TControl>)

Perform a search for controls starting with the given control as root and matching the given path from the given position. Puts all matching controls on the list and returns the number of controls that have been matched.

Declaration

public static int TryFindControls<TControl>(InputControl control, string path, int indexInPath, ref InputControlList<TControl> matches)
    where TControl : InputControl

Parameters

Type	Name	Description
InputControl	control	Control at which the given path is rooted.
System.String	path
System.Int32	indexInPath
InputControlList<TControl>	matches

Returns

Type	Description
System.Int32

Type Parameters

Name	Description
TControl

Remarks

Matching is case-insensitive.

Does not allocate managed memory.

Exceptions

Type	Condition
System.ArgumentNullException

TryGetControlLayout(String)

Declaration

public static string TryGetControlLayout(string path)

Parameters

Type	Name	Description
System.String	path

Returns

Type	Description
System.String

TryGetDeviceLayout(String)

From the given control path, try to determine the device layout being used.

Declaration

public static string TryGetDeviceLayout(string path)

Parameters

Type	Name	Description
System.String	path	A control path (like "/<gamepad>/leftStick")

Returns

Type	Description
System.String	The name of the device layout used by the given control path or null if the path does not specify a device layout or does so in a way that is not supported by the function.

Remarks

This function will only use information available in the path itself or in layouts referenced by the path. It will not look at actual devices in the system. This is to make the behavior predictable and not dependent on whether you currently have the right device connected or not.

Examples

InputControlPath.TryGetDeviceLayout("/<gamepad>/leftStick"); // Returns "gamepad".
InputControlPath.TryGetDeviceLayout("/*/leftStick"); // Returns "*".
InputControlPath.TryGetDeviceLayout("/gamepad/leftStick"); // Returns null. "gamepad" is a device name here.

Exceptions

Type	Condition
System.ArgumentNullException	path is null

TryGetDeviceUsages(String)

Declaration

public static string[] TryGetDeviceUsages(string path)

Parameters

Type	Name	Description
System.String	path

Returns

Type	Description
System.String[]

See Also

path

FindControls(String)