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
// 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 |
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
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 |
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 |
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 |
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
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 |