fscommand(), which facilitates communication between a SWF file and its container.| Function | Defined By | ||
|---|---|---|---|
|
Lets the SWF file communicate with either Flash Player or the program hosting Flash Player,
such as a web browser.
| flash.system | ||
| fscommand | () | function |
public function fscommand(command:String, args:String = ""):void
Lets the SWF file communicate with either Flash Player or the program hosting Flash Player,
such as a web browser. You can also use the fscommand() function to pass messages to
Director or to Visual Basic, 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.
You can prevent a SWF file from using this method by setting the
allowNetworking parameter of the the object and embed
tags in the HTML page that contains the SWF content.
For more security-related information, see the following:
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
args 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 (args) | 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. |
Not all of the commands listed in the table are available in all applications:
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 args 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
web page that contains the SWF file. For moviename, supply the name of the Flash object that you used for the
NAME attribute 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 is set by default 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 9, 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 Flash Player 9 Security white paper at
http://www.adobe.com/go/fp9_0_security.
Usage 3: The fscommand() function can send messages to Director (Macromedia Director from Adobe).
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/.
Note: If 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 Director (Usage 3).
Parameters
command:String — A string passed to the host application for any use, or a command passed to Flash Player.
|
|
args:String (default = " |
fscommand() can be used to direct
Flash Player to go into full screen mode and not allow scaling. An orange box is then
added to the stage using draw(). In draw(), a click
event listener is added named clickHandler(), which responds to click
events by directing Flash Player to exit using another call to fscommand().
Note: this example should be executed in the standalone Flash Player and not within a web browser.
package {
import flash.display.Sprite;
import flash.text.TextField;
import flash.system.fscommand;
import flash.events.MouseEvent;
public class FSCommandExample extends Sprite {
private var bgColor:uint = 0xFFCC00;
private var size:uint = 100;
public function FSCommandExample() {
fscommand("fullscreen", "true");
fscommand("allowscale", "false");
draw();
}
private function clickHandler(event:MouseEvent):void {
fscommand("quit");
trace("clickHandler");
}
private function draw():void {
var child:Sprite = new Sprite();
child.graphics.beginFill(bgColor);
child.graphics.drawRect(0, 0, size, size);
child.graphics.endFill();
child.buttonMode = true;
addEventListener(MouseEvent.CLICK, clickHandler);
var label:TextField = new TextField();
label.text = "quit";
label.selectable = false;
label.mouseEnabled = false;
child.addChild(label);
addChild(child);
}
}
}