Quick Layers (ssk.display.*)

quickLayers( parentGroup, ... ) - This function allows you to easily specify display group hierachies with optional nesting in a single call.

The quickLayers() function returns a single display group (layers) that contains the hierarchy as specified and that gives acess to each layer by its name, making game layering both fast and easy to implement.

Furthermore, the returned layers object provides two very useful methods:

layers:destroy() - Destroys the entire hierachy and all its children in one call.
layers:purge( [ name [, recursive ] ) - Purge the contents of any named layer.
- name (nil) - Name of layer to purge. If not specified, purge starting from root of hierarchcy.
recursive (true) - Clear objects in this layer and all objects in all child layers.

Tip: Purges do not destroy the layer groups themselves, so the hierarchy is maintained.

Creating A Layer System


-- Create Layers For Current Scene
local layers = ssk.display.quickLayers( sceneGroup, 
   "underlay", 
   "world",
      {  "background", 
         "content", 
         "foreground" },
   "overlay" )

Produces this bottom-to-top layered group hierarchy (parentGroup is sceneGroup in this example):


\ (parentGroup)
|--\ underlay
|--\ world
   |--\ background
   |--\ content
   |--\ foreground
|--\ overlay

Using A Layer System


-- Create grey rectangle in background layer
--
local back = newRect( layers.background, centerX, centerY, 
                       { w = fullw, h = fullh, fill = _DARKGREY_ } )

-- Add a 'player' in the 'content' layer
--
local player = newImageRect( layers.content, centerX, centerY, "images/smiley.png" )

Purging A Layer


-- Create 100 cirlces in 'overlay' layer.
--
for i = 1, 100 do
   newRect( layers.overlay, centerX + math.radom( -200, 200), centerY + math.radom( -200, 200), 
            { fill = ssk.colors.randomColor() }   )
end

-- Wait 2 seconds, then purge the 'overlay' layer thus destroying all those circles.
--
timer.performWithDelay( 2000, function() layers:purge( "overlay" ) end )