docs.unity.cn
    Show / Hide Table of Contents

    Class InputControlPath

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

    Inheritance
    Object
    InputControlPath
    Namespace: UnityEngine.InputSystem
    Syntax
    public static class InputControlPath : object
    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 = null
    Field Value
    Type Description
    String

    Separator

    Declaration
    public const char Separator = null
    Field Value
    Type Description
    Char

    Wildcard

    Declaration
    public const string Wildcard = null
    Field Value
    Type Description
    String

    Methods

    Combine(InputControl, String)

    Declaration
    public static string Combine(InputControl parent, string path)
    Parameters
    Type Name Description
    InputControl parent
    String path
    Returns
    Type Description
    String

    Matches(String, InputControl)

    Declaration
    public static bool Matches(string expected, InputControl control)
    Parameters
    Type Name Description
    String expected
    InputControl control
    Returns
    Type Description
    Boolean

    MatchesPrefix(String, InputControl)

    Check whether the given path matches control or any of its parents.

    Declaration
    public static bool MatchesPrefix(string expected, InputControl control)
    Parameters
    Type Name Description
    String expected

    A control path.

    InputControl control

    An input control.

    Returns
    Type Description
    Boolean

    True if the given path matches at least a partial path to control.

    Remarks
    // True as the path matches the Keyboard device itself, i.e. the parent of
    // Keyboard.aKey.
    InputControlPath.MatchesPrefix("<Keyboard>", Keyboard.current.aKey);
    
    // False as the path matches none of the controls leading to Keyboard.aKey.
    InputControlPath.MatchesPrefix("<Gamepad>", Keyboard.current.aKey);
    
    // True as the path matches Keyboard.aKey itself.
    InputControlPath.MatchesPrefix("<Keyboard>/a", Keyboard.current.aKey);

    Parse(String)

    Splits a control path into its separate components.

    Declaration
    public static IEnumerable<InputControlPath.ParsedPathComponent> Parse(string path)
    Parameters
    Type Name Description
    String path

    A control path such as "<Gamepad>/buttonSouth".

    Returns
    Type Description
    IEnumerable<InputControlPath.ParsedPathComponent>

    An enumeration of the parsed components. The enumeration is empty if the given path is empty.

    Remarks

    You can use this method, for example, to separate out the components in a binding's path.

    var parsed = InputControlPath.Parse("<XRController>{LeftHand}/trigger").ToArray();
    
    Debug.Log(parsed.Length); // Prints 2.
    Debug.Log(parsed[0].layout); // Prints "XRController".
    Debug.Log(parsed[0].name); // Prints an empty string.
    Debug.Log(parsed[0].usages.First()); // Prints "LeftHand".
    Debug.Log(parsed[1].layout); // Prints null.
    Debug.Log(parsed[1].name); // Prints "trigger".
    
    // Find out if the given device layout is based on "TrackedDevice".
    Debug.Log(InputSystem.IsFirstLayoutBasedOnSecond(parsed[0].layout, "TrackedDevice")); // Prints true.
    
    // Load the device layout referenced by the path.
    var layout = InputSystem.LoadLayout(parsed[0].layout);
    Debug.Log(layout.baseLayouts.First()); // Prints "TrackedDevice".
    See Also
    path
    FindControl(String)

    ToHumanReadableString(String, out String, out String, InputControlPath.HumanReadableStringOptions, InputControl)

    Create a human readable string from the given control path.

    Declaration
    public static string ToHumanReadableString(string path, out string deviceLayoutName, out string controlPath, InputControlPath.HumanReadableStringOptions options = default(InputControlPath.HumanReadableStringOptions), InputControl control = null)
    Parameters
    Type Name Description
    String path

    A control path such as "<XRController>{LeftHand}/position".

    String deviceLayoutName

    Receives the name of the device layout that the control path was resolved to. This is useful

    String controlPath

    Receives the path to the referenced control on the device or null if not applicable. For example, with a path of "<Gamepad>/dpad/up", the resulting control path will be "dpad/up". This is useful when trying to look up additional resources (such as images) based on the control that is being referenced.

    InputControlPath.HumanReadableStringOptions options

    Customize the resulting string.

    InputControl control

    An optional control. If supplied and the control or one of its children matches the given path, display names will be based on the matching control rather than on static information available from InputControlLayouts.

    Returns
    Type Description
    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
    ToDisplayString(InputBinding.DisplayStringOptions, InputControl)
    GetBindingDisplayString(InputAction, Int32, InputBinding.DisplayStringOptions)

    ToHumanReadableString(String, InputControlPath.HumanReadableStringOptions, InputControl)

    Create a human readable string from the given control path.

    Declaration
    public static string ToHumanReadableString(string path, InputControlPath.HumanReadableStringOptions options = default(InputControlPath.HumanReadableStringOptions), InputControl control = null)
    Parameters
    Type Name Description
    String path

    A control path such as "<XRController>{LeftHand}/position".

    InputControlPath.HumanReadableStringOptions options

    Customize the resulting string.

    InputControl control

    An optional control. If supplied and the control or one of its children matches the given path, display names will be based on the matching control rather than on static information available from InputControlLayouts.

    Returns
    Type Description
    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
    ToDisplayString(InputBinding.DisplayStringOptions, InputControl)
    GetBindingDisplayString(InputAction, Int32, InputBinding.DisplayStringOptions)

    TryFindChild(InputControl, String, Int32)

    Declaration
    public static InputControl TryFindChild(InputControl control, string path, int indexInPath = 0)
    Parameters
    Type Name Description
    InputControl control
    String path
    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
    String path
    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
    String path
    Int32 indexInPath
    Returns
    Type Description
    InputControl

    TryFindControl<TControl>(InputControl, String, Int32)

    Return the first child 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

    Control root at which to start the search.

    String path

    Path of the control to find. Can be null or empty, in which case null is returned.

    Int32 indexInPath

    Index in path at which to start parsing. Defaults to 0, i.e. parsing starts at the first character in the path.

    Returns
    Type Description
    TControl

    The first (direct or indirect) child control of control that matches path.

    Type Parameters
    Name Description
    TControl
    Remarks

    Does not allocate.

    Note that if multiple child controls match the given path, which one is returned depends on the ordering of controls. The result should be considered indeterministic in this case.

    // Find X control of left stick on current gamepad.
    InputControlPath.TryFindControl(Gamepad.current, "leftStick/x");
    
    // Find control with PrimaryAction usage on current mouse.
    InputControlPath.TryFindControl(Mouse.current, "{PrimaryAction}");
    See Also
    Item[String]

    TryFindControls(InputControl, String, Int32)

    Declaration
    public static InputControl[] TryFindControls(InputControl control, string path, int indexInPath = 0)
    Parameters
    Type Name Description
    InputControl control
    String path
    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
    String path
    InputControlList<InputControl> matches
    Int32 indexInPath
    Returns
    Type Description
    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.

    String path
    Int32 indexInPath
    InputControlList<TControl> matches
    Returns
    Type Description
    Int32
    Type Parameters
    Name Description
    TControl
    Remarks

    Matching is case-insensitive.

    Does not allocate managed memory.

    TryGetControlLayout(String)

    Declaration
    public static string TryGetControlLayout(string path)
    Parameters
    Type Name Description
    String path
    Returns
    Type Description
    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
    String path

    A control path (like "/<gamepad>/leftStick")

    Returns
    Type Description
    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.

    TryGetDeviceUsages(String)

    Declaration
    public static string[] TryGetDeviceUsages(string path)
    Parameters
    Type Name Description
    String path
    Returns
    Type Description
    String[]

    See Also

    path
    FindControls(String)
    Back to top Copyright © 2022 Unity Technologies
    Generated by DocFX
    on Wednesday, January 5, 2022
    Terms of use