native.showWebPopup()

Type Function
Library native.*
Return value none
Revision Current Public Release (2014.2189)
Keywords web view, web popup, web overlay
See also native.newWebView()

Overview

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

Gotchas

Web popups are only available on the Mac OS X Simulator and device builds.

Only one Web popup object can be displayed at a time. For multiple web overlays, see native.newWebView().

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

Web popup objects, like other native objects, don't work in groups and are always displayed on top of regular display objects (images, text, etc.).

On Android, if this popup is displaying web pages from the Internet, then you must add an Internet permission to your build.settings file. This permission is unnecessary if the popup will only being displaying local HTML files that do not access the Internet.

settings =
{
    android =
    {
        usesPermissions =
        {
            "android.permission.INTERNET",
        },
    },
}

Syntax

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

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

x, y, width, height (optional)

Numbers. If specified, these parameters control the position and dimensions of the popup.

options (optional)

Table. Optional table containing additional parameters for the popup. See Format for options below.

Format for options

This is an optional table you can pass containing additional options for the web popup.

local options =
{
    baseUrl = system.ResourceDirectory, -- default: nil
    hasBackground = false,  -- default: true
    autoCancel = false,  -- default: true (android)
    urlRequest = listener_function,  -- default: nil
}
baseUrl (optional)

String or Constant. Determines whether the url parameter to native.showWebPopup() is interpreted as a relative or absolute url.

  • By default, nil means 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.
hasBackground (optional)

Boolean. Controls whether the popup has a an opaque background or not. If not specified, the background will be opaque (true).

autoCancel (optional)

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

urlRequest (optional)

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

Example

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 )