Recipe 2.1. Creating a Custom Class


Problem

You want to write a custom class.

Solution

Save a new file with the .as file extension and the filename matching the name of the class. Then add the class definition to the file with the following structure:

package package  {     public class Class {     } }

Discussion

As noted earlier, the class is the basic building block of all ActionScript 3.0-based applications, so it's essential that you master the basics of writing a class. For starters, all classes must be placed in .as files, which are plain text files saved with an .as file extension. There can be only one public class definition per .as file, and the name of the file must be the same as the name of the class. For example, if you name a class Example then the definition must be saved in a file called Example.as.

In ActionScript 3.0 all classes must be placed in packages. A package is a way of organizing classes into groups, and in ActionScript 3.0 a package is synonymous with a directory on the filesystem. Packages are relative to the classpath (which is discussed in detail in Recipe 2.2), but for this initial discussion the classpath is defined as a path relative to the project (the .fla file, in the case of Flash or the main class or MXML document in the case of Flex). Therefore, the top-level package is synonymous with the project's root. The package declaration is always the first thing that appears in a class file; an example syntax follows:

package name { }

When the class is defined as part of the top-level package, the package name doesn't need to be specified. In those cases, the package declaration is as follows:

package { }

When the class file is saved within a subdirectory, the package name corresponds to the relative path of the subdirectory using dots (.) between each directory. For example, if a file is saved in a subdirectory (relative to the project root) called example, then the package declaration is as follows:

package example { }

If the class file is saved in a subdirectory of example called subpackage, the package declaration is as follows:

package example.subpackage { }

Packages are an important part of working with classes because they allow you to ensure that your classes won't conflict with any other classes. For example, it's entirely possible that two developers might write two different classes and name them MessageManager. The two classes could have the same name but be responsible for very different tasks. One might manage emails while the other manages binary socket messages. You cannot have two classes with the same name in the same scope. If you did, the compiler wouldn't know which one to use. One option is to always use unique class names.

In this example, you could name the classes EmailManager and BinarySocket- MessageManager, but there are good reasons why that isn't always possible or preferable. Since a project could use potentially hundreds of classes, it would be very difficult to ensure all the classes have unique names. Furthermore, many projects may rely on preexisting libraries of code, and you may not have written many of the classes. Because many classes in a library might have dependencies on other classes, it would be very difficult to change the names of classes. This is where packages make things much simpler. Even though you cannot have two classes with the same name within the same directory, you can have as many classes with the same name as you want, so long as they are within different directories. Packages allow you to place one MessageManager in the net.messaging.email package and one in the net.messaging.binarysocket package.

Although the preceding package names may initially seem like good choices, it's possible to use better package names to ensure a higher probability of uniqueness. It's generally better to use package names that correspond to the owner and/or relevant project. By convention, package names start with reverse order domain names. For example, if Example Corp (examplecorp.com) writes ActionScript 3.0 classes, they would place all classes in the com.examplecorp package (or a subpackage of com.examplecorp). That way, if another Example Corp from the U.K. (examplecorp.co.uk) also writes ActionScript 3.0 classes, they can ensure uniqueness by using the package uk.co.examplecorp.

The exception to this guideline is when the classes are part of a product or library that transcends company/organization boundaries. For example, all the native Flash Player classes are in the Flash package (for example, flash.net.URLRequest) and all the classes in the ActionScript 3.0 Cookbook library are in the ascb package (see http://www.rightactionscript.com/ascb).


When classes are part of a common library used by many projects within a company/organization then they can be placed in subpackages directly within the main package. For example, if the aforementioned MessageManager classes are part of a common library used by many Example Corp applications then they could be placed in the com.examplecorp.net.messaging.email and com.examplecorp.net.messaging.binary- socket packages. When a class is part of a specific application, it should be placed within a subpackage specific to that application. For example, Example Corp might have an application called WidgetStore. If the WidgetStore application uses a class called ApplicationManager, then it ought to be placed within com.examplecorp.widgetstore or a subpackage of that package.

By convention, package names start with lowercase characters.


The next step is to declare the class itself, as follows:

public class Name { }

The name of a class starts with a capital letter by convention. The name of a class must follow the same naming rules as variables and functions (consists of letters, numbers, and underscores, and cannot start with a number). The class declaration appears within the package declaration. The following code defines a class called Example within the top-level package:

package {     public class Example {     } }

The class body appears within the class declaration's curly braces, and it consists of properties and methods. Properties are variables associated with the class, and you declare them much as you would declare variables by using the var keyword. However, properties also must be modified by attributes, which determine the scope of the property. The following is a list of the attributes you can use with properties:


private

Properties are private when they're accessible only within the class.


public

Properties are public when they're accessible within the class as well as from instances of the class (or directly from the class reference when declared as static).


protected

Properties are protected when they're accessible only within the class and to subclasses.


internal

Properties are internal when they're accessible within the package.

The default state of a property is internal unless you specify a different attribute. In most cases, properties should be declared as either private or protected. By convention, it's helpful to start private and protected property names with an underscore (_). The following declares a new private property called _id within the Example class:

package {     public class Example {         private var _id:String;     } }

Methods are essentially functions associated with a class, and you can declare a method much like you would declare a function using the function keyword. However, as with properties, all methods must belong to a namespace defined by one of the attributes from the previous list. The public, private, protected, and internal attributes work identically for methods and properties. Methods should be declared public only when they need to be called from instances of the class (or from the class itself when declared as static). If the method is designed to be called only from within the class, then it should be declared as private or protected. A method should be protected only when you want to be able to reference it from a subclass. The following declares a method called getId( ):

package {     public class Example {         private var _id:String;         public function getId(  ):String {             return _id;         }     } }

Method names are subject to the same rules as variables and properties. That means that method names must contain only numbers, letters, underscores, and dollar signs. Additionally, while method names can contain numbers, they cannot begin with numbers. By convention, method names start with lowercase characters. There is one exception to that guideline, however. Every class can have a special method with the same name as the class itself. This special method is called the constructor, and as the name implies, you can use the function to construct new instances of the class. In ActionScript 3.0, all constructors must be public (this is a change from ActionScript 2.0). Unlike standard methods, constructors cannot return values, and they must not declare a return type. The following declares a constructor method for the Example class:

package {     public class Example {         private var _id:String;         public function Example(  ) {             _id = "Example Class";         }         public function getId(  ):String {             return _id;         }     } }

The following illustrates how to construct an instance of the Example class:

var example:Example = new Example(  ); trace(example.getId(  )); // Displays: Example Class

See Also

Recipe 2.2




ActionScript 3. 0 Cookbook
ActionScript 3.0 Cookbook: Solutions for Flash Platform and Flex Application Developers
ISBN: 0596526954
EAN: 2147483647
Year: 2007
Pages: 351

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net