| fscommand( ) Global Function | Flash 3; enhanced in Flash 5 to support "trapallkeys" |
| send a message to the Standalone Player or to the Player's host application (usually a web browser) |
A string passed to the host application, often the name of a JavaScript function.
A string passed to the host application, often an argument to the function named by command.
With the fscommand( ) function, a Flash movie can communicate with the Standalone Player or with the Player's host application�the environment in which the Flash Player is running (usually a web browser, but possibly Macromedia Director or an application that can host ActiveX controls). The fscommand( ) function typically is used in one of three ways:
To send one of a limited set of built-in commands to the Standalone Player
To send commands to a scripting language, such as JavaScript or VBScript, in a web browser
When used with the Standalone Player, fscommand( ) takes one of the built-in sets of command/argument pairs, as shown in Table 18-6. Note that as of Flash 6, the Stage.scaleMode and Stage.showMenu properties are preferred over the "allowscale" and "showmenu" fscommand( ) calls.
|
Command |
Argument |
Description |
|---|---|---|
|
"true" or "false" |
When "false", prevents the contents of a movie from growing or shrinking in relation to the window size of the Player. "allowscale" is often used in combination with "fullscreen" to create a Standalone Player that covers the entire screen while maintaining the movie's original size. See also Stage.scaleMode. |
|
|
"application_name" |
Launches an external application (works in Standalone Player only). The path to the application is specified in the string application_name. In Flash MX, the application must reside in a folder named "fscommand" directly beneath the .swf file (if a .swf file resides in /demo/, the application to launch must reside in /demo/fscommand/). For example, to launch someApp.exe, use "fscommand("exec", "someApp.exe")", without the subfolder name /fscommand/. Attempts to use "exec" with an executable in another directory will fail silently. In Flash 5, the application to launch can reside anywhere on the drive from which the movie was loaded. For details on forming paths for Flash 5 Projectors, see: http://www.macromedia.com/support/flash/ts/documents/fscommand_projectors.htm. |
|
|
"true" or "false" |
When "true", causes the Standalone Player's window to maximize (fill the entire screen). |
|
|
not applicable |
Closes the movie and exits the Standalone Player. |
|
|
"true" or "false" |
When "false", suppresses the display of the controls in the contextual menu of the Player, leaving only minimal options. The contextual menu is accessed via right-click on Windows and Ctrl-click on Macintosh. As of Flash 6, the Stage.showMenu is preferred. |
|
|
"true" or "false" |
When "true", causes all keystrokes�even keyboard shortcuts�to be sent to the Flash movie. "trapallkeys" is used to disable the control keys in the Standalone Player (e.g., Ctrl-F or Command-F for Full Screen mode, Ctrl-Q or Command-Q for Exit, Esc for Stop/exit Full Screen mode, etc.). Added to fscommand in Flash 5. |
When used from within a .swf file playing in a browser, fscommand( ) invokes a special JavaScript function (in Netscape) or VBScript function (in Internet Explorer) on the HTML page that contains the movie. The name of this special function takes the general form movieID_DoFSCommand( ), where movieID is the name specified in the HTML <OBJECT> tag's ID attribute (in Internet Explorer) or the <EMBED> tag's NAME attribute (in Netscape). In the following Example, the <OBJECT> tag's ID attribute is "testmovie", so Internet Explorer executes the VBScript function testmovie_DoFSCommand( ) when the Flash Player invokes an fscommand( ).
When movieID_DoFSCommand( ) is invoked, the values of the fscommand( )'s command and parameters parameters are passed as arguments to the movieID_DoFSCommand( ) function. If no movieID_DoFSCommand( ) function exists in the host HTML page, fscommand( ) fails silently. Although a detailed discussion of writing a movieID_DoFSCommand( ) function in JavaScript or VBScript is beyond the scope of this book, see the following Example for a sample.
Regardless, calls to fscommand(
) won't work unless your HTML
page's <OBJECT> tag
includes the ID attribute, or the
<EMBED> tag includes the
NAME attribute (the latter should not be confused
with the unrelated NAME attributes used in
<OBJECT> tags). These attributes are not
included by default but can be added easily in the authoring tool
under File 
Publish Settings
HTML Template Flash with
FSCommand. See the Example for sample
<OBJECT> and
<EMBED> tags. Note that in order for
fscommand( ) to work with
Netscape, the SWLIVECONNECT attribute of the HTML
<EMBED> tag must be set to
"true" (and don't forget the
NAME attribute, which is also required) as shown
in the Example.
It is not possible to communicate with a browser via fscommand( ) under the following system configurations:
Internet Explorer on the Macintosh OS
Any version of Netscape 6 prior to 6.2 (fscommand( ) in Netscape 6.2 and later requires at least Flash Player 6.0.40.0)
Any browser running on a 68K-series Macintosh
Any browser running on Windows 3.1
Note that fscommand( ) does not always provide the best means of communicating with a Director movie from Flash. The preferred way to communicate with Macromedia Director is via the getURL( ) function using either the event: or lingo: protocol. For details, see the getURL( ) function or the following Macromedia technotes:
To quit a Standalone Player (Projector), use:
fscommand("quit");
To run a Standalone Player fullscreen, use:
fscommand("fullscreen", "true");
To run a Standalone Player fullscreen while maintaining the original movie's size, use:
fscommand("fullscreen", "true");
fscommand("allowscale", "false");
For information on launching a movie in a fullscreen web browser window, see:
The following code shows an HTML page with the JavaScript and VBScript needed to respond to a simple fscommand( ) from a movie. Notice that the VBScript function simply calls the JavaScript function; this allows us to handle both Internet Explorer and Netscape with a single JavaScript function. Note the ID, NAME, and SWLIVECONNECT attributes in bold:
<HTML>
<HEAD>
<TITLE>fscommand demo</TITLE>
<SCRIPT LANGUAGE="JavaScript">
<!--
function testmovie_DoFSCommand(command, args) {
alert("Here's the Flash message " + command + ", " + args);
}
//-->
</SCRIPT>
<SCRIPT LANGUAGE="VBScript">
<!--
Sub testmovie_FSCommand(ByVal command, ByVal args)
call testmovie_DoFSCommand(command, args)
end sub
//-->
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<OBJECT
ID="testmovie"
CLASSID="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
WIDTH="100%"
HEIGHT="100%"
CODEBASE="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab">
<PARAM NAME="MOVIE" VALUE="flash-to-javascript.swf">
<EMBED
NAME="testmovie"
SRC="flash-to-javascript.swf"
WIDTH="100%"
HEIGHT="100%"
SWLIVECONNECT="true"
PLUGINSPAGE="http://www.macromedia.com/go/flashplayer/"
</EMBED>
</OBJECT>
</BODY>
</HTML>
To invoke the preceding testmovie_DoFSCommand( ) JavaScript function from the flash-to-javascript.swf movie, we use:
fscommand("hello", "world");
For more information on fscommand( ) and controlling Flash with JavaScript, see:
