Struct InputControlList<TControl>

Keep a list of InputControl without allocating managed memory.

Namespace: UnityEngine.InputSystem

Syntax

public struct InputControlList<TControl> : IList<TControl>, ICollection<TControl>, IReadOnlyList<TControl>, IReadOnlyCollection<TControl>, IEnumerable<TControl>, IEnumerable, 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 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 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.

Exceptions

Type	Condition
System.ArgumentNullException	values is null.

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.
System.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
System.Collections.Generic.IEnumerable<TControl>	values	Sequence of values to populate the list with.
Allocator	allocator	Allocator to use for requesting unmanaged memory.

Exceptions

Type	Condition
System.ArgumentNullException	values is null.

Properties

Capacity

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

Declaration

public int Capacity { get; set; }

Property Value

Type	Description
System.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 int Count { get; }

Property Value

Type	Description
System.Int32	Number of controls currently in the list.

IsReadOnly

This is always false.

Declaration

public bool IsReadOnly { get; }

Property Value

Type	Description
System.Boolean	Always false.

Item[Int32]

Return the control at the given index.

Declaration

public TControl this[int index] { get; set; }

Parameters

Type	Name	Description
System.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.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	index is less than 0 or greater than or equal to Count

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 = -1, int destinationIndex = -1)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<TControl>	list	Sequence of controls to add.
System.Int32	count	Number of controls from list to add. If negative (default), all controls from list will be added.
System.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.

Exceptions

Type	Condition
System.ArgumentNullException	list is null.

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 = -1, int destinationIndex = -1, int sourceIndex = 0)
    where TList : IReadOnlyList<TControl>

Parameters

Type	Name	Description
TList	list	List to take the slice of values from.
System.Int32	count	Number of elements to copy from list.
System.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.
System.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).

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The range of count and sourceIndex is at least partially outside the range of values available in list.

Clear()

Declaration

public void Clear()

Contains(TControl)

Declaration

public bool Contains(TControl item)

Parameters

Type	Name	Description
TControl	item

Returns

Type	Description
System.Boolean

CopyTo(TControl[], Int32)

Declaration

public void CopyTo(TControl[] array, int arrayIndex)

Parameters

Type	Name	Description
TControl[]	array
System.Int32	arrayIndex

Dispose()

Declaration

public void Dispose()

GetEnumerator()

Declaration

public IEnumerator<TControl> GetEnumerator()

Returns

Type	Description
System.Collections.Generic.IEnumerator<TControl>

IndexOf(TControl)

Declaration

public int IndexOf(TControl item)

Parameters

Type	Name	Description
TControl	item

Returns

Type	Description
System.Int32

Insert(Int32, TControl)

Declaration

public void Insert(int index, TControl item)

Parameters

Type	Name	Description
System.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
System.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
System.Int32	index	Index of control to remove.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	index is negative or equal or greater than Count.

Sort<TCompare>(Int32, Int32, TCompare)

Declaration

public void Sort<TCompare>(int startIndex, int count, TCompare comparer)
    where TCompare : IComparer<TControl>

Parameters

Type	Name	Description
System.Int32	startIndex
System.Int32	count
TCompare	comparer

Type Parameters

Name	Description
TCompare

SwapElements(Int32, Int32)

Declaration

public void SwapElements(int index1, int index2)

Parameters

Type	Name	Description
System.Int32	index1
System.Int32	index2

ToArray()

Declaration

public TControl[] ToArray()

Returns

Type	Description
TControl[]

ToString()

Declaration

public override string ToString()

Returns

Type	Description
System.String

Overrides

System.ValueType.ToString()