Flash CS4 Professional ActionScript 2.0

Using the fscommand() function

NOTE

 

The External API is a replacement for fscommand() in Flash 8 and later for interoperating with a HTML page or a container application. The External API offers more robust functionality than fscommand() in this situation. For more information, see About the External API.

You use the fscommand() function to send a message to whichever program is hosting Flash Player, such as a web browser.

NOTE

 

Using the fscommand() to call JavaScript does not work on the Safari or Internet Explorer browsers for the Macintosh.

The fscommand() function has two parameters: command and arguments. To send a message to the stand-alone version of Flash Player, you must use predefined commands and arguments. For example, the following event handler sets the stand-alone player to scale the SWF file to the full monitor screen size when the button is released:

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

The following table shows the values you can specify for the command and arguments parameters of fscommand() to control the playback and appearance of a SWF file playing in the stand-alone player, including projectors.

NOTE

 

A projector is a SWF file saved in a format that can run as a stand-alone application--that is, embedding Flash Player with your content in an executable file.

Command

Arguments

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 Settings and About Flash Player.

exec

Path to application

Executes an application from within the projector.

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 arguments parameters. These parameters can be strings or expressions and are used in a JavaScript function that "catches," or handles, the fscommand() function.

An fscommand() function invokes the JavaScript function moviename_DoFSCommand in the HTML page that embeds the SWF file, where moviename is the name of Flash Player as assigned by the name attribute of the embed tag or the id attribute of the object tag. If the SWF file is assigned the name myMovie, the JavaScript function invoked is myMovie_DoFSCommand.

 To use fscommand() to open a message box from a SWF file in the HTML page through JavaScript:

  1. Create a new FLA file, and save it as myMovie.fla.
  2. Drag two instances of the Button component to the Stage and give them the instance names window_btn and alert_btn, respectively, and the labels Open Window and Alert.
  3. Insert a new layer on the Timeline, and rename it Actions.
  4. Select Frame 1 of the Actions layer, and add the following ActionScript in the Actions panel:
    window_btn.onRelease = function() {
        fscommand("popup", "http://www.adobe.com/");
    };
    alert_btn.onRelease = function() {
        fscommand("alert", "You clicked the button.");
    };
    
    
  5. Select File > Publish Settings, and make sure that Flash with FSCommand is selected in the Template menu on the HTML tab.
  6. Select File > Publish to generate the SWF and HTML files.
  7. In an HTML or text editor, open the HTML file that was generated in step 6 and examine the code. When you published your SWF file using the Flash with FSCommand template on the HTML tab of the Publish Settings dialog box, some additional code was inserted in the HTML file. The SWF file's NAME and ID attributes are the filename. For example, for the file myMovie.fla, the attributes would be set to myMovie.
  8. In the HTML file, add the following JavaScript code where the document says // Place your code here.:
    if (command == "alert") {
        alert(args);
    } else if (command == "popup") {
        window.open(args, "mmwin", "width=500,height=300");
    }
    
    

    (For more information about publishing, see Using Flash.)

    Alternatively, for Microsoft Internet Explorer applications, you can attach an event handler directly in the <SCRIPT> tag, as shown in this example:

    <script Language="JavaScript" event="FSCommand (command, args)" for="theMovie">
    ...
    </script>
    
    
  9. Save and close the HTML file.

    When you're editing HTML files outside of Flash in this way, remember that you must deselect the HTML check box in File > Publish Settings, or your HTML code is overwritten by Flash when you republish.

  10. In a web browser, open the HTML file to view it. Click the Open Window button; a window is opened to the Macromedia website. Click the Alert button; an alert window appears.

The fscommand() function 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 it 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.

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.adobe.com/support/flash.