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.
__/ REQUIREMENTS \__
ActionScript 3.0 (or later)
__/ IMPORTS \__
flash.utils.* flash.display.* com.bnm.api.instances.ErrorBroadcast com.bnm.api.instances.Exception flash.events.TimerEvent
__/ EXTENDS \__
com.bnm.api.CoreData
__/ IMPLEMENTS \__
nothing
__/ NOTICE \__
©opyright 2008 Bay New Media. All rights, as stipulated in the The MIT License, are reserved.
This ActionScript library is licensed and released under the MIT License (http://www.opensource.org
Please visit http://www.baynewmedia.com/ or email contact@baynewmedia.com for information, questions, concerns, or bug reports.
__/ NOTES \__
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/
The BNMAPI is officially available (primary sources) on Source Forge (http://sourceforge.net/projects/bnmapi/), on the Bay New Media site (http;//www.baynewmedia.com/), on the PeaBee project site (http://www.peabee.com/), and through the Bay New Media SVM repository server (visit http://www.baynewmedia.com/ for more information). Downloads from other sources may not be complete or up-to-date.
If you’re interested in joining the BNMAPI project in any capacity (development, testing, distribution, etc.), please visit us on Source Forge or the Bay New Media web site.
| Introspection | The Introspection class is used to analyze, or “introspect”, a running application. |
| Variables | |
| Introspection_debugEnabled | (Boolean) If TRUE, debug messages are enabled for the application. |
| Introspection_propMonitor | (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. |
| Introspection_monitorTimer | (Timer) This <Timer> instance used to monitor the Introspection_propMonitor array. |
| Functions | |
| Introspection | Constructor method for the class instance. |
| enableDebug | Used to enable debugging messages via the debug method. |
| disableDebug | Used to disable debugging messages via the debug method. |
| debug | Sends a debug message to all registered listeners. |
| coreClass | Returns the top-level or core class of the specified parameter object. |
| isChildOf | Recursively checks whether the “child” object, as specified in the parameter, is a display object child of the “container” property. |
| isDynamic | Attempts to determine if the specified parameter object is dynamic. |
| getInstanceInParent | |
| getInstance | Attempts to find and create an instance of the supplied class name. |
| getClass | Attempts to find a class definition in memory and returns a reference to it if it exists. |
| getSuperClass | Returns a reference to the super class object of the supplied parameter. |
| onExists | Begins a monitoring process for a property within a specified object. |
| onExistsMonitor | Timer-based looping method that monitors specified target object(s) for properties and invokes callback methods once those properties become available. |
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.
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.
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.
eventObj (Object, required): A standard BNMAPI event object or a simple empty object (no sub-properties required).
nothing
nothing
nothing
no
public function disableDebug( eventObj: Object ):void
Used to disable debugging messages via the debug method. This method may either be invoked directly, using a fake parameter object, or via an “Introspection.DEBUG.DISABLE” event broadcast.
eventObj (Object, required): A standard BNMAPI event object or a simple empty object (no sub-properties required).
nothing
nothing
nothing
no
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.
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.
nothing
Introspection.DEBUG
nothing
no
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.
value (untyped, optional): Any object or reference.
Object: The core class from which the parameter object is descended, or NULL if no applicable class can be found.
nothing
nothing
no
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.
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.
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.
nothing
nothing
no
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.
targetObject (untyped, required): The target object to evaluate.
Boolean: TRUE if the target object is dynamic and can have member properties added or removed dynamically, FALSE otherwise.
nothing
nothing
no
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”).
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.
untyped: A reference to the newly created class instance, or NULL if there was a problem instantiating the class for whatever reason.
BNMAPI.ERROR
com.bnm.api.instances.Exception
no
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.
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”.
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.
BNMAPI.ERROR
com.bnm.api.instances.Exception
no
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).
baseObject (untyped, required): The base object from which to find the first super class.
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.
nothing
nothing
no
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.
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.
nothing
nothing
nothing
no
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.
eventObj (TimerEvent, required): A <TimerEvent> object.
nothing
nothing
nothing
no
(Boolean) If TRUE, debug messages are enabled for the application.
public static var Introspection_debugEnabled: Boolean
(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.
public static var Introspection_propMonitor: Array
(Timer) This Timer instance used to monitor the Introspection_propMonitor array.
public static var Introspection_monitorTimer: Timer
Constructor method for the class instance.
public function Introspection()
Used to enable debugging messages via the debug method.
public function enableDebug( eventObj: Object ):void
Sends a debug message to all registered listeners.
public function debug( message: *, ... args ):void
Used to disable debugging messages via the debug method.
public function disableDebug( eventObj: Object ):void
Returns the top-level or core class of the specified parameter object.
public function coreClass( ... value ):Object
Recursively checks whether the “child” object, as specified in the parameter, is a display object child of the “container” property.
public function isChildOf( container: DisplayObjectContainer, child: DisplayObjectContainer ):Boolean
Attempts to determine if the specified parameter object is dynamic.
public function isDynamic ( targetObject: * ):Boolean
public function getInstanceInParent( displayObject: * ):Object
Attempts to find and create an instance of the supplied class name.
public function getInstance( className: String, ... params ):*
Attempts to find a class definition in memory and returns a reference to it if it exists.
public function getClass( className: String ):Class
Returns a reference to the super class object of the supplied parameter.
public function getSuperClass( baseObject: * ):*
Begins a monitoring process for a property within a specified object.
public function onExists( property: String, target: *, callback: Function, ... parms ):void
Timer-based looping method that monitors specified target object(s) for properties and invokes callback methods once those properties become available.
private function onExistsMonitor( eventObj: TimerEvent ):void