object:insert()

Type Function
Object GroupObject
Library display.*
Return value none
Revision Release 2024.3703
Keywords insert, group insert
See also Group Programming (guide)

Overview

Inserts an object into a group.

Gotchas

Inserting display objects into a group also removes the object from it current group (objects cannot be in multiple groups). All display objects are part of stage object when first created. At this time, Corona only has one stage, which is the entire screen area.

Syntax

group:insert( [index,] child, [, resetTransform] )
index (optional)

Number. Inserts child at index into group, shifting up other elements as necessary. The default value index is n+1 where n is the number of children in the group.

An easy way to move an object above all its siblings (top) is to re-insert it: object.parent:insert( object ).

If a group has 3 display objects:

  • group[1] is at the bottom of the group.
  • group[2] is in the middle of the group.
  • group[3] is at the top of the group.

Objects at the higher index numbers will be displayed on top of objects with lower index numbers (if the objects overlap).

child (required)

DisplayObject. Object to be inserted into the group.

resetTransform (optional)

Boolean. Determines what happens to child’s transform. When false, child’s local position, rotation, and scale properties are preserved, except the local origin is now relative to the new parent group, not its former parent; When true, child’s transform is reset (i.e. the x, y, rotation, xScale, and yScale properties of child are reset to 0, 0, 0, 1, and 1, respectively). The default value for resetTransform is false.

Example

local txt = display.newText( "Hello", 0, 0 )
local g1 = display.newGroup()
local g2 = display.newGroup()
              
-- Insert text object into g1
g1:insert( txt )               
-- Insert same text object into g2
g2:insert( txt )
 
print( "g1[1]: " .. tostring(g1[1]) )  -- prints nil
print( "g2[1]: " .. tostring(g2[1]) )  -- prints textObject
print( "number of children in g1 and g2: " .. g1.numChildren, g2.numChildren )