Corona Reference: Display Objects

A group is a display object itself, but one that can contain other display objects (including other groups). A new, empty group can be created using the newGroup function; below, we'll create an empty group called cloudGroup:

local circleGroup = display.newGroup()

Display objects can be added to a group as they are defined, or by using the insert() method. Below, we'll create some randomly sized and placed circles to mimic a cloud, and add each to the group as we do. We'll also create a single rectangle and add that to the group within its definition:

local circleGroup = display.newGroup()

for i = 1,20 do
    local c = display.newCircle( math.random(100,500), math.random(100,500), math.random(10,90))
    c:setFillColor(math.random(8,10)/10)
    circleGroup:insert( c )
end

local r = display.newRect( circleGroup, 200, 800, 50, 50 )

Now, we can make changes to all objects in the group at once, such as moving the entire group or setting the alpha value of all objects in the group:

circleGroup.y = 600
circleGroup.alpha = 0.8

Just as with display objects, groups are layered according to the painter's model: the last group created will be "on top" of other groups, regardless of when the objects within the group are defined.

Note that changing the position of a group does NOT change the x and y position of the objects within the group. They will appear to move on screen, but the x and y properties of the objects will be the original values defined. If you need to get the actual current coordinates of an object within a group, use the localToContent() function, which returns two values:

local newX, newY = r:localToContent(0,0)	-- get current position relative to origin

Groups have infinite size (as opposed to containers, described below). This means that groups do not have anchor points. However, we can force groups to have anchor behavior by setting the group's anchorChildren property to true. If we then provide and x and y value for the group as well as an anchor point for the group, all objects within the group will be positioned accordingly:

circleGroup.anchorChildren = true
circleGroup.x = 300
circleGroup.y = 200
circleGroup.anchorX = 1
circleGroup.anchorY = 0