flash.html

# HTMLHost - AS3

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

More examples

Defining browser-like user interfaces for HTML content

Related API Elements

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

Related API Elements

HTMLLoader.htmlHost

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

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

    package
     {
         import flash.display.Sprite;

         public class SimpleHTMLBox extends Sprite
         {
             import flash.html.HTMLHost;
             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:

Copy

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

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