The native library provides access to platform-specific UI elements. This guide discusses some of the more common among these.
Native objects may not appear/work consistently between different devices or even the Corona Simulator. You should always test on target devices.
Native objects are not part of the OpenGL canvas. They do not obey the Corona display hierarchy and they cannot be inserted into display groups. They can be manipulated using basic display object methods — setting their position, for example — but they always appear in front of normal display objects.
Single-line text input fields are created using the native.newTextField() API. Please refer to the documentation for usage examples.
local textField = native.newTextField( left, top, width, height [, listener] )The following properties/methods can be used to modify the appearance:
| Property/Method | Description |
|---|---|
textField.align | Alignment of the text in the input field, either "left", "center", or "right". |
textField.font | Font used for the input field. May be set to a font object returned by native.newFont(). |
textField.hasBackground | Controls whether the input field has an opaque background. Default is true (opaque). |
textField.inputType | The keyboard type for the input field. See the documentation for details. |
textField.isSecure | Controls whether text in the input field is obscured, i.e. for passwords. Default is false. |
textField:setTextColor( r,g,b,a ) | Sets the color of the text in the input field. |
textField.size | Sets the size of the text in the input field. |
textField.text | Sets the text contents of the input field. |
User input to a text field is monitored by the following event.phase values:
"began" — this is the "keyboard has appeared" event.
"ended" — this event occurs when the text field loses focus (user touches a different field or dismisses the keyboard).
"submitted" — this event is dispatched when the user presses the "return" key to finish editing.
"editing" — this event occurs when the user modifies text in the field. During this phase, several input properties are available.
Setting the focus on a specific text field can be accomplished as follows:
native.setKeyboardFocus( textField )This sets the keyboard focus on that field and, where appropriate, shows or hides the keyboard. To remove focus on a text field and dismiss (hide) the keyboard, pass nil to the function:
native.setKeyboardFocus( nil )The native.newTextBox() API creates a scrollable, multi-line text box for displaying text-based content. Text boxes can also be used for text input by setting the isEditable property to true. Please refer to the documentation for usage examples.
local textBox = native.newTextBox( left, top, width, height [,listener] )The following properties/methods can be used to modify the appearance and behavior:
| Property/Method | Description |
|---|---|
textBox.align | Alignment of the text in the text box, either "left", "center", or "right". |
textBox.font | Font used for the text box. May be set to a font object returned by native.newFont(). |
textBox.hasBackground | Controls whether the text box has an opaque background. Default is true (opaque). |
textBox.isEditable | Controls whether the text box is editable. Default is false. |
textBox:setTextColor( r,g,b,a ) | Sets the color of the text in the text box. |
textBox.size | Sets the size of the text in the text box. |
textBox.text | Sets the contents of the text box. |
User input to an editable text box is monitored by the following event.phase values:
"began" — this is the "keyboard has appeared" event.
"ended" — this event occurs when the text box loses focus (user touches a different field or dismisses the keyboard).
"editing" — this event occurs when the user modifies text in the box. During this phase, several input properties are available.
Setting the focus on a specific text box can be accomplished as follows:
native.setKeyboardFocus( textBox )This sets the keyboard focus on that box and, where appropriate, shows or hides the keyboard. To remove focus on a text box and dismiss (hide) the keyboard, pass nil to the function:
native.setKeyboardFocus( nil )The native.newWebView() API loads remote web content or local HTML in a web view container. The web view differs from the older web popup in that you can move it, rotate it (iOS only), and assign a physical body to it. Please refer to the documentation for notes and usage examples.
local webView = native.newWebView( left, top, width, height [,listener] )The following properties/methods can be used to control the appearance and behavior:
| Property/Method | Description |
|---|---|
webView:request( url ) | Loads a specific URL into the web view. See the documentation for details. |
webView:back() | Takes the web view back one step in its history. |
webView:forward() | Takes the web view forward one step in its history. |
webView:reload() | Reloads the current web view page. |
webView:stop() | Stops loading the current page (if loading). |
webView.canGoBack | Read-only property that is true if the web view can go back a page, false if not. |
webView.canGoForward | Read-only property that is true if the web view can go forward a page, false if not. |
webView.hasBackground | Controls whether the web view background is visible or not. Default is true (visible). |
Status of the web view is monitored by the following event values:
event.url — the absolute URL of the request.
event.type — the type of urlRequest event indicating the action associated with the request. See the documentation for details.
event.name — the urlRequest string.
event.errorCode — a platform-specific error code if a problem occurred in the URL request.
event.errorMessage — description of an error that occurred in the URL request. This property is only defined if an error occurs.
The native.newVideo() API displays a video object that can be moved and rotated. You can also add a physical body to it. This API supports local videos (in one of the system directories) or remote videos from a server. Please refer to the documentation for notes and usage examples.
This API is supported on iOS only. If you require video support on other platforms, use media.playVideo() instead.
local videoView = native.newVideo( left, top, width, height [,listener] )The following properties/methods can be used to control the video:
| Property/Method | Description |
|---|---|
videoView:load( path ) | Loads the specified video. |
videoView:play() | Plays the currently loaded video. |
videoView:pause() | Pauses the currently loaded video. |
videoView:seek( timeInSeconds ) | Jumps to a specified time in the current video (within its total range). |
videoView.currentTime | The current time position of the video in seconds (read-only). |
videoView.totalTime | The length of the current video in seconds (read-only). |
videoView.isMuted | Controls whether the video's audio channel is muted. |
The native.showPopup() API displays the operating system's default popup window for a specified service such as email, SMS, etc. It returns a boolean value indicating whether the request is successful or not. If it returns false, the popup is not available or the service is not available for the device.
local popup = native.showPopup( name, options )Please refer to the documentation for notes and usage examples since the options vary considerably for each popup type.
The native.showAlert() API displays a native popup alert box with one or more buttons. Program activity, including animation, will continue in the background, but all other user interactivity will be blocked until the user clicks a button or the alert is cancelled programmatically. Please refer to the documentation for notes and usage examples.
local alert = native.showAlert( title, message [, { buttonLabels } [, listener] ] )title — the title string displayed in the alert (required).
message — the message string displayed in the alert text (required).
buttonLabels — an optional table of strings, each of which will create a button with the corresponding label. If you provide this argument, include at least one button label 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 (5).
listener — the listener function (optional) that will be called when the user clicks a 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 properties:
event.action — this represents how the alert was dismissed. A value of "cancelled" indicates that native.cancelAlert() was called to close the alert, while "clicked" indicates the user clicked a button to close the alert.
event.index — the index of the button pressed. It corresponds to the index in the buttonLabels parameter.
2013 Corona Labs Inc. All Rights Reserved. (Last updated: 15-Jan-2014)
Help us help you! Give us feedback on this page:
联系客服
