CoreObject

MovieClip
CoreObject

The CoreObject class is the top of the API trunk chain.  It defines global properties for the API (such as version, copyright notice, etc.) and any methods that are used by any class in the API.  Because of the broad nature of this class, it typically contains very few items.

__/ REQUIREMENTS \__

ActionScript 3.0 (or later)

__/ IMPORTS \__

flash.events.Event flash.system.* flash.utils.* flash.display.* com.bnm.api.CoreInterface

__/ EXTENDS \__

flash.display.MovieClip

__/ IMPLEMENTS \__

com.bnm.api.CoreInterface

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

Please visit http://www.baynewmedia.com/ or email con.nosp@m.tact@baynewm.nosp@m.edia.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.

Summary
CoreObjectThe CoreObject class is the top of the API trunk chain.
Constants
_version(String) The BNMAPI revision number.
_copyright(String) The BNMAPI copyright notice.
Variables
API(BNMAPI) A static reference to the BNMAPI singleton instance.
_stageExists(Boolean) TRUE if the main stage object exists, FALSE otherwise.
CoreObject_environData(Object) Stores global environment data for the current application.
CoreObject_stageExistCallbacks(Array) An array of method references to be called when the main ‘stage’ object instance becomes available.
CoreObject_stageSearchActive(Boolean) Tracks whether or not the stage search method is currently active or not.
Functions and Properties
CoreObjectThe constructor method for the class.
setStageCallbackRegisters the supplied method with a list of callback methods to invoke when the main `stage` object becomes available.
onStageExistsEvent listener invoked when the main `stage` object becomes available in the associated application.
get versionRetreives the BNMAPI version number from the constant value.
version
get copyrightRetreives the BNMAPI copyright notice from the constant value.
copyright
get environmentReturns core environment settings and information such as the runtime type (web player, standalone, AIR, etc.)
environment
get runtimeGets the portion of the environment data that deals specifically with the runtime.
runtime
get stageExistsReturns TRUE if the main `stage` object exists, FALSE otherwise.
stageExists
queryEnvironmentQueries the environment to determine what type of functionality the API should and shouldn’t be allowed to execute.
searchStageInstanceWaits for the existence of the main “stage” object instance and broadcasts an event/calls associated methods when it becomes available.

Constants

_version

public const _version: String

(String) The BNMAPI revision number.  This is used for compatibility checking by current and past versions and may also be used by developers.

_copyright

public const _copyright: String

(String) The BNMAPI copyright notice.  This is strictly for end-user information.  A getter is provided.

Variables

API

public static var API: Object

(BNMAPI) A static reference to the BNMAPI singleton instance.  Any class that extends this class will have automatic access to the API instance (wherever it was created) through this variable.  The BNMAPI sets this reference to itself when the whole API chain has finished instantiating, so it should never be directly updated by anything else.

_stageExists

public var _stageExists: Boolean

(Boolean) TRUE if the main stage object exists, FALSE otherwise.  A getter is supplied to retrieve this property.

CoreObject_environData

private static var CoreObject_environData: Object

(Object) Stores global environment data for the current application.  This includes items like the runtime (web player, AIR, etc.), startup variables (FlashVars), and so on.  A getter if provided.

CoreObject_stageExistCallbacks

private static var CoreObject_stageExistCallbacks: Array

(Array) An array of method references to be called when the main ‘stage’ object instance becomes available.  Adding a method to this array (via a supplied setter) is one way to ensure that a class has a proper reference to the stage object.  The other method is to resgister with the “BNMAPI.ONSTAGEEXIST” event.

CoreObject_stageSearchActive

private static var CoreObject_stageSearchActive: Boolean

(Boolean) Tracks whether or not the stage search method is currently active or not.  This is set to prevent multipl extending instances from adding the same event listener for this functionality.

Functions and Properties

CoreObject

public function CoreObject()

The constructor method for the class.

Parameters

none

Returns

nothing

Broadcasts

nothing

Throws

nothing

Bubbles

no

setStageCallback

public function setStageCallback(methodRef: Function):void

Registers the supplied method with a list of callback methods to invoke when the main `stage` object becomes available.  If the stage is already available, the method is invoked immediately.

Parameters

methodRef (function, required): The method to register for the callback.

Returns

nothing

Broadcasts

nothing

Throws

nothing

Bubbles

no

onStageExists

public function onStageExists(eventObj: Event):void

Event listener invoked when the main `stage` object becomes available in the associated application.  This happens when the first frame event is broadcast since frame events are associated with the existence of the main stage.

Parameters

none

Returns

nothing

Broadcasts

BNMAPI.ONSTAGEEXIST

Throws

nothing

Bubbles

no

get version

Retreives the BNMAPI version number from the constant value.  This is provided for external access.

Returns

String: The current revision number of the BNMAPI.

Broadcasts

nothing

Throws

nothing

Bubbles

no

version

public function get version():String

get copyright

Retreives the BNMAPI copyright notice from the constant value.  This is provided for external access.

Returns

String: The copyright notice from the BNMAPI, including GPL version number.

Broadcasts

nothing

Throws

nothing

Bubbles

no

copyright

public function get copyright():String

get environment

Returns core environment settings and information such as the runtime type (web player, standalone, AIR, etc.).  These are detected when the API is instantiated via the queryEnvironment method.

Returns

Object: A data object containing various environment settings, variables, and other information.

Broadcasts

nothing

Throws

nothing

Bubbles

no

See also

queryEnvironment

environment

public function get environment():Object

get runtime

Gets the portion of the environment data that deals specifically with the runtime.  This includes the runtime type, version, and other information.

Returns

Object: A data object containing runtime-specific information from the environment information object.

Broadcasts

nothing

Throws

nothing

Bubbles

no

See also

queryEnvironment

runtime

public function get runtime():Object

get stageExists

Returns TRUE if the main `stage` object exists, FALSE otherwise.

Returns

Boolean: TRUE if the main `stage` object exists, FALSE otherwise.

Broadcasts

nothing

Throws

nothing

Bubbles

no

stageExists

public function get stageExists():Boolean

queryEnvironment

private function queryEnvironment():void

Queries the environment to determine what type of functionality the API should and shouldn’t be allowed to execute.  For example, JavaScript functions are not allowed when the application is running in the AIR runtime.

Parameters

none

Returns

nothing

Broadcasts

CoreObject.ONGETENVIRON

Throws

nothing

Bubbles

no

searchStageInstance

private function searchStageInstance():void

Waits for the existence of the main “stage” object instance and broadcasts an event/calls associated methods when it becomes available.  Many classes are instantiated before the main stage exists and Flash will throw an error if this NULL object is accessed before it is ready.

Parameters

none

Returns

nothing

Broadcasts

nothing

Throws

nothing

Bubbles

no

This is the core interface for the BNMAPI.
Provides facilities for data checking and conversion for all types of Flash data types.
public const _version: String
(String) The BNMAPI revision number.
public const _copyright: String
(String) The BNMAPI copyright notice.
public static var API: Object
(BNMAPI) A static reference to the BNMAPI singleton instance.
public var _stageExists: Boolean
(Boolean) TRUE if the main stage object exists, FALSE otherwise.
private static var CoreObject_environData: Object
(Object) Stores global environment data for the current application.
private static var CoreObject_stageExistCallbacks: Array
(Array) An array of method references to be called when the main ‘stage’ object instance becomes available.
private static var CoreObject_stageSearchActive: Boolean
(Boolean) Tracks whether or not the stage search method is currently active or not.
public function CoreObject()
The constructor method for the class.
public function setStageCallback(methodRef: Function):void
Registers the supplied method with a list of callback methods to invoke when the main `stage` object becomes available.
public function onStageExists(eventObj: Event):void
Event listener invoked when the main `stage` object becomes available in the associated application.
public function get version():String
public function get copyright():String
public function get environment():Object
public function get runtime():Object
public function get stageExists():Boolean
private function queryEnvironment():void
Queries the environment to determine what type of functionality the API should and shouldn’t be allowed to execute.
private function searchStageInstance():void
Waits for the existence of the main “stage” object instance and broadcasts an event/calls associated methods when it becomes available.