Packageflash.media
Classpublic final class StageWebView
InheritanceStageWebView Inheritance EventDispatcher Inheritance Object

Language version: ActionScript 3.0
Runtime version: AIR 2.5

The StageWebView class displays HTML content in a stage view port.

The StageWebView class provides a simple means to display HTML content on devices where the HTMLLoader class is not supported. The class provides no interaction between ActionScript and the HTML content except through the methods and properties of the StageWebView class itself. There is, for example, no way to pass values or call functions between ActionScript and JavaScript.

AIR profile support: This feature is supported on all desktop operating systems and mobile devices, but is not supported on AIR for TV devices. You can test for support at run time using the StageWebView.isSupported property. See AIR Profile Support for more information regarding API support across multiple profiles.

On devices in the mobile and extended mobile profiles, the StageWebView class uses the system web control provided by the device operating system. Thus, the available features and rendering appearance may vary from device to device.

On android, inline HTML5 video is supported only if <application android:hardwareAccelerated="true"/> is included in the application descriptor.

On desktop computers (in the desktop and extended desktop profiles), the StageWebView class uses the system web control provided by the Flash Player plugin. The features available and rendering appearance are the same as those of the HTMLLoader class (without the close integration and script bridging between ActionScript and JavaScript provided by an HTMLLoader instance). Since the HTMLLoader class uses the internal AIR WebKit engine, concurrent use of StageWebView and HTMLLoader instances is strongly discouraged as it has undefined behavior and can possibly terminate the application.

The StageWebView class is NOT a display object and cannot be added to the Flash display list. Instead you display a StageWebView object by attaching it directly to a stage using the stage property. The StageWebView instance attached to a stage is displayed on top of any Flash display objects. You control the size and position of the rendering area with the viewPort property. There is no way to control the depth ordering of different StageWebView objects. Overlapping two instances is not recommended.

When the content within the StageWebView object has focus, the StageWebView object has the first opportunity to handle keyboard input. The stage to which the StageWebView object is attached dispatches any keyboard input that is not handled. The normal event capture/bubble cycle does not apply here since the StageWebView instance is not part of the display list.

In Android 3.0+, an application must enable hardware acceleration in the Android manifestAdditions element of the AIR application descriptor to display plug-in content in a StageWebView object.

View the examples.

See also

Enabling Flash Player and other plug-ins in a StageWebView object
HTMLLoader class


Public Properties
 PropertyDefined by
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  isHistoryBackEnabled : Boolean
[read-only] Reports whether there is a previous page in the browsing history.
StageWebView
  isHistoryForwardEnabled : Boolean
[read-only] Reports whether there is a next page in the browsing history.
StageWebView
  isSupported : Boolean
[static][read-only] Reports whether the StageWebView class is supported on the current device.
StageWebView
  location : String
[read-only] The URL of the current location.
StageWebView
  mediaPlaybackRequiresUserAction : Boolean
Set whether User is required to perform gesture to play media content.
StageWebView
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  stage : Stage
The stage on which this StageWebView object is displayed.
StageWebView
  title : String
[read-only] The HTML title value.
StageWebView
  viewPort : Rectangle
The area on the stage in which the StageWebView object is displayed.
StageWebView
Public Methods
 MethodDefined by
  
StageWebView(... configuration)
Creates a StageWebView object.
StageWebView
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
  
assignFocus(direction:String = "none"):void
Assigns focus to the content within this StageWebView object.
StageWebView
 Inherited
Dispatches an event into the event flow.
EventDispatcher
  
Disposes of this StageWebView object.
StageWebView
  
Draws the StageWebView's view port to a bitmap or image.
StageWebView
  
Draws the StageWebView's view port to a bitmap.
StageWebView
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
  
Navigates to the previous page in the browsing history.
StageWebView
  
Navigates to the next page in the browsing history.
StageWebView
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
loadString(text:String, mimeType:String = "text/html"):void
Loads and displays the specified HTML string.
StageWebView
  
Loads the page at the specified URL.
StageWebView
  
Posts a message to the HTML content within the StageWebView host.
StageWebView
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
Reloads the current page.
StageWebView
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
  
Halts the current load operation.
StageWebView
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 EventSummaryDefined by
 Inherited [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
   Signals that the last load operation requested by loadString() or loadURL() method has completed.StageWebView
 Inherited [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
   Signals that an error has occurred.StageWebView
   Dispatched when this StageWebView object receives focus.StageWebView
   Dispatched when the StageWebView relinquishes focus.StageWebView
   Signals that the location property of the StageWebView object has changed.StageWebView
   Signals that the location property of the StageWebView object is about to change.StageWebView
   Dispatched when the StageWebView rendering to a target has completed.StageWebView
   Dispatched when the HTML contents within the StageWebView posts a message out to the client application.StageWebView
Property detail
isHistoryBackEnabledproperty
isHistoryBackEnabled:Boolean  [read-only]

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Reports whether there is a previous page in the browsing history.

Implementation
    public function get isHistoryBackEnabled():Boolean
isHistoryForwardEnabledproperty 
isHistoryForwardEnabled:Boolean  [read-only]

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Reports whether there is a next page in the browsing history.

Implementation
    public function get isHistoryForwardEnabled():Boolean
isSupportedproperty 
isSupported:Boolean  [read-only]

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Reports whether the StageWebView class is supported on the current device.

Implementation
    public static function get isSupported():Boolean
locationproperty 
location:String  [read-only]

Language version: ActionScript 3.0
Runtime version: AIR 2.5

The URL of the current location.

Implementation
    public function get location():String
mediaPlaybackRequiresUserActionproperty 
mediaPlaybackRequiresUserAction:Boolean  [read-write]

Language version: ActionScript 3.0
Runtime version: AIR 3.3

Set whether User is required to perform gesture to play media content. For iOS, this property will not be honored, and media autoPlay can only be achieved through the constructor StageWebView(). Default value is True.

Implementation
    public function get mediaPlaybackRequiresUserAction():Boolean
    public function set mediaPlaybackRequiresUserAction(value:Boolean):void
stageproperty 
stage:Stage  [read-write]

Language version: ActionScript 3.0
Runtime version: AIR 2.5

The stage on which this StageWebView object is displayed.

Set stage to null to hide this StageWebView object.

Implementation
    public function get stage():Stage
    public function set stage(value:Stage):void
titleproperty 
title:String  [read-only]

Language version: ActionScript 3.0
Runtime version: AIR 2.5

The HTML title value.

Implementation
    public function get title():String
viewPortproperty 
viewPort:Rectangle  [read-write]

Language version: ActionScript 3.0
Runtime version: AIR 2.5

The area on the stage in which the StageWebView object is displayed.

Implementation
    public function get viewPort():Rectangle
    public function set viewPort(value:Rectangle):void

Throws
RangeError — The Rectangle value is not valid.
Constructor detail
StageWebView()constructor
public function StageWebView(... configuration)

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Creates a StageWebView object.

The object is invisible until it is attached to a stage and until the viewPort is set.

Note: The StageWebView is always now provided by an operating system component, AIR does not ship with an embedded WebKit build now. The earlier useNative argument is ignored.

The arguments for this constructor have changed in AIR 51.0, previously there had been two optional boolean arguments (useNative defaulting to false, and mediaPlaybackRequiresUserAction defaulting to true). These have been replaced with the ...rest argument which means the constructor can take any number of arguments. If there are zero arguments, or one or two boolean arguments, then these would be treated in the same way as previously i.e. as if these are the earlier useNative and mediaPlaybackRequiresUserAction with their default values). However, if a single Object is passed in, it will be treated like a configuration object, and its properties will be enumerated and evaluated appropriately based on the support available within the AIR runtime.

For example, the StageWebView object could be created with:

var swv : StageWebView = new StageWebView( { userAgent:"my-app-ua-string", mediaPlaybackRequiresUserAction:false } );

Note that some options may be platform-specific and could depend upon the available components from the operating system.

Parameters
... configuration
Method detail
assignFocus()method
public function assignFocus(direction:String = "none"):void

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Assigns focus to the content within this StageWebView object.

Direction values are defined in FocusDirection class and include: "bottom", "none", and "top".

Parameters
direction:String (default = "none") — specifies whether the first or last focusable object in the displayed content should receive focus.

See also

dispose()method 
public function dispose():void

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Disposes of this StageWebView object.

Calling dispose() is optional. If you do not maintain a reference to this StageWebView instance it will be eligible for garbage collection. Calling dispose() can make garbage collection occur sooner, or at a more convenient time.

drawViewPortAsync()method 
public function drawViewPortAsync(target:Object):void

Language version: ActionScript 3.0
Runtime version: AIR 33.1

Draws the StageWebView's view port to a bitmap or image.

This is an asynchronous form of the drawViewPortToBitmapData method, which is requred for the new Edge-based StageWebView. Using this you can pass in either a BitmapData object in order to draw the web contents into a bitmap, or a PNGEncoderOptions or JPEGEncoderOptions object in order to draw the web contents into a new ByteArray object.

When the functionality is complete, the StageWebView object will dispatch a WebViewDrawEvent object that contains the requested image data.

Parameters
target:Object — The BitmapData object on which to draw the visible portion of the StageWebView's view port, or one of the PNG/JPEG EncorderOptions objects to specify a ByteArray should be created for the image.

Throws
ArgumentError — The bitmap's width or height is different from view port's width or height, or the provided object is not one of BitmapData/PNGEncoderOptions/JPEGEncoderOptions.
drawViewPortToBitmapData()method 
public function drawViewPortToBitmapData(bitmap:BitmapData):void

Language version: ActionScript 3.0
Runtime version: AIR 2.6

Draws the StageWebView's view port to a bitmap.

Capture the bitmap and set the stage to null for displaying the content above the StageWebView object.

Note: The behavior of this method is not guaranteed for pages that contain plugin content (such as embedded PDF and SWF files).

Parameters
bitmap:BitmapData — The BitmapData object on which to draw the visible portion of the StageWebView's view port.

Throws
ArgumentError — The bitmap's width or height is different from view port's width or height.
 
Error — The bitmap is null.

Example
The following example displays two labels: google and facebook. Clicking on the label captures the corresponding web page and displays it as a snapshot on the stage.

package
{
    import flash.display.Bitmap;
	import flash.display.BitmapData;
	import flash.display.Sprite;
	import flash.events.*;
	import flash.geom.Rectangle;
	import flash.media.StageWebView;
	import flash.net.*;
	import flash.text.TextField;
	
	public class stagewebview1 extends Sprite
	{	
		public var webView:StageWebView = new StageWebView();
		public var textGoogle:TextField=new TextField();
		public var textFacebook:TextField=new TextField();
	
		public function stagewebview()
		
		{
			textGoogle.htmlText="<b>Google</b>";
			textGoogle.x=300;
			textGoogle.y=-80;		
			addChild(textGoogle);
			textFacebook.htmlText="<b>Facebook</b>";
			textFacebook.x=0;
			textFacebook.y=-80;		
			addChild(textFacebook);
			textGoogle.addEventListener(MouseEvent.CLICK,goGoogle);
			textFacebook.addEventListener(MouseEvent.CLICK,goFaceBook);
			webView.stage = this.stage;
			webView.viewPort = new Rectangle(0, 0, stage.stageWidth, stage.stageHeight);

		}	
	
		public function goGoogle(e:Event):void
		
		{
			webView.loadURL("http://www.google.com");
			webView.stage = null;
			webView.addEventListener(Event.COMPLETE,handleLoad);
		}
	
		public function goFaceBook(e:Event):void
		{
			webView.loadURL("http://www.facebook.com");
			webView.stage = null;
			webView.addEventListener(Event.COMPLETE,handleLoad);
		}
	
		public function handleLoad(e:Event):void
		{
			var bitmapData:BitmapData = new BitmapData(webView.viewPort.width, webView.viewPort.height);
			webView.drawViewPortToBitmapData(bitmapData);
			var webViewBitmap:Bitmap=new Bitmap(bitmapData);
			addChild(webViewBitmap);
		}
	}
}

historyBack()method 
public function historyBack():void

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Navigates to the previous page in the browsing history.

historyForward()method 
public function historyForward():void

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Navigates to the next page in the browsing history.

loadString()method 
public function loadString(text:String, mimeType:String = "text/html"):void

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Loads and displays the specified HTML string.

When the loadString() method is used, the location is reported as "about:blank." Only standard URI schemes can be used in URLs within the HTML string. The AIR URI schemes, "app:" and "app-storage:" are not allowed.

The HTML content cannot load local resources, such as image files. XMLHttpRequests are not allowed.

Only the "text/html" and "application/xhtml+xml" MIME types are supported.

Parameters
text:String — the string of HTML or XHTML content to display.
 
mimeType:String (default = "text/html") — The MIME type of the content, either "text/html" or "application/xhtml+xml".

Example
The following example sets up a StageWebView object to fill the stage. The example loads an HTML page with the loadString() method.

var webView:StageWebView = new StageWebView();
webView.stage = this.stage;
webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight );

var htmlString:String = "<!DOCTYPE HTML>" +
    					"<html>" +
							"<body>" +
								"<h1>Example</h1>" +
								"<p>King Phillip cut open five green snakes.</p>" +
							"</body>" +
						"</html>";

webView.loadString( htmlString, "text/html" );

loadURL()method 
public function loadURL(url:String):void

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Loads the page at the specified URL.

The URL can use the following URI schemes: http:, https:, file:, data:, and javascript:. Content loaded with the file: scheme can load other local resources.

Parameters
url:String

Example
The following example sets up a StageWebView object to fill the stage. The example loads a web site with the loadURL() method.

Note: On Android, you must specify the INTERNET permission in your AIR application descriptor to load remote URLs.


var webView:StageWebView = new StageWebView();
webView.stage = this.stage;
webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight );

webView.loadURL( "http://www.example.com" );

postMessage()method 
public function postMessage(message:String):void

Language version: ActionScript 3.0
Runtime version: AIR 51.0

Posts a message to the HTML content within the StageWebView host. The message is provided as a string but may be stringified JSON. This is asynchronous, the message will be posted to the container but if a response is required, it would need to be seperately posted back by the JavaScript code, and can be obtained by listening for the webViewMessage event.

Parameters
message:String
reload()method 
public function reload():void

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Reloads the current page.

stop()method 
public function stop():void

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Halts the current load operation.

Event detail
completeevent 
Event object type: flash.events.Event
Event.type property = flash.events.Event.COMPLETE

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Signals that the last load operation requested by loadString() or loadURL() method has completed.

The Event.COMPLETE constant defines the value of the type property of a complete event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe network object that has completed loading.
errorevent  
Event object type: flash.events.ErrorEvent

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Signals that an error has occurred.

focusInevent  
Event object type: flash.events.FocusEvent

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Dispatched when this StageWebView object receives focus.

focusOutevent  
Event object type: flash.events.FocusEvent

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Dispatched when the StageWebView relinquishes focus.

locationChangeevent  
Event object type: flash.events.LocationChangeEvent

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Signals that the location property of the StageWebView object has changed.

The event cannot be canceled.

locationChangingevent  
Event object type: flash.events.LocationChangeEvent

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Signals that the location property of the StageWebView object is about to change.

A locationChanging event is only dispatched when the location change is initiated through HTML content or code running inside the StageWebView object,such as when a user clicks a link. By default, the new location is displayed in this StageWebView object. You can call the preventDefault() method of the event object to cancel the default behavior. For example, you could use the flash.net.navigateToURL() function to open the page in the system browser based on the location property of the event object

A locationChanging event is not dispatched when you change the location with the following methods:

webViewDrawCompleteevent  
Event object type: flash.events.WebViewDrawEvent

Language version: ActionScript 3.0
Runtime version: AIR 33.1

Dispatched when the StageWebView rendering to a target has completed.

webViewMessageevent  
Event object type: flash.events.DataEvent

Language version: ActionScript 3.0
Runtime version: AIR 51.0

Dispatched when the HTML contents within the StageWebView posts a message out to the client application.

Examples
examples\StageWebViewExample.1
The following example sets up a StageWebView object to fill the stage. The example loads a web site with the loadURL() method and uses the device Back and Search softkeys for history navigation.
package  {
    import flash.display.MovieClip;
	import flash.media.StageWebView;
	import flash.geom.Rectangle;
	import flash.events.KeyboardEvent;
	import flash.ui.Keyboard;
	import flash.desktop.NativeApplication;
                
	public class StageWebViewExample extends MovieClip{

		private var webView:StageWebView = new StageWebView();
                                
		public function StageWebViewExample() 
		{
			webView.stage = this.stage;
			webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight );
			webView.loadURL( "http://www.example.com" );
                                                
			stage.addEventListener( KeyboardEvent.KEY_DOWN, onKey );
		}
                                
		private function onKey( event:KeyboardEvent ):void
		{
			if( event.keyCode == Keyboard.BACK && webView.isHistoryBackEnabled )
			{
				trace("Back.");
				webView.historyBack();
				event.preventDefault();
			}

			if( event.keyCode == Keyboard.SEARCH && webView.isHistoryForwardEnabled )
			{
				trace("Forward.");
				webView.historyForward();
			}
		}
	}
}