ActionScript® 3.0 Reference for the Adobe® Flash® Platform
Home  |  Show Packages and Classes List |  Packages  |  Classes  |  What's New  |  Index  |  Appendixes
flash.media 

StageWebView  - AS3

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

Language Version: ActionScript 3.0
Runtime Versions: 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 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

More examples

Learn more

Related API Elements



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
      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(useNative:Boolean = false)
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
  
    dispose():void
Disposes of this StageWebView object.
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
  
    historyBack():void
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
  
    loadURL(url:String):void
Loads the page at the specified URL.
StageWebView
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
    reload():void
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
  
    stop():void
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
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
  
    complete
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
  
    error
Signals that an error has occurred.StageWebView
  
    focusIn
Dispatched when this StageWebView object receives focus.StageWebView
  
    focusOut
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
Property Detail
    

isHistoryBackEnabled

property
isHistoryBackEnabled:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

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



Implementation
    public function get isHistoryBackEnabled():Boolean
    

isHistoryForwardEnabled

property 
isHistoryForwardEnabled:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

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



Implementation
    public function get isHistoryForwardEnabled():Boolean
    

isSupported

property 
isSupported:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

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



Implementation
    public static function get isSupported():Boolean
    

location

property 
location:String  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

The URL of the current location.



Implementation
    public function get location():String
    

stage

property 
stage:Stage

Language Version: ActionScript 3.0
Runtime Versions: 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
    

title

property 
title:String  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

The HTML title value.



Implementation
    public function get title():String
    

viewPort

property 
viewPort:Rectangle

Language Version: ActionScript 3.0
Runtime Versions: 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(useNative:Boolean = false)

Language Version: ActionScript 3.0
Runtime Versions: 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: Although it is not prohibited, with some content, failures can occur when the same process uses both the embedded and the system WebKit, so it is recommended that all StageWebViews in a given application be constructed with the same value for useNative. In addition, as HTMLLoader depends on the embedded WebKit, applications using HTMLLoader should only construct StageWebViews with useNative set to false.

Parameters
useNative:Boolean (default = false) — When useNative is false, a version of WebKit embedded within AIR is used as the source of the StageWebView created. When useNative is true, then AIR will use the the system's default web engine. Mobile platforms only support using the system web engine, so useNative is ignored on mobile platforms.
Method Detail

    assignFocus

()method
public function assignFocus(direction:String = "none"):void

Language Version: ActionScript 3.0
Runtime Versions: 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.

Related API Elements

    dispose

()method 
public function dispose():void

Language Version: ActionScript 3.0
Runtime Versions: 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.

    drawViewPortToBitmapData

()method 
public function drawViewPortToBitmapData(bitmap:BitmapData):void

Language Version: ActionScript 3.0
Runtime Versions: 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  ( How to use this 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 Versions: AIR 2.5

Navigates to the previous page in the browsing history.

    historyForward

()method 
public function historyForward():void

Language Version: ActionScript 3.0
Runtime Versions: 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 Versions: 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  ( How to use this 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 Versions: 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  ( How to use this 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" );
                                                

    reload

()method 
public function reload():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

Reloads the current page.

    stop

()method 
public function stop():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

Halts the current load operation.

Event Detail
    

complete

Event
Event Object Type: flash.events.Event
property Event.type = flash.events.Event.COMPLETE

Language Version: ActionScript 3.0
Runtime Versions: 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.
    

error

Event  
Event Object Type: flash.events.ErrorEvent

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

Signals that an error has occurred.

    

focusIn

Event  
Event Object Type: flash.events.FocusEvent

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

Dispatched when this StageWebView object receives focus.

    

focusOut

Event  
Event Object Type: flash.events.FocusEvent

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

Dispatched when the StageWebView relinquishes focus.

    

locationChange

Event  
Event Object Type: flash.events.LocationChangeEvent
property LocationChangeEvent.type = flash.events.LocationChangeEvent.LOCATION_CHANGE

Language Version: ActionScript 3.0
Runtime Versions: AIR 2.5

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

The event cannot be canceled.

Dispatched after every location change.
    

locationChanging

Event  
Event Object Type: flash.events.LocationChangeEvent
property LocationChangeEvent.type = flash.events.LocationChangeEvent.LOCATION_CHANGING

Language Version: ActionScript 3.0
Runtime Versions: 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:

  • historyBack()
  • historyForward()
  • loadString()
  • loadURL()
  • reload()
The LOCATION_CHANGING constant defines the value of the type property LocationChangeEvent object dispatched before a change in page location.
StageWebViewExample.1.as

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();
            }
        }
    }
}