flash.html.HTMLHost - Adobe® Flex® 4 Language Reference (Flex 4)

Package	flash.html
Class	public class HTMLHost
Inheritance	HTMLHost Object

Runtime Versions:

AIR 1.0

An HTMLHost object defines behaviors of an HTMLLoader object for user interface elements that can be controlled by setting various properties or by calling various methods of the window object of the HTML page. These methods and properties are:

window.blur()
window.focus()
window.moveBy()
window.moveTo()
window.location
window.close()
window.open()
window.resizeBy()
window.resizeTo()
window.status
window.document.title

The methods in the HTMLHost class provide ways of handling changes in each of these window settings. To use this class, create a new class (a subclass) that extends the HTMLHost class and that overrides the methods for which you want to define behaviors. The methods of the HTMLHost class handle JavaScript properties and methods as follows:

JavaScript property or method	HTMLHost method
`window.blur()`	`windowBlur()`
`window.focus()`	`windowFocus`
`window.location`	`updateLocation`
`window.close()`	`windowClose`
`window.open()`	`createWindow`
`window.status`	`updateStatus`
`window.document.title`	`updateTitle`

To respond to changes in the window.moveBy(), window.moveTo(), window.resizeBy(), and window.resizeTo() methods, override the set windowRect() method in the subclass of HTMLHost.

Each HTMLHost object can be associated with at most one HTMLLoader object. Assigning an HTMLHost instance to the htmlHost property of the HTMLLoader object establishes this relationship. Assigning null to the htmlHost property of the HTMLLoader object or setting the HTMLHost object as the htmlHost property of another HTMLLoader object removes the HTMLHost from the first HTMLLoader object.

View the examples

See also

HTMLLoader
HTMLWindowCreateOptions

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
		htmlLoader : flash.html:HTMLLoader [read-only] The HTMLLoader object to which this HostControl object applies.	HTMLHost
		prototype : Object [static] A reference to the prototype object of a class or function object.	Object
		windowRect : Rectangle The property that is changed when JavaScript code in the HTMLLoader object calls the window.moveBy(), window.moveTo(), window.resizeBy(), or window.resizeTo() method.	HTMLHost

Public Methods

Hide Inherited Public Methods

Show Inherited Public Methods

	Method		Defined By
		HTMLHost(defaultBehaviors:Boolean = true) Creates an HTMLHost object.	HTMLHost
		createWindow(windowCreateOptions:flash.html:HTMLWindowCreateOptions):flash.html:HTMLLoader The function called when JavaScript code in the HTMLLoader object calls the window.open() method.	HTMLHost
		hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined.	Object
		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
		propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable.	Object
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		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
		updateLocation(locationURL:String):void The function called when JavaScript code in the HTMLLoader object sets the window.location property.	HTMLHost
		updateStatus(status:String):void The function called when JavaScript code in the HTMLLoader object sets the window.status property.	HTMLHost
		updateTitle(title:String):void The function called when JavaScript code in the HTMLLoader object sets the window.document.title property or when the title element changes, either via the DOM or because of a new page load.	HTMLHost
		valueOf():Object Returns the primitive value of the specified object.	Object
		windowBlur():void The function called when JavaScript code in the HTMLLoader object calls the window.blur() method.	HTMLHost
		windowClose():void The function called when JavaScript code in the HTMLLoader object calls the window.close() method.	HTMLHost
		windowFocus():void The function called when JavaScript code in the HTMLLoader object calls the window.focus() method.	HTMLHost

Property Detail

htmlLoader

property

htmlLoader:flash.html:HTMLLoader [read-only]

Runtime Versions:

AIR 1.0

The HTMLLoader object to which this HostControl object applies. The htmlHost property of that HTMLLoader object is set to this HostControl object.

Implementation
public function get htmlLoader():flash.html:HTMLLoader

windowRect

property

windowRect:Rectangle

Runtime Versions:

AIR 1.0

The property that is changed when JavaScript code in the HTMLLoader object calls the window.moveBy(), window.moveTo(), window.resizeBy(), or window.resizeTo() method.

In the subclass of HTMLHost, override the set windowRect() method to handle the new window bounds, as desired.

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

Constructor Detail

HTMLHost

()

Constructor

public function HTMLHost(defaultBehaviors:Boolean = true)

Runtime Versions:

AIR 1.0

Creates an HTMLHost object.

Parameters

defaultBehaviors:Boolean (default = true) — Indicates wether root-content behaviors should be provided by default.

Method Detail

createWindow

()

method

public function createWindow(windowCreateOptions:flash.html:HTMLWindowCreateOptions):flash.html:HTMLLoader

Runtime Versions:

AIR 1.0

The function called when JavaScript code in the HTMLLoader object calls the window.open() method.

By default, a JavaScript call to window.open() in the HTML page of an HTMLLoader does not open an new NativeWindow object in the runtime. You can open a new NativeWindow object in the runtime by creating a new NativeWindow object in the createWindow method override in the subclass of the HTMLHost class.

Parameters

windowCreateOptions:flash.html:HTMLWindowCreateOptions — An object containing properties in the string passed as the features parameter of the call to window.open().

Returns

flash.html:HTMLLoader — An HTMLLoader object that contains the new HTML page. Typically, you create a new HTMLLoader object in this method, add it to the stage of a new NativeWindow object, and then return it.

updateLocation

()

method

public function updateLocation(locationURL:String):void

Runtime Versions:

AIR 1.0

The function called when JavaScript code in the HTMLLoader object sets the window.location property.

Parameters

locationURL:String — The value to which the location property of the window property of the HTMLLoader object is set.

updateStatus

()

method

public function updateStatus(status:String):void

Runtime Versions:

AIR 1.0

The function called when JavaScript code in the HTMLLoader object sets the window.status property.

Parameters

status:String — The value to which the status property of the window property of the HTMLLoader object is set.

updateTitle

()

method

public function updateTitle(title:String):void

Runtime Versions:

AIR 1.0

The function called when JavaScript code in the HTMLLoader object sets the window.document.title property or when the title element changes, either via the DOM or because of a new page load.

Parameters

title:String — The value to which the window.document.title property of the HTMLLoader object is set.

windowBlur

()

method

public function windowBlur():void

Runtime Versions:

AIR 1.0

The function called when JavaScript code in the HTMLLoader object calls the window.blur() method.

windowClose

()

method

public function windowClose():void

Runtime Versions:

AIR 1.0

The function called when JavaScript code in the HTMLLoader object calls the window.close() method.

By default, a JavaScript call to window.close() in the HTML page of an HTMLLoader object closes the windows containing the HTMLLoader object.

windowFocus

()

method

public function windowFocus():void

Runtime Versions:

AIR 1.0

The function called when JavaScript code in the HTMLLoader object calls the window.focus() method.

Examples How to use this example

HTMLHost.1.as

The following code defines CustomHost, a subclass of HTMLHost. Methods of the CustomHost class override the inherited methods in the HTMLHost class to define actions taken when JavaScript code in the HTMLLoader page sets various properties or calls various methods of the window object:

package
{
    import flash.html.HTMLHost;
    import flash.html.HTMLLoader;
    import flash.display.NativeWindow;
    import flash.display.NativeWindowInitOptions;
    import flash.display.StageScaleMode;
    import flash.geom.Rectangle;
    import flash.text.TextField;

    public class CustomHost extends HTMLHost
    {
        import flash.html.*;
        public var statusField:TextField;
        public function CustomHost(defaultBehaviors:Boolean=true)
        {
            super(defaultBehaviors);
        }
        override public function windowClose():void
        {
            htmlLoader.stage.window.close();
        }
        override public function createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader
        {
            var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions();
            var window:NativeWindow = new NativeWindow(initOptions);
            window.visible = true;
            var htmlLoader2:HTMLLoader = new HTMLLoader();
            htmlLoader2.width = window.width;
            htmlLoader2.height = window.height;
            window.stage.scaleMode = StageScaleMode.NO_SCALE;
            window.stage.addChild(htmlLoader2);
            return htmlLoader2;
        }
        override public function updateLocation(locationURL:String):void
        {
            trace(locationURL);
        }        
        override public function set windowRect(value:Rectangle):void
        {
            htmlLoader.stage.nativeWindow.bounds = value;
        }
        override public function updateStatus(status:String):void
        {
            statusField.text = status;
        }        
        override public function updateTitle(title:String):void
        {
            htmlLoader.stage.nativeWindow.title = title + "- Example Application";
        }
        override public function windowBlur():void
        {
            htmlLoader.alpha = 0.5;
        }
        override public function windowFocus():void
        {
            htmlLoader.alpha = 1;
        }
    }
}

Create the following class, which adds an HTMLLoader object to the stage, as well as a TextField object named statusBar. The HTMLLoader object defines a CustomHost object as its htmlHost property:

package
 {
     import flash.display.Sprite;
 
     public class SimpleHTMLBox extends Sprite
     {
         import mx.controls.HTML;
         import flash.html.HTMLLoader;
         import flash.text.TextField;
         import flash.net.URLRequest;
         import CustomHost;
         private var host:CustomHost;
         private var statusField:TextField;
         private var html:HTMLLoader;
         
         public function SimpleHTMLBox()
         {
             html = new HTMLLoader();
             var url:String = "Test.html";
             var urlReq:URLRequest = new URLRequest(url); 
             html.load(urlReq);
             
             host = new CustomHost();
             html.htmlHost = host;
             statusField = new TextField();
             host.statusField = statusField;
             
             configureUI();
         }
         private function configureUI():void
         {
             html.width = 400;
             html.height = 200;
             statusField.width = 400;
             statusField.height = 24;
             statusField.border = true;
             statusField.y = 200;
             
             addChild(html);
             addChild(statusField);                
         }
         
     }
 }

Build an AIR application that adds an object defined by this class to the main window's stage.

Create an HTML page named Test.html in the application resources directory (the directory that contains the application descriptor file), and add the following content to it:

<html>
     <head>
         <title>Test</title>
     </head>
     <body>
         <a href="#" onclick="window.open('Test.html')">window.open('Test.html')</a>
         <br/><a href="#" onclick="window.document.location = 'www.adobe.com'">window.document.location = 'www.adobe.com'</a>
         <br/><a href="#" onclick="window.moveBy(6, 12)">moveBy(6, 12)</a>
         <br/><a href="#" onclick="window.close()">window.close()</a>
         <br/><a href="#" onclick="window.blur()">window.blur()</a>
         <br/><a href="#" onclick="window.focus()">window.focus()</a>
         <br/><a href="#" onclick="window.status = new Date().toString()">window.status = new Date().toString()</a>
     </body>
 </html>

When you test the application, the CustomHost class handles the user-interface-related JavaScript settings in the HTML page.