分享

Corona Docs: guide > system > EnterpriseUI

 quasiceo 2014-01-18

Native UI Objects

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

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

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

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

Popup

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.

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

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.

2013 Corona Labs Inc. All Rights Reserved. (Last updated: 15-Jan-2014)


Help us help you! Give us feedback on this page:

    本站是提供个人知识管理的网络存储空间,所有内容均由用户发布,不代表本站观点。请注意甄别内容中的联系方式、诱导购买等信息,谨防诈骗。如发现有害或侵权内容,请点击一键举报。
    转藏 分享 献花(0

    0条评论

    发表

    请遵守用户 评论公约

    类似文章 更多