Packageflash.external
Classpublic dynamic class HostObject
InheritanceHostObject Inheritance EventDispatcher Inheritance Object

The HostObject is the base class of all host objects. It can either be used directly, as it is a completely dynamic object, or via derived classes that implement known elements complete with type declarations; these implementations would call one of the protected methods below for direct access to host object elements.

HostObjects support enumeration as well as dynamic lookup. It is, therefore, possible to use HostObjects as such, without having to create ActionScript wrappers for each host object class.



Public Properties
 PropertyDefined by
  available : Boolean
[static][read-only] Indicates whether this player is in a container that offers a high-bandwidth interface.
HostObject
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  extensions : Array
[static][read-only] Retrieve a list of the package names of all registered object model extensions.
HostObject
  mainExtension : String
[static][read-only] Retrieve the fully qualified package name of the main object model extension.
HostObject
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
Public Methods
 MethodDefined by
  
__call(methName:String, args:Array):*
The universal method invoke method receives the property name and returns the result of the method call.
HostObject
  
__get(propName:String):*
The universal getter method receives the property name and returns whatever the property value is.
HostObject
  
__set(propName:String, value:*):void
The universal setter method stores the supplied value into the given property.
HostObject
 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
  
create(className:String, ... rest):HostObject
[static] Generic creation function for a new host object with a varying number of creation arguments.
HostObject
 Inherited
Dispatches an event into the event flow.
EventDispatcher
  
[static] Register this method as an event listener to have the host application process a Flex event.
HostObject
  
[static] Return the host object that is a class object for the given class name.
HostObject
  
[static] Return the fully qualified class name of the given value.
HostObject
  
[static] Return the host object that is a root object for the given extension.
HostObject
 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
  
[static] Check for the availability of a certain object model extension.
HostObject
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
[static] Check whether this HostObject wrapper object still is connected to its host counterpart.
HostObject
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 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
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
  
Implement toString() by calling the host object's toString() method if available; if not, return [HostObject xxx], where xxx is the class name.
HostObject
  
Implement valueOf() by calling the host object's valueOf() method if available; if not, return this instance to indicate the absence of a primitive value.
HostObject
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Protected Methods
 MethodDefined by
  
The universal constructor method initizalizes a new instance of the current class.
HostObject
Events
 EventSummaryDefined by
 Inherited [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
 Inherited [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
Property detail
availableproperty
available:Boolean  [read-only]

Language version: ActionScript 3.0
Runtime version: 

Indicates whether this player is in a container that offers a high-bandwidth interface. If the high-bandwidth interface is available, this property is true; otherwise, it is false.

Implementation
    public static function get available():Boolean
extensionsproperty 
extensions:Array  [read-only]

Language version: ActionScript 3.0
Runtime version: 

Retrieve a list of the package names of all registered object model extensions. The first element of that list is the package name of the main extension, which is used to complete bare class names, if the host registered a main extension.

Implementation
    public static function get extensions():Array
mainExtensionproperty 
mainExtension:String  [read-only]

Language version: ActionScript 3.0
Runtime version: 

Retrieve the fully qualified package name of the main object model extension. This name be an empty string if the host did not register a main extension. Note that other components inside the host may choose to register their own object model extensions.

Implementation
    public static function get mainExtension():String
Method detail
__call()method
public function __call(methName:String, args:Array):*

Language version: ActionScript 3.0
Runtime version: 

The universal method invoke method receives the property name and returns the result of the method call. Derived classes use this method to implement their own methods. For ease of implementation, the arguments object can be used as argument to this method.

Note: This method is intended for use by SWC code only that implements wrapper classes for host objects.

Parameters
methName:String — the method name to invoke
 
args:Array — the arguments; use the arguments object

Returns
* — whatever the method call returns

Example

__construct()method 
protected function __construct(args:Array):void

Language version: ActionScript 3.0
Runtime version: 

The universal constructor method initizalizes a new instance of the current class. Use this method to implement host-side constructors for host wrapper classes.

Note: This method may throw if the host does not support the construction of the given class.

Note: This method is intended for use by SWC code only that implements wrapper classes for host objects.

Parameters
args:Array — the arguments; use the arguments object

Example

__get()method 
public function __get(propName:String):*

Language version: ActionScript 3.0
Runtime version: 

The universal getter method receives the property name and returns whatever the property value is. Derived classes use this method to implement property read acces.

Note: This method is intended for use by SWC code only that implements wrapper classes for host objects.

Parameters
propName:String — the property name

Returns
* — the property value

Example

__set()method 
public function __set(propName:String, value:*):void

Language version: ActionScript 3.0
Runtime version: 

The universal setter method stores the supplied value into the given property. Derived classes use this method to implement property write acces.

Note: This method is intended for use by SWC code only that implements wrapper classes for host objects.

Parameters
propName:String — the property name
 
value:* — the property value

Example

create()method 
public static function create(className:String, ... rest):HostObject

Language version: ActionScript 3.0
Runtime version: 

Generic creation function for a new host object with a varying number of creation arguments. Use this static method to create a HostObject without using an ActionScript wrapper object derived from HostObject. The class name is the host object class name. If not fully qualified, the package name of the main object model extension is used as the package name. The class name can be either in dot format(packagename.classname) or in ActionScript format(packagename::classname).

Parameters
className:String — the fully qualified class name of the object to create
 
... rest — all remaining arguments are passed to the constructor for that object

Returns
HostObject — the newly created object
eventListener()method 
public static function eventListener(e:Event):void

Language version: ActionScript 3.0
Runtime version: 

Register this method as an event listener to have the host application process a Flex event. If this function is registered as an event listener, the event is forwarded to all event processors registered until one of them signals that the event has been processed.

Parameters
e:Event — the Event object to forward
getClassObject()method 
public static function getClassObject(className:String):HostObject

Language version: ActionScript 3.0
Runtime version: 

Return the host object that is a class object for the given class name. The supplied string is the fully qualified class name of the class object to be returned. If a bare class name is supplied, the main extension's package name is assumed. The class object is required to access class properties and methods. The class name can be either in dot format packagename.classname) or in ActionScript format(packagename::classname). Note that the returned object is a plain HostObject, not an ActionScript Class object. ActionScript wrapper classes retrieve the class object from the host and access the class elements as instance elements of the class object.

Parameters
className:String — class name of the class object to return

Returns
HostObject — the class object
getQualifiedClassName()method 
public static function getQualifiedClassName(value:*):String

Language version: ActionScript 3.0
Runtime version: 

Return the fully qualified class name of the given value. This method can be viewed as an extension of flash.utils.getQualifiedClassName() that also covers generic HostObject instances that do not have an ActionScript wrapper class implemented. A call to flash.utils.getQualifiedClassName() with a HostObject as argument would always return "flash.external::HostObject", while this method returns the combination of the host object's package name and host class name, like e.g. "com.adobe.indesign::Document".

Parameters
value:* — value whose class name to return

Returns
String — the value's fully qualified class name
getRoot()method 
public static function getRoot(name:String = ""):HostObject

Language version: ActionScript 3.0
Runtime version: 

Return the host object that is a root object for the given extension. The supplied string is the package name of the extension whose root object is to be returned. An example is "com.adobe.photoshop". If the string is empty or null, the package name of the main extension is assumed. Use the fully qualified package name for registered extensions that are not main extensions. Note that the extension may choose to return null if there is no root object.

Parameters
name:String (default = "") — package name of the extension

Returns
HostObject — the root object, or null if the root object cannot be returned
isExtensionAvailable()method 
public static function isExtensionAvailable(packageName:String):Boolean

Language version: ActionScript 3.0
Runtime version: 

Check for the availability of a certain object model extension. Use the package name to identify the extension. Returns true if the extension is available, false if not, or the HostObject API is not available at all.

Parameters
packageName:String — package name of the extension to check for

Returns
Boolean — true if the extension has been registered
isValid()method 
public static function isValid(obj:HostObject):Boolean

Language version: ActionScript 3.0
Runtime version: 

Check whether this HostObject wrapper object still is connected to its host counterpart. Disconnected objects throw exceptions on any access attempt. This method checks the object's status without throwing an exception.

Parameters
obj:HostObject — the HostObject wrapper object to check

Returns
Boolean — true if the object is still connected to its host counterpart
toString()method 
public final override function toString():String

Language version: ActionScript 3.0
Runtime version: 

Implement toString() by calling the host object's toString() method if available; if not, return [HostObject xxx], where xxx is the class name. The method is declared final so derived classes cannot provide their own implementation, but must rely on this default implementation, which already calls the host object's toString() method if defined.

Returns
String
valueOf()method 
public final function valueOf():*

Language version: ActionScript 3.0
Runtime version: 

Implement valueOf() by calling the host object's valueOf() method if available; if not, return this instance to indicate the absence of a primitive value. The method is declared final so derived classes cannot provide their own implementation, but must rely on this default implementation, which already calls the host object's valueOf() method if defined.

Returns
*