In Corona‘s graphics model, groups have been the workhorse way of organizing objects hierarchically. When you modify a group’s properties, the children are affected. For example, if you set the alpha on a group, then each child’s alpha is effectively multiplied by that alpha of the parent group.
The new graphics engine is going to have a new kind of group called a Container.
Before I dive into that, let’s digress and talk about a common task in creating interfaces: limiting the rendering of a group to a rectangular region. To do this in the old graphics engine (well, old to me) is a bit of a task because groups don’t provide this functionality out of the box.
By themselves, groups have an infinite boundary, so no object is ever clipped by the group. Now the renderer might decide to cull offscreen objects in a group, but that’s different from the group itself having a boundary. If the screen were stretched so its dimensions were sufficiently large, all the children in a group would be rendered.
So the standard way in the old engine to “clip” the rendering of the children in a group, you’d need to do something extra. Specifically, you’d have to set a rectangular mask on the group.
The problem with this approach is this required some foresight because the mask has to be based on a bitmap file. In other words, you’d have to know exactly the dimensions when you create them in Adobe Photoshop, Illustrator, etc. And if you wanted to create various groups with different clipping dimensions, there are some tricks like scaling the mask, but none of them were perfect.
That brings us back to Containers.
Containers are a new feature that will be introduced in the new graphics engine. Containers derive from groups, so they inherit all the methods to add and remove children. On top of that, they will provide first-class support for clipping the children of a group, based on the width and height for the group. No more messing with separate mask files — just specify the width and height that you want!
In the video below, we show a container with two children (a background image and a text object). As the container’s height shrinks, only the parts of the children inside the container bounds render:
Initially, the container is 300×300. Then we add our favorite aquarium image from the ‘Fishies’ sample and some text. Notice that the container clips the aquarium image so you only see the center of the original full 320×480 image. And as the height shrinks, the container will eventually clip the text object as well.
Here’s the corresponding code. Basically, think of the container as the same as a group, except you call a different constructor and you can change the ‘width’ and ‘height’ properties:
local container = display.newContainer( 300, 300 )
container:translate( 160, 240 ) -- center the container
local bkgd = display.newImage( "aquariumbackgroundIPhone.jpg" )
container:insert( bkgd, true ) -- insert and center bkgd
local myText = display.newText( "Hello, World!", 0, 0, native.systemFont, 40 )
myText:setFillColor( 255,255,0 )
container:insert( myText, true ) -- insert and center text
-- dynamically resize the height of the container
transition.to( container, height = 20, time=2000 )