Native UI Objects

The native library provides access to platform-specific UI elements. This guide discusses some of the more common among these.

Notes

Text Input Field

Single-line text input fields are created using the native.newTextField() API. Please refer to the documentation for usage examples.

local textField = native.newTextField( centerX, centerY, 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.placeholder Provides a "hint" as to what the user should enter in the field.
textField:setReturnKey() Sets the return key of the keyboard.
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 Events

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.

Controlling Focus

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 )

Multi-Line Text Box

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( centerX, centerY, 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.placeholder Provides a "hint" as to what the user should enter in the text box.
textField:setReturnKey() Sets the return key of the keyboard.
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 Events

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.

Controlling Focus

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 )

Web View

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( centerX, centerY, 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).

Web View Events

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.

Video View

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( centerX, centerY, 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.

Alert

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] ] )

Alert Events

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.