Fireworks Article

Handling Fireworks events with ActionScript 3.0

Custom panels are one of the features by which you can extend Fireworks to introduce new functionality into the tool or workflows into your team's procedures. You create or modify custom panels in Flash CS3 Professional and then export them as SWF files for use in Fireworks CS3. You can use ActionScript 2.0 or ActionScript 3.0 to extend these panels and handle Fireworks events.

This article focuses on handling Fireworks events in custom panels using ActionScript 3.0.

Requirements

In order to make the most of this article, you need the following software and files:

Fireworks CS3

• Try
• Buy

Flash CS3 Professional

• Try
• Buy

Sample files:

fw_events_as3.zip (ZIP, 690K)

Prerequisite knowledge

It's best to have a basic understanding of ActionScript 3.0, the Fireworks DOM, and working with JavaScript in Fireworks. Refer to the following articles by Trevor McCauley for more details on how to create custom panels (using ActionScript 2.0):

• Creating Fireworks panels – Part 1: Introduction to custom panels
• Creating Fireworks panels – Part 2: Advanced custom panel development

Receiving an event

When an event is generated in Fireworks, it calls the IsFwCallbackInstalled function in an ActionScript 3.0 SWF file to find out if the event handling code is written in the custom panel. If the function returns true, Fireworks first executes the event code written in the custom panel and then executes its own event handling code. Figure 1 depicts the control flow for a Fireworks event.

Figure 1. Control flow of a Fireworks event

Part 2 of Trevor's "Creating Fireworks panels" series shows a table containing all the events generated by Fireworks. To take advantage of these events in ActionScript 3.0 with Fireworks CS3, you need to write two functions for your custom panel:

• IsFwCallbackInstalled: This function is called by Fireworks to check if the event handler is written for the generated event.

  The following example returns true when Fireworks checks for the events related to a Fireworks document being opened or closed. This tells Fireworks that it should call handlers for those events for the custom panel when the actions occur:

  function IsFwCallbackInstalled( funcName:String ):Boolean
  {
     switch( funcName )
     {
        case "onFwDocumentOpen":
             return true;
        case "onFwDocumentClose":
             return true;
        case "setfwActiveToolForSWFs":
             return true;
     }
     return false;
  }

• Event function: Your code for handling the event. This is the function you define to run commands that relate to the event as it happens in Fireworks. The following example shows event handlers for the onFwDocumentOpen and OnFwDocumentClose events. An alert message should pop up whenever a document is open (see Figure 2) or closed (see Figure 3):

  function OpenDoc()
  {
     MMExecute('alert("Opening Document");');
  }

  

  Figure 2. Alert message when document is opened

  function CloseDoc ()
  {
     MMExecute('alert("Closing Document");');
  }

  

  Figure 3. Alert message when document is closed

Registering functions

You must register all functions written in ActionScript 3.0 that Fireworks calls. Fireworks cannot call any function in a custom panel that is not registered. In order to register a function, add the following line of code to it:

ExternalInterface.addCallback("<alias name>",<function name>);

where:

• <alias name> is event function name that Fireworks calls
• <function name> is the name of the function written in ActionScript 3.0

For example, to register IsFwCallbackInstalled, you would need to add the following line of code:

ExternalInterface.addCallback("IsFwCallbackInstalled",IsFwCallbackInstalled);

Similarly, for OpenDoc and CloseDoc, you would need to add the following lines of code, respectively:

ExternalInterface.addCallback("onFwDocumentOpen",OpenDoc);
ExternalInterface.addCallback("onFwDocumentClose",CloseDoc);

ActionScript 3.0 functions that handle events are executed in Fireworks only if they and IsFwCallbackInstalled are registered, and if IsFwCallbackInstalled returns true when that event is generated.

Using the sample file

The sample file accompanying this article, fw_events_as3.zip, contains two files:

• ActionScript.swf: Copy this file into the Fireworks installation folder:

  • Windows: C:\Program Files\Adobe\Adobe Fireworks CS3\Configuration\Command Panels

  • Mac OS: Hard Drive:Applications:Adobe Fireworks CS3:Configuration:Command Panels

  Now when you restart Fireworks, the new panel will be added. Select Windows > ActionScript to open this new panel (see Figure 4). This panel lists the current tool in use and shows the alert message whenever a document is opened or closed.

  

  Figure 4. ActionScript panel showing current tool in use

• ActionScript.fla: This Flash CS3 Professional file contains the source code for the Fireworks panel. It explains how to capture the Fireworks event and handle it.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License

About the author