graphics.newGradient( )

Creates a gradient object that adds horizontal/vertical linear gradients to rectangle and text objects.

The gradient starts with color1 and goes to color2. Both color1 and color2 are table arrays.

Syntax: 

local g = graphics.newGradient( color1, color2 [ , direction] )

Example: 

local g = graphics.newGradient(
  { 255, 255, 255 },
  { 200, 200, 200 },
  "down" )
 
-- sets gradient 'g' on rect
local rect = display.newRect( 0, 0, 100, 200 )
rect:setFillColor( g ) 
 
-- sets gradient 'g' on text
local text = display.newText("Hello World!", 0, 0, native.systemFont, 16)
text:setTextColor( g )

Parameters: 

color1
Table array with the starting gradient color.

The table format for both color1 and color2 can be one of the following:
{ gray }
{ gray, alpha }
{ red, green, blue }
{ red, green, blue, alpha }

Gray, alpha, red, green, and blue are values in the range of 0 to 255.

color2
Table array with the ending gradient color.

direction
String containing the gradient direction. Defaults to "down" if not supplied.

"up" gradient starts at bottom and goes to the top
"down" gradient starts at the top and goes to the bottom (default)
"left" gradient starts at the right and goes to the left
"right" gradient starts at the left and goes to the right

Returns: 

Gradient Object
Returns a gradient object that is used with object:setFillColor and object:setTextColor.

Supported on:
Mac OS X: 
Build 2011.612
Windows: 
Build 2011.612
iOS: 
Build 2011.612
Android: 
Build 2011.612
Remarks: 

Gradients do not work with display.newCircle, display.newRoundedRect, or display.newGroup.

display.loadRemoteImage( )

This a convenience method, similar to network.download(), which returns a display object containing the image, as well as saving the image to file.

Syntax: 

object = display.loadRemoteImage( url, method, listener [, params], destFilename [, baseDir] [, x, y] )

Example: 


The following example downloads a remote image to a local file copy, and then displays it on the screen at (50, 50) after a short alpha transition:

local function networkListener( event )
        if ( event.isError ) then
                print ( "Network error - download failed" )
        else
                event.target.alpha = 0
                transition.to( event.target, { alpha = 1.0 } )
        end
        
        print ( "RESPONSE: " .. event.response )
end
 
display.loadRemoteImage( "http://developer.anscamobile.com/demo/hello.png", "GET", networkListener, "helloCopy.png", system.TemporaryDirectory, 50, 50 )

Parameters: 

url
String: The HTTP request URL.

method
String: The HTTP method; valid values are "GET" (the default) or "POST".

listener
Function: The listener function invoked when the HTTP operation has completed. It is passed an event object that contains the following properties:

  • event.response
    A string containing the destination filename. This is useful if you're writing a general event handler for a variety of file downloads.
  • event.target
    The new display object created after the image is downloaded.
  • event.isError
    A boolean value: true in the case of a network error, false otherwise.

params
Table: An optional table that specifies custom HTTP headers or body to include in the request. To specify custom headers, attach a headers table that specifies header values with string keys. To specify a custom body message, attach a body property to this table whose string value is the HTTP body.

  • params.headers
  • A table specifying header values with string keys.

  • params.body
  • A string containing the HTTP body.

destFilename
String: The name of the file to which the HTTP response will be saved.

baseDir
String: The folder path to which the file will be saved.

x
The x position of the newly created display object; default is 0.

y
The y position of the newly created display object; default is 0.

Returns: 

Nothing is returned from calling this method. The listener callback will contain the Display Object value (event.target) if the download was successful.

Supported on:
Mac OS X: 
Build 2011.268
Windows: 
--
iOS: 
Build 2011.268
Android: 
Build 2011.336
Remarks: 

Image Guidelines
Images should not contain an embedded ICC profile. Use "Save for Web" when exporting images to be used on the device.

To avoid images from using too much texture memory, make sure the image is between 72 and 170 DPI.

Be aware of the gamma and color differences between your development system (Mac and Windows machines) and the device. For best results color calibrate the display used for creating the images.

graphics.newMask( )

Creates a bit mask from an image file. The image is converted internally to grayscale; black values are then masked, while white values are not.

The white pixels of the bit mask allow the covered image to be visible. Black pixels hide (mask) the covered image. The area outside of the mask is filled with black pixels which mask off the area outside the bit mask image.

Note: Bit Mask Requirements
1. The mask image width and height must be multiples of 4.
2. The mask image must have a black border around the mask that is 3 or more pixels.

Syntax: 

local mask = graphics.newMask( filename [, baseDir] )

Example: 

This sample code uses images from the Graphics/Flashlight sample in the Corona SDK. It applies a mask to the image and then scales the mask to twice its original size.

-- Create and position image to be masked
local image = display.newImageRect( "image.png", 768, 1024 )
image:translate( display.contentCenterX, display.contentCenterY )
 
-- Create mask and apply to image
local mask = graphics.newMask( "circlemask.png" )
image:setMask( mask )
 
-- Transform mask
image.maskScaleX, image.maskScaleY = 2,2

Here is an example of how to add a bit mask to a display group. It uses the assets from the X-Ray sample code.
local g = display.newGroup()
 
local bar = display.newImage( g, "paper_bkg.png" ) -- create and add to group
 
local mask = graphics.newMask("circlemask.png")
 
g:setMask(mask)
 
-- Center the mask over the Display Group
g:setReferencePoint( display.CenterReferencePoint )
g.maskX = g.x
g.maskY = g.y

Parameters: 

filename
String: The name of the image file to create the mask from.

baseDir
String: Specifies the directory path that contains the mask image.

Returns: 

Userdata
A mask object that can be applied to any display object using object:setMask()

Supported on:
Mac OS X: 
Build 2011.268
Windows: 
Build 2011.288
iOS: 
Build 2011.268
Android: 
Build 2011.288
Remarks: 

Prior to build 2011.510, masking an image does not affect the touch (or tap) area so touch events will happen for areas of the image that is masked off. If you need touch events to happen only on the masked portion of the object, you will need to create a "hidden" object that tracks the position and size of the masked object and set this as the touch target. The hidden object can be a newRect or newCircle with the alpha property set to 0.0 (so it doesn't show).

Starting with build 2011.510, only the masked portion of the object is affected by touch/tap. Note, however, that the touch sensitive area still corresponds to the mask image shape and is therefore always rectangular, regardless of the actual image! This masking can be disabled with the object.isHitTestMasked property; see the Flashlight sample project.

display.setDefault( )

Set default colors for display objects. Colors default to white if not set.

Syntax: 

display.setDefault( key, gray )
display.setDefault( key, gray, alpha )
display.setDefault( key, r, g, b )
display.setDefault( key, r, g, b, alpha )

Example: 

-- set default fill color for vector objects to red
display.setDefault( "fillColor", 255, 0, 0 )

Parameters: 

key
String: Specifies which default color value to set: "fillColor", "strokeColor", "textColor", "lineColor", "background".

  • "background" corresponds to the default color for that the screen is cleared with. The default is initially black. (Available to subscribers starting in daily build 2011.505)
  • "fillColor" corresponds to the default color for vector objects (e.g. display.newRect). The default is initially white.
  • "strokeColor" corresponds to the default color for vector objects (e.g. display.newRect). The default is initially white.
  • "lineColor" corresponds to the default color for line objects (e.g. display.newLine). The default is initially white.
  • "textColor" corresponds to the default color for text objects (e.g. display.newText). The default is initially white.

gray, r, g, b, alpha
Color values between 0 and 255.

Returns: 

Nothing.

Supported on:
Mac OS X: 
Build 2011.268
Windows: 
Build 2011.268
iOS: 
Build 2011.268
Android: 
Build 2011.268

display.newGroup()

Creates a group in which you can add and remove child display objects. Initially, there are no children in a group. The local origin is at the parent’s origin; the reference point is initialized to this local origin. See Groups.

Groups are created with a default reference point of TopLeftReferencePoint, where most other Display Objects are created with CenterReferencePoint. See the Remarks section about changing group properties.

Syntax: 

display.newGroup()

Example: 

local rect = display.newRect(0, 0, 100, 100)
rect:setFillColor(140, 140, 140)
 
local group = display.newGroup()
group:insert( rect )

Parameters: 

none

Returns: 

display object

Supported on:
Mac OS X: 
Corona SDK 1.0
Windows: 
Corona SDK 2.0
iOS: 
Corona SDK 1.0
Android: 
Corona SDK 2.0
Remarks: 

Note: You should have at least one Display Object inserted into a Display Group before you change or read any of the properties of the group (e.g., x, y, setReferencePoint, etc.). There is a bug in Corona that will set/return properties with a very large value (2147483648) if a property is changed and the group is empty.

display.newRoundedRect()

Creates a width by height rounded rectangle with the top-left corner at (left, top). The corners are rounded by quarter circles of radius cornerRadius. The local origin is at the center of the rectangle; the reference point is initialized to this local origin.

Syntax: 

display.newRoundedRect( [parentGroup,] left, top, width, height, cornerRadius )

Example: 

local myRoundedRect = display.newRoundedRect(0, 0, 150, 50, 12)
myRoundedRect.strokeWidth = 3
myRoundedRect:setFillColor(140, 140, 140)
myRoundedRect:setStrokeColor(180, 180, 180)

Parameters: 

parentGroup
object: display group in which to insert the rectangle.

left
number: specify that the image's left corner.

top
number: specify that the image's top corner.

width
number: width of the rectangle

height
number: height of the rectangle

cornerRadius
number: corners are rounded by quarter circles of radius

Returns: 

display object

Supported on:
Mac OS X: 
Corona SDK 1.0
Windows: 
Corona SDK 2.0
iOS: 
Corona SDK 1.0
Android: 
Corona SDK 2.0
Remarks: 

By default, there is no stroke color. and the fill color is white (rgb 255, 255, 255).

display.newImageRect()

Automatically substitute higher-resolution assets on higher-resolution devices. The actual image chosen will depend on the current content scale determined by Corona, which is the ratio between the current screen and the base content dimensions defined in config.lua. Based on this scale, Corona uses the imageSuffix table (also defined in config.lua), which lists the suffixes for the same family of images, to find the best match from the image choices available.

Syntax: 

object = display.newImageRect( [parentGroup,] filename [, baseDirectory] width, height )

Example: 

local myDynamicImage = display.newImageRect( "baseImage.png", 100, 100 ) 

Parameters: 

parentGroup
object: display group in which to insert the image.

filename
string: Filename of the image.

baseDirectory
path: Path to load the image data from filename. Default is system.ResourceDirectory. See system.pathForFile for valid values of baseDirectory).

width
number: the content width of the image, which is the width in the reference screen of the content.

height
number: the content height of the image, which is the height in the reference screen of the content.

Returns: 

display object

Supported on:
Mac OS X: 
Corona SDK 1.0
Windows: 
Corona SDK 2.0
iOS: 
Corona SDK 1.0
Android: 
Corona SDK 2.0
Remarks: 

All loaded images are cached. To save texture memory the image in the cache memory is used when it detects an image with the same file name is displayed. This means that loading the same image multiple times doesn't increase the amount of texture memory used on the device.

A negative side-effect to the image caching is the comparison is based on the file name and not the file content. This means if an image file is displayed and then deleted from the directory, any file loaded after that with the same file name will still display the previous cached image. Use a different file name to avoid this problem.

Image Guidelines
Images should not contain an embedded ICC profile. Use "Save for Web" when exporting images to be used on the device.

To avoid images from using too much texture memory, make sure the image is between 72 and 170 DPI.

Be aware of the gamma and color differences between your development system (Mac and Windows machines) and the device. For best results color calibrate the display used for creating the images.

You should NOT use progressive JPGs since they will take much longer to load than non-progressive JPGs.

display.newRect()

Creates a width by height rectangle with the top-left corner at (left, top). The local origin is at the center of the rectangle; the reference point is initialized to this local origin.

Beginning with build 2011.612, gradients can be added using object:setFillColor.

Syntax: 

display.newRect( [parentGroup,] left, top, width, height )

Example: 

local myRectangle = display.newRect(0, 0, 150, 50)
myRectangle.strokeWidth = 3
myRectangle:setFillColor(140, 140, 140)
myRectangle:setStrokeColor(180, 180, 180)

Parameters: 

parentGroup
object: display group in which to insert the rectangle.

left
number: specify that the image's left corner.

top
number: specify that the image's top corner.

width
number: width of the rectangle

height
number: height of the rectangle

Returns: 

display object

Supported on:
Mac OS X: 
Corona SDK 1.0
Windows: 
Corona SDK 2.0
iOS: 
Corona SDK 1.0
Android: 
Corona SDK 2.0
Remarks: 

By default, there is no stroke color. and the fill color is white (rgb 255, 255, 255).

display.newLine( )

Draw a line from one point to another. Optionally, append points to the end of the line. See Polylines.

Syntax: 

display.newLine( [parent,] x1,y1, x2,y2 )

Example: 

local star = display.newLine( 0,-110, 27,-35 )
star:append( 105,-35, 43,16, 65,90, 0,45, -65,90, -43,15, -105,-35, -27,-35, 0,-110 )
star:setColor( 255, 102, 102, 255 )
star.width = 3 

Parameters: 

parent
object: Specify an optional display group in which to insert the line. Uses the current Stage if not specified.

x1,y1
number: Coordinates of the beginning of the line.

x2,y2
number: Coordinates of the end of the line.

Returns: 

Display object

Supported on:
Mac OS X: 
Corona SDK 2.0
Windows: 
Corona SDK 2.0
iOS: 
Corona SDK 2.0
Android: 
Corona SDK 2.0
Remarks: 

Note: Currently display.newLine objects do not support touch events (case #3803).

By default, the fill color is white (rgb 255, 255, 255). The default color can be changed using display.setDefault.

display.newCircle()

Creates a circle with radius radius centered at (xCenter, yCenter). The local origin is at the center of the circle. The reference point is initialized to this local origin.

Syntax: 

display.newCircle( [parentGroup,] xCenter, yCenter, radius )

Example: 

display.setStatusBar( display.HiddenStatusBar )
 
local myCircle = display.newCircle( 100, 100, 30 )
myCircle:setFillColor(128,128,128)

You also set a border around the circle, along with it's color.

myCircle.strokeWidth = 5
myCircle:setStrokeColor(128,0,0)  -- red

Parameters: 

parentGroup
object: display group in which to insert the rectangle. (optional)

xCenter
number: x-coordinate for the center of the circle

yCenter
number: y-coordinate for the center of the circle

radius
number: radius for the circle from x, y. The radius must be greater than 0.

Returns: 

Display object

Supported on:
Mac OS X: 
Corona SDK 1.0
Windows: 
Corona SDK 2.0
iOS: 
Corona SDK 1.0
Android: 
Corona SDK 2.0
Remarks: 

By default, there is no stroke color. and the fill color is white (rgb 255, 255, 255).