Table of Contents

#include path

Arguments

path

A string indicating the name and location of the script file to import, which can be specified relative to the .fla file or as an absolute path (see samples under Example). Note that forward slashes, not backslashes, should be used in the path. Script files should be named with the .as file extension.

Description

The #include directive imports script text from an external text file (preferably one with the .as extension) into the current script, placing it directly where the #include command occurs in the script. If the file can't be found at the specified path, the directive will cause an error and no external text will be included.

The #include operation is performed at compile time, meaning that the text included in a movie is the text that existed at the time the movie was tested, exported, or published from the authoring tool. If the external file changes after the movie is exported, the changes will not be reflected in the movie. In order for the changes to be incorporated into the movie, the movie must be reexported.

Including an external file with the #include directive does not alter the .fla file permanently; nor does it allow you to view the imported file's contents easily. Likewise, if the external file is missing, or if it has changed, the next time the .fla file is recompiled into a .swf, your code may break unexpectedly. To permanently import an external .as file's code and break the connection to the external .as file itself, you must copy and paste the text into the current .fla file (and remove the #include directive).

Note that an #include directive is always executed, even when it is placed inside a conditional statement. For example, the following code does not cause theScript.as to be left out of the movie:

if (false) {
  #include "theScript.as"
}

The #include directive commonly is used to incorporate the same block of code in multiple scripts or across Flash projects (much as you'd use an external asset library). You would do this in order to centralize your code, to maintain code in a version-control system tool (such as CVS or Microsoft Visual Source Safe), or to use an external text editor that you prefer over the ActionScript editor. It is also handy when a programmer is working separately from, say, a graphic artist creating the Flash animations. External files lend themselves well to code repositories, such as a library of classes or functions that are independent of the current timeline or movie clip. They tend to be less useful for code that needs to be integrated tightly with the Flash timeline.

To use international characters in an included file, save the file in UTF-8 format in your text editor, and add the following line to the beginning of the file (note the forward slashes and the space following the two dashes):

//!-- UTF8

The #include directive does not support UTF-16-encoded files.

Nested includes are supported, so a wrapper .as file can be used to include a series of related classes via a single statement, much like a Java package.

The text in an included file is checked when a syntax check is performed using the Check Syntax command (Ctrl-T or Command-T) in the Actions panel menu (found under the arrow button in the upper-right corner of the panel).

Usage

Note that an #include directive begins with a pound sign (#), does not use parentheses, and must not end in a semicolon. Any #include statements that end in a semicolon will cause an error and will not successfully import the external script.

Bugs

In Flash 5, a blank line is required between #include directives. The blank line can be inserted between the directives themselves or in the source of the file being included. This is a known bug that affects Flash 5 only. For example:

// This always works.
#include "file1.as"

#include "file2.as"

// In Flash 5, this only works if there's a blank line at the end of file1.as.
#include "file1.as"
#include "file2.as"

In Flash 5 and Flash MX, if the last line of an included file is a comment, subsequently included files will not be incorporated (they will be commented out by the trailing comment in the previously included file). For example:

// WRONG!
doSomething();  // This comment will disable subsequently included files.
// RIGHT
// This comment is nice and safe.
doSomething();

Example

The following code imports an external .as file, named myScript.as, into the current .fla file. When using a relative path, myScript.as must be in the same folder as the .fla file containing the #include directive:

#include "myScript.as"

We can construct a relative path including a subdirectory. The following assumes that myScript.as is one level down from the current .fla file in a subdirectory named includes:

#include "includes/myScript.as"

Use two dots to indicate the folder above the current folder. The following assumes that myScript.as is one level up from the current .fla file:

#include "myScript.as"

The following assumes that myScript.as is in a subdirectory named includes, adjacent to the subdirectory containing the current .fla file:

#include "includes/myScript.as"

You can also specify an absolute path to any folder, such as:

#include "C:/WINDOWS/Desktop/myScript.as"

but absolute paths are not cross-platform and may need to be changed if you compile the .fla file on a different machine with a different directory structure. Note the differences in the drive letter specification and folder separators on the two platforms:

#include "C:/WINDOWS/Desktop/myScript.as"                // Windows
#include "Mac HD:Desktop folder:working:myScript.as"     // Macintosh

See Also

"Externalizing ActionScript Code," in Chapter 16

Table of Contents