flash.media

# StageWebView - AS3

Package | flash.media
Class | public final class StageWebView
Inheritance | StageWebView EventDispatcher 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 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

More examples

Displaying HTML content in mobile apps

Learn more

About the HTML control
Mark Doherty: AIR on Android: TweetrApp
Mark Doherty: OAuth Support
Enabling Flash Player and other plug-ins in a StageWebView object

Related API Elements

HTMLLoader class

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : 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
|  | 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
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | StageWebView(useNative:Boolean = false) Creates a StageWebView object. | StageWebView
|  | 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
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | dispose():void Disposes of this StageWebView object. | StageWebView
|  | drawViewPortToBitmapData(bitmap:BitmapData):void Draws the StageWebView's view port to a bitmap. | StageWebView
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | historyBack():void Navigates to the previous page in the browsing history. | StageWebView
|  | historyForward():void Navigates to the next page in the browsing history. | StageWebView
|  | isPrototypeOf(theClass:Object):Boolean 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
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | reload():void Reloads the current page. | StageWebView
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | stop():void Halts the current load operation. | StageWebView
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [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
|  | deactivate | [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
|  | locationChange | Signals that the location property of the StageWebView object has changed. | StageWebView
|  | locationChanging | 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`

### mediaPlaybackRequiresUserAction

property

`mediaPlaybackRequiresUserAction:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 21.0

Set whether User is required to perform gesture to play media content. Default value is True.

Implementation
`public function get mediaPlaybackRequiresUserAction():Boolean`
`public function set mediaPlaybackRequiresUserAction(value:Boolean):void`

### 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

FocusDirection

### 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.
Copy

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

    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.

Copy

    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:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The 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.
Examples How to use this example
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.
Copy

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

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00