Flash

Tackling the ActionScript Language Reference

Getting Acquainted

Referrals to the documentation arrive in all flavors, from the gentle, “Chin up! What you’re after is available in the ActionScript Language Reference,” to the sarcastic, “Don’t be afraid of the F1 key…”; from the stern, “Look it up,” to the brutal, “RTFM!” The thing is, you’ve tried, haven’t you? You have hit the F1 key—but then what?

There it is, the Help panel. Check out the angry red stripe. Not very welcoming at all, in spite of what it says. (Open this panel from Help > Help in the file menu or by pressing the F1 key.)

Figure 1.1 Really, where should you even start?

Navigation

Before we dive in, let’s think navigation. When Hansel and Gretel were lost in the woods, they scattered bread crumbs in hopes of providing a trail for the return trip. As it turned out, that wasn’t such a good idea, since birds eat crumbs. Fortunately, you’re not in their shoes: the Help panel contains these four navigation icons, which won’t disappear.

Figure 1.2 Navigation icons.

The first two are just like the Back and Forward buttons on your browser. Wherever you are, you can “step back” to the previous page or “step forward” to an already-visited page in your travels. The book icon takes you to the Table of Contents at any time. The magnifying glass icon allows you to search the entire documentation. Search is my personal favorite.

There are two additional icons. One prints the current page and the other updates the help files . If you haven’t already clicked the Update icon, do it now to ensure you have the latest and greatest.

Ready? Click the Table of Contents icon and let’s begin.

You should see a new column in the Help panel in which subject headings are categorized with blue book icons. Click on the first icon, Welcome, to see a number of subheadings represented by page icons.

The first option, Welcome to Help, leads back to the red-striped intro page you’ve already seen. New User Topics may interest you if you’re brand new to Flash; topics include learning about the workspace, creating a document and setting its properties, adding media content, using Timeline effects, and more. Flash Designer Topics are useful to designers (people whose main interest is graphics, rather than programming). Finally, Flash Developer Topics provide a good starting point for someone like you—someone who is interested in programming in Flash.

Flash Developer Topics

The subheadings under Flash Developer Topics are very useful. The first provides a number of tutorials. The second two, “Read about the ActionScript language” and “Read about working with ActionScript,” are mini essays. They’re quick reads, honestly, and will give you a crash course in ActionScript fundamentals. If you read these two sections, you will be ahead of the curve. If nothing else, read “ActionScript basics overview” and you will know more about ActionScript than 65% of the people posting questions, easily. (That’s an unofficial estimate, of course; just my own opinion based on the kinds of questions I see. Sometimes I feel it’s a conservative estimate.)

You think I’m kidding? Let’s take a quick look at the information you get from these sections. Please note, I’m only skimming here, but these are the topics that generate a bulk of daily forum questions.

Terminology Variables, functions, methods, parameters, constructors, on and on. What do all these words mean? This section gives you bona fide, official, useful definitions.
Syntax Parentheses, curly braces, semicolons, slashes … what are all these punctuation marks for? This section provides a great overview.
About data types Eh, what are those? In this section, you’ll learn about the characteristics your variables can take. How does a String differ from a Number or a Boolean? When do you have to use quotes? How can you add special characters, such as line breaks and tabs, to your variables? Find out here.
About variables For that matter, what are variables?
Specifying an object’s path Very important. Many, many people have their logic worked out properly, but fail to path correctly to the necessary objects. Make sure you understand this section.
Using conditional statements if() statements, switch() statements, and more. This is where programmatic decision making begins.

I have participated in discussion threads where people insist they don’t have time to read this material. I’ve seen these same people come back again and again, frustrated because they don’t understand the terminology, perplexed because they “found some code” but discover it doesn’t do exactly what they need; they “just need it to do this,” yet don’t know where to begin.

Tip: read these introductory articles and you will have a major head start.

Searching

All right. You may feel comfortable with ActionScript fundamentals, but you’re still stuck. The Search icon (magnifying glass) is your friend. In fact, once you familiarize yourself with the basics, this may be the first icon you click every time.

Narrowing the field

Let’s say you want your movie to link to a new URL when someone clicks a button on the Stage. This is a common undertaking. In our hypothetical scenario, you have typed the following incorrect code, but don’t know why it fails.

		myButton.onRelease = function() {
			getURL(http://www.mydomain.com);
		}

As with any troubleshooting situation, it’s a good idea to narrow the field. In this small example, there are two points of possible failure: A) something is wrong with our button code or B) something is wrong with the code inside the button (namely, the getURL() function). Let’s use trace() to make sure our button works at all. We’ll have the button trace a message to the Output panel and temporarily comment out the other line. If the button works, we will have reduced our possibilities to getURL() and will have something to look up in the Language Reference. Here’s our trace:

		myButton.onRelease = function() {
			trace("Button is working");
			// getURL(http://www.mydomain.com);
		}

Aha! Upon clicking the button, we find the phrase “Button is working” in the Output panel. So the button works fine, and our trouble is indeed caused by getURL(). Let’s look it up!

There are two tabs in the Help window, “Help” and “How Do I…” Click Help, then the Search icon. Type getURL() (with parentheses) in the search field and click the Search button.

Wow, quite a few matches show up! Since the ActionScript Language Reference is our dictionary, we don’t need anything from the Using Flash or Using ActionScript in Flash sections. It may come as a surprise to see we have six matches (didn’t we want only one thing?), but don’t panic, we’ll narrow it down. Of the Language Reference choices—getURL(), loadVariables(), loadVariablesNum(), MovieClip class, MovieCLip.getURL(), and System.useCodepage—which ones make the most sense? Probably getURL() and possibly MovieClip.getURL(). Between those two, let’s stick with the simpler stand-alone getURL(). After all, we haven’t prefaced our usage of this function with the instance name of a movie clip. It stands by itself, so getURL() it is. Double click.

Anatomy of a reference entry

Almost every dictionary entry in the ActionScript Language Reference contains the following useful headings. Let’s step through them one by one.

Availability

This is where you learn which version of the Flash Player first supported the term in question. In our example, we learn that getURL() has been available since Flash Player 2, which makes this function very reliable: everyone with plug-in version 2 or higher will successfully see this function execute. We also learn that the GET and POST options have been available since Flash Player 4. Useful stuff!

The Availability heading is especially helpful with some of the more recent features—for example, MovieClip.getNextHighestDepth(), which is only available since Flash Player 7. If the requirements of your project dictated, for example, that accommodations must be made for Flash Player 6, you would know by reading this heading that you’d have to find another way to achieve the functionality provided by this method.

Usage

This section is often a tough one for beginners, since some of the punctuation doesn’t actually belong in your ActionScript. In Usage, you would be misled to follow what you see to the letter, so let’s uncover what’s going on here.

getURL() happens to be a function, and functions are triggered by parentheses. Not all functions receive parameters, but those that do (like this one), receive their parameters between those parentheses. Thing is, this entry also shows square brackets and colons—none of which are in your own ActionScript—so what gives?

In the Usage section, brackets show which parameters are required and which are optional. Bracketed parameters are optional. In our case, the first parameter, url, is not contained within brackets, so we know this parameter is required. (After all, where would getURL() send the browser if no URL was provided?) The second and third parameters are within brackets and are therefore optional. You can verify this information by checking against the Parameters section below.

Now, what about those colons? The “post colon suffix,” as it is referred to by Colin Moock in his excellent Essential ActionScript 2.0, indicates the datatype of the parameter in question. The fact that url has :String after it tells you the first parameter must be a string. In fact, this solves our problem. In our code, the URL is not wrapped in quotation marks, which means it isn’t a string. Bingo! So let’s put those quotation marks in place and remove the earlier trace() statement …

		myButton.onRelease = function() {
			getURL("http://www.mydomain.com;");
		}

For interest’s sake, note that parameters two and three, if we had been using them, would also be strings. The :Void after the final parenthesis tells us the dataype returned by this function. As it happens, getURL() returns nothing (a fact also summarized in the Returns section below), and this suffix tells us as much. In contrast, something like String.split()—completely different entry, but for fun, look it up!—accepts a string and an optional number. It returns an array.

Parameters

What Usage gives as quick-and-dirty, the Parameters section breaks out in detail. Note that each of the aforementioned parameters, required or not, is elaborated nicely.

Returns

This section states the datatype of the given function or method’s return value. Any function might return a value, but getURL() doesn’t, so this section states “Nothing.”

Description

This section describes in “plain English” what the search term does. If you still don’t “get it” after reading the Usage and Parameters sections, try this and the Example section below.

Example

Not every search term provides examples—and unfortunately, some that do are confusing or overly complex (for an example, see MovieClipLoader.loadClip())—but for the most part, the sample code in this section is your friend.

Note in your own Language Reference that information is given for how make getURL() send email messages from Flash and how to communicate with JavaScript.

Conclusion

The ActionScript Language Reference has more useful information than you might have expected. Though not perfect, the Language Reference provides an respectable account of ActionScript and how to use it. You’re likely to find answers much quicker by using the built-in Search icon than by posting and waiting, sometimes for days, before an expert happens upon your issue.

Quip.net - David Stiller Résumé

Tutorials