Class: List

Phaser.Structs. List

List is a generic implementation of an ordered list which contains utility methods for retrieving, manipulating, and iterating items.


new List(parent)

Parameters:
Name Type Description
parent *

The parent of this list.

Since: 3.0.0
Source: src/structs/List.js (Line 20)

Members


_sortKey :string

The property key to sort by.

Type:
  • string
Since: 3.4.0
Source: src/structs/List.js (Line 90)

addCallback :function

A callback that is invoked every time a child is added to this list.

Type:
  • function
Since: 3.4.0
Source: src/structs/List.js (Line 72)

<readonly> first :integer

The first item in the List or null for an empty List.

Type:
  • integer
Since: 3.0.0
Source: src/structs/List.js (Line 709)

<readonly> last :integer

The last item in the List, or null for an empty List.

Type:
  • integer
Since: 3.0.0
Source: src/structs/List.js (Line 735)

<readonly> length :integer

The number of items inside the List.

Type:
  • integer
Since: 3.0.0
Source: src/structs/List.js (Line 692)

list :Array.<*>

The objects that belong to this collection.

Type:
  • Array.<*>
Since: 3.0.0
Default Value:
  • []
Source: src/structs/List.js (Line 48)

<readonly> next :integer

The next item in the List, or null if the entire List has been traversed.

This property can be read successively after reading #first or manually setting the #position to iterate the List.

Type:
  • integer
Since: 3.0.0
Source: src/structs/List.js (Line 761)

parent :*

The parent of this list.

Type:
  • *
Since: 3.0.0
Source: src/structs/List.js (Line 39)

position :integer

The index of the current element.

This is used internally when iterating through the list with the #first, #last, #get, and #previous properties.

Type:
  • integer
Since: 3.0.0
Default Value:
  • 0
Source: src/structs/List.js (Line 60)

<readonly> previous :integer

The previous item in the List, or null if the entire List has been traversed.

This property can be read successively after reading #last or manually setting the #position to iterate the List backwards.

Type:
  • integer
Since: 3.0.0
Source: src/structs/List.js (Line 789)

removeCallback :function

A callback that is invoked every time a child is removed from this list.

Type:
  • function
Since: 3.4.0
Source: src/structs/List.js (Line 81)

Methods


add(child [, skipCallback])

Adds the given item to the end of the list. Each item must be unique.

Parameters:
Name Type Argument Default Description
child * | Array.<*>

The item, or array of items, to add to the list.

skipCallback boolean <optional>
false

Skip calling the List.addCallback if this child is added successfully.

Since: 3.0.0
Source: src/structs/List.js (Line 100)
Returns:

The list's underlying array.

Type
*

addAt(child [, index] [, skipCallback])

Adds an item to list, starting at a specified index. Each item must be unique within the list.

Parameters:
Name Type Argument Default Description
child *

The item, or array of items, to add to the list.

index integer <optional>
0

The index in the list at which the element(s) will be inserted.

skipCallback boolean <optional>
false

Skip calling the List.addCallback if this child is added successfully.

Since: 3.0.0
Source: src/structs/List.js (Line 125)
Returns:

The List's underlying array.

Type
*

bringToTop(child)

Brings the given child to the top of this List.

Parameters:
Name Type Description
child *

The item to bring to the top of the List.

Since: 3.0.0
Source: src/structs/List.js (Line 474)
Returns:

The item which was moved.

Type
*

count(property, value)

Returns the total number of items in the List which have a property matching the given value.

Parameters:
Name Type Description
property string

The property to test on each item.

value *

The value to test the property against.

Since: 3.0.0
Source: src/structs/List.js (Line 322)
Returns:

The total number of matching elements.

Type
integer

destroy()

Destroys this List.

Since: 3.0.0
Source: src/structs/List.js (Line 677)

each(callback [, context] [, args])

Passes all children to the given callback.

Parameters:
Name Type Argument Description
callback EachListCallback

The function to call.

context * <optional>

Value to use as this when executing callback.

args * <optional>
<repeatable>

Additional arguments that will be passed to the callback, after the child.

Since: 3.0.0
Source: src/structs/List.js (Line 635)

exists(child)

Checks if an item exists within the List.

Parameters:
Name Type Description
child *

The item to check for the existence of.

Since: 3.0.0
Source: src/structs/List.js (Line 598)
Returns:

true if the item is found in the list, otherwise false.

Type
boolean

getAll( [property] [, value] [, startIndex] [, endIndex])

Returns all children in this List.

You can optionally specify a matching criteria using the property and value arguments.

For example: getAll('parent') would return only children that have a property called parent.

You can also specify a value to compare the property to:

getAll('visible', true) would return only children that have their visible property set to true.

Optionally you can specify a start and end index. For example if this List had 100 children,
and you set startIndex to 0 and endIndex to 50, it would return matches from only
the first 50 children in the List.

Parameters:
Name Type Argument Description
property string <optional>

An optional property to test against the value argument.

value * <optional>

If property is set then Child.property must strictly equal this value to be included in the results.

startIndex integer <optional>

The first child index to start the search from.

endIndex integer <optional>

The last child index to search up until.

Since: 3.0.0
Source: src/structs/List.js (Line 289)
Returns:

All items of the List which match the given criterion, if any.

Type
Array.<*>

getAt(index)

Retrieves the item at a given position inside the List.

Parameters:
Name Type Description
index integer

The index of the item.

Since: 3.0.0
Source: src/structs/List.js (Line 151)
Returns:

The retrieved item, or undefined if it's outside the List's bounds.

Type
*

getByName(name)

Searches for the first instance of a child with its name
property matching the given argument. Should more than one child have
the same name only the first is returned.

Parameters:
Name Type Description
name string

The name to search for.

Since: 3.0.0
Source: src/structs/List.js (Line 231)
Returns:

The first child with a matching name, or null if none were found.

Type
*

getFirst(property, value [, startIndex] [, endIndex])

Returns the first element in a given part of the List which matches a specific criterion.

Parameters:
Name Type Argument Default Description
property string

The name of the property to test or a falsey value to have no criterion.

value *

The value to test the property against, or undefined to allow any value and only check for existence.

startIndex number <optional>
0

The position in the List to start the search at.

endIndex number <optional>

The position in the List to optionally stop the search at. It won't be checked.

Since: 3.0.0
Source: src/structs/List.js (Line 268)
Returns:

The first item which matches the given criterion, or null if no such item exists.

Type
*

getIndex(child)

Locates an item within the List and returns its index.

Parameters:
Name Type Description
child *

The item to locate.

Since: 3.0.0
Source: src/structs/List.js (Line 168)
Returns:

The index of the item within the List, or -1 if it's not in the List.

Type
integer

getRandom( [startIndex] [, length])

Returns a random child from the group.

Parameters:
Name Type Argument Default Description
startIndex integer <optional>
0

Offset from the front of the group (lowest child).

length integer <optional>
(to top)

Restriction on the number of values you want to randomly select from.

Since: 3.0.0
Source: src/structs/List.js (Line 250)
Returns:

A random child of this Group.

Type
*

moveDown(child)

Moves the given child down one place in this group unless it's already at the bottom.

Parameters:
Name Type Description
child *

The item to move down.

Since: 3.0.0
Source: src/structs/List.js (Line 527)
Returns:

The item which was moved.

Type
*

moveTo(child, index)

Moves an item in the List to a new position.

Parameters:
Name Type Description
child *

The item to move.

index integer

Moves an item in the List to a new position.

Since: 3.0.0
Source: src/structs/List.js (Line 356)
Returns:

The item that was moved.

Type
*

moveUp(child)

Moves the given child up one place in this group unless it's already at the top.

Parameters:
Name Type Description
child *

The item to move up.

Since: 3.0.0
Source: src/structs/List.js (Line 508)
Returns:

The item which was moved.

Type
*

remove(child [, skipCallback])

Removes one or many items from the List.

Parameters:
Name Type Argument Default Description
child *

The item, or array of items, to remove.

skipCallback boolean <optional>
false

Skip calling the List.removeCallback.

Since: 3.0.0
Source: src/structs/List.js (Line 374)
Returns:

The item, or array of items, which were successfully removed from the List.

Type
*

removeAll( [skipCallback])

Removes all the items.

Parameters:
Name Type Argument Default Description
skipCallback boolean <optional>
false

Skip calling the List.removeCallback.

Since: 3.0.0
Source: src/structs/List.js (Line 450)
Returns:

This List object.

Type
Phaser.Structs.List

removeAt(index [, skipCallback])

Removes the item at the given position in the List.

Parameters:
Name Type Argument Default Description
index integer

The position to remove the item from.

skipCallback boolean <optional>
false

Skip calling the List.removeCallback.

Since: 3.0.0
Source: src/structs/List.js (Line 399)
Returns:

The item that was removed.

Type
*

removeBetween( [startIndex] [, endIndex] [, skipCallback])

Removes the items within the given range in the List.

Parameters:
Name Type Argument Default Description
startIndex integer <optional>
0

The index to start removing from.

endIndex integer <optional>

The position to stop removing at. The item at this position won't be removed.

skipCallback boolean <optional>
false

Skip calling the List.removeCallback.

Since: 3.0.0
Source: src/structs/List.js (Line 424)
Returns:

An array of the items which were removed.[description]

Type
Array.<*>

replace(oldChild, newChild)

Replaces a child of this List with the given newChild. The newChild cannot be a member of this List.

Parameters:
Name Type Description
oldChild *

The child in this List that will be replaced.

newChild *

The child to be inserted into this List.

Since: 3.0.0
Source: src/structs/List.js (Line 580)
Returns:

Returns the oldChild that was replaced within this group.

Type
*

reverse()

Reverses the order of all children in this List.

Since: 3.0.0
Source: src/structs/List.js (Line 546)
Returns:

This List object.

Type
Phaser.Structs.List

sendToBack(child)

Sends the given child to the bottom of this List.

Parameters:
Name Type Description
child *

The item to send to the back of the list.

Since: 3.0.0
Source: src/structs/List.js (Line 491)
Returns:

The item which was moved.

Type
*

setAll(property, value [, startIndex] [, endIndex])

Sets the property key to the given value on all members of this List.

Parameters:
Name Type Argument Description
property string

The name of the property to set.

value *

The value to set the property to.

startIndex integer <optional>

The first child index to start the search from.

endIndex integer <optional>

The last child index to search up until.

Since: 3.0.0
Source: src/structs/List.js (Line 615)

shuffle()

Shuffles the items in the list.

Since: 3.0.0
Source: src/structs/List.js (Line 563)
Returns:

This List object.

Type
Phaser.Structs.List

shutdown()

Clears the List and recreates its internal array.

Since: 3.0.0
Source: src/structs/List.js (Line 664)

sort(property)

Sort the contents of this List so the items are in order based
on the given property. For example, sort('alpha') would sort the List
contents based on the value of their alpha property.

Parameters:
Name Type Description
property string

The property to lexically sort by.

Since: 3.0.0
Source: src/structs/List.js (Line 186)
Returns:

This List object.

Type
Phaser.Structs.List

swap(child1, child2)

Swaps the positions of two items in the list.

Parameters:
Name Type Description
child1 *

The first item to swap.

child2 *

The second item to swap.

Since: 3.0.0
Source: src/structs/List.js (Line 340)