9.5.1 ActionScript Classes

Classes are always identified with their full class name. A class ID consists of the concatenation of the packages of a class and the class name, each separated by a dot character. To reduce the pain of explicitly type the full ID of a class, import declarations can be used at the top of each class file (or anywhere within an embedded RVML ActionScript block) and are used at compile time to resolve class names to full class identifiers.

Class identifiers are always represented using their full name in all output. Import declarations are not stored in the output SWF.

Class methods can be either private with access restricted to class subclass members, or public and are globally accessible. There are two types of methods: instance methods and class methods.

Methods with a 'get'/'set' prefix are described in below under 'Properties'.

Instances methods are added to the prototype of the class, class methods are added to the class object. KineticFusion will automatically prefix references to class methods with the full class identifier.

There is no private/public qualifiers associated with methods in the output SWF. These qualifiers are used purely for compile-time checks.

Class fields can be either private with access restricted to class subclass members, or public and are globally accessible. There are two types of fields: instance fields and class fields.

Field definitions are not explicitly added to the output class unless initialized, for example:

private var notInitialized:Number;
private var initialized:Number = 1.0;

When not initialized, field values are created only when set. For this reason, if a field is referenced before its value is set, the value of the field will always be 'undefined' instead of 'null'.

When using an instance field initializer, care should be taken to ensure that Object references are not accidentally shared between multiple instances of a class. The field initialization code is executed only once and the result is assigned to the prototype object. This means that all new instances of the class will automatically share any non-primitive value assigned to the field until the field value is explicitly reassigned.

Because initialization code is executed when a class is first defined, the initialization code for instance fields must be a compile-time constant. Any other type of initialization should be carried out in the constructor of the class.

There is no private/public qualifiers associated with fields in the output SWF. These qualifiers are used purely for compile-time checks.

Properties are methods that represent a 'virtual' field that can be updated using normal field syntax. A property is defined for a class if either a 'get' or 'set' method is defined and the name of the property taken from the name of the method.

When a method name is prefixed with the reserved word 'set', the method is automatically transformed to a 'setter' method for a property of the same name. This method is used to set the value of a property and must have a single parameter that represents the new property value. The declared type of the 'set' parameter should always equal the declared return type of a 'get' method, if one is defined. Setter methods should always return 'Void

When a method name is prefixed with the reserved word 'get', the method is automatically transformed to a 'getter' method for a property of the same name. This method is used to retrieve the value of a property and should take no arguments. The method should return an argument of a type that reflects the type of the property. The return type of the 'get' method should always equal the declared parameter type of a 'set' method, if one is defined.

At compile time the property methods are converted to class functions : getter methods are prefixed with '__get__' and setter methods are prefixed with '__set__'. The methods are associated with the class using the intrinsic addProperty() Object method on the class prototype. These methods are not available for reference by any other AS2.0 code.

Classes are always stored in a directory hierarchy corresponding to the package of the class, each package represented in the file system as a sub folder. Multiple separate package hierarchies can be referenced within ActionScript. When locating a class, the User Class Path is searched first, then the System Class Path. These are outlined below.

This class path is normally used to define the location for user classes referenced in RVML documents or by the Class Analyzer. It can be set using the configuration option kinesis.actionscript.userClassPath.

Classes and packages with the same case-sensitive name are not permitted on the user class path. In particular, this means that the intrinsic System and TextField classes and packages cannot be located on this class path.

All classes located on the user class path are subject to the full range of semantic checks implemented by KineticFusion.

This class path is normally used to define the location for intrinsic classes and optional component classes referenced in RVML documents or by the Class Analyzer. It can be set using the configuration option kinesis.actionscript.systemClassPath.

Analysis and compilation of classes located on this path are treated differently than those on the user class path. The key differences are:

• The package names "System" and "TextField" are permitted on this class path. These packages share the same name as classes and this is forbidden by the KineticFusion compiler. However, since these classes and packages are intrinsic and defined within the player, they are permitted.
• All compilation warnings for classes on the system class path are discarded. This is extremely useful when working with class hierarchies from 3rd parties. As it is expected that these hierarchies are tested and stable then warning messages are disabled. This permits a development group to implement coding standards that may conflict with those of 3rd parties. The system class path is a good location to place the V2 component classes, if they are used by the user.

The installation classes directory contains a set of intrinsic class definitions shipped with KineticFusion. On installation, the systemClassPath property in the config/KineticFusion.properties file is set to this directory. On Windows, the installed Macromedia Flash MX 2004 classes are also added to the System Class Path, if it is installed.

Note: the System class path is searched AFTER the user class path so it is possible for a user to override a system class with a class on the user class path.

The Macromedia Flash player provides built-in support for a number of very useful classes. That is, a script can reference classes that are not explicitly defined within the movie e.g. String, Number, XMLNode. While these classes do not need to be included with an SWF movie, the definition of these classes must be available to the ActionScript compiler so it can perform appropriate type checking on all references to these classes, their constructors, methods, fields, and properties. These declarations are known as intrinsic class definitions. They are defined in a class file in the same way as a normal AS2.0 class with the following restrictions:

• The class name must be preceded by the keyword intrinsic
• If field initializers are provided, they must be compile-time constants
• Constructors and method declarations are not permitted to have statement bodies i.e. the declaration must be terminate by semi-colon, not a statement block.

This is a simple example of an intrinsic class definition:

intrinsic class DonkeyClass{
      static var NUM_LEGS:Number = 4;
            
      public var name:String;
      
      // Constructor      
      public function DonkeyClass ( name:String);
      
      // Method
      public function getName():String;
} 

There is nothing special about intrinsic classes; they are just declarations that are used during compiling for semantic analysis. KineticFusion ships with a predefined set of intrinsic classes for the built-in classes of the Macromedia Flash player. These have been compiled from the documentation of the player but some them have been augmented with additional logical restrictions. For example, the intrinsic class definition for the built-in Microphone class is declared as final and has a private constructor to prevent users from creating Microphone objects using the class or from subclassing the Microphone class which could result in Microphone objects being created (Microphone objects should only be created using the static get(index:Number):Microphone method):

/**
 *    Microphone Class
 *    @final
 */
intrinsic class Microphone{
...
    // Private constructor so instances cannot be created programmatically
    private function Microphone();
    
...
} 

Only certain of the shipped intrinsic classes are marked as dynamic classes. Additionally, there are no mixin class definitions (these are additional methods and properties that can be added to a class at runtime e.g. using the AsBroadcaster class) in any of the shipped intrinsic classes. If a developer wishes to add these features or to remove any of the restrictions imposed by the KineticFusion intrinsic classes, simply modify the class definition in the classes installation folder (remembering to make a copy of the directory first to ensure you can revert in future).

KineticFusion has augmented all intrinsic classes with additional constraints defined within Javadoc comments. These constraints are generally used to express the multiple permissible permutations of parameters that are accepted for class methods. These class files can also be easily modified by a developer to add additional constraints or remove constraints (again, do not forget to backup first), and changes are read in immediately by the KineticFusion application.

Another very important use of intrinsic class definitions is when combining AS2.0 classes with AS1.0 classes. There is a lot of existing ActionScript written as AS1.0 classes. In order to be able to refer to these classes from AS2.0 scripts and classes, each AS1.0 class must be defined as an intrinsic class. This allows the ActionScript compiler to check all AS2.0 against the defined class definitions while allowing the developer to reuse existing AS1.0 code without having to migrate it to AS2.0 standards. It is important that the developer remembers to manually include the class definitions as AS1.0 scripts to ensure the class definitions are available at runtime.