Display Object Factories (ssk.display.*)

(Each object below (except spinning circle) was created with a single function call.) Extended Display Object Samples

SSK versus Pure Corona SDK

SSK provides a set of improved factories to replace/extend (→) the traditional display.* factories:

The benefit of these factories over the traditional ones is that a display object can often be fully configured, colorized, have a body added, and even have listeners added, all in one easily-typed and legible function call.

The SSK Way


newImageRect( group, centerX - 100 , centerY - 50,
              "images/kenney/physicsAssets/yellow_round.png", 
              { size = 40 }, 
              { radius = 20, bounce = 1, gravityScale = 0.2 } ) 

newImageRect( group, centerX - 100, centerY + 100, 
              "images/kenney/physicsAssets/stone/square2.png", 
              { size = 40 }, 
              { bodyType = "static" } )

SSK verus Pure Corona SDK

The Old Way - Blech!


local ball = display.newImageRect( group, "images/kenney/physicsAssets/yellow_round.png", 40, 40 )
ball.x = display.contentCenterX + 100
ball.y = display.contentCenterY - 50
physics.addBody( ball, { radius = 20, bounce = 1, radius = 20  } )
ball.gravityScale = 0.2

local block = display.newImageRect( group, "images/kenney/physicsAssets/stone/square2.png", 40, 40 )
block.x = display.contentCenterX + 100
block.y = display.contentCenterY + 100
physics.addBody( block, "static" )

The Standard Factories

All of the Standard Factories take similar arguments. Please see Factory Arguments below for details on these arguments.

(I am not providing individual examples here. To learn about using these factories, please explore the samples.)

newCircle

ssk.display.newCircle( group, x, y [, visualParams [, bodyParams [, behaviorsList ]]] )

newRect

ssk.display.newRect( group, x, y [, visualParams [, bodyParams [, behaviorsList ]]] )

newImage

ssk.display.newImage( group, x, y, imgSrc [, visualParams [, bodyParams [, behaviorsList ]]] )

newImageRect

ssk.display.newImageRect( group, x, y, imgSrc [, visualParams [, bodyParams [, behaviorsList ]]] )

Factory Arguments

As you will have noticed, the above factories have a fairly consistent function signature and share common arguments. Those argument can be summarized as follows:

Other Factories

This page (of the docs) only discusses the 'Standard Factories', however ssk.diplay.* also has these factories: Arcs, Lines, Quick Layers

Visual Parameters (visualParams)

The first (common) table that all of these builders takes is the visualParams table. With this table, you can set almost all visual properties on the object and you can also attach or set any arbitrary property.

visualParams - 'Standard' Properties

Aside from the 'custom' and specially handled properties listed above, you may set any normal Corona property as well.


-- Create a red circle with a 50% alpha
newCircle( nil, 100, 100 { fill = _R_, alpha = 0.5 } )

See the Corona docs for the complete list of 'Display Object Properties' (external link).

visualParams - 'Custom' Properties

visualParams - 'Listeners'

In addition to being able to set many visual properties via the visualParams table, you can supply function references to the following property names:
accelerometer axis collision enterFrame
finalize key mouse sprite
tap timer touch

If any of these parameters is specified, SSK will automatically hook-up and start the specified listener(s).

Note: Only works if enableAutoListeners = true. See Configuring SSK2.

Listener Example 1 - touch


local function onTouch( self, event)
   if( event.phase == "ended" ) then
      print("My name is: " .. self.myName )
   end
   return false
end

local tmp = newRect( nil, 100, 100, { touch = onTouch, myName = "Rect 1" }) 

local tmp = newRect( nil, 200, 100, { touch = onTouch, myName = "Rect 2" })

Now, if you touch either of the two rectangles created by this code, they will print:

My name is: Rect 1 OR My name is: Rect 2

Listener Example 2 - enterFrame


local function onEnterFrame( self )

   self.x = self.x + 1

   if( self.x >= right ) then

      self.x = right

      ignore( "enterFrame", self )

      self.enterFrame = nil

    end

end

newCircle( nil, left, centerY, { enterFrame = onEnterFrame } )

The sample above creates a white circle with a radius of 20 pixels on the very left-edge of the screen and vertically centered.

As soon as is created, the circle immediately starts moving one pixel to the right every frame.

Once has reached the right-edge of the screen it will stop and remove the listener.

visualParams - 'Arbitrary' Properties

Lastly, as you may have noticed in the prior section, visualParams can take any arbitrary property name and assign a value to it. This is extremely handy for setting flags and other values used later in your code.


local tmp = newRect( nil, 100, 100, { myName = "Bob", myAge = 21, amHappy = true }) 

print( tmp.myName, tmp.myAge, tmp.amHappy )

Body Parameters (bodyParams)

The second optional table you can pass to all of the builder functions is the bodyParams table.

bodyParams - The Default Body {}

Specifying an empty table tell SSK to add a default body to the object.


newCircle( nil, 100, 100, { radius = 50 }, {} )

newRect( nil, 100, 100, { w = 50, h = 20 }, {} )

After the prior code executes, we will have a circle and a rectangle, both with default bodies.

The circle will have a circular body and the rectangle will have a rectangular body that matches the dimensions of the rectangle.

Both bodies will have this (default) physics configuration:

bodyParams - 'Standard' Properties

As with visualParams, you may pass key-value pairs in this table to set properties. These properties include all the standard Physics property.


-- Create a circle with a static body that is also a sensor
newCircle( nil, 100, 100, { radius = 50 }, { bodyType = "static", isSensor = true } )

See the Corona docs for a full list of 'Physics Body Properties' (external link).

bodyParams - 'Custom' Properties

Besides the many 'Standard' properties supported by Corona and SSK, you can specify these custom properties too:


-- Make a circle that uses the 'player' settings from a previously created and configured Collision Calculator.
newCircle( nil, 100, 100, { radius = 50 }, { calculator = myCC, colliderName = "player" } )

Behaviors (behaviorsList)

This is a work-in-progress feature.

When it is released, you will be able to create objects with complex behaviors like:

RoamingGamer Copyright © Roaming Gamer, LLC. 2008-2016; All Rights Reserved