×
A new build of Corona SDK is now available to subscribers. Not a subscriber? Subscribe now.
CoronaSDK 2014.2279 | Released: 23 Apr 2014, 3:40pm | What's New | Download Now

group:insert( )

Description:

Inserts an object into a group.

Syntax:

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

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 )          

Parameters:

index
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
object: An object to insert into the group.

resetTransform
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.

Returns:

Nothing.

Remarks:

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

Supported on operating systems and platforms for build numbers shown:
  • Mac OS X:
    Corona SDK 1.0
  • Windows:
    Corona SDK 2.0
  • iOS:
    Corona SDK 1.0
  • Android:
    Corona SDK 2.0

Replies

kimber
User offline. Last seen 2 years 21 weeks ago. Offline
Joined: 25 Feb 2011

Just a quick question, I can 't seem to find the answer in the documentation, but what does it mean when you set a variable = #nameofaGroup
does it set the variable to a number or the number of items in the group?
Sorry it may be a simple question but I can't seem to find the answer?

Tom
User offline. Last seen 4 hours 58 min ago. Offline
Staff
Joined: 13 Jul 2010

"#" is a Lua operator that returns the highest index value in a table. Since Groups are a form of a Lua indexed table, it returns the number of elements in the group.

kimber
User offline. Last seen 2 years 21 weeks ago. Offline
Joined: 25 Feb 2011

Thanks Tom, I thought it would be something relatively simple. I appreciate you quick response...

Kimber

personalnadir
User offline. Last seen 19 weeks 2 days ago. Offline
Joined: 24 Nov 2010

Is there any way to find out an object's current position in the parent's display group?

I often want to change the background on objects, and really just need to find out the appropriate index, so I can insert them just in front or behind.

Display groups always seem like such a heavy handed approach to solving this problem

Tom
User offline. Last seen 4 hours 58 min ago. Offline
Staff
Joined: 13 Jul 2010

If you know the object's handle, you can search the group (it's a table). You can also add a name property (or any other custom property) to each object and iterate through the group's children (objects) and find the object you're looking for.

The other way is to keep a table of objects you're interested in controlling along with their parent (group) and index position. In this case you would need to remove the object from the table when you remove the object from the group.

If you have more questions, please post them in the forums.

personalnadir
User offline. Last seen 19 weeks 2 days ago. Offline
Joined: 24 Nov 2010

Thanks!

In the end I came across the the toFront() calls which made ordering the group a little less verbose. Would still be happy to be able to have a function for inserting objects just in front of or behind other other objects as that would make the code clearer.

mightE
User offline. Last seen 1 year 15 weeks ago. Offline
Joined: 27 Jul 2011

How can I move a group as one?

Tom
User offline. Last seen 4 hours 58 min ago. Offline
Staff
Joined: 13 Jul 2010

You move a group like you do any other display object, set group.x and group.y or group:translate( deltaX, deltaY ).

perseusspartacus
User offline. Last seen 33 weeks 1 day ago. Offline
Joined: 9 Aug 2011

I try inserting a single object (a cannon to be precise) into a group. However, the cannon disappears entirely. I try setting its x and y coordinates, even going so far as to make it a rectangle rather than an image, but none of that works. Everything else works, but the cannon just disappears. Why is that? Here's the relevant code:

1
2
3
4
5
6
7
8
9
10
11
12
local cannonGroup = display.newGroup()
 
local cannon = display.newImage( "cannon.png" )
cannon.x = 240
cannon.y = 250
cannon.rotation = -90
 
-- The rotation is -90 because the image is positioned poorly for the
-- format of angles used by Corona (the cannon is pointing right in the
-- image when it should be pointing up for optimal performance)
 
cannonGroup:insert(cannon)

perseusspartacus
User offline. Last seen 33 weeks 1 day ago. Offline
Joined: 9 Aug 2011

Ignore this. It was just that I created a background after creating the group, so anything in the group would be placed behind the background. It's fixed now.

john11
User offline. Last seen 1 year 32 weeks ago. Offline
Joined: 13 Sep 2011

Can groups be inserted into groups?

Apologies if this has been asked before and I wasn't patient enough to dig through to the answer.

,John

LuckiiClover Labs
User offline. Last seen 34 weeks 2 days ago. Offline
Joined: 22 Jun 2010

How can I move an object that is not in a group behind all objects that are in a certain group? So I have an image that is being created after that of objects in this mainGroup.

Thanks,

rarmstrong
User offline. Last seen 2 days 9 hours ago. Offline
Joined: 23 Mar 2011

John,

Yes. Groups can be inserted into other groups.

Hopefully you've already found the answer on your own now but in case others were wondering...

paul.weidner
User offline. Last seen 1 year 41 weeks ago. Offline
Joined: 31 Jan 2012

can you insert multiple things into a group at once? just to save time.

For example, is there something like:

group1 = display.newGroup()

group1:insert(obj1, obj2, obj3)

I tried this and it didnt work, is there something else that accomplishes the same thing without multiple lines of code?

tarunLuthra
User offline. Last seen 7 weeks 2 days ago. Offline
Joined: 22 Feb 2012

I have added a number of display objects in a group. The number of children it contains is also going as is. But objects of the group are not getting displayed on the screen, though I have set the x and y coordinates of the group....
My group as:

thisgroup = display.newGroup()
thisGroup:insert("tile1.png",true)
thisGroup:insert("tile2.png",true)
thisGroup.x = 240
thisGroup.y = 400

please help.... its urgent..... Thanks

paul.weidner
User offline. Last seen 1 year 41 weeks ago. Offline
Joined: 31 Jan 2012

Make sure you insert your group into the main group if you have one. For example, if you're using director you probably have a localGroup by "default". Make sure you add thisGroup into the localGroup.

localGroup:insert(thisGroup)

then add objects to "thisGroup"

thisGroup:insert("tile1.png",true)
thisGroup:insert("tile2.png",true)

Also, while I'm not 100% sure, you may want to set the x and y of the group to 0,0. I'm fairly certain that groups normally are made at 0,0 and that the objects inside of a group are relevant to the GROUP not the screen. I am not 100% about this, though. Hope that helps

tarunLuthra
User offline. Last seen 7 weeks 2 days ago. Offline
Joined: 22 Feb 2012

Thanks paul.weidner for your support. I think this will solve the purpose. I am going to apply it and ring you again if problem persists....
Thanks again

tarunLuthra
User offline. Last seen 7 weeks 2 days ago. Offline
Joined: 22 Feb 2012

Hi paul.weidner,
I tried the way you told me. But it is not working, the problem still remains there. The contents of the group are not displaying. I have set the x and y coordinates of objects even and that of thisGroup as well. But the problem remains the same in both the cases.

tarunLuthra
User offline. Last seen 7 weeks 2 days ago. Offline
Joined: 22 Feb 2012

Can we save a group or table as a value of the user defined property. Such as:

Is it possible:
thisgroup = display.newGroup()
thisGroup:insert("tile1.png",true)
thisGroup:insert("tile2.png",true)
thisGroup.x = 240
thisGroup.y = 400

ground.contents = thisGroup

deadmorozz
User offline. Last seen 15 weeks 3 days ago. Offline
Joined: 2 Feb 2012

I added the code sample - how to get the objects inside the groups easily.
Hope, it will help.

tarunLuthra
User offline. Last seen 7 weeks 2 days ago. Offline
Joined: 22 Feb 2012

Thanks deadmorozz for your support.
i tried this even, but unfortunately, this is not working...
Please help with new solution

tarunLuthra
User offline. Last seen 7 weeks 2 days ago. Offline
Joined: 22 Feb 2012

Yeah!! The table can't be stored in the user defined property but the display object is being stored.

Tom
User offline. Last seen 4 hours 58 min ago. Offline
Staff
Joined: 13 Jul 2010

Please post your questions on the forums and not on the documentation pages.

Thanks.

HypnotiComp
User offline. Last seen 1 year 44 weeks ago. Offline
Joined: 25 May 2012

Storing a custom Object.
I am making an app which allows the user to make a custom group, like dragging text boxes around putting text where they want to, changing background colours. What is the best way to store the final group. I was thinking of creating a new group then just inserting each object they want into the group as you normally would, then store the whole group in my database. Does anyone know a better way to store a group. Or if it is even possible.

Tom
User offline. Last seen 4 hours 58 min ago. Offline
Staff
Joined: 13 Jul 2010

Please post your questions on the forums and not on the documentation pages.

Comments will soon be turned off and deleted on all document pages so posting in the forums is your best bet to get an answer to your question.

Thanks.

shk13408
User offline. Last seen 1 year 44 weeks ago. Offline
Joined: 23 May 2012

Hi! It seems to me that parameter index does not work.
I try:

1
2
3
4
5
6
g = display.newGroup()
c = display.newRect(100, 100, 200, 200)
 
g:insert( 20, c )
 
print( g[20] ) --return nil
Can you explain me what the problem?

tarunLuthra
User offline. Last seen 7 weeks 2 days ago. Offline
Joined: 22 Feb 2012

Hi,
I think you are new to Programming world.
Please read the sample codes carefully to get the answer.

Here,
As, you are writing print( g[20] )..... This means that you going to call the value at 20th position in group g. whereas there are only 2 values in the same group. So how could the computer answer the value at 20th position?

You can write the following ways:
print( g[1] ) to get answer as 20
and
print( g[2] ) to get answer as c

But now if you try to figure out the value for any position beyond 2, it will surely give you the same error. Because you don't have filled positions more than number 2.

So please read the sample codes first, before going for any development.