docs.unity3d.com
    Show / Hide Table of Contents

    Struct InputControlList<TControl>

    Keep a list of InputControls without allocating managed memory.

    Namespace: UnityEngine.InputSystem
    Syntax
    public struct InputControlList<TControl> : IList<TControl>, IReadOnlyList<TControl>, IDisposable where TControl : InputControl
    Type Parameters
    Name Description
    TControl

    Type of InputControl to store in the list.

    Remarks

    This struct is mainly used by methods such as FindControls(String) or TryFindControls<TControl>(InputControl, String, Int32, ref InputControlList<TControl>) to store an arbitrary length list of resulting matches without having to allocate GC heap memory.

    Requires the control setup in the system to not change while the list is being used. If devices are removed from the system, the list will no longer be valid. Also, only works with controls of devices that have been added to the system (added). The reason for these constraints is that internally, the list only stores integer indices that are translates to InputControl references on the fly. If the device setup in the system changes, the indices may become invalid.

    This struct allocates unmanaged memory and thus must be disposed or it will leak memory. By default allocates Allocator.Persistent memory. You can direct it to use another allocator by passing an value to one of the constructors.

    // Find all controls with the "Submit" usage in the system.
    // By wrapping it in a `using` block, the list of controls will automatically be disposed at the end.
    using (var controls = InputSystem.FindControls("*/{Submit}"))
        /* ... */;

    Constructors

    InputControlList(TControl[])

    Construct a list and add the given values to it.

    Declaration
    public InputControlList(params TControl[] values)
    Parameters
    Type Name Description
    TControl[] values

    Sequence of controls to add to the list.

    InputControlList(Allocator, Int32)

    Construct a list that allocates unmanaged memory from the given allocator.

    Declaration
    public InputControlList(Allocator allocator, int initialCapacity = 0)
    Parameters
    Type Name Description
    Allocator allocator

    Allocator to use for requesting unmanaged memory.

    Int32 initialCapacity

    If greater than zero, will immediately allocate memory and set Capacity accordingly.

    Examples
    // Create a control list that allocates from the temporary memory allocator.
    using (var list = new InputControlList(Allocator.Temp))
    {
        // Add all gamepads to the list.
        InputSystem.FindControls("<Gamepad>", ref list);
    }

    InputControlList(IEnumerable<TControl>, Allocator)

    Construct a list and populate it with the given values.

    Declaration
    public InputControlList(IEnumerable<TControl> values, Allocator allocator = null)
    Parameters
    Type Name Description
    IEnumerable<TControl> values

    Sequence of values to populate the list with.

    Allocator allocator

    Allocator to use for requesting unmanaged memory.

    Properties

    Capacity

    Total number of controls that can currently be stored in the list.

    Declaration
    public int Capacity { get; set; }
    Property Value
    Type Description
    Int32

    Total size of array as currently allocated.

    Remarks

    This can be set ahead of time to avoid repeated allocations.

    // Add all keys from the keyboard to a list.
    var keys = Keyboard.current.allKeys;
    var list = new InputControlList<KeyControl>(keys.Count);
    list.AddRange(keys);

    Count

    Current number of controls in the list.

    Declaration
    public readonly int Count { get; }
    Property Value
    Type Description
    Int32

    Number of controls currently in the list.

    IsReadOnly

    This is always false.

    Declaration
    public readonly bool IsReadOnly { get; }
    Property Value
    Type Description
    Boolean

    Always false.

    Item[Int32]

    Return the control at the given index.

    Declaration
    public TControl this[int index] { get; set; }
    Parameters
    Type Name Description
    Int32 index

    Index of control.

    Property Value
    Type Description
    TControl
    Remarks

    Internally, the list only stores indices. Resolution to InputControl happens dynamically by looking them up globally.

    Methods

    Add(TControl)

    Add a control to the list.

    Declaration
    public void Add(TControl item)
    Parameters
    Type Name Description
    TControl item

    Control to add. Allowed to be null.

    Remarks

    If necessary, Capacity will be increased.

    It is allowed to add nulls to the list. This can be useful, for example, when specific indices in the list correlate with specific matches and a given match needs to be marked as "matches nothing".

    See Also
    Remove(TControl)

    AddRange(IEnumerable<TControl>, Int32, Int32)

    Add a sequence of controls to the list.

    Declaration
    public void AddRange(IEnumerable<TControl> list, int count = null, int destinationIndex = null)
    Parameters
    Type Name Description
    IEnumerable<TControl> list

    Sequence of controls to add.

    Int32 count

    Number of controls from list to add. If negative (default), all controls from list will be added.

    Int32 destinationIndex

    Index in the control list to start inserting controls at. If negative (default), controls will be appended to the end of the control list.

    Remarks

    If count is not supplied, list will be iterated over twice.

    AddSlice<TList>(TList, Int32, Int32, Int32)

    Add a slice of elements taken from the given list.

    Declaration
    public void AddSlice<TList>(TList list, int count = null, int destinationIndex = null, int sourceIndex = 0)
        where TList : IReadOnlyList<TControl>
    Parameters
    Type Name Description
    TList list

    List to take the slice of values from.

    Int32 count

    Number of elements to copy from list.

    Int32 destinationIndex

    Starting index in the current control list to copy to. This can be beyond Count or even Capacity. Memory is allocated as needed.

    Int32 sourceIndex

    Source index in list to start copying from. count elements are copied starting at sourceIndex.

    Type Parameters
    Name Description
    TList

    Type of list. This is a type parameter to avoid boxing in case the given list is a struct (such as InputControlList itself).

    Clear()

    Declaration
    public void Clear()

    Contains(TControl)

    Declaration
    public bool Contains(TControl item)
    Parameters
    Type Name Description
    TControl item
    Returns
    Type Description
    Boolean

    Contains(TControl, Int32, Int32)

    Declaration
    public bool Contains(TControl item, int startIndex, int count = null)
    Parameters
    Type Name Description
    TControl item
    Int32 startIndex
    Int32 count
    Returns
    Type Description
    Boolean

    CopyTo(TControl[], Int32)

    Declaration
    public void CopyTo(TControl[] array, int arrayIndex)
    Parameters
    Type Name Description
    TControl[] array
    Int32 arrayIndex

    Dispose()

    Declaration
    public void Dispose()

    GetEnumerator()

    Declaration
    public IEnumerator<TControl> GetEnumerator()
    Returns
    Type Description
    IEnumerator<TControl>

    IndexOf(TControl)

    Declaration
    public int IndexOf(TControl item)
    Parameters
    Type Name Description
    TControl item
    Returns
    Type Description
    Int32

    IndexOf(TControl, Int32, Int32)

    Declaration
    public int IndexOf(TControl item, int startIndex, int count = null)
    Parameters
    Type Name Description
    TControl item
    Int32 startIndex
    Int32 count
    Returns
    Type Description
    Int32

    Insert(Int32, TControl)

    Declaration
    public void Insert(int index, TControl item)
    Parameters
    Type Name Description
    Int32 index
    TControl item

    Remove(TControl)

    Remove a control from the list.

    Declaration
    public bool Remove(TControl item)
    Parameters
    Type Name Description
    TControl item

    Control to remove. Can be null.

    Returns
    Type Description
    Boolean

    True if the control was found in the list and removed, false otherwise.

    See Also
    Add(TControl)

    RemoveAt(Int32)

    Remove the control at the given index.

    Declaration
    public void RemoveAt(int index)
    Parameters
    Type Name Description
    Int32 index

    Index of control to remove.

    Sort<TCompare>(Int32, Int32, TCompare)

    Declaration
    public void Sort<TCompare>(int startIndex, int count, TCompare comparer)
        where TCompare : IComparer<TControl>
    Parameters
    Type Name Description
    Int32 startIndex
    Int32 count
    TCompare comparer
    Type Parameters
    Name Description
    TCompare

    SwapElements(Int32, Int32)

    Declaration
    public void SwapElements(int index1, int index2)
    Parameters
    Type Name Description
    Int32 index1
    Int32 index2

    ToArray(Boolean)

    Convert the contents of the list to an array.

    Declaration
    public TControl[] ToArray(bool dispose = false)
    Parameters
    Type Name Description
    Boolean dispose

    If true, the control list will be disposed of as part of the operation, i.e. Dispose() will be called as a side-effect.

    Returns
    Type Description
    TControl[]

    An array mirroring the contents of the list. Not null.

    ToString()

    Declaration
    public override string ToString()
    Returns
    Type Description
    String
    Back to top
    Terms of use
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023