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.

print()

Receives any number of arguments, and prints their values to stdout (terminal, Xcode, ADB, etc.), using the tostring function to convert them to strings. print is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use string.format.

This API is useful for debugging your application to verify the value of variables and Display Objects and program flow.

Syntax: 

print (...)

Example: 

local rect = display.newRect( 0, 0, 100, 200 )
local value = 125
print( "Hello world" ) -- Hello world
print( 5 )  -- 5
print( "Value = " .. 5 ) -- Value = 5
print( "Values", 5, 10 ) -- Values     5     10
print( "Value = " .. tonumber( value ) ) -- Value = 125
print( "Display Object: " .. tostring( rect ) ) -- Display Object: table: 0x19a21df0

Parameters: 

1
String(s) or number(s) to print.

Returns: 

Nothing.

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

On the Mac Simulator and Windows Simulator, the print output goes to the terminal window.

On iOS devices, the Xcode console will display the print messages if the device is connected to the Xcode console.

On Android devices, the ADB (debugger) will display the print messages.

native.newTextBox()

Creates a scrollable, multiline text box for display content. Text boxes can be used for text input (and multi-line text input) by setting the .isEditable property to true.

Use "\n" to start text on a new line. Text will automatically wrap to the next line if it't too long.

Note: Native text boxes are only available in device builds and on the Corona Mac Simulator.

Syntax: 

native.newTextBox( left, top, width, height [, listener] )

Example: 

textBox = native.newTextBox( 15, 70, 280, 70 )
textBox.text = "This is line 1.\nAnd this is line2"

Parameters: 

left
X-coordinate of the top left corner of the text field.

top
Y-coordinate of the top left corner of the text field.

width
Width of the text field.

height
Height of the text field.

listener
(Optional) listener function to respond to keyboard events. The 'isEditable' property of the text box in order for keyboard events to be sent to the text box. If you choose to handle this event with a table listener, the event name is "userInput". These events come with a phase attribute, as follows:

  • event.phase = "began" -- this is the “keyboard has appeared” event. Depending on your interface design, you may want to adjust the screen contents when the keyboard is onscreen.
  • event.phase = "ended" -- this event is called when the text box loses focus: touching a different field or the on-screen keyboard is dismissed
  • event.phase = "submitted" -- used only on the Corona Mac Simulator when Text Box loses focus. It is sent before sending "ended" event. This event is NOT used on iOS or Android devices. The "ended" event should be used instead of "submitted."
  • event.phase = "editing" -- this event occurs when the user modifies text in the textbox. During this phase, several other keys are present in the event table:
    • event.startPosition -- number representing the position the cursor was at when the edit took place.
    • event.text -- string that represents the text of the textbox (to include the new edit).
    • event.newCharacters -- string that represents any new characters that were typed in during the event.
    • event.oldText -- string that represents the characters before the new characters were typed in during the event.
Returns: 

The created native text box object.

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

Other properties that affect the text box:
object.align
object.font
object.hasBackground
object.size
object.text
object.isEditable
object:setTextColor

Note: This API is supported in the Corona Mac Simulator but not in the Corona Windows Simulator.

Note: Native Text Box objects, like other native objects don't work in groups and are always displayed on top of regular Display Objects (vector, images, and text).

The argument 'listener' is only available starting in daily build 609.

native.cancelWebPopup()

Dismisses the currently displaying web pop-up.

Syntax: 

native.cancelWebPopup()

Parameters: 

None.

Returns: 

Returns true if web pop-up was displaying prior to the call; false otherwise.

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

Not supported in Corona Simulators.

native.showWebPopup()

Creates a web popup that loads a local or remote web page.

Note: Web popups are only available on device builds.

Syntax: 

native.showWebPopup( url [, options] )  
native.showWebPopup( x, y, width, height, url [, options] )

Example: 

native.showWebPopup( 10, 10, 300, 300, 
                  "http://www.anscamobile.com", 
                  {urlRequest=listener} )

This example reads the html code from a local file in the /Documents directory.
local function listener( event )
        local shouldLoad = true
 
        local url = event.url
        if 1 == string.find( url, "corona:close" ) then
                -- Close the web popup
                shouldLoad = false
        end
 
        if event.errorCode then
                -- Error loading page
                print( "Error: " .. tostring( event.errorMessage )
                shouldLoad = false
        end
 
        return shouldLoad
end
 
local options = { hasBackground=false, baseUrl=system.DocumentsDirectory, urlRequest=listener }
native.showWebPopup( "localpage1.html", options )

Parameters: 

url
URL of the local or remote web page. By default, the URL is assumed to be an absolute URL to a remote server. If x, y, width, height are not specified, the popup occupies the entire screen.

  • Note: To control scaling, make sure your popup's HTML head element contains the following: <meta name="viewport" content="width=320; initial-scale=1.0; maximum-scale=1.0; user-scalable=0;"/>.
  • To prevent text within a web popup from being resized add the following style to your HTML document:
    <style type="text/css"> 
         html {        -webkit-text-size-adjust: none;  }
    </style>

x, y, width, height
If specified, these parameters control the position and dimensions of the popup.

options
Optional table containing additional parameters for the popup:

  • options.baseUrl determines whether the url parameter to native.showWebPopup() is interpreted as a relative or absolute url.

    • By default (nil) the url is absolute.
    • To refer to a local file instead, set the base url to one of the base directory constants, e.g. system.ResourceDirectory. Then the url parameter is relative to that base directory.
    • For remote files, you can also specify a remote base, and the url parameter will be relative to the remote base.
  • options.hasBackground
  • is a Boolean that controls whether the popup has a an opaque background or not. If not specified, the background will be opaque.

  • options.autoCancel
  • is a Boolean which sets up the popup to be automatically closed when the Android back key has been pressed when there is no more web history to navigate to. This is true by default.

  • options.urlRequest
  • designates a listener function that will intercept all urlRequest events from the web popup. This also provides a standard method for passing information back from a web page using pseudo-URLs. For example, the Interface/WebOverlay sample project displays a local HTML page that contains the following HTML:

    <form action="corona:close">
            <input type="submit"/>
    </form>      

    When the user clicks Submit in the web pop-up, the designated listener function is sent a urlRequest event object with its url property set to "corona:close", allowing the application to react appropriately.

    Note: The listener function must return true or the web popup will close. Without a return statement, false is assumed.

Returns: 

Nothing.

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

Not supported in Corona Simulators.

Only one WebPopup object can be displayed at a time.

Webpopup objects cannot be moved or resized. They must be canceled and recreated if they need to be moved or resized.

Note: Native Web Popup objects, like other native objects don't work in groups and are always displayed on top of regular Display Objects (vector, images, and text).

Here is a link to working sample code showing how to use CSS in a local HTML file.
https://github.com/ansca/My-Portfolio/

event.name

The native.showWebPopup listener event returns the string, "urlRequest".

Syntax: 

event.name

Example: 

local function listener( event )
    print( "Webpopup: " .. event.name, event.errorCode )
    return true  -- load the page
end
 
native.showWebPopup( 10, 10, 300, 300, 
                  "http://www.anscamobile.com", 
                  {urlRequest=listener} )

Parameters: 

None

Returns: 

string
Returns the string, "urlRequest".

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

system.vibrate()

Vibrates the phone. On the Corona simulator this will sound a system beep.

Syntax: 

1
system.vibrate()

Example: 

system.vibrate()  -- vibrate the device

Parameters: 

None.

Returns: 

Nothing.

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: 

To enable the vibrate function on Android devices, you must set the permission level in the build.settings file.

1
2
3
4
5
6
7
settings =
{
   androidPermissions =
   {
       "android.permission.VIBRATE"
   },
}

native.cancelAlert()

Dismisses an alert box programmatically. For example, you may wish to have a popup alert that automatically disappears after ten seconds even if the user doesn’t click it. In that case, you could call this function at the end of a ten-second timer.

Syntax: 

native.cancelAlert( alert )

Example: 

-- Handler that gets notified when the alert closes
local function onComplete( event )
        if "clicked" == event.action then
                local i = event.index
                if 1 == i then
                        -- Do nothing; dialog will simply dismiss
                elseif 2 == i then
                        -- Open URL if "Learn More" (the 2nd button) was clicked
                        system.openURL( "http://developer.anscamobile.com" )
                end
        end
end
 
-- Show alert with two buttons
local alert = native.showAlert( "Corona", "Dream. Build. Ship.", 
                                        { "OK", "Learn More" }, onComplete )
 
-- Dismisses "alert" after 10 seconds if user has not responded
local function cancelMyAlert()
        native.cancelAlert( alert )
end
 
timer.performWithDelay( 10000, cancelMyAlert )

Parameters: 

alert
id of the alert to cancel (from native.showAlert)

Returns: 

Nothing.

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: 

None.

native.showAlert()

Displays a popup alert box with one or more buttons, using a native alert control. Program activity, including animation, will continue in the background, but all other user interactivity will be blocked until the user selects a button or cancels the dialog.

Syntax: 

native.showAlert( title, message [, { buttonLabels } [, listener] ] )

Example: 

-- Handler that gets notified when the alert closes
local function onComplete( event )
        if "clicked" == event.action then
                local i = event.index
                if 1 == i then
                        -- Do nothing; dialog will simply dismiss
                elseif 2 == i then
                        -- Open URL if "Learn More" (the 2nd button) was clicked
                        system.openURL( "http://developer.anscamobile.com" )
                end
        end
end
 
-- Show alert with two buttons
local alert = native.showAlert( "Corona", "Dream. Build. Ship.", 
                                        { "OK", "Learn More" }, onComplete )

Parameters: 

title
The title string displayed in the alert

message
Message string displayed in the alert text.

buttonLabels
Table of strings, each of which will create a button with the corresponding label. Include at least one buttonLabel or the dialog will not have any buttons. The first button will have a unique color to suggest that the user should choose it by default.

The maximum number of buttons in an alert box is five. The most common format is one or two buttons, for example “OK” and “Cancel”.

listener
The listener to be notified when a user presses any button in the alert box. It can assign an action to each button according to its numerical index: the first button is index 1, the second is index 2, and so on. The listener can be either a function listener or a table listener. If listener is a table, it must have a completion method.

The event dispatched to the listener will be a completion event with the following additional properties:

  • event.action represents how the alert was dismissed: "cancelled" indicates that native.cancelAlert() was called to close the alert, while "clicked" indicates that the user clicked on a button to close the alert.
  • event.index is the index of the button pressed. It corresponds to the index in the buttonLabels parameter.
Returns: 

alert
id of the alert. (Can be used to cancel the alert.)

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: Native Show Alert object, like other native objects don't work in groups and are always displayed on top of regular Display Objects (vector, images, and text).

native.setActivityIndicator()

Displays or hides a platform-specific activity indicator. Touch events are ignored while the indicator is shown.

Note that the indicator will not show until the Lua code block containing the setActivityIndicator(true) call has completed execution. Also, if you try to show and hide the indicator within the same code block then the indicator will not show properly. Instead, call the code to hide the activity indicator in a separate function call or callback.

The code in the example uses the timer object to hide the indicator after 2 seconds have elapsed.

Syntax: 

native.setActivityIndicator( state )

Example: 

native.setActivityIndicator( true )
timer.performWithDelay( 2000,  
     function() 
         native.setActivityIndicator( false )
     end)

Parameters: 

state
Use true to show the indicator and false to hide it.

Returns: 

Nothing

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

Note: Native Activity Indicator object, like other native objects don't work in groups and are always displayed on top of regular Display Objects (vector, images, and text).