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.

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.save( )

Renders the display object referenced by displayObject into a JPEG image and saves it in filename. The display object must currently be in the display hierarchy; otherwise no image is saved. If the display object is a group object, then all children are rendered. The object to be saved must be on the screen and fully within the screen boundary.

Syntax: 

display.save( displayObject, filename [, baseDirectory] )

Example: 

local myObject1 = display.newRect( 50, 50, 100, 150 ) -- Create a rectangle object
local myObject2 = display.newCircle( 100, 300, 50 )   -- Create a circle object
 
local g = display.newGroup()
 
g:insert(myObject1)
g:insert(myObject2)
 
local baseDir = system.DocumentsDirectory
display.save( g, "entireGroup.jpg", baseDir )

Parameters: 

displayObject
object: Name of display object to save.

filename
string: Name of the file to save the JPEG.

baseDirectory
system path: Optional. Can be either system.DocumentsDirectory (the default) or system.TemporaryDirectory.

Returns: 

Nothing.

Supported on:
Mac OS X: 
Corona SDK 1.0
Windows: 
Build 2011.484
iOS: 
Corona SDK 1.0
Android: 
Build 2011.591
Remarks: 

Higher resolution image saved to jpeg file in build #299.

Note1: There is a problem with object captures when the device orientation is different from the initial orientation. There is also a problem capturing the entire object on iPad and iPhone4 devices when Dynamic Scaling (in config.lua) is enabled. [case #928]

Note2: display.save uses the openGL buffer viewport for saving the specified Display Object. When using the Simulator, the size of the saved image will be smaller than expected if the simulator "skin" is not displayed full size. This generally occurs when the simulator skin is displayed on a smaller monitor (e.g., 13") or when Zoomed Out. When the skin is displayed full size, the saved image will match that of the simulated device.

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.newText()

Creates a text object with its top-left corner at (left, top). The local origin is at the center of the text; the reference point is initialized to this local origin. By default, the text color is white (255, 255, 255). See Text for more.

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

Syntax: 

display.newText( [parentGroup,] string, left, top,
                               [width, height,] font, size )

Example: 

local myText = display.newText("Hello World!", 0, 0, native.systemFont, 16)
myText:setTextColor(255, 255, 255)

Update the text string and size:

local myText = display.newText("", 0, 0, native.systemFont, 12)
myText:setTextColor(255, 255, 255)
 
myText.text = "Hello World!"
myText.size = 16

Parameters: 

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

string
string: specify text to display.

left, top
number: coordinates for the object's top left corner

width, height
number: optional arguments to enable multi-line text. Text will be wrapped at width and be cropped at height. Set height to 0 and the height will change according to amount of text — except it will *not* exceed the maximum texture height for the device.

font
string: Names the font. Obtain an array of available fonts via native.getFontNames() . Alternatively, you can also pass the following constants instead of a string:

native.systemFont
native.systemFontBold

Note: On Android 1.6, using a named font is not supported. This is a limitation of the OS.

size
number: size of the text in pixels

Returns: 

Text 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: There is currently a bug on all platforms that will cause text to disappear when rotated when "antialias" is set to "true" in config.lua. This does not affect the text if the rotation is 0, 90, or 180 degrees. If you need rotated text, the only solution is to set antialias to false.

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.