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 int Count { get; }

Property Value

Type	Description
Int32	Number of controls currently in the list.

IsReadOnly

This is always false.

Declaration

public 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