The native library provides access to various native UI features on the device.

Activity Indicator

native.setActivityIndicator( )

native.setActivityIndicator( visible ) 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 end of 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, hide the activity indicator in a separate function call or callback. For example, the following code uses the timer object to hide the indicator after 2 seconds have elapsed.

1
2
3
4

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

Below are examples of how the activity indicator varies across platforms using the same code. Pictured on the left is the Corona Simulator on Mac OS X. Pictured on the right is the same app running on the iPhone.

Alert

native.showAlert( )

native.showAlert( title, message [, buttonLabels [, listener]] ) 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.

The strings title and message are the title and message text displayed in the alert. buttonLabels is a table of strings, each of which will create a button with the corresponding label. You should 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 six. The most common format is one or two buttons, for example “OK” and “Cancel”.

The listener is notified when a user presses any button in the alert box, and 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. It will contain the following additional properties:

event.action

event.action indicates how the alert was dismissed:

• "cancelled" indicates that native.cancelAlert() was called to close the alert.
• "clicked" indicates that the user clicked on a button to close the alert.

event.index

event.index is the index of the button pressed. It corresponds to the index in the buttonLabels parameter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

-- 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 five buttons
local alert = native.showAlert( "Corona", "Dream. Build. Ship.", 
                                        { "OK", "Learn More" }, onComplete )

Note: When running in the Corona Simulator, the alert box displayed will be a native Mac OS X alert sheet rather than an iPhone alert box (shown at left). On the iPhone, the alerts will function the same as native alerts (right):

native.cancelAlert( )

native.cancelAlert( alert ) Dismisses the 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.

1
2
3
4
5
6

-- Dismisses "alert" from previous code sample after 10 seconds
local function cancelMyAlert()
        native.cancelAlert( alert )
end
 
timer.performWithDelay( 10000, cancelMyAlert )

Examples

For further examples of how to use native alerts, see the Alert project in the Sample Code folder of the Corona SDK.

Fonts

native.newFont( )

native.newFont( name [, size] ) Creates a font object that you can use to specify fonts in native text fields and text boxes. You can also pass it as a parameter to the display text objects in the display.newText() function.

The name parameter is a string that names the font. You can 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

The size parameter is optional. You can use it to specify the point size of the font. By default, it will be the standard system font size of the device.

native.getFontNames()

Returns an array of the available native fonts.

Note: on the simulator, the available fonts may not correspond to the fonts actually available on the device. In general, iPhone device fonts can be accessed from the simulator within MacOS, but additional Mac fonts will also be available that may not work on the iPhone. If you encounter a problem of fonts appearing in the simulator but not on your device, this is the most likely cause. When in doubt, check the available device font names using native.getFontNames().

Text Input

native.newTextField( )

native.newTextField( left, top, width, height [, listener] ) Creates a single-line textfield for text input.

Properties

object.align

object.align can be a string "left", "center", or "right".

object.font

object.font is a font object returned by native.newFont().

object.isSecure

object.isSecure is controls whether text is hidden, e.g. passwords, or not. Default is false.

object.size

object.size is the size of the text

object.text

object.text is a string of the contents of the text box.

Methods:

object:setTextColor( )

object:setTextColor( r, g, b [, a] ) sets the color of the text.

Note: native textfields are only available on device builds.

Because native textfields are not part of the OpenGL canvas, they do not obey the Corona display object hierarchy. For example, while they can be manipulated using display object methods, they always appear above normal display objects.

Also, they do not inherit display group properties like isVisible, x, y and alpha. If you need to set display properties on native objects, apply them to the objects directly.

To remove a native textfield from the display, use object:removeSelf().

Listening for Keyboard Events

You may optionally provide a listener function to respond to keyboard events. 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 user stops editing a field: for example, when they touch a different field.

event.phase = "submitted" -- this event occurs when the user presses the “"return"” key (if available) on the onscreen keyboard.

If you choose to handle this event with a table listener, the event name is "userInput".

native.setKeyboardFocus( )

native.setKeyboardFocus( textField ) Sets keyboard focus on a textField and (where appropriate) shows the keyboard. Pass nil to remove focus and dismiss the keyboard.

Supported Keyboard Types

Five keyboard types are supported in the input textfield, using a property named "inputType". This property is optional. See the Interface/NativeKeyboard sample code for a demo of the various available types.

Example:

numericField = native.newTextField( 50, 150, 220, 36, handlerFunction )
numericField.inputType = "number"

The five possible values for the inputType property are:

• "default" - the default keyboard, supporting general text, numbers and punctuation
• "number" - a numeric keypad
• "phone" - a keypad for entering phone numbers
• "url" - a keyboard for entering website URLs
• "email" - a keyboard for entering email addresses

As before, you can set the isSecure boolean to create a password-entry field:

passwordField.isSecure = true

Multiline Textfields

native.newTextBox( )

native.newTextBox( left, top, width, height ) Creates a scrollable, multi-line text box

Properties:

object.align

object.align can be a string "left", "center", or "right".

object.font

object.font is a font object returned by native.newFont().

object.hasBackground

object.hasBackground is true when there is background and false when the background is transparent.

object.size

object.size is the size of the text

object.text

object.text is a string of the contents of the text box.

Methods:

object:setTextColor( )

object:setTextColor( r, g, b [, a] )

Note: this feature is only available on device builds.

Because native textboxes are not part of the OpenGL canvas, they do not obey the Corona display object hierarchy. For example, while they can be manipulated using display object methods, they always appear above normal display objects.

Also, they do not inherit display group properties like isVisible, x, y and alpha. If you need to set display properties on native objects, apply them to the objects directly.

To remove a native textbox from the display, use object:removeSelf().

Web Popups

Web Popups let you open a local or remote Web page within a your app. The contents of the Web Popup are specified by a URL. For an example, see the WebOverlay sample. Note: Web popups are only available on device builds.

To create a Web Popup use the method native.showWebPopup( ). Example:

1

native.showWebPopup( "http://www.anscamobile.com" )

This will create an overlay displaying your Web page, filling the entire screen. By default, the url is assumed to be an absolute url to a remote server.

Optionally, you can create a web popup at any x,y position and with any width and height, instead of occupying the entire screen. Example:

1

native.showWebPopup( 10, 10, 300, 300, "http://www.anscamobile.com" )

Web popup scaling

To ensure that HTML content scales appropriately, add the following to your HTML document's <head> element:

1

<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:

1
2
3
4
5

<style type="text/css">
html {
        -webkit-text-size-adjust: none;
}
</style>

Web Popup Options

There is an optional sixth parameter, options, that allows you to customize certain features. The parameter must be passed as a table. For example:

1

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

You may assign the following properties in your options table:

options.baseUrl determines whether url is interpreted as a relative or absolute url. The default (nil) implies that the url is absolute. To load a local file, 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 controls whether the popup has a an opaque background or not. It not specified, the background will be opaque.

options.urlRequest designates a function that will intercept all urlRequest events coming from the web pop-up. 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:

1
2
3

<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.

Removing the Web Popup

To remove or dismiss the web popup use the method native.cancelWebPopup(). Returns true if web popup was displaying prior to the call; false otherwise.

Handling Web Popup Events

If you supply an event handler to the urlRequest property in your options table, the Web Popup will pass events to your handler when the user clicks links in the Web page. It will pass the following events:

1
2
3
4

event.errorCode
event.errorMessage
event.name
event.url

To ensure that your event handler is only triggered once for each click, check for errors before executing your code. Otherwise, your handler may be triggered for the initial click and for any errors passed as well. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

function listener( event )
  --if no errors, then execute my code
  if event.errorMessage == nil then
          myOnClickHandler( event.url )
  end
  return true
end
 
local options = { 
  baseUrl = system.ResourceDirectory, 
  hasBackground = false, 
  urlRequest = listener 
}
 
native.showWebPopup( "test.html", options )