Struct InputControlList<TControl>

Keep a list of InputControls without allocating managed memory.

Implements

IList<TControl>

ICollection<TControl>

IReadOnlyList<TControl>

IReadOnlyCollection<TControl>

IEnumerable<TControl>

IEnumerable

IDisposable

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

Namespace: UnityEngine.InputSystem

Assembly: Unity.InputSystem.dll

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, int, 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 Allocator 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(IEnumerable<TControl>, Allocator)

Construct a list and populate it with the given values.

Declaration

public InputControlList(IEnumerable<TControl> values, Allocator allocator = Allocator.Persistent)

Parameters

Type	Name	Description
IEnumerable<TControl>	values	Sequence of values to populate the list with.
Allocator	allocator	Allocator to use for requesting unmanaged memory.

Exceptions

Type	Condition
ArgumentNullException	values is null.

InputControlList(Allocator, int)

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.
int	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(params 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
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
int	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
int	Number of controls currently in the list.

IsReadOnly

This is always false.

Declaration

public bool IsReadOnly { get; }

Property Value

Type	Description
bool	Always false.

this[int]

Return the control at the given index.

Declaration

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

Parameters

Type	Name	Description
int	index	Index of control.

Property Value

Type	Description
TControl

Remarks

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

Exceptions

Type	Condition
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>, int, int)

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
IEnumerable<TControl>	list	Sequence of controls to add.
int	count	Number of controls from list to add. If negative (default), all controls from list will be added.
int	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
ArgumentNullException	list is null.

AddSlice<TList>(TList, int, int, int)

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.
int	count	Number of elements to copy from list.
int	destinationIndex	Starting index in the current control list to copy to. This can be beyond Count or even Capacity. Memory is allocated as needed.
int	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
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
bool

Contains(TControl, int, int)

Declaration

public bool Contains(TControl item, int startIndex, int count = -1)

Parameters

Type	Name	Description
TControl	item
int	startIndex
int	count

Returns

Type	Description
bool

CopyTo(TControl[], int)

Declaration

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

Parameters

Type	Name	Description
TControl[]	array
int	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
int

IndexOf(TControl, int, int)

Declaration

public int IndexOf(TControl item, int startIndex, int count = -1)

Parameters

Type	Name	Description
TControl	item
int	startIndex
int	count

Returns

Type	Description
int

Insert(int, TControl)

Declaration

public void Insert(int index, TControl item)

Parameters

Type	Name	Description
int	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
bool	True if the control was found in the list and removed, false otherwise.

See Also

Add(TControl)

RemoveAt(int)

Remove the control at the given index.

Declaration

public void RemoveAt(int index)

Parameters

Type	Name	Description
int	index	Index of control to remove.

Exceptions

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

Resize(int)

Resizes the list to be exactly size entries. If this is less than the current Count, additional entries are dropped. If it is more than the current Count, additional null entries are appended to the list.

Declaration

public void Resize(int size)

Parameters

Type	Name	Description
int	size	The new value for Count.

Remarks

Capacity is increased if necessary. It will, however, not be decreased if it is larger than size entries.

Exceptions

Type	Condition
ArgumentOutOfRangeException	size is negative.

Sort<TCompare>(int, int, TCompare)

Declaration

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

Parameters

Type	Name	Description
int	startIndex
int	count
TCompare	comparer

Type Parameters

Name	Description
TCompare

SwapElements(int, int)

Declaration

public void SwapElements(int index1, int index2)

Parameters

Type	Name	Description
int	index1
int	index2

ToArray(bool)

Convert the contents of the list to an array.

Declaration

public TControl[] ToArray(bool dispose = false)

Parameters

Type	Name	Description
bool	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

Overrides

ValueType.ToString()

Implements

IList<T>

ICollection<T>

IReadOnlyList<T>

IReadOnlyCollection<T>

IEnumerable<T>

IEnumerable

IDisposable