Built-In Object Classes

In the next section, we'll briefly review many of the built-in object classes that ActionScript provides, as well as some ways they are used. Before we do, however, it's important to discuss how to actually get instances of classes into your project in the first place, so you can begin to utilize their power and functionality.

You can create object instances in one of two ways. To create a new instance of the MovieClip, Button, or TextField class, you create it on the stage or drag it onto the stage from the library. However, only MovieClip, Button, and TextField instances can be created in this way. To create an instance of any other class, you must use a constructor a simple line of code that tells Flash to create an object instance of a particular class. A constructor looks like this:

 nameOfInstance:nameOfClass = new nameOfClass(); 

If you wanted to create an instance of the Sound class, the constructor would look like this:

 mySound:Sound = new Sound(); 

Whenever you create an object instance, you must give it a unique name. This allows you to change a property or invoke a method as it relates to that particular instance (remember, an instance inherits all the properties and methods of the class to which it belongs). We'll demonstrate the concept in examples. As you gain programming experience, you'll begin to understand when you should use constructors.

While instances of the MovieClip, TextField, and Button classes can be created on the stage manually by dragging them from the library, they can also be created dynamically using ActionScript.

NOTE

Object names follow the same naming conventions as variables, which means they can't contain spaces, symbols, or a number as the first character.

Some object classes are known as top-level classes, which means you can't create instances of them using the methods we've shown. What differentiates these classes from those of which you create instances? Top-level classes represent and control global functionalities within your project. Take, for example, the Mouse class, which controls cursor visibility (among other things). You have just one cursor, so it wouldn't make sense to be able to create instances of this class; instead, you use the methods available to it, to do various things with the mouse. Look at the example:

 Mouse.hide() 

This line of script hides the cursor. Notice that the name of an instance is not referenced in relation to the hide() method. Instead, the name of the top-level class is referenced (in this case, Mouse), followed by the name of the method you wish to use. Similar syntax is used with any top-level class. As we go through the rest of this lesson, we'll introduce you to other top-level classes and the syntax required to use them.

In the Actions panel under the Built-in Classes book, you can access all of Flash's built-in classes, each of which is contained in one of these five subbooks:

• Core. These classes deal with information storage and manipulation, not including information that's being moved into or out of Flash itself.

• Media. These classes assist with manipulating sound and video in your Flash movie, such as playing sounds, gaining access to the system camera, and streaming video.

• Movie. These classes deal with visual content and system-related information such as movie clips, text fields, the stage, and accessibility.

• Client/Server. These classes control the movement of information in and out of Flash.

• Authoring. These classes assist you in creating custom actions and custom components.

The following describes many of the built-in classes available in ActionScript as well as where and how you might use them. We'll indicate whether a class is a top-level class (creating instances is not required), or not, in which case you must create individual instances.

Accessibility Class (Top-Level)

This class contains read-only information about the computer's ability to use a screen reader:

 Accessibility.isActive(); 

This script returns a result of either true or false. If the result is true, the user's computer can employ a screen reader.

Array Class (Instances)

An array is a storage device for multiple pieces of information. Arrays store information that can be set and referenced using a numbering system. For example:

 var cakeType:Array = new Array(); cakeType[0] = "Chocolate"; cakeType[1] = "Angel Food"; cakeType[2] = "Baked Alaska"; 

The first line creates a new instance of the Array class called cakeType using the Array constructor. The next lines place data inside that array.

The Array class contains many useful methods that will help you add, remove, and sort array items from instances of that class.

NOTE

For more on arrays, see Lesson 6, "Creating and Manipulating Data."

Boolean Class (Instances)

Instances of the Boolean class store one of two values, true or false. You can create a Boolean object by using the Boolean constructor or by using the = assign operator. For example:

 var toggle:Boolean = new Boolean(false); 

and

 var toggle:Boolean = false; 

create identical objects.

Button Class (Instances)

When you place a button on the stage, you create an instance of the Button class. Only MovieClip and TextField objects are created in a similar fashion that is, by placing actual instances on the stage. The Button class contains properties and methods that allow you to control the appearance, tab order, functionality, and more of button instances.

Capabilities Class (Top-Level)

This class contains information about the user's computer, such as screen resolution and whether it can play sounds. The following script places the horizontal resolution of the user's computer into myVariable:

 var myVariable:Number = System.capabilities.screenResolutionX; 

TIP

Being able to access computer information allows you to create movies that tailor themselves to the capabilities of your user's computer. For example, you can determine whether a handheld computer is accessing the movie and, if so, redirect the user to a page designed expressly for handheld devices.

Color Class (Instances)

You use an instance of this class to change a movie clip's color dynamically. When you create a Color object, you point it at a particular movie clip. Using the Color class's methods, you can alter your movie clip's color. You create a Color object using the Color class constructor method:

 var myColor:Color = new Color(pathToTimeline); 

Later in this lesson you'll complete an exercise using an instance of the Color class.

ContextMenu Class (Instances)

The context menu is the menu seen in the Flash player when you right-click (Control-click on the Macintosh). This class is used in conjunction with instances of the ContextMenuItems class (described shortly) to create customized context menus (with custom commands), which appear when the user right-clicks (or Control-clicks) a visual element in the Flash player window. This class also allows you to enable or disable any and all of the built-in context menu commands (such as Play, Stop, and Print) even as your movie plays.

This script creates a new ContextMenu object named myCustomMenu:

 var myCustomMenu:ContextMenu = new ContextMenu(); myCustomMenu.hideBuiltInItems(); myCustomMenu.builtInItems.print = true; myMovieClip_mc.menu = myCustomMenu; myButton_btn.menu = myCustomMenu; myTextField_txt.menu = myCustomMenu; 

The second line of the script uses the hideBuiltInItems() method to hide all the built-in menu commands, and the third line enables the Print command so that it will appear when the menu is opened. The last three lines assign the custom menu to a movie clip, button, and text field instance. Right-clicking (or Control-clicking) any of these instances will cause the custom menu to appear.

ContextMenuItems Class (Instances)

This class is used in conjunction with the ContextMenu class (described just above) to create items that appear in a custom context menu. Your Flash project can be scripted to capture when a user clicks a custom menu item so that you can have a specific action or actions occur. For example, you can create a custom context menu that will allow a user to right-click in your project and choose to mute the volume.

NOTE

You will see more on the ContextMenu and ContextMenuItems classes in Lesson 20, "Maximum-Strength SWFs".

Date Class (Instances)

With this class you can access the current time as local time or Greenwich Mean Time, as well as easily determine the current day, week, month, or year. To create a new instance of the Date class, you use the Date class constructor method. This example demonstrates one use of the Date class:

 var now:Date = new Date(); var largeNumber:Number = now.getTime(); 

The example creates a variable called largeNumber, whose value is the number of milliseconds since midnight January 1, 1970.

NOTE

We will use the Date object in Lesson 16, "Time- and Frame-Based Dynamism."

Error Class (Instances)

The Error class was introduced in Flash MX 2004 to help with managing errors in your projects. An error is whatever you define an error to be (a number was too large or too small, for example). When an error occurs, a new instance of the Error class is instantiated this is known as "throwing" an error. With the Error class you can capture errors and write code to handle them so that your application behaves well, rather than acting in an unpredictable way.

NOTE

You will see more on the Error class in Lesson 19, "Testing and Debugging."

Key Class (Top-Level)

You use the Key class to determine the state of the keys on the keyboard for example, whether the Caps Lock key is toggled on, which key was pressed last, and which key or keys are currently pressed.

You will complete an exercise using this object later in this lesson.

LoadVars Class (Instances)

Flash allows you to load data into a movie from an external source. Using the LoadVars class, Flash can load in variables from a specified URL (which can be a standard text file). For example:

 var myObj:LoadVars = new LoadVars(); myObj.load("http://www.mysite.com/myFiles/file.txt"); 

In the example, all of the loaded variables become properties of the myObj LoadVars instance.

Math Class (Top-Level)

With the Math class, you can perform many useful calculations and have the result returned. Here's one:

 var positiveNumber:Number = Math.abs(-6); 

The script uses the absolute value method of the Math object to convert the 6 to a positive number.

Mouse Class (Top-Level)

The Mouse class controls cursor visibility and allows you to set up Listeners to track mouse activity. Here is an example:

 Mouse.hide(); 

The script hides the mouse from view. The mouse is still active, but it is not visible.

MovieClip Class (Instances)

You create instances of this most familiar class either in the authoring environment (by placing them on the stage), or with ActionScript actions such as createEmptyMovieClip() and duplicateMovieClip() not by using the constructor function. Movie clip instances have many properties and methods that are used frequently in an interactive project. Here's an example:

 myClip_mc.gotoAndStop("Menu"); 

With this script, a movie clip with an instance name of myClip_mc will be sent to the frame labeled Menu.

MovieClipLoader Class (Instances)

This class provides a way for you to easily load and gain access to information during the load of an SWF or JPG into a target movie clip or level. With an instance of the MovieClipLoader class, you know the file size of the external asset you are loading as well as how much of it has been loaded. By continually checking to see how much of the asset has been loaded, you can build a progress bar that indicates how far along an asset is in the loading process.

The MovieClipLoader class also provides a way for you to be informed of when the asset has finished loading.

NOTE

This class will be used in Lesson 18, "Loading External Assets."

NetConnection Class (Instances)

The NetConnection class is used together with the NetStream class to play external Flash Video (FLV) files from an HTTP address or a hard drive.

NetStream Class (Instances)

The NetStream class provides methods and properties for controlling the playback of external Flash Video (FLV) files.

NOTE

You will see more on the NetConnection and NetStream classes in Lesson 18, "Loading External Assets."

Number Class (Top-Level)

You can create a Number class instance by using its constructor method or by assigning a number as the value of a variable. For instance:

 var age:Number = new Number(26); 

is equivalent to:

 var age:Number = 26; 

The new Number() constructor method is rarely used, however, because creating a new number without the constructor takes less effort and achieves the same result.

Object Class (Instances)

No, it's not a typo: there is an Object class! You can use this generic class which is also known as ActionScript's root class (meaning it's the highest in the class hierarchy) in various ways. By employing the properties and methods available to it, you can affect and modify other object classes (such as those listed in this section). It also comes in handy for creating object instances that hold information about the current user, or instances that track chunks of related data (to name just a couple of uses).

The following is the syntax for creating a generic object:

 var names:Object = new Object(); names.cat = "Hayes"; 

The first line of script creates a new object called names. The second line adds a variable (property) to the object called cat. The variable is considered a property of this object.

In Lesson 7, "Creating Custom Classes," we'll show you how to create your own custom classes of objects (better than generic objects!) as well as how to create properties and methods for your custom class. Once you know how to do this, you can create objects and classes that do precisely what you want.

PrintJob Class (Instances)

Previous versions of Flash left much to be desired in the area of printing. For example, various frames on the timeline had to be specified as printable before the movie was exported to an SWF file. In addition, printing content from multiple timelines opened multiple Print dialog boxes. Flash MX 2004 provides a much-improved way to handle printing. With the PrintJob class you are able to dynamically specify frames from various timelines to print from a single Print dialog box.

NOTE

This class is used in Lesson 21, "Printing and Context Menus."

Selection Class (Top-Level)

You use the Selection class to retrieve information or set characteristics relating to selected items in your movies, especially text in text fields. When the cursor is in an area of a text field, that field is said to be "in focus." You can employ the Selection class to set the focus to a specific text field, to find out which text field is currently in focus, or even to programmatically select specific chunks of text in a field so that it can be manipulated in some way. Here's an example of one use of the Selection class:

 Selection.setFocus("firstName"); 

The script sets into focus the input text field with the instance name of firstName.

You'll complete an exercise using this class later in this lesson.

Sound Class (Instances)

You use instances of the Sound class to control sounds for example, setting volume and adjusting left and right speaker pan settings. To learn more about this class, see Lesson 17, "Scripting for Sound."

Stage Class (Top-Level)

With the Stage class, you can control and get information about characteristics of the stage, such as alignment. For example:

 Stage.height 

The script returns the height of the stage in pixels.

String Class (Instances)

You use the String class to manipulate and get information about strings of text. You can create a new string by using the String class constructor method or by putting quotes around a value when setting a variable. For example:

 var bird:String = new String("Robin"); 

is the same as:

 var bird:String = "Robin"; 

You'll use this class to complete an exercise later in this lesson.

StyleSheet Class (Instances)

The StyleSheet class is used to define a set of style rules for text. It can then be applied to a text field which makes the text in that text field adhere to the style rules (such as font size and color). The StyleSheet class is useful because you can have several text fields use the same style. If you decide to change something about the style, such as the text color, then all the text fields that use the style will be affected. In addition, external Cascading Style Sheet (CSS) files can be used, providing a way to achieve a uniform look to text content both on your CSS-enhanced Web pages and the Flash content embedded in them (since both can make use of a single style sheet definition). This script creates a new StyleSheet object, then loads an external CSS file into that object.

 var myStyleSheet = new TextField.StyleSheet(); myStlyeSheet.load("externalStyleSheet.css"); 

NOTE

The StyleSheet class will be used in more detail in Lesson 14, "Working with Text Fields."

System Class (Top-Level)

This class contains information about your user's computer system, such as the operating system, the language being used, and all the properties of the Capabilities object.

One of the System class's properties is a string called serverString that contains a list of the system capabilities (concatenated into one string). You can send this list to the server so that you can store or use the information it contains. To access the string, use:

 System.capabilities.serverString 

TextField Class (Instances)

Using this class, you can dynamically create a new text field and control most of its characteristics for example, setting the format of the text field or the scrolling of text. Instances of this class are created when a text field is placed on the stage while you're authoring your movie, or created dynamically using the createTextField() method. We'll use this object later in this lesson.

TextFormat Class (Instances)

Instances of the TextFormat class are used to change the format/style of text displayed in text fields. Once it's created, you apply the instance of the TextFormat class to a text field using the setTextFormat()or setNewTextFormat() methods:

 nameOfTextField_txt.setTextFormat(nameOfFormatObject); 

XML Class (Instances)

XML is one of the most popular standards for formatting data it's no surprise when you consider that XML-formatted data lets all kinds of applications transfer information seamlessly. Using Flash, you can create an XML object (which is an instance of the XML class) to store an XML-formatted document that can then be sent from or loaded into XML objects. Here's one use of the XML object:

 var myXML:XML = new XML(); myXML.load("myFile.xml"); 

The script creates a new XML object and loads an XML-formatted file into that object.

NOTE

In Lesson 12, "Using XML with Flash," you will learn more about using the XML class.

XMLSocket Class (Instances)

Flash also allows you to set up a persistent connection with a socket server an application that runs on a Web server. The socket server waits for users to connect to it. Once connected, the socket server can transfer information between all connected users at very fast speeds, which is how most chat systems and multiplayer games are created. An XML socket is so named because it uses the XML format as the standard for transferred information.

You can create an XMLSocket object instance by using the XMLSocket class constructor method. The following is an example of one use of this type of object:

 var mySocket:XMLSocket = new XMLSocket(); mySocket.connect("http://www.electrotank.com", 8080); 

This script creates a new instance of the XMLSocket class and opens up a connection with a socket server. See Lesson 12, "Using XML with Flash," for a detailed description of socket servers and the XMLSocket class, as well as an exercise in creating your own chat application.

Covering every built-in class in detail is beyond the scope of this book. However, throughout the lessons we'll use many of these classes in various ways, and provide detailed instructions about how and why we're using them. The following exercises will concentrate on just a few of these classes to give you a general idea of how you can use them.