# Mojo.Widget.WebView

## Namespace Detail

### Overview

To embed a contained web object, declare and instantiate a WebView widget. You can bound the widget within your declaration to get a scrolling view, or allow it to take over an entire scene at your discretion. You can use it to render local markup or to load an external URL; as long as you can define the source as a URL, WebView can be applied.

### Declaration

>     <div x-mojo-element="WebView" id="WebId" class="WebClass" name="WebName"></div>

Properties | Required | Value | Description
--- | --- | --- | ---
x-mojo-element | Required | WebView | Declares the widget as type 'WebView'.
id | Required | Any String | Identifies the widget element for use when instantiating or rendering.
class | Optional | Any String | Provide your own unique class and override the framework's styles.
name | Optional | Any String | Adds a unique name to the WebView widget; generally used in templates.

### Events

>     Mojo.Event.listen(this.controller.get("WebId"),
>       Mojo.Event.webViewLoadProgress, this.handleUpdate);

Event Type | Value | Event Handling
--- | --- | ---
Mojo.Event.webViewLoadStarted |  | Indicates that the WebView widget has started loading the content.
Mojo.Event.webViewLoadProgress | progress | Indicates that some progress has been made in loading content and returns the amount in progress. Note: this will show 100% even in the case of a failed page load.
Mojo.Event.webViewLoadStopped |  | Indicates that the page has finished loading. Note: "finished loading" is a tricky concept in AJAX web pages, so be careful how you use this event.
Mojo.Event.webViewLoadFailed | errorCode, message | Indicates that the content failed to load and supplies an error code (errorCode) and localized message (message).
Mojo.Event.webViewDownloadFinished | url, mimeType, tmpFilePath | File download completed.
Mojo.Event.webViewLinkClicked | url | The user tapped a link.
Mojo.Event.webViewTitleUrlChanged | title, url, canGoBack, canGoForward |
Mojo.Event.webViewTitleChanged | title |
Mojo.Event.webViewUrlChanged | url, canGoBack, canGoForward |
Mojo.Event.webViewCreatePage | pageIdentifier |
Mojo.Event.webViewTapRejected |  |
Mojo.Event.webViewScrollAndScaleChanged |  |
Mojo.Event.webViewEditorFocused | focused |
Mojo.Event.webViewUpdateHistory | url, reload |
Mojo.Event.webViewSetMainDocumentError | domain, errorCode, failingURL, message |
Mojo.Event.webViewServerConnect |  |
Mojo.Event.webViewServerDisconnect |  |
Mojo.Event.webViewResourceHandoff |  |
Mojo.Event.webViewFirstPaintComplete |  |
Mojo.Event.webViewUrlRedirect | url, appId |
Mojo.Event.webViewModifierTap | up, linkInfo |
Mojo.Event.webViewMimeNotSupported | url, mimeType | Indicates that the BrowserServer cannot handle a given URL.
Mojo.Event.webViewMimeHandoff | url, mimeType | Indicates that the BrowserServer cannot (or isn't supposed to) handle a mime type.
Mojo.Event.webViewPluginSpotlightStart |  |
Mojo.Event.webViewPluginSpotlightEnd |  |

### Instantiation

>     this.controller.setupWidget("WebId",
>       this.attributes = {
>           url: 'http://www.palm.com',
>           minFontSize: 18,
>           virtualpagewidth: 20,
>           virtualpageheight: 10
>       },
>       this.model = {
>       }
>     );

### Attribute Properties

Attribute Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
virtualpageheight | Integer | Optional | none | DEPRECATED The browser's virtual page height.
virtualpagewidth | Integer | Optional | none | DEPRECATED The browser's virtual page width.
url | String | Required | none | The initial URL to display.
pageIdentifier | String | Optional | none | The BrowserServer page identifier. This is used when the BrowserServer instructs an application to open a new page.
minFontSize | Integer | Optional | none | The minimum font size that the browser will display.
topMargin | Integer | Optional | none | The margin above the WebView that is scrolled off the screen when a new page is loaded.
cacheAdapter | Boolean | Optional | undefined | If true, cache this adapter; if false, do not. If undefined, use the browser-adapter default. Default is undefined.
interrogateClicks | Boolean | Optional | false | If the host application wants to be called for every hyperlink click via Mojo.Event.webViewLinkClicked event.
showClickedLink | Boolean | Optional | true | Styles a clicked link with grey background and border.

Note that virtualpageheight and virtualpagewidth attributes are deprecated. The supported method for controlling the size of content within a WebView is to use a viewport meta tag in the target HTML file. See the article on Developing Web Content for the Palm webOS Platform for more information.

### Model Properties

The WebView widget has no model properties.

### Methods

Method | Arguments | Description
--- | --- | ---
setTopMargin | Integer | Sets the top margin (in pixels).
clearCache | None | Clears browser cache. Will clear the cache for all open pages.
clearCookies | None | Clears browser cookies. Will clear cookies for all open pages.
deleteImage | String {fname} | Deletes the image file specified by the argument.
generateIconFromFile | String {inFilName}, String {outFileName}, Number {left}, Number {top}, Number {right}, Number {bottom} | Generates a 64x64 pixel icon from a portion of an input file. The output icon will be given a drop shadow and sheen consistent with other launcher icons.
goBack | None | Goes to the previous page in the user's browing history.
goForward | None | Goes to the next page in the user's browsing history.
openURL | String | Navigates to the specified url in the WebView.
reloadPage | None | Reloads the currently loaded page.
resizeImage | String {inFileName}, String {outFileName},Number {width}, Number {height} | Resizes the input file (PNG format only) to the specified width/height and writes the new image to the specified output file. Note that pathnames must be relative names (e.g., '/tmp/image.png') rather than URL-like (e.g., 'file://var/usr/applications/myApp/images/image.png').
getHistoryState | Function {successCb} | Retrieves the current history state from the Browser server. Will call successCb with results.
isEditing | Function {callback} | Determines if an editable field is in focus. Will call "callback" with boolean value.
insertStringAtCursor | String {string} | Inserts given string at cursor position of editable field in focus.
setBlockPopups | Boolean | Enables or disables popup blocking. This setting is on a per-WebView widget basis.
setAcceptCookies | Boolean | Enables or disables accepting cookies. This setting is on a per-WebView widget basis.
addUrlRedirect | String {urlRe}, Boolean {redirect},Object {userData}, Number {type} | Adds a URL redirect. When the browser server nagivates to a URL matching urlRe and redirect is true, then it will not navigate to that URL and will instead send a Mojo.Event.webViewUrlRedirect event.
addSystemRedirects | String {appId} | Adds all entries from the system's command/resource handlers table. The optional appId parameter can be used to omit all command/resource handler entries that match a given app ID.
saveViewToFile | String {fname}, Number {left}, Number {top}, Number {width}, Number {height} | Saves the current view to the specified file. The save region is optional. If omitted then the full view will be saved to fname.
setEnableJavaScript | Boolean | Enables or disables JavaScript. This setting is on a per-WebView widget basis.
stopLoad | None | Stops loading the current page.
focus | None | Focuses the WebView widget.
blur | None | Blurs the WebView widget.
clearHistory | None | Clears session history. This setting is on a per-WebView widget basis.
setShowClickedLink | Boolean | Enhances the showing of a clicked link. This setting is on a per-WebView widget basis.
copy | Function {callback} |
selectAll | None |
pluginSpotlightRemove | None | WebView gets out of the spotlight mode, in which gestures only go into the spotlight rect. Gestures modified by meta go into the adapter and not into the spotlight.
pluginSpotlightCreate | Number {left}, Number {top}, Number {right}, Number {bottom}, String {mode}, Boolean {notifyClient}) | Creates spotlight at given rectangle.

### Summary

- Mojo.Widget.WebView.DialogPromptAssistant
- Mojo.Widget.WebView.DialogUsernamePasswordAssistant

### Detail

#### Mojo.Widget.WebView.DialogPromptAssistant

Assistant for the prompt dialog.

#### Mojo.Widget.WebView.DialogUsernamePasswordAssistant

Assistant for the username/password dialog.