fscommand()

Availability

Flash Player 3.

Usage

fscommand("command", "parameters")

Parameters

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

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

Returns

Nothing.

Description

Function; allows the SWF file to communicate with either Flash Player or the program hosting Flash Player, such as a web browser. You can also use the fscommand action to pass messages to Macromedia Director, or to Visual Basic, Visual C++, and other programs that can host ActiveX controls.

Usage 1: To send a message to Flash Player, you must use predefined commands and parameters. The following table shows the values you can specify for the command and parameters parameters of the fscommand action to control a SWF file playing in Flash Player (including projectors):

Command	Parameters	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` dims all the context menu items except About Flash Player.
`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.

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 fscommand exec command to call an application, the application must reside in a subdirectory named fscommand.

Usage 2: To use the fscommand action 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 are used in a JavaScript function that "catches," or handles, the fscommand action.

In a web browser, the fscommand action calls the JavaScript function moviename_DoFScommand in the HTML page containing the SWF file. The moviename is the name of the Flash Player as assigned by the NAME attribute of the EMBED tag or the ID property of the OBJECT tag. If you assign the Flash Player the name myDocument, the JavaScript function called is myDocument_DoFScommand.

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

Usage 4: In Visual Basic, 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.macromedia.com/support/flash.

Example

Usage 1: In the following example, the fscommand action sets the Flash Player to scale the SWF file to the full monitor screen size when the button is released.

on(release){
  fscommand("fullscreen", true);
}

Usage 2: The following example uses the fscommand action applied to a button in Flash to open 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 HTML page that contains the SWF file. This function, myDocument_DoFSCommand sits in the HTML page and waits for an fscommand action in Flash. When an fscommand is triggered in Flash (for example, when a user presses 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 (or "message box") opens and displays the contents of the parameters string.

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

In the Flash document, add the fscommand action to a button:

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

You can also use expressions for the fscommand action and parameters, as in the following example:

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

To test the movie, choose File > Publish Preview > HTML.

Note: If you publish your SWF file using the Flash with FSCommand template in the HTML Publish Settings, the myDocument_DoFSCommand function is inserted 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.