Flash CS4 Professional ActionScript 2.0

fscommand function

fscommand(command:String, parameters:String) : Void

Lets the SWF file communicate with either Flash Player or the program that is hosting Flash Player, such as a web browser. You can also use the fscommand() function to pass messages to Macromedia Director, or to Visual Basic (VB), Visual C++, and other programs that can host ActiveX controls.

The fscommand() function lets a SWF file communicate with a script in a web page. However, script access is controlled by the web page's allowScriptAccess setting. (You set this attribute in the HTML code that embeds the SWF file--for example, in the PARAM tag for Internet Explorer or the EMBED tag for Netscape. When allowScriptAccess is set to "never", a SWF file cannot access web page scripts. With Flash Player 7 and later, when allowScriptAccess is set to "always", a SWF file can always access web page scripts. When allowScriptAccess is set to "sameDomain", scripting is allowed only from SWF files that are in the same domain as the web page; scripting is always allowed with previous versions of Flash Player. If allowScriptAccess is not specified in an HTML page, the attribute is set by default to "sameDomain" for SWF files of version 8 and later, and to "always" for SWF files of version 7 and earlier.

Usage 1: To use fscommand() to send a message to Flash Player, you must use predefined commands and parameters. The following table shows the values that you can specify for the fscommand() function's command and parameters parameters. These values control SWF files that are playing in Flash Player, including projectors. (A projector is a SWF file saved in a format that can run as a stand-alone application--that is, without Flash Player.)

Command

Parameter

Purpose

quit

None

Closes the projector.

fullscreen

true or false

Specifying true sets Flash Player to full-screen mode. Specifying false returns the player to normal menu view.

allowscale

true or false

Specifying false sets the player so that the SWF file is always drawn at its original size and never scaled. Specifying true forces the SWF file to scale to 100% of the player.

showmenu

true or false

Specifying true enables the full set of context menu items. Specifying false hides all of the context menu items except About Flash Player and Settings.

exec

Path to application

Executes an application from within the projector.

trapallkeys

true or false

Specifying true sends all key events, including accelerator keys, to the onClipEvent(keyDown/keyUp) handler in Flash Player.

Availability:

  • None of the commands described in the table are available in web players.
  • All of the commands are available in stand-alone applications, such as projectors.
  • Only allowscale and exec are available in test-movie players.

The exec command can contain only the characters A-Z, a-z, 0-9, period (.), and underscore (_). The exec command runs in the subdirectory fscommand only. In other words, if you use the exec command to call an application, the application must reside in a subdirectory named fscommand. The exec command works only from within a Flash projector file.

Usage 2: To use fscommand() to send a message to a scripting language such as JavaScript in a web browser, you can pass any two parameters in the command and parameters parameters. These parameters can be strings or expressions, and they are used in a JavaScript function that handles, or catches, the fscommand() function.

In a web browser, fscommand() calls the JavaScript function moviename_DoFScommand, which resides in the webpage that contains the SWF file. For moviename, supply the name of the Flash object that you used for the NAMEattribute of the EMBED tag or the ID property of the OBJECT tag. If you assign the SWF file the name myMovie, the JavaScript function myMovie_DoFScommand is called.

In the web page that contains the SWF file, set the allowScriptAccess attribute to allow or deny the SWF file's ability to access the web page. (You set this attribute in the HTML code that embeds the SWF file--for example, in the PARAM tag for Internet Explorer or the EMBED tag for Netscape.) When allowScriptAccess is set to "never", outbound scripting always fails. When allowScriptAccess is set to "always", outbound scripting always succeeds. When it is set to "sameDomain", scripting is allowed only from SWF files that are in the same domain as the web page. If allowScriptAccess is not specified in a web page, it defaults to "sameDomain" for Flash Player 8, and to "always" for previous versions of Flash Player.

When using this function, consider the Flash Player security model. For Flash Player 8, the fscommand() function is not allowed if the calling SWF file is in the local-with-file-system or local-with-network sandbox and the containing HTML page is in an untrusted sandbox. For more information, see the following:

  • Chapter 17, "Understanding Security," in Learning ActionScript 2.0 in Flash
  • The Flash Player 9 Security white paper at http://www.adobe.com/go/fp9_0_security
  • The Flash Player 8 Security-Related API white paper at http://www.adobe.com/go/fp8_security_apis

Usage 3: The fscommand() function can send messages to Macromedia Director. These messages are interpreted by Lingo (the Director scripting language) as strings, events, or executable Lingo code. If a message is a string or an event, you must write the Lingo code to receive the message from the fscommand() function and carry out an action in Director. For more information, see the Director Support Center at www.adobe.com/support/director.

Usage 4: In VisualBasic, Visual C++, and other programs that can host ActiveX controls, fscommand() sends a VB event with two strings that can be handled in the environment's programming language. For more information, use the keywords "Flash method" to search the Flash Support Center at www.adobe.com/support/flash.

NOTEIf you are publishing for Flash Player 8 or later, the ExternalInterface class provides better functionality for communication between JavaScript and ActionScript (Usage 2) and between ActionScript and VisualBasic, Visual C++, or other programs that can host ActiveX controls (Usage 4). You should continue to use fscommand() for sending messages to Flash Player (Usage 1) and Macromedia Director (Usage 3).

Availability: ActionScript 1.0; Flash Player 3

Parameters

command: String - A string passed to the host application for any use, or a command passed to Flash Player.

parameters: String - A string passed to the host application for any use, or a value passed to Flash Player.

Example

In the following example, fscommand() sets Flash Player to scale the SWF file to the full monitor screen size when the fullscreen_btn or unfullscreen_btn button is released:

this.fullscreen_btn.onRelease = function() {
 fscommand("fullscreen", true);
};

this.unfullscreen_btn.onRelease = function() {
 fscommand("fullscreen", false);
};


The following example applies fscommand() to a button in Flash for the purpose of opening a JavaScript message box in an HTML page. The message itself is sent to JavaScript as the fscommand parameter.

You must add a function to the web page that contains the SWF file. This function, myDocument_DoFSCommand(), waits for an fscommand() call. When fscommand() is triggered in Flash (for example, when a user clicks the button), the command and parameter strings are passed to the myDocument_DoFSCommand()function. You can use the passed strings in your JavaScript or VBScript code in any way you like. In this example, the function contains a conditional if statement that checks to see if the command string is "messagebox". If it is, a JavaScript alert box displays the contents of the fscommand() function's parameters string.

function myDocument_DoFSCommand(command, args) {
 if (command == "messagebox") {
 alert(args);
 }
}

In the Flash document, add fscommand() to a button:

fscommand("messagebox", "This is a message box called from within Flash.")

You can use expressions for the parameters of the fscommand() function, as shown in the following example:

fscommand("messagebox", "Hello, " + name + ", welcome to our website!")

To test the SWF file, select File > Publish Preview > HTML. If you publish your SWF file using the Flash with FSCommand template (in the Publish Settings dialog box, select the HTML tag), Flash inserts the myDocument_DoFSCommand() function automatically. The SWF file's NAME and ID attributes will be the filename. For example, for the file myDocument.fla, the attributes would be set to myDocument.

See also

ExternalInterface (flash.external.ExternalInterface)