Introspection

The Introspection class is used to analyze, or “introspect”, a running application. This includes the ability to “see” running classes, class members, and other useful information. Also, various facilities are included to support runtime application debugging and other useful developer tools. Introspection routines require extra processing time to perform analysis so it is recommended to disable it when not in use. This can also be accomplished externally through API event broadcasts.

This ActionScript library is licensed and released under the MIT License (http://www.opensource.org/licenses/mit-license.php). Please refer to the accompanying text file “license.txt”, which should be distributed with every package and version of this library, for information on usage, distribution, copying, and other important information.

This class is commented using the NaturalDocs documentation system. It is intended to be easily read both from the direct source code and from an adaptation that is generated as hyperlinked HTML. The NaturalDocs specification used in this class’ documentation is version 1.35 though older versions may probably be used safely. For more information, please visit: http://www.naturaldocs.org/

Timer-based looping method that monitors specified target object(s) for properties and invokes callback methods once those properties become available.

Variables

Introspection_debugEnabled

public static var Introspection_debugEnabled: Boolean

(Boolean) If TRUE, debug messages are enabled for the application. If FALSE, no debug messages are sent to listeners or any output windows. Methods are provided to update this value.

Introspection_propMonitor

public static var Introspection_propMonitor: Array

(Array) Contains an array of objects, each containing a target object, property name (string), and callback method reference, which is used to monitor the existence or properties. This is used in conjunction with the onExists method.

Introspection_monitorTimer

public static var Introspection_monitorTimer: Timer

(Timer) This <Timer> instance used to monitor the Introspection_propMonitor array. It is automatically started and stopped as required. A default of 10 milliseconds is used for property monitoring. This may be increased or decreased as required.

Functions

Introspection

public function Introspection()

Constructor method for the class instance.

Parameters

none

Returns

Introspection: A new instance of the Introspection object.

Broadcasts

nothing

Throws

nothing

Bubbles

no

See also

enableDebug

public function enableDebug(

eventObj:

Object

):void

Used to enable debugging messages via the debug method. This method may either be invoked directly, using a fake parameter object, or via an “Introspection.DEBUG.ENABLE” event broadcast.

Parameters

Returns

nothing

Broadcasts

nothing

Throws

nothing

Bubbles

no

debug

public function debug(

message:

*,

...

args

):void

Sends a debug message to all registered listeners. This is very similar to the standard “trace” function except that it also sends the message extenally to any debug windows (like the BNM Debugger Application). Any method may also register as a debug event listener by registering for the “Introspection.DEBUG” event.

Parameters

message (untyped, optional): Any string, number, or object to be sent to debug listeners. Complex objects are converted to strings using the “toString” method as are numbers. If the parameter is not defined, a blank string is sent. If the object is an XML object, it is converted to a string by using “toXMLString” instead. legacy (boolean, optional): If TRUE, the legacy “message” property is used to denote the debug broadcast. If FALSE (default), the “event” property is used instead, along with newer debugging information for v3.1+ listeners.

Returns

nothing

Broadcasts

Introspection.DEBUG

Throws

nothing

Bubbles

no

coreClass

public function coreClass(

...

value

):Object

Returns the top-level or core class of the specified parameter object. The object inheritance is traversed all the way to the very top to retrieve the first class from which the object is descended. A limit of 1000 parent classes is imposed on this process to prevent possible recursion errors. This limit, however, is unlikely to be reached.

Parameters

value (untyped, optional): Any object or reference.

Returns

Object: The core class from which the parameter object is descended, or NULL if no applicable class can be found.

Broadcasts

nothing

Throws

nothing

Bubbles

no

isChildOf

public function isChildOf(

container:

DisplayObjectContainer,

child:

DisplayObjectContainer

):Boolean

Recursively checks whether the “child” object, as specified in the parameter, is a display object child of the “container” property. The child can be nested any number of levels deep with the container; in other words, it doesn’t need to be a direct child.

Parameters

container (DisplayObjectContainer, required): The display object that is thought to contain the “child” object. This may not necessarily be the container; that determination is to be made by this method. child (DisplayObjectContainer, required): The display object that is thought to be within the “container” parameter. This does not ncssarily need to be a child; that is to be determined by this method.

Returns

Boolean: TRUE if the “child” is a child of the “container”. This is TRUE both if the child is immediate (one level deep), or deeply nested. FALSE is returned if the “container” does not contain the “child”, or if the supplied parameter(s) is/are incorrect.

Broadcasts

nothing

Throws

nothing

Bubbles

no

isDynamic

public function isDynamic (

targetObject:

*

):Boolean

Attempts to determine if the specified parameter object is dynamic. Returns TRUE if the object is dynamic (members can be added or removed at runtime) or FALSE if it’s not.

Parameters

targetObject (untyped, required): The target object to evaluate.

Returns

Boolean: TRUE if the target object is dynamic and can have member properties added or removed dynamically, FALSE otherwise.

Broadcasts

nothing

Throws

nothing

Bubbles

no

getInstanceInParent

public function getInstanceInParent(

displayObject:

*

):Object

getInstance

public function getInstance(

className:

String,

...

params

):*

Attempts to find and create an instance of the supplied class name. The class name parameter must be a fully qualified class name (e.g. “flash.display.MovieClip” rather than simply “MovieClip”).

Parameters

className (String, required): The fully qualified package/class name of the instance to create. In other words, “flash.display.MovieClip” rather than simply “MovieClip”. ... (untyped, optional): Any number of parameters to pass to the constructor method of the class. The number, order, and type of these values is entirely dependent on the class being instantiated.

Returns

untyped: A reference to the newly created class instance, or NULL if there was a problem instantiating the class for whatever reason.

Broadcasts

BNMAPI.ERROR

Throws

com.bnm.api.instances.Exception

Bubbles

no

getClass

public function getClass(

className:

String

):Class

Attempts to find a class definition in memory and returns a reference to it if it exists. Although the “getDefinitionByName” method produces the same result, it is advisable to use this method since it provides centralized error reporting and attempts to recover and/or fix simple errors in class/path names, etc.

Parameters

className (String, required): The fully qualified package/class name of the class definition to find. In other words, “flash.display.MovieClip” rather than simply “MovieClip”.

Returns

Class: A class object reference, or NULL if no such class can be found. Note that this is NOT a class instance. Rather, it is a reference to the class definition.

Broadcasts

BNMAPI.ERROR

Throws

com.bnm.api.instances.Exception

Bubbles

no

getSuperClass

public function getSuperClass(

baseObject:

*

):*

Returns a reference to the super class object of the supplied parameter. The returned object can be used to create an instance of the class (it is not an instance but a class reference).

Parameters

baseObject (untyped, required): The base object from which to find the first super class.

Returns

Object: A reference to the super class of the supplied object parameter. This returned object can be used to create a new class instance -- it is not a class instance but the class reference itself.

Broadcasts

nothing

Throws

nothing

Bubbles

no

onExists

public function onExists(

property:

String,

target:

*,

callback:

Function,

...

parms

):void

Begins a monitoring process for a property within a specified object. If the object or property don’t exist, a continuous background scan is conducted until it becomes available. Once the property is no longer UNDEFINED or NULL, the callBack method is invoked and monitoring for this property is removed. Once all properties have been detected, monitoring stops altogether. The “property” parameter of this method may either be a single property name (e.g. “myMovieClip”) or a dot notation reference (e.g. “myMovieClip.currentSelection”). When dot notation is used in this way, properties are automatically detected down through the stack starting with the left-most property. In this case, “myMovieClip” would be detected first and then “currentSelection”. Only when “currentSelection” became available would the monitor stop and report success.

Parameters

property (String, required): The property name to watch for. Property names may be dot-notated like standard properties. target (untyped, required): The object that is to contain the property. callback (Function, required): The callback method to invoke once the property becomes available.

Returns

nothing

Broadcasts

nothing

Throws

nothing

Bubbles

no

See also

onExistsMonitor

private function onExistsMonitor(

eventObj:

TimerEvent

):void

Timer-based looping method that monitors specified target object(s) for properties and invokes callback methods once those properties become available. The <Timer> object associated with property monitoring is managed automatically to reduce processing time. This method should be used in conjunction with the onExists method.

Parameters

eventObj (TimerEvent, required): A <TimerEvent> object.

Returns

nothing

Broadcasts

nothing

Throws

nothing

Bubbles

no

Provides facilities for data checking and conversion for all types of Flash data types.