The FWLaunch API | Developing Extensions for Macromedia Dreamweaver 8

< Day Day Up >

The FWLaunch object lets extensions open Fireworks, perform Fireworks operations using the Fireworks JavaScript API, and then return values back to Dreamweaver. This chapter describes the FWLaunch Communication API and how to use it.

FWLaunch.bringDWToFront()

Availability

Dreamweaver 3, Fireworks 3.

Description

This function brings Dreamweaver to the front.

Arguments

None.

Returns

Nothing.

FWLaunch.bringFWToFront()

Availability

Dreamweaver 3, Fireworks 3.

Description

This function brings Fireworks to the front if it is running.

Arguments

None.

Returns

Nothing.

FWLaunch.execJsInFireworks()

Availability

Dreamweaver 3, Fireworks 3.

Description

This function passes the specified JavaScript, or a reference to a JavaScript file, to Fireworks to execute.

Arguments

 javascriptOrFileURL

The javascriptOrFileURL argument, which is expressed as a file:// URL, is either a string of literal JavaScript or the path to a JavaScript file.

Returns

A cookie object if the JavaScript passes successfully or a nonzero error code that indicates one of the following errors occurred:

Invalid usage, which indicates that the javascriptOrFileURL argument is specified as a null value or as an empty string, or the path to the JS or JSF file is invalid.
File I/O error, which indicates that Fireworks cannot create a Response file because the disk is full.
Error notifying Dreamweaver that the user is not running a valid version of Dreamweaver (version 3 or later).
Error starting Fireworks process, which indicates that the function does not open a valid version of Fireworks (version 3 or later).
User cancelled the operation.

FWLaunch.getJsResponse()

Availability

Dreamweaver 3, Fireworks 3.

Description

This function determines whether Fireworks is still executing the JavaScript passed to it by the FWLaunch.execJsInFireworks() function, whether the script completed successfully, or whether an error occurred.

Arguments

 progressTrackerCookie

The progressTrackerCookie argument is the cookie object that the FWLaunch.execJsInFireworks() function returns.

Returns

A string that contains the result of the script passed to the FWLaunch.execJsInFireworks() function if the operation completes successfully, a null value if Fireworks is still executing the JavaScript, or a nonzero error code that indicates one of the following errors occurred:

Invalid usage, which indicates that a JavaScript error occurred while Fireworks executed the script.
File I/O error, which indicates that Fireworks cannot create a Response file because the disk is full.
Error notifying Dreamweaver that the user is not running a valid version of Dreamweaver (version 3 or later).
Error starting Fireworks process, which indicates that the function does not open a valid version of Fireworks (version 3 or later).
User cancelled the operation.

Example

The following code passes the string "prompt('Please enter your name:')" to FWLaunch.execJsInFireworks() and checks for the result:

 var progressCookie = FWLaunch.execJsInFireworks("prompt('Please enter your name:')"); var doneFlag = false; while (!doneFlag){   // check for completion every 1/2 second   setTimeout('checkForCompletion()',500); } function checkForCompletion(){   if (progressCookie != null) {     var response = FWLaunch.getJsResponse(progressCookie);     if (response != null) {       if (typeof(response) == "number") {         // error or user-cancel, time to close the window         // and let the user know we got an error         window.close();         alert("An error occurred.");       }else{         // got a valid response!         alert("Nice to meet you, " + response);         window.close();       }         doneFlag = true;     }   } }

FWLaunch.mayLaunchFireworks()

Availability

Dreamweaver 2, Fireworks 2.

Description

This function determines whether it is possible to open a Fireworks optimization session.

Arguments

None.

Returns

A Boolean value that indicates whether the platform is Windows or the Macintosh; if it is the Macintosh, the value indicates if another Fireworks optimization session is already running.

FWLaunch.optimizeInFireworks()

Availability

Dreamweaver 2, Fireworks 2.

Description

This function opens a Fireworks optimization session for the specified image.

Arguments

 docURL, imageURL, {targetWidth}, {targetHeight}

The docURL argument is the path to the active document, which is expressed as a file:// URL.
The imageURL argument is the path to the selected image. If the path is relative, it is relative to the path that you specify in the docURL argument.
The targetWidth argument, which is optional, defines the width to which the image should be resized.
The targetHeight argument, which is optional, defines the height to which the image should be resized.

Returns

Zero, if a Fireworks optimization session successfully opens for the specified image; otherwise, a nonzero error code that indicates one of the following errors occurred:

Invalid usage, which indicates that the docURL argument, the imageURL argument, or both, are specified as a null value or an empty string.
File I/O error, which indicates that Fireworks cannot create a response file because the disk is full.
Error notifying Dreamweaver that the user is not running a valid version of Dreamweaver (version 2 or later).
Error starting Fireworks process, which indicates that the function does not open a valid version of Fireworks (version 2 or later).
User cancelled the operation.

FWLaunch.validateFireworks()

Availability

Dreamweaver 2, Fireworks 2.

Description

This function looks for the specified version of Fireworks on the user's hard disk.

Arguments

 {versionNumber}

The versionNumber argument is an optional floating-point number that is greater than or equal to 2; it represents the required version of Fireworks. If this argument is omitted, the default is 2.

Returns

A Boolean value that indicates whether the specified version of Fireworks was found.

Example

The following code checks whether Fireworks is installed:

 if (FWLaunch.validateFireworks(6.0)){   alert("Fireworks 6.0 or later is installed."); }else{   alert("Fireworks 6.0 is not installed."); }

A simple FWLaunch communication example

The following command asks Fireworks to prompt the user for their name and returns the name to Dreamweaver:


 <html> <head> <title>Prompt in Fireworks</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <script> function commandButtons(){   return new Array("Prompt", "promptInFireworks()", "Cancel", "readyToCancel()", "Close" ,"window.close()"); } var gCancelClicked = false; var gProgressTrackerCookie = null; function readyToCancel() {   gCancelClicked = true; } function promptInFireworks() {   var isFireworks3 = FWLaunch.validateFireworks(3.0);   if (!isFireworks3) {     alert("You must have Fireworks 3.0 or later to use this command");   return; }   // Tell Fireworks to execute the prompt() method.   gProgressTrackerCookie = FWLaunch.execJsInFireworks ("prompt('Please enter your name:')");   // null means it wasn't launched, a number means an error code   if (gProgressTrackerCookie == null || typeof(gProgressTrackerCookie) == "number") {     window.close();     alert("an error occurred");     gProgressTrackerCookie = null;   } else {     // bring Fireworks to the front     FWLaunch.bringFWToFront();     // start the checking to see if Fireworks is done yet     checkOneMoreTime();   } } function checkOneMoreTime() {   // Call checkJsResponse() every 1/2 second to see if Fireworks    // is done yet   window.setTimeout("checkJsResponse();", 500); } function checkJsResponse() {   var response = null;   // The user clicked the cancel button, close the window   if (gCancelClicked) {     window.close();     alert("cancel clicked");   } else {     // We're still going, ask Fireworks how it's doing     if (gProgressTrackerCookie != null)       response = FWLaunch.getJsResponse(gProgressTrackerCookie);     if (response == null) {       // still waiting for a response, call us again in 1/2 a       // second       checkOneMoreTime();     } else if (typeof(response) == "number") {       // if the response was a number, it means an error       // occurred       // the user cancelled in Fireworks       window.close();       alert("an error occurred.");     } else {       // got a valid response!  This return value might not       // always be a useful one, since not all functions in       // Fireworks return a string, but we know this one does,       // so we can show the user what we got.       window.close();       FWLaunch.bringDWToFront();  // bring Dreamweaver to the front       alert("Nice to meet you, " + response + "!");     }   } } </script> </head> <body> <form> <table width="313" nowrap> <tr> <td>This command asks Fireworks to execute the prompt() function. When you click Prompt,  Fireworks comes forward and asks you to enter a value into a dialog box. That value is  then returned to Dreamweaver and displayed in an alert.</td> </tr> </table> </form> </body> </html>

< Day Day Up >