object:remove()

Type Function
Object GroupObject
Library display.*
Return value none
Revision 2017.3110
Keywords remove, remove child
See also object:removeSelf()
display.remove()
Group Programming (guide)

Overview

Remove an object from a group by either an index number or a reference to the object.

Gotchas

If an object is being removed (deleted), it is recommended to use object:removeSelf() or display.remove() instead.

Using this method will delete the specified child object, not simply remove it from the group. If you want to remove an object from a group, insert it into a different group, or insert it into the global stage group instead.

When an object is removed, the rendering-related resources of the removed object are deleted immediately. What remains of object is simply a plain Lua table with all non-display object properties (the metatable is set to nil and all properties relating to display object are removed). Thus, if there are still references to object in Lua, they will simply be references to a normal Lua table.

Syntax

object:remove( indexOrChild )
indexOrChild (required)

Number or DisplayObject. Removes the display object specified from the group, shifting down other elements as needed. The argument is either the index position of the child within group (number) or the child display object itself.

Example

display.getCurrentStage():remove( 2 )  -- Removes the second object from the group