. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .551Chapter 1: Introducing ActionScriptextensions for Flash Lite for the digitalhomeWhat is Flash Lite for the digital home?Adobe® Flash® Lite® for the digital home is Adobe Flash Lite 3.1 optimized for hardware and software architectures ofdigital home electronics. These devices include, for example, television sets, Blu-ray players, game consoles, and set-top boxes. Adobe Flash® developers can create applications for Flash Lite for the digital home that stream and playhigh-definition video from the Internet. These developers can also create rich Internet applications and graphical userinterfaces for Flash Lite for the digital home.These applications are in SWF file format. Flash Lite for the digital home can run multiple SWF applications at onetime. The SWF content of each application appears in its own Stage. The Stage is a rectangular area on the displaydevice. Flash Lite for the digital home uses a StageWindow instance to control each application’s Stage. EachStageWindow instance creates a Flash Lite instance. The Flash Lite instance contains a Flash® Player that runs the SWFapplication. The Flash Player supports Flash Lite 3.1.Flash Lite for the digital home provides an interface to load and run SWF content on the target platform. This interfaceis the IStagecraft interface. A C++ application running on your platform that uses the IStagecraft interface is called thehost application. The host application is the client of the IStagecraft interface (just as any program that uses an interfaceis a client of the interface).The Flash Lite for the digital home source distribution provides a host application you can use for testing. This hostapplication is in stagecraft_main.cpp in the directory <installation directory>/source/executables/stagecraft.What is ActionScript?Adobe Flash® CS4 Professional is the professional standard authoring tool for producing high-impact web experiences.Adobe ActionScript® is the language you use to add interactivity to rich media applications. These applications aresimple animated SWF files or more complex rich Internet applications.ActionScript is based on ECMAScript. Flash Lite for the digital home uses ActionScript 2.0. ActionScript 2.0 is anobject-oriented programming language that supports classes, inheritance, interfaces, and other common object-oriented programming concepts. ActionScript 2.0 also includes features such as variable data typing, functionparameters and return types, and comprehensive debugging information.Using Flash CS4 Professional, a Flash developer adds ActionScript code to an application in the application’s FLA fileor in a separate ActionScript (.as) file. The Flash developer publishes the application, creating an executable SWF file.Flash Lite for the digital home, running on your platform, executes the SWF file.See alsoLearning ActionScript 2.0 in Adobe FlashActionScript 2.0 Language Reference2DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMEIntroducing ActionScript extensions for Flash Lite for the digital homeWhat is an ActionScript extension?ActionScript provides many built-in classes. For example, MovieClip, Array, and NetConnection are built-in classes.Additionally, a Flash developer can create application-specific classes. Sometimes an application-specific class extendsa built-in class.An ActionScript extension is a combination of an ActionScript class declaration and a corresponding C++implementation. The C++ implementation provides access to features that are not available in the built-in classes, andthat are not possible to implement in application-specific classes. An ActionScript extension typically surfaces device-specific functionality. For example, you could create an ActionScript extension for changing the channel on a TV.An ActionScript extension can provide such functionality because the C++ implementation has access to the platformon which you are running Flash Lite for the digital home. Built-in and application-specific ActionScript classes do nothave access to the platform.The extension framework of Flash Lite for the digital home passes information between the C++ extensionimplementation and the ActionScript running in a SWF application.Tasks to create an ActionScript extensionCreating an ActionScript extension involves the following high-level tasks.Declare the ActionScript extension

Set up the ActionScript (.as) file that declares the methods and properties that theActionScript extension exposes.Define the ActionScript extension

Code the C++ class that implements the ActionScript extension.Register the ActionScript extension

Provide code that tells Flash Lite for the digital home about the ActionScriptextension.Build and test the ActionScript extension

Create and edit makefiles to build the ActionScript extension. Then, test theextension’s functionality by creating a SWF application that uses the extension.Before you beginBefore you begin developing ActionScript extensions for Flash Lite for the digital home, do the following:•Install and build Flash Lite for the digital home on your Linux platform.•Run Flash Lite for the digital home on your platform so that it executes a sample SWF application provided withthe source distribution.Read Getting Started with Adobe Flash Lite for the Digital Home for details about how to install, build, and run FlashLite for the digital home.For information about coding and building C++ libraries and executables for Flash Lite for the digital home, read thechapter Coding, building, and testing in Optimizing Adobe Flash Lite for the Digital Home. The information aboutcoding includes macros, types, and classes provided by Flash Lite for the digital home. The information about buildingincludes instructions about directory structures and makefiles.Finally, before you test your ActionScript extensions, read Developing Applications for Adobe Flash Lite for the DigitalHome. This document discusses how to create SWF applications that run on Flash Lite for the digital home.3Chapter 2: Declaring an ActionScriptextensionTo declare an Adobe ActionScript extension, you provide a .as file. The .as file contains the ActionScript classdeclaration of the extension. For example, the following code shows the declaration of the Process extension providedwith the source distribution. The declaration is in the file Process.as in the directory <installationdirectory>/source/ae/edk/flash/com/adobe/digitalhome/os.intrinsic dynamic class com.adobe.digitalhome.os.Process

{

public function createProcess(command: String): Boolean;

// createProcess creates an operating system process using command as the

// command line to create the process with. It returns true if successful,

// false otherwise. It will return false if a process is already created and

// still running.

public function isComplete (): Boolean;

// returns true if the process is not running.

public function readStdout(): String;

// reads a string from the process' standard output,

// returns an empty string "" if no output string available

public function readStderr(): String;

// reads a string from the process' standard error,

// returns an empty string "" if no error string available

public function writeStdin(string: String );

// writes a string to the process' standard input

public function getReturnCode(): Number;

// gets the return code of the process,

// only valid after onNotifyComplete is called

public function getProcessID(): Number;

// gets the process id of the process; only valid from a successful call

// to createProcess until onNotifyComplete is called

public function sendInterrupt();

// sends an interrupt signal to the process

public function kill() ;

// sends an unconditional kill signal to the process

public function onNotifyComplete();

// this function is called to notify that the process is complete.

// You many call readStdout() and readStderr() from within this function to read any

// remaining stdout or stderr strings. (Note you can also call readStdOut()

// and readStdErr()at any other time).

//

// You should specify your own onNotifyComplete() function as follows:

}In the declaration of your ActionScript extension, do the following:•Declare the classintrinsic. The keywordintrinsicindicates that no function implementation is included inActionScript. However, the ActionScript compiler does type checking when the Adobe Flash developer publishesthe application. You declare the classintrinsicbecause you code the function implementation in C++.•Optionally declare the classdynamic. The keyworddynamicspecifies that objects based on the class can add andaccess dynamic properties at runtime. Type checking on dynamic classes is less strict than type checking on non-dynamic classes. The type checking is less strict because members accessed inside the class definition and on classinstances are not compared with those members defined in the class scope. Class member functions, however, canstill be type checked for return type and parameter types.•Provide a class name. The name can be a simple class name such as MyClass. Alternatively, the name can be a fullyqualified class name of the form base.sub1.sub2.MyClass. If so, store the .as file for the class in a directory structurethat reflects the fully qualified class name, such as base/sub1/sub2/MyClass.as.A classpath lists the directories Adobe Flash CS4 Professional uses to find a .as file when compiling your application.For a class with a simple name, make sure that the classpath includes the directory containing the .as file. For a classwith a fully qualified name, make sure that the classpath includes the directory containing the base directory of thefully qualified name.For more information about classpath, seeAbout setting and modifying the classpathin Learning ActionScript 2.0in Adobe Flash.•Declare the class methodspublic. The public methods can be either instance methods or static methods. Todeclare a method static, include the keywordstaticafterpublic. Each method corresponds to a method in theC++ class you implement to provide the functionality.Note: Because the class implementation is in C++, any processing that would normally be done by private methods isdone in the C++ implementation. Therefore, declare no methodsprivatein the ActionScript extension.•Declare the member variables in the ActionScript extension. Declare the variablespublic. Unlike class methods,you do not declare a corresponding member variable in the C++ class you implement for the ActionScriptextension. Instead, you manipulate member variables in your C++ implementation using“ASValue” on page

15.5DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMEDeclaring an ActionScript extensionNote: Because the class implementation is in C++, declare no private member variables. Any processing that wouldnormally access private variables is done in the C++ implementation.To declare a variable static, include the keywordstaticafterpublic. However, because the class is intrinsic, theActionScript compiler does not allocate static variables. Adobe Flash Lite for the digital home provides an interimsolution for handling static member variables so the application can use them as constants. For an example, see theStageWindowClass constructor in StageWindowClass.cpp. This file is in <installation directory>/source/ae/edk.For more information about declaring a class in ActionScript 2.0, seeThe class statementin ActionScript 2.0 LanguageReference.6Chapter 3: Coding an ActionScriptextensionAfter you have declared an Adobe ActionScript extension in a .as file, you are ready to define the extension. To definethe extension, you create a C++ class that implements each method of the ActionScript extension.Adobe Flash Lite for the digital home provides the framework for creating this C++ class. To create the C++ class, youuse the classes in the following table. These classes are in the file <installationdirectory>/include/ae/stagecraft/ASExtensions.h:The extension framework of Flash Lite for the digital home passes information between the C++ extensionimplementation and the ActionScript running in a SWF application. The following table summarizes thecorrespondence between classes, class instances, and methods in the C++ and ActionScript environments.ClassDescriptionASExtensionClassASExtensionClass is the base class for implementing ActionScript extensions. You derive a subclass fromASExtensionClass that corresponds to the ActionScript extension class that you declared in a .as file. In thesubclass, you implement the methods inherited from the ASExtensionClass. Also in the subclass, you implementa method for each method declared in the corresponding ActionScript class. These methods of theASExtensionClass subclass are called C++ extension methods.ASValueAn instance of this class represents an instance of an ActionScript variable. The ActionScript variable is of one ofthese ActionScript types: String, Number, Boolean, Object, or Array. Using an ASValue instance, you canmanipulate the corresponding ActionScript variable. For example, you can set the value of an ActionScriptString variable.One parameter of each C++ extension method is an array of ASValue instances. The array is of the typeASValueArray. The array contains the actual parameter values passed to the corresponding ActionScript classmethod.Flash Lite for the digital home provides the implementation for ASValue and ASValueArray.ASObjectAn instance of this class represents an instance of an ActionScript variable of type Object (or subclass of Object).Using an ASObject instance, you can manipulate the corresponding ActionScript Object instance. For example,you can call a method of the ActionScript Object instance.One parameter of each C++ extension method is an ASObject instance. The ASObject instance corresponds tothe ActionScript extension class instance for which the method is being called. If the C++ extension method isstatic, then the ASObject instance is an object that the Flash Lite instance uses internally to represent thedefinition of the ActionScript extension class.An ASObject instance can also be an element of the ASValue array passed to a C++ extension method. ThisASObject instance corresponds to an ActionScript Object instance passed as a parameter to a method of theActionScript extension.Flash Lite for the digital home provides the implementation for the ASObject methods.ActionScript environment itemCorresponding C++ itemActionScript extension class (sometimes called an ActionScriptextension)ASExtensionClass subclassAn instance of the ActionScript extension classAn instance of the ASExtensionClass subclass.7DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionMany examples in this chapter use the Process ActionScript extension class and the corresponding subclass ofASExtensionClass named ProcessClass. The Process class is a complete implementation that spawns and maintainsLinux processes. Other examples use the StageWindow ActionScript extension class and the ASExtensionClasssubclass named StageWindowClass. The StageWindow class creates and manages StageWindow instances. Thefollowing table shows where to find the related files.Note: The source distribution provides two implementations of the ProcessClass. These implementations are inProcessClassLinux.cpp and ProcessClassWin32.cpp. One implementation targets a Linux platform, and the other targetsa Win32 platform. The Linux implementation derives the class ProcessClassLinux from ProcessClass. However, createmultiple implementations or an intermediary subclass for your ActionScript extension only if doing so makes sense foryour extension. For example, if the purpose of your ActionScript extension is to manipulate hardware on your Linuxplatform, do not create a Win32 implementation. In such a case, you also do not need an intermediary subclass.ASExtensionClassA subclass of ASExtensionClass represents an ActionScript extension class. The ASExtensionClass subclass defines amethod for each method declared in the ActionScript class. These methods of the ASExtensionClass subclass are calledC++ extension methods.C++ extension methods implement the ActionScript extension’s functionality. They can also manipulate the ASObjectinstance that corresponds to the ActionScript extension class instance for which the C++ extension method was called.In your ASExtensionClass subclass, do the following:•Implement the constructor and destructor, if a default constructor and destructor are not enough for yourimplementation.An ActionScript Object instance (which is an instance of anActionScript variable of type Object or derived from Object)An ASObject instance.An instance of an ActionScript variable of type Number, String,Boolean, Array, or ObjectAn ASValue instance.A method of the ActionScript extension classA C++ extension method defined in an ASExtensionClasssubclass.Declaration or implementationFileProcess extension classdeclaration<installation directory>/source/ae/edk/flash/com/adobe/digitalhome/os/Process.asProcessClass (subclass ofASExtensionClass) declaration<installation directory>/source/ae/edk/ProcessClass.hProcessClass subclassimplementation<installation directory>/source/ae/edk/ProcessClassLinux.cppStageWindow extension classdeclaration<installation directory>/source/ae/edk/flash/com/adobe/tv/StageWindow.asStageWindowClass (subclass ofASExtensionClass) declaration<installation directory>/source/ae/edk/StageWindowClass.hStageWindowClass subclassimplementation<installation directory>/source/ae/edk/StageWindowClass.cppActionScript environment item Corresponding C++ item8DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extension•Implement the C++ extension methods.•Implement the ASExtensionClass virtual method“OnUpdate()” on page

14.•Implement the ASExtensionClass static methods.The ASExtensionClass static methods are the following:•“ConstructInstance()” on page

9•“DestructInstance()” on page

10•“FiresEvents()” on page

11•“GetClassName()” on page

12•“GetMethods()” on page

12When a Flash Lite instance is executing a SWF application, the Flash Lite instance calls your ASExtensionClasssubclass methods as follows:•When the SWF application instantiates the ActionScript extension, the Flash Lite instance callsConstructInstance().•When the SWF application calls a method of the ActionScript extension, the Flash Lite instance calls thecorresponding C++ extension method.•When the SWF application destructs the instance of the ActionScript extension, the Flash Lite instance callsDestructInstance().The Flash Lite instance calls the methodsGetClassName(),GetMethods(), andFiresEvents()as part of its internalprocessing.C++ extension methodsEach method of the ActionScript extension class has a corresponding method in an ASExtensionClass subclass, calleda C++ extension method. The C++ extension methods provide the functionality of the ActionScript extension.The C++ extension method can be a virtual method, a non-virtual method, or a pure virtual method. The choicedepends on your implementation. However, if the method in the ActionScript class is static, then declare thecorresponding C++ extension method as static. Similarly, if the method in the ActionScript class is not static, then donot declare the corresponding C++ extension method as static.Give the C++ extension method a similar name as the corresponding method in the ActionScript class. For example,the methodcreateProcess()in the ActionScript extension named Process corresponds to the C++ extensionmethodProcessClass::CreateProcess().Each C++ extension method has the following signature:void <method name>(StageWindow * pStageWindow, ASObject & asObject,

A pointer to the StageWindow instance running the SWF application. Use this pointer to access theStageWindow instance. Depending on the functionality of your ActionScript extension, you might not need to use thisparameter.asObject

A reference to an ASObject instance. This ASObject instance corresponds to an ActionScript Objectinstance of the ActionScript extension class. The ActionScript Object instance is the one for which a method is beingcalled. If the C++ extension method is static, then the ASObject instance is an object that the Flash Lite instance uses9DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensioninternally to represent the definition of the ActionScript extension class. In the static case, only use theasObject

A reference to an array of type ASValueArray. This array contains ASValue instances for each parameterpassed to the method of the ActionScript extension class.retValToSet

A reference to an ASValue instance. If the method of the ActionScript extension class has a returnvalue, the C++ extension method sets this ASValue instance with the return value.Example using the retValToSet parameterThis example shows setting a return value in a C++ extension method.void ProcessClassLinux::GetProcessID(StageWindow * pStageWindow, ASObject & asObject,

A pointer to the StageWindow instance running the SWF application.asObject

A reference to an ASObject instance. This ASObject instance corresponds to the ActionScript Objectinstance being constructed. The ActionScript Object instance being constructed is an instance of your ActionScriptextension class.constructorArguments

A reference to an array of type ASValueArray. This array contains ASValue instances foreach parameter passed to the constructor of the ActionScript extension class.ReturnsA pointer to the newly constructed instance of your ASExtensionClass subclass.DescriptionFlash Lite for the digital home calls the static methodConstructInstance()when an instance of the ActionScriptextension class is being constructed.ConstructInstance()returns a pointer to an instance of yourASExtensionClass subclass. Therefore, codeConstructInstance()to allocate an instance of your subclass.If the constructor of your ActionScript class takes parameters, the parameters are available toConstructInstance()

as ASValue instances in theconstructorArgumentsarray. Use the ASValue instances to determine how to constructthis instance of your ASExtensionClass subclass.You can use the parameterasObjectofConstructInstance()to access the ActionScript extension class instance.Note: When the ASExtensionClass subclass instance is being instantiated, the corresponding ActionScript Object instancehas already been created. Therefore, you can access the ActionScript Object instance from withinConstructInstance(). You can also access the ActionScript Object instance from withinDestructInstance(). TheActionScript Object instance is not destructed until after the call toDestructInstance().If yourConstructInstance()implementation needs access to the StageWindow instance in which the SWFapplication is running, use thepStageWindowparameter.Flash Lite for the digital home requires you to implement this method in your ASExtensionClass subclass.ExampleASExtensionClass * ProcessClass::ConstructInstance(

}Use theAE_NEWmacro when creating the ASExtensionClass subclass instance. For more information, see the chapterCoding, building, and testing in Optimizing Adobe Flash Lite for the Digital Home.DestructInstance()Usagestatic void DestructInstance(StageWindow * pStageWindow, ASObject & asObject);ParameterspStageWindow

A pointer to the StageWindow instance running the SWF application.11DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionasObject

A reference to an ASObject instance. This ASObject instance corresponds to the ActionScript Objectinstance being destructed. The ActionScript Object instance being destructed is an instance of your ActionScriptextension class.ReturnsNothing.DescriptionFlash Lite for the digital home calls the static methodDestructInstance()when an instance of the ActionScriptextension class is being destructed. The instance is destructed, for example, when it goes out of scope, is deleted, orwhen the Flash Lite instance terminates. Therefore, code the cleanup tasks for the ActionScript extension inDestructInstance(). Also, codeDestructInstance()to delete your subclass instance.You can use the parameterasObjectofDestructInstance()to access the ActionScript extension class instance.The ActionScript extension class instance is not destructed until afterDestructInstance()returns.If yourDestructInstance()implementation needs access to the StageWindow instance in which the SWFapplication is running, use thepStageWindowparameter.When implementingDestructInstance(), consider the following:•Use theAE_DELETEmacro when destructing the ASExtensionClass subclass instance. For more information, seethe chapter Coding, building, and testing in Optimizing Adobe Flash Lite for the Digital Home.•Use theGetClassInstance()method of theasObjectparameter to get the ASExtension subclass instance todestruct. Remember thatDestructInstance()is a static member of your ASExtensionClass subclass, so thethis

pointer is not applicable inDestructInstance(). In non-static C++ extension methods in your ASExtensionClasssubclass,GetClassInstance()is the same as thethispointer.•BecauseGetClassInstance()returns a pointer to an ASExtensionClass instance, cast the returned pointer to apointer to your ASExtensionClass subclass.Flash Lite for the digital home requires you to implement this method in your ASExtensionClass subclass.Examplevoid ProcessClass::DestructInstance(StageWindow * pStageWindow, ASObject & asObject)

{

AE_DELETE((ProcessClassLinux *)asObject.GetClassInstance());

}FiresEvents()Usagestatic bool FiresEvents();ParametersNone.ReturnsThe valuetrueif an instance of the ASExtensionClass subclass is allowed to send events to event listeners. Otherwise,FiresEvents()returnsfalse.12DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionDescriptionImplement this static method to returntrueif you want to send events. Then, you can send events to event listeners.The event listeners are ActionScript Object instances that are listening for events on an instance of your ActionScriptextension. If you do not want to send events, implement this method to returnfalse. Adobe recommends thatFiresEvents()returnsfalsebecause an ASExtensionClass subclass that does not fire events uses fewer resourcesthan one that does.Flash Lite for the digital home requires you to implement this method in your ASExtensionClass subclass.Examplestatic bool MyExtension::FiresEvents()

{

return true;

}See also“FireEvent()” on page

33GetClassName()Usagestatic const char * GetClassName();ParametersNone.ReturnsA string which is the name of the ActionScript extension class.DescriptionThe static methodGetClassName()returns the name of the ActionScript extension class exactly as you declared it ina .as file.Flash Lite for the digital home requires you to implement this method in your ASExtensionClass subclass.Examplestatic const char * GetClassName()

A reference to an array of type MethodArray. MethodArray is defined in ASExtensions.h.MethodArray derives from AEArray, which is defined in <installation directory>/include/ae/AETemplates.h.GetMethods()fills this array with pointers to the C++ extension methods for the ASExtensionClass subclass.ReturnsNothing.DescriptionThe static methodGetMethods()returns an array with pointers to the C++ extension methods in theASExtensionClass subclass. The array to fill is passed as a reference parameter.Flash Lite for the digital home requires you to implement this method in your ASExtensionClass subclass. Copy thefollowing example to implement this method.Examplestatic void GetMethods(ASExtensionClass::MethodArray & methodArrayToFill)

{

methodArrayToFill.Append(Method("createProcess",

(MemberFunctionPointer)&ProcessClass::CreateProcess));

methodArrayToFill.Append(Method("isComplete",

(MemberFunctionPointer)&ProcessClass::IsComplete));

methodArrayToFill.Append(Method("readStdout",

(MemberFunctionPointer)&ProcessClass::ReadStdout));

methodArrayToFill.Append(Method("readStderr",

(MemberFunctionPointer)&ProcessClass::ReadStderr));

methodArrayToFill.Append(Method("writeStdin",

(MemberFunctionPointer)&ProcessClass::WriteStdin));

methodArrayToFill.Append(Method("getReturnCode",

(MemberFunctionPointer)&ProcessClass::GetReturnCode));

methodArrayToFill.Append(Method("getProcessID",

(MemberFunctionPointer)&ProcessClass::GetProcessID));

methodArrayToFill.Append(Method("sendInterrupt",

(MemberFunctionPointer)&ProcessClass::SendInterrupt));

methodArrayToFill.Append(Method("kill",

(MemberFunctionPointer)&ProcessClass::Kill));

}Copy this example to your ASExtensionClass subclass. When you edit it, consider the following:•CallmethodArrayToFill.Append()for each C++ extension method in your ASExtensionClass subclass.•The parameter you pass tomethodArrayToFill.Append()is an instance of the Method class. Method is definedin ASExtensions.h.•This example uses the Method class constructor to create and pass an instance of Method tomethodArrayToFill.Append().•The first parameter to the Method constructor is a string. The string exactly matches the name of a method in theActionScript extension class you declared in the .as file. The name is case sensitive.•The second parameter to the Method constructor is a pointer to the corresponding C++ extension method in yourASExtensionClass subclass. Code the method pointer with the method’s class name. For example, code it&ProcessClass::Killrather than just&Kill.14DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extension•Cast the method pointer to one of these types:*StaticFunctionPointeror

ASExtensionClass::*MemberFunctionPointer. These pointer types are defined in ASExtensionClass.h.•Choose the *StaticFunctionPointerpointer type only if you declared the corresponding ActionScript classmethod as static.OnUpdate()Usagevirtual void OnUpdate(StageWindow * pStageWindow, ASObject & asObject)ParameterspStageWindow

A pointer to the StageWindow instance running the SWF application.asObject

A reference to an ASObject instance. This ASObject instance represents an ActionScript Object instancethat is an instance of your ActionScript extension class. The ASObject instance corresponds to this instance of yourASExtensionClass subclass.ReturnsNothing.DescriptionFlash Lite for the digital home callsOnUpdate()once per Flash frame of the SWF application. Therefore, the frequencyof calls toOnUpdate()depends on the frame rate of the SWF application. However, Flash Lite for the digital homecallsOnUpdate()only ifStartUpdates()had been called for the ASObject instance that corresponds to this instanceof your ASExtensionClass subclass. This ASObject instance is the same one that is passed as theasObjectparametertoOnUpdate().You can use the parameterasObjectto access the ActionScript Object instance. If yourOnUpdate()implementationneeds access to the StageWindow instance in which the SWF application is running, use thepStageWindowparameter.UseOnUpdate()for performing any necessary periodic tasks. Typically,OnUpdate() first checks some status of theASExtensionClass subclass instance. Then,OnUpdate()uses theasObjectparameter to report the status back to theActionScript Object instance. For example,OnUpdate()can callasObject.CallMethod()to call a method of theActionScript Object to report status to it. Alternatively,OnUpdate()can callFireEvent()to tell multipleActionScript event listeners about the status. When you no longer have periodic tasks to perform, callStopUpdates().Minimize the processing inOnUpdate(). This method runs in the same thread as the Flash Lite instance in Flash Litefor the digital home. Therefore, lots of processing inOnUpdate()can adversely affect SWF application performance.For tasks requiring more than minimal processing, consider creating a separate thread to do the processing. Then, youcan useOnUpdate()to simply check the thread’s status or check a message queue. Make sure that the status check isthread safe. For example, use the IAEKernel::Mutex class in <installation directory>/include/ae/IAEKernel.h.Note: If you use threads other than the thread of the Flash Lite instance, do not call any methods of yourASExtensionClass subclass from the other threads.The ASExtensionClass class provides an empty function for its implementation ofOnUpdate(). OverrideOnUpdate()

in your ASExtensionClass subclass only if you have periodic tasks to perform.15DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionExampleThis example shows a few simplified lines of the ProcessClassOnUpdate()method in <installationdirectory>/source/ae/edk/ProcessClassLinux.cpp. Once for each frame update, the ProcessClass instance checks thestatus of the Linux process that it started. If the process is no longer running,OnUpdate()calls a method of theActionScript Object instance that corresponds to this ProcessClass instance.void ProcessClass::OnUpdate(StageWindow * pStageWindow, ASObject & asObject)

{

bool bProcessDead = false;

// Code that determines the value of bProcessDead goes here.

if (bProcessDead) {

asObject.CallMethod("onNotifyComplete");

}

}See also“StartUpdates()” on page

46“StopUpdates()” on page

47Thread considerationsIn Flash Lite for the digital home, a Flash Lite instance runs the SWF application. The Flash Lite instance calls themethods of your ASExtensionClass subclass. Therefore, all the methods execute in the same thread as the Flash Liteinstance. Executing in the Flash Lite instance’s thread has the following ramifications to your ASExtensionClasssubclass code:•Place all initialization and cleanup of your ASExtensionClass subclass inConstructInstance()andDestructInstance(), or in functions called from these methods.•Do not call your ASExtensionClass subclass methods from outside the Flash Lite instance thread.•When usingOnUpdate()to perform periodic tasks, consider the possible performance impact to the SWFapplication. If the periodic tasks require extensive processing, consider creating a separate thread to do theprocessing. Then, in the Flash Lite instance thread inOnUpdate(),you only check the status. See“OnUpdate()”on page

14.ASValueAn instance of this class represents an instance of an ActionScript variable. The ActionScript variable is of one of theseActionScript types: String, Number, Boolean, Object, or Array. Using an ASValue instance, you can manipulate thecorresponding ActionScript variable. For example, you can set the value of an ActionScript String variable.An ASValue array is a parameter of each C++ extension method. The ASValue array contains the actual parametervalues passed to the corresponding ActionScript class method.The ASValue class provides methods to:•Determine the type of the ActionScript variable.•Set the ActionScript variable to some value.•Get the value of the ActionScript variable.16DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionNote: When manipulating strings in your C++ code, use the class AEString that Flash Lite for the digital home provides.Type enumerationThe ASValue class provides a public enumeration that specifies the possible types of values.enum Type /// Represents the type of the ActionScript Value

{

kTypeVoid = 0, // An uninitialized (invalid) AS value

kTypeNull, // An ActionScript value of null

kTypeUndefined, // An ActionScript value of undefined

kTypeInteger, // An ActionScript Number value that is an integer

kTypeNumber, // An ActionScript Number value that is floating point

kTypeString, // An ActionScript String value

kTypeBoolean, // An ActionScript Value that is a Boolean

kTypeObject // An ActionScript value that is an ActionScript Object

};GetType()Usagevirtual Type GetType() = 0;ParametersNone.ReturnsTheTypeenumeration value of the ASValue instance.DescriptionCallGetType()to determine the ActionScript type of an ASValue instance.Example// asValue is a reference to an ASValue instance

}IsDouble()Usageinline bool IsDouble() { return GetType() == kTypeNumber; }ParametersNone.ReturnsThe Boolean valuetrueif the ASValue instance is of typekTypeNumber. Otherwise,IsDouble()returnsfalse.DescriptionCallIsDouble()to determine if an ASValue instance represents an ActionScript value that is a double precisionfloating point number.Example// asValue is a reference to an ASValue instance

double accountBalance;

if (asValue.IsDouble()) {

accountBalance = asValue.ReadDouble();

}

else {

// Do error-handling for when asValue is not a double floating point value.

}IsInt()Usageinline bool IsInt() { return GetType() == kTypeInteger; }ParametersNone.ReturnsThe Boolean valuetrueif the ASValue instance is of typekTypeInteger. Otherwise,IsInt()returnsfalse.18DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionDescriptionCallIsInt()to determine if an ASValue instance represents an ActionScript value that is an integer.Example// asValue is a reference to an ASValue instance

}IsString()Usageinline bool IsString() { return GetType() == kTypeString; }ParametersNone.ReturnsThe Boolean valuetrueif the ASValue instance is of typekTypeString. Otherwise,IsString()returnsfalse.19DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionDescriptionCallIsString()to determine if an ASValue instance represents an ActionScript value that is a string.Example// asValue is a reference to an ASValue instance

if (asValue.IsString()) {

AEString name;

asValue.ReadString(name);

}

else {

// Do error-handling for when asValue is not a string.

}IsValid()Usageinline bool IsValid() { return GetType() != kTypeVoid; }ParametersNone.ReturnsThe Boolean valuetrueif the ASValue instance is not of typekTypeVoid. Otherwise,IsValid()returnsfalse.DescriptionCallIsValid()to determine if an ASValue instance represents a valid value. A valid value is any value for which thetype is notkTypeVoid. All other values ofASValue::Type, includingkTypeNullandkTypeUndefined, indicate validvalues.Example// asValue is a reference to an ASValue instance

if (!asValue.IsValid()) {

// Do error-handling

}ReadBool()Usagevirtual bool ReadBool() = 0;ParametersNone.ReturnsA Boolean with the value of the ASValue instance.20DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionDescriptionCallReadBool()to get the Boolean value of an ASValue instance. If the ASValue instance is not a Boolean value,ReadBool()returnsfalse.To first verify that the ASValue instance is a Boolean value, useIsBool()orGetType()before callingReadBool().Example// asValue is a reference to an ASValue instance.

bool bVal = asValue.ReadBool();ReadDouble()Usagevirtual double ReadDouble() = 0;ParametersNone.ReturnsA double precision floating point number with the value of the ASValue instance.DescriptionCallReadDouble()to get the double precision floating point value of an ASValue instance. If the ASValue instance isnot a double value,ReadDouble()returns 0.0.If 0.0 is a valid value for the double, useIsDouble()orGetType()before callingReadDouble().Example// asValue is a reference to an ASValue instance.

double val = asValue.ReadDouble();ReadInt()Usagevirtual int ReadInt() = 0;ParametersNone.ReturnsAn integer with the value of the ASValue instance.DescriptionCallReadInt()to get the integer value of an ASValue instance. Integer values range from -228to 228- 1. If the ASValueinstance is not an integer value,ReadInt()returns 0.If 0 is a valid value for the integer, useIsInt()orGetType()before callingReadInt().21DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionExample// asValue is a reference to an ASValue instance.

int nValue = asValue.ReadInt();ReadObject()Usagevirtual ASObject & ReadObject() = 0;ParametersNone.ReturnsA reference to an ASObject instance that is the value of the ASValue instance.DescriptionCallReadObject()to get the ASObject instance that is the value of an ASValue instance. If the value of the ASValueinstance is not an ASObject instance,ReadObject()returns an ASObject instance for whichASObject::IsValid()

returnsfalse.To first verify that the value of an ASValue instance is an ASObject instance, useIsObject()orGetType()beforecallingReadObject().Example// asValue is a reference to an ASValue instance.

A reference to theAEStringvariable that is to hold the value of the ASValue instance.ReturnsNothing.DescriptionCallReadString()to get the string value of an ASValue instance.ReadString()setsstringToSet, theAEString

reference parameter, to the value. If the ASValue is not a string value,ReadString()setsstringToSetto an emptystring.If an empty string is a valid value for the string, useIsString()orGetType()before callingReadString().22DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionExample// asValue is a reference to an ASValue instance.

The Boolean value to use to set the value of the ASValue instance.ReturnsNothing.DescriptionCallSetBool()to set an ASValue instance to a Boolean value.SetBool()sets the ASValue instance to the value ofthebValparameter.SetBool()also changes the type of the ASValue instance tokTypeBoolean, a value of theenumerationASValue::Type.Example// isComplete is a reference to an ASValue instance

The double precision floating point value to use to set the value of the ASValue instance.ReturnsNothing.DescriptionCallSetDouble()to set an ASValue instance to a double precision floating point value.SetDouble()sets theASValue instance to the value of thevalparameter.SetDouble()also changes the type of the ASValue instance tokTypeNumber, a value of the enumerationASValue::Type.Example// accountBalance is a reference to an ASValue instance

The integer value to use to set the value of the ASValue instance.ReturnsNothing.DescriptionCallSetInt()to set an ASValue instance to an integer value. Integer values range from -228to 228- 1.SetInt()setsthe ASValue instance to the integer value of thenIntparameter.SetInt()also changes the type of the ASValueinstance tokTypeInteger, a value of the enumerationASValue::Type.Exampleint nVal = 8;

// asValue is a reference to an ASValue instance

asValue.SetInt(nVal);SetNull()Usagevirtual void SetNull() = 0;ParametersNone.ReturnsNothing.DescriptionCallSetNull()to set an ASValue instance to the ActionScript valuenull. This method also changes the type of theASValue instance tokTypeNull, a value of the enumerationASValue::Type.Example// asValue is a reference to an ASValue instance

The ASObject instance to use to set the value of the ASValue instance.24DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionReturnsNothing.DescriptionCallSetObject()to set the ASValue instance to an ASObject instance.SetObject()sets the ASValue instance tothe value of the parameterobject. This method also changes the type of the ASValue instance tokTypeObject, avalue of the enumerationASValue::Type.Example// asValue is a reference to an ASValue instance

// Set asValue to myObject, which is a reference to an ASObject instance.

A pointer to the string to use to set the value of the ASValue instance.ReturnsNothing.DescriptionCallSetString()to set an ASValue instance to a string value.SetString()sets the ASValue instance to the stringpointed to by thepStringparameter.SetString()also changes the type of the ASValue instance tokTypeString,a value of the enumerationASValue::Type.To set the value of the ASValue instance to an empty string, callSetString(NULL)orSetString(""). To set thevalue of the ASValue instance to an undefined value, useSetUndefined().Example// asValue is a reference to an ASValue instance

asValue.SetString("Hello, World");SetUndefined()Usagevirtual void SetUndefined() = 0;ParametersNone.ReturnsNothing.25DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionDescriptionCallSetUndefined()to set an ASValue instance to the ActionScript valueundefined. This method also changes thetype of the ASValue instance tokTypeUndefined, a value of the enumerationASValue::Type.Example// asValue is a reference to an ASValue instance

asValue.SetUndefined();operator int()Usageinline operator int() { return ReadInt(); };ParametersNone.ReturnsAn integer with the value of the ASValue instance.DescriptionThis casting operator allows the ASValue instance to be read as an integer. The operator is convenient way of callingReadInt(). If the ASValue instance is not an integer value, this casting operator returns 0.If 0 is a valid value for the integer, useIsInt()orGetType()before using the casting operator.Example// asValue is a reference to an ASValue instance

int nValue = (int)asValue;operator double()Usageinline operator double() { return ReadDouble(); };ParametersNone.ReturnsA double precision floating point number with the value of the ASValue instance.DescriptionThis casting operator allows the ASValue instance to be read as a double precision floating point value. The operator isconvenient way of callingReadDouble(). If the ASValue instance is not a double value, this casting operator returns 0.0.If 0.0 is a valid value for the double, useIsDouble()orGetType()before using the casting operator.26DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionExample// asValue is a reference to an ASValue instance

double val = (double)asValue;operator bool()Usageinline operator bool() { return ReadBool(); };ParametersNone.ReturnsA Boolean with the value of the ASValue instance.DescriptionThis casting operator allows the ASValue instance to be read as a Boolean. The operator is convenient way of callingReadBool(). If the ASValue instance is not a Boolean value, this casting operator returnsfalse.To first verify that the ASValue instance is a Boolean value, useIsBool()orGetType()before using this castingoperator.Example// asValue is a reference to an ASValue instance

bool bVal = (bool)asValue;operator ASObject()Usageinline operator ASObject&() { return ReadObject(); };ParametersNone.ReturnsA reference to an ASObject instance that is the value of the ASValue instance.DescriptionThis casting operator allows the ASValue instance to be read as an ASObject instance. The operator is convenient wayof callingReadObject(). If the ASValue instance is not an ASObject value, this casting operator returns an ASObjectinstance for whichIsValid()returnsfalse.To first verify that the ASValue instance is an ASObject instance, useIsObject()orGetType()before using thiscasting operator.Example// asValue is a reference to an ASValue instance

ASObject & myObject = (ASObject &)asValue;27DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionASObjectAn instance of the ASObject class represents an instance of an ActionScript variable of type Object (or subclass ofObject). Using an ASObject instance, you can manipulate the corresponding ActionScript Object instance. Forexample, you can call a method of the ActionScript Object instance. The ActionScript Object instance that correspondsto an ASObject instance is called the underlying ActionScript Object instance.An ASObject instance is a parameter of each C++ extension method. This parameter is the ASObject instancecorresponding to the ActionScript extension class instance for which the method is being called. If the C++ extensionmethod is static, then the ASObject instance is an object that the Flash Lite instance uses internally to represent thedefinition of the ActionScript extension class. In the static case, only use the ASObject instance parameter to callCreateASValue(),CreateASObject(), andCallGlobalMethod().An ASObject instance can also be an element of the ASValue array passed to a C++ extension method. This ASObjectinstance corresponds to an ActionScript Object instance passed as a parameter to a method of the ActionScriptextension.The ASObject class provides methods to do the following:•Call ActionScript global methods (CallGlobalMethod())•Call methods of the underlying ActionScript Object instance (CallMethod()).•Create new ASObject and ASValue instances (CreateASObject(),CreateASValue()).•Get and set properties of the underlying ActionScript Object instance (GetProperty(),SetProperty()).•Determine how many properties the underlying ActionScript Object instance has (GetNumProperties()).•Determine if the underlying ActionScript Object instance is an instance of a particular ActionScript class, aMovieClip instance, or any valid instance (IsInstanceOf(),IsMovieClip(),IsValid()).•Determine if the underlying ActionScript Object instance is an ActionScript Array instance. If so, other ASObjectmethods get the array length and access an array element by index (IsArray(),GetArrayLength(),GetArrayElement()).•Get the ASExtensionClass instance that corresponds to the ASObject instance (GetClassInstance()). Only usethis method when the underlying ActionScript Object instance is an ActionScript extension class instance.•Fire an event to event listeners on the underlying ActionScript Object instance (FireEvent()). Only use thismethod when the underlying ActionScript Object instance is an ActionScript extension class instance.•Enable and disable a polling update mechanism that allows for the dispatch of asynchronous notifications toActionScript Object instances (StartUpdates(),StopUpdates()). Only use these methods when the underlyingActionScript Object instance is an ActionScript extension class instance.•Compare two ASObject instances for equality (operator ==).•Manipulate when an ActionScript Object instance is destructed by increasing and decreasing its reference count inthe ActionScript environment (AddRef(),Release()).AddRef()Usagevirtual ASObject * AddRef() = 0;28DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionParametersNone.ReturnsA pointer to this ASObject instance.DescriptionUseAddRef()to create a new pointer to the same ASObject instance. The purpose of AddRef() is to cause the FlashLite instance to not delete the corresponding ActionScript Object instance, even if the Object instance goes out ofscope. Each call toAddRef()creates a new pointer to the ASObject instance, and increments the reference count forthe ActionScript Object. The methodRelease()decrements the reference count, and makes the pointer invalid.When no references remain, the Flash Lite instance deletes the ActionScript Object instance.Save the pointer thatAddRef()returns for future access to the ActionScript Object instance. However, you can onlyuse the pointer in the thread in which your C++ extension methods andOnUpdate()method run.CallRelease()on the pointer thatAddRef()returns as soon as you no longer need access to the ActionScript Objectinstance. At the latest, callRelease()in the destructor of your ASExtensionClass subclass instance.You can useAddRef()on the ASObject instance that represents an instance of an ActionScript extension class.Sometimes the functionality of an ActionScript extension class requires that the Flash Lite instance not destruct theActionScript extension instance when it goes out of scope. One reason to keep the ActionScript extension instancealive is if the extension has callback methods that are not called until some later time, such as inOnUpdate()or in aC++ extension method executed later.Similarly, useAddRef()on any ASObject instance, such as one passed as a parameter to an ActionScript extensionmethod. UseAddRef()if you want to manipulate the ActionScript Object instance later, such as in an ActionScriptextension method called at a later time or inOnUpdate().ExampleOne reason for usingAddRef()is to keep the ActionScript extension instance from being destructed when it goes outof scope. For example, consider an instance of the Process ActionScript extension class. The Process instance receivesnotifications from theOnUpdate()method of the corresponding C++ ProcessClass instance throughout the life of theLinux process. However, if the Process instance goes out of scope, the Flash Lite instance destroys it. Therefore, theCreateProcess()C++ extension method callsAddRef(). Doing so allows the Process instance to continue to existand to receive ongoing notifications throughout the life of the Linux process.The following code illustrates a call toAddRef(). These lines are excerpts from theCreateProcess()C++ extensionmethod in ProcessClassLinux.cpp.29DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionvoid ProcessClassLinux::CreateProcess(StageWindow * pStageWindow, ASObject & asObject,

ASValueArray & arguments, ASValue & retValToSet)

{

// The declaration of the corresponding ActionScript method is:

// public function createProcess(command: String): Boolean;

// The following variable will contain the Linux command for which a process

// will be created.

AEString command;

// Read the first argument, knowing it is the command string.

arguments[0]->ReadString(command);

// Continue with code to fork and exec a process to run the Linux command.

// ...

// After the fork and exec, in the original process, start updates.

// asObject is the ActionScript Object that corresponds to this ASExtensionClass

// subclass instance. That is, asObject is the instance of the Process ActionScript class.

A string that is the name of the ActionScript global method to call.methodArguments

A reference to an ASValueArray instance. The array contains one element for each argument topass to the global method. Each element is an ASValue instance.ReturnsA reference to an ASValue instance that is the return value of the called global method.DescriptionUseCallGlobalMethod()to call a global ActionScript method.30DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionExample// asObject is a reference to an ASObject instance

A string that is the name of the ActionScript class method to call. The method is a method of theunderlying ActionScript Object for this ASObject.arg1

A reference to an ASValue instance that is the first argument to pass to the method.arg2

A reference to an ASValue instance that is the second argument to pass to the method.arg3

A reference to an ASValue instance that is the third argument to pass to the method.methodArguments

A reference to an ASValueArray instance. The array contains one element for each argument topass to the method. Each element is an ASValue instance.ReturnsA reference to an ASValue instance that is the return value of the called method.DescriptionUseCallMethod()to call an ActionScript method of the underlying ActionScript Object for this ASObject. Theversion ofCallMethod()you call depends on the number of arguments to pass to the ActionScript method. Use theversion with themethodArgumentsparameter if the ActionScript method takes more than three arguments, or youwant to pass the arguments in an array.Example with no argumentsvoid MyASClass::StopMovieClip(StageWindow * pStageWindow, ASObject & asObject,

ASValueArray & arguments, ASValue & retValToSet)

{

// the first argument to StopMovieClip() is the MovieClip to operate on.

A pointer to a string which is the name of an ActionScript class. An instance of the specified class iscreated and used as the value of the new ASObject instance.32DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionconstructorArguments

A reference to an ASValueArray instance. The array contains one element for eachargument to pass to the constructor of the new ActionScript class instance. The new ActionScript class instance is usedas the value of the new ASValue instance.ReturnsA reference to a new ASObject instance.DescriptionUseCreateASObject()to create an ASObject instance. The ASObject instance represents a new instance of theActionScript class specified bypClassName. For example, the following C++ statement creates an ActionScript Stringclass instance.ASObject & myString = asObject.CreateASObject("String");The above C++ statement is equivalent to the following ActionScript statement.var myString:String = new String();If you want to pass parameters to the constructor of the ActionScript class, use theconstructorArguments

ASObject & myString = asObject.CreateASObject("String", args);The above C++ statements are equivalent to the following ActionScript statement.var myString:String = new String("The quick brown fox");The new ASObject instance has a reference count of 1. Therefore, the Flash Lite instance will delete it when the instancegoes out of scope. However, the Flash Lite instance increments the reference count of in each of the following cases:•You pass the new ASObject instance as a parameter to an ActionScript class method.•You assign the new ASObject instance to a property of another ASObject instance.•You call AddRef() on the new ASObject instance.CreateASValue()Usagevirtual ASValue & CreateASValue() = 0;

virtual ASValue & CreateASValue(int nInt) = 0;

virtual ASValue & CreateASValue(const char * pString) = 0;

virtual ASValue & CreateASValue(double val) = 0;

virtual ASValue & CreateASValue(bool bVal) = 0;ParametersnInt

The integer value to use as the value of the new ASValue instance.pString

A pointer to a string to use as the value of the new ASValue instance.val

The double precision floating point value to use as the value of the new ASValue instance.bVal

The Boolean value to use as the value of the new ASValue instance.33DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionReturnsA reference to a new ASValue instance.DescriptionUseCreateASValue()to create an ASValue instance with the value specified by the parameter. The following tableshows theASValue::Typeof the new ASValue instance:When you pass no parameters toCreateASValue(), the new ASValue instance is uninitialized until you call one ofthese ASValue methods:SetBool(),SetDouble(),SetInt(),SetString(), orSetObject().Examples// asObject is a reference to an ASObject instance.

A pointer to a string which is the name of the event to fire. This name is the name of the event handlermethod to call on each ActionScript Object instance that is an event listener for this event of this ASObject instance.eventArg

A reference to an ASValue object which contains the parameter to pass to each event handler method.ReturnsThe Boolean valuetrueif the event is successfully sent. Otherwise, the return value isfalse.DescriptionUseFireEvent()to send an event from an ASExtensionClass subclass instance to event listeners. Event listeners areActionScript Object instances that are listening for events on an instance of your ActionScript extension. If an eventlistener is interested in an event, it does the following:•Defines an event handler method that has the name of the event.•Registers as an event listener with an instance of the ActionScript extension.ParameterASValue::Type value of the new ASValue instanceno parameterskTypeVoidint nIntkTypeIntegerconst char *pStringkTypeStringdouble valkTypeNumberbool bValkTypeBoolean34DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionWhen a method of a ASExtension subclass instance callsFireEvent()withpEventName, the Flash Lite instance callsthe method namedpEventNamefor each registered event listener with a method by that name.This event mechanism is the same as the ActionScript 2.0 event handling described inUsing event listenersin LearningActionScript 2.0 in Adobe Flash. However, the difference is that rather than the Flash Lite instance determining whento fire an event, your C++ implementation of an ActionScript extension class callsFireEvent().FireEvent()requires a second parameter. The second parameter is the ASValue instance to pass as a parameter toeach event handler method. If the event handler method does not require a parameter, define it to take a parameteranyway. Then, callSetUndefined()on the ASValue instance you pass inFireEvent().To allow your ASExtensionClass subclass to successfully callFireEvent(), implement its static methodFiresEvents()to returntrue.ExampleThis example shows a few lines of a modified version of the ProcessClassOnUpdate()method in <installationdirectory>/source/ae/edk/ProcessClassLinux.cpp. Once for each frame update, the ProcessClass instance checks thestatus of the Linux process that it started. If the process is no longer running, this example ofOnUpdate()fires an eventto all the event listeners.First, the ActionScript of the SWF application contains the following code.// Import the Process ActionScript extension class declaration in

// com/adobe/digitalhome/os/Process.as

import com.adobe.digitalhome.os.Process;

// Create an instance of the Process extension class.

var myProcess:Process = new Process();

// Next, create an event listener ActionScript Object.

// Define its event listener method onNotifyComplete.

var listenerObject:Object = new Object();

listenerObject.onNotifyComplete = function(pid:Number) {

// Event Listener's code for handling the onNotifyComplete event.

}

// Register the listenerObject as an event listener on myProcess.

myProcess.AddListener(listenerObject);

// Create a process that runs the Linux ls command.

myProcess.createProcess("ls -Fal");In the .cpp file of the implementation of the ASExtensionClass subclass ProcessClass, the following code shows firingtheonNotifyCompleteevent.35DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extensionstatic bool ProcessClass::FiresEvents ()

An integer which is the index of the ActionScript Array element to retrieve. Valid values are between 0 and

GetArrayLength() - 1, inclusive.ReturnsA reference to the ASValue instance which is the element of the ActionScript Array at the index specified bynIndex.DescriptionUseGetArrayElement()to retrieve the ActionScript Array element at a specified index.Note: Manipulate the ActionScript Array Object in the same way you manipulate any ActionScript Object. Specifically,call an ActionScript Object’s methods usingASObject::CallMethod(). See the following example for code that calls theActionScript Array methodpush().ExampleThis example uses a C++ extension methodMyMethod()of the C++ extension class MyExtensionClass. It illustrates:•Verifying that a parameter is an ActionScript Array.36DEVELOPING ACTIONSCRIPT EXTENSIONS FOR FLASH LITE FOR THE DIGITAL HOMECoding an ActionScript extension•Getting the length of the ActionScript Array.•Looping through the array.•Calling a method of the ActionScript Array.void MyExtensionClass::MyMethod(StageWindow * pStageWindow, ASObject & asObject,

ASValueArray & arguments, ASValue & retValToSet)

{

// This is the C++ extension method for the following ActionScript method:

// public function myMethod(colors: Object) : void;

// The first argument passed to myMethod() can be a single ActionScript Object