The Flash Objects API

The Flash Objects API lets extension developers build objects that create simple Flash content through Flash Generator. This API provides a way to set parameters in a Flash Generator template and output a SWF or image file. The API lets you create new Flash objects as well as read and manipulate existing Flash objects. The Flash button and Flash text features are built using this API.

The SWT file is a Flash Generator Template file, which contains all the information you need to construct a Flash Object file. These API functions let you create a new SWF file (or image file) from a SWT file by replacing the parameters of the SWT file with real values. For more information on Flash, see the Flash documentation. The following functions are methods of the SWFFile object.

SWFFile.createFile()

Description

This function generates a new Flash Object file with the specified template and array of parameters. It also creates a GIF, PNG, JPEG, and MOV version of the title if filenames for those formats are specified.

If you want to specify an optional parameter that follows optional parameters that you do not want to include, you need to specify empty strings for the unused parameters. For example, if you want to specify a PNG file, but not a GIF file, you need to specify an empty string before specifying the PNG filename.

Arguments

 templateFile, templateParams, swfFileName, {gifFileName}, {pngFileName}, {jpgFileName},  {movFileName}, {generatorParams} 

• The templateFile argument is a path to a template file, which is expressed as a file:// URL. This file can be a SWT file.

• The templateParams argument is an array of name/value pairs where the names are the parameters in the SWT file, and the values are what you want to specify for those parameters. For Dreamweaver to recognize a SWF file as a Flash object, the first parameter must be "dwType". Its value should be a string that represents the name of the object type, such as "Flash Text".

• The swfFileName argument, which is expressed as a file:// URL, is the output filename of an SWF file or an empty string to ignore.

• The gifFileName argument, which is expressed as a file:// URL, is the output filename of a GIF file. This argument is optional.

• The pngFileName argument, which is expressed as a file:// URL, is the output filename of a PNG file. This argument is optional.

• The jpgFileName argument, which is expressed as a file:// URL, is the output filename of a JPEG file. This argument is optional.

• The movFileName argument, which is expressed as a file:// URL, is the output filename of a QuickTime file. This argument is optional.

• The generatorParams argument is an array of strings that represents optional Generator command line flags. This argument is optional. Each flag's data items must follow it in the array. Some commonly used flags are listed in the following table:

  Option Flag	Data	Description	Example
  -defaultsize	Width, height	Sets the output image size to the specified width and height	"-defaultsize", "640", "480"
  -exactFit	None	Stretches the contents in the output image to fit exactly into the specified output size	"-exactFit"

  
  

Returns

A string that contains one of the following values:

• "noError" means the call completed successfully.

• "invalidTemplateFile" means the specified template file is invalid or not found.

• "invalidOutputFile" means at least one of the specified output filenames is invalid.

• "invalidData" means that one or more of the templateParams name/value pairs is invalid.

• "initGeneratorFailed" means the Generator cannot be initialized.

• "outOfMemory" means there is insufficient memory to complete the operation.

• "unknownError" means an unknown error occurred.

Example

The following JavaScript creates a Flash object file of type "myType", which replaces any occurrences of the string "text" inside the Template file with the string, "Hello World". It creates a GIF file as well as a SWF file.

 var params = new Array; params[0] = "dwType"; params[1] = "myType"; params[2] = "text"; params[3] = "Hello World"; errorString = SWFFile.createFile( "file:///MyMac/test.swt", params, "file:///MyMac/test .swf", "file:///MyMac/test.gif"); 

SWFFile.getNaturalSize()

Description

This function returns the natural size of any Flash content.

Arguments

 fileName 

• The fileName argument, which is expressed as a file:// URL, is a path to the Flash content.

Returns

An array that contains two elements that represent the width and the height of the Flash content or a null value if the file is not a Flash file.

SWFFile.getObjectType()

Description

This function returns the Flash object type; the value that passed in the dwType parameter when the SWFFile.createFile() function created the file.

Arguments

 fileName  

• The fileName argument, which is expressed as a file:// URL, is a path to a Flash Object file. This file is usually a SWF file.

Returns

A string that represents the object type, or null if the file is not a Flash Object file or if the file cannot be found.

Example

The following code checks to see if the test.swf file is a Flash object of type myType:

 if ( SWFFile.getObjectType("file:///MyMac/test.swf") == "myType" ){   alert ("This is a myType object."); }else{   alert ("This is not a myType object."); } 

SWFFile.readFile()

Description

This function reads a Flash Object file.

Arguments

 fileName 

• The fileName argument, which is expressed as a file:// URL, is a path to a Flash Object file.

Returns

An array of strings where the first array element is the full path to the template SWT file. The following strings represent the parameters (name/value pairs) for the object. Each name is followed in the array by its value. The first name/value pair is "dwType", followed by its value. The function returns a null value if the file cannot be found or if it is not a Flash Object file.

Example

Calling var params = SWFFile.readFile("file:///MyMac/test.swf") returns the following values in the parameters array:

 "file:///MyMac/test.swt"  // template file used to create this .swf file "dwType"                  // first parameter "myType"                  // first parameter value "text"                    // second parameter "Hello World"             // second parameter value