Adobe Extending Fireworks CS5

User Manual: adobe Adobe Fireworks - CS5 - Extending Free User Guide for Adobe Fireworks Software, Manual

Open the PDF directly: View PDF .
Page Count: 333

Download
Open PDF In Browser	View PDF

Extending

ADOBE® FIREWORKS® CS5

Legal notices

Legal notices
For legal notices, see http://help.adobe.com/en_US/legalnotices/index.html.

Last updated 5/2/2011

iii

Contents
Chapter 1: Extending Fireworks Overview
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Installing an extension

................................................................................................. 1

What’s new in Extending Fireworks CS5
Conventions used in this guide

................................................................................ 2

........................................................................................ 6

Additional resources for extension writers

.............................................................................. 6

Chapter 2: The Fireworks Object Model
Using the Fireworks Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Using Fireworks API functions
Using the common API

Working with selected objects
Global methods
Core objects

......................................................................................... 9

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Adobe AIR Extension

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 3: The Document object
Document object properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Document functions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 4: The Fireworks Object
Fireworks functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Chapter 5: Objects within Fireworks documents
Behavior object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Brush object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Contour object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

ContourNode object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

ContourNodeDynamicInfo object
ControlPoint object
Effect object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

EffectList object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Element object

ElementMask object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

ExportFrameInfo object
ExportOptions object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

ExportPaletteInfo object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

ExportSettings object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Fill object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Frame object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

FrameNLayerIntersection object
Gradient object

GradientNode object
Guides object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Last updated 5/2/2011

EXTENDING FIREWORKS
Contents

Layer object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

PathAttrs object
Pattern object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

RectanglePrimitive object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

RegisterMoveParms object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

SingleTextRun object
SmartShape object
Style object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

TextAttrs object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

TextRuns object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Widget object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Chapter 6: HTML export objects
BehaviorInfo object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
BehaviorsList object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

exportDoc object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

ImageMap object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

ImagemapList object
SliceInfo object
Slices object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Chapter 7: Cross-Product Extensions
Cross-product architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Flash panels

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Chapter 8: Auto Shapes
How Auto Shapes work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Creating an Auto Shape

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Chapter 9: Rich symbols
How Rich symbols work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
MXML Export

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Chapter 10: Additional Fireworks Functions
Property inspector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
History panel functions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Static Document Functions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Last updated 5/2/2011

Chapter 1: Extending Fireworks Overview
To extend Adobe® Fireworks® CS5, you must write JavaScript code. You can use JavaScript to write your own objects
and commands that affect Fireworks documents and the elements within them. To accomplish these tasks, you must
be proficient in JavaScript and in Fireworks.
This guide introduces the Fireworks Object Model, explains how to write cross-product extensions (extensions written
in, or for, other Adobe applications), and discusses the JavaScript Auto Shape construction. The final chapter is a
reference to the Fireworks JavaScript application programming interface (API)—the custom JavaScript functions that
are built into Fireworks.

Prerequisites
Because Fireworks extensions must be written in JavaScript, this guide assumes that readers are familiar with
JavaScript syntax and with basic programming concepts such as functions, arguments, and data types. It also assumes
that readers understand the concept of working with objects and properties. This guide does not attempt to teach
programming in general or JavaScript in particular.
Anyone who wants to extend Fireworks should have a good JavaScript reference to help with syntax questions (for
example, is it substring() or subString()?). Useful JavaScript references include JavaScript Bible by Danny
Goodman (IDG), JavaScript: The Definitive Guide by David Flanagan (O’Reilly), and Pure JavaScript by R. Allen
Wyke, Jason D. Gilliam, and Charlton Ting (Sams).

Installing an extension
As you start learning the process of writing extensions, you might want to explore the extensions and resources already
available through the Adobe Exchange website (www.adobe.com/go/exchange). By installing an existing extension,
you will become familiar with some of the tools that you need to work with your own extensions.
To install an extension:
1 Download and install the Adobe® Extension Manager, which is available on the Adobe Downloads website
(www.adobe.com/exchange/em_download/).
2 Log on to the Adobe Exchange website (www.adobe.com/go/exchange).
3 Click the Fireworks Exchange link.
4 From the available extensions, choose one that you want to use. Click the Download link to download the extension

package.
5 Save the extension package in a directory on your machine.
6 In Fireworks, choose Commands > Manage Extensions to start the Extension Manager (or you can start Extension

Manager, located in the Adobe program group, independently from Fireworks).
7 In the Extension Manager, choose File > Install Extension, and choose the extension package you just saved.

The Extension Manager automatically installs the extension into Fireworks.

Last updated 5/2/2011

EXTENDING FIREWORKS
Extending Fireworks Overview

You cannot begin using some extensions until you restart Fireworks. If you are running Fireworks when you install
the extension, you might be prompted to quit and restart the application.
To view basic information on the extension after its installation, go to the Extension Manager (Commands >
Manage Extensions) in Fireworks.

What’s new in Extending Fireworks CS5
Fireworks CS5 includes the following new features and interfaces that you can use to develop extensions for the
product:
CSS-based layouts Fireworks CS5 now allows you to design complete web pages and export web standards-compliant

CSS-based layouts. You can select a layout and integrate foreground and background graphics with automatic margin
and padding detection. You can drop HTML rich symbols on your Fireworks layouts to specify headings, links, and
form properties for precise CSS control. You can also use rectangles with rounded corners and gradients for creating
layouts.
Adobe Type Engine The new Adobe Type Engine provides enhanced typesetting capabilities similar to Adobe®

Photoshop® and Adobe® Illustrator®. You can import or copy/paste double-byte characters from Illustrator or
Photoshop without loss of fidelity, and create advanced effects such as setting text inside a path.
Export to PDF You can generate high-fidelity, interactive, secure PDF documents from your Fireworks design comps
and receive review comments through a shared PDF review.
Smart Guides Use Smart Guides to expertly position and layouts objects on canvas. Use Smart Guides with tool tips

to achieve precise positioning.
Live Styles With Live Styles, you can use professionally designed styles or create your own collection. Enhanced
capabilities include redefining styles, dynamically updating effects, colors, and text attributes by updating the style
source.
FXG export You can export designs as FXG files and use them in advanced design tools to develop rich Internet

applications and experiences that can run on Adobe® Flash Player or Adobe® AIR™.
Adobe AIR export You can package your Fireworks documents as Adobe AIR applications that you can secure using

a digital signature.
The following APIs have been added or modified for this release:

Last updated 5/2/2011

EXTENDING FIREWORKS
Extending Fireworks Overview

Class

Property or Method

Description

AIRExt

AIRext.PreviewDocument()

Calls the ADL tool to preview an HTML document as an Adobe AIR
application.

AIRext.PackageApplication()

Calls the ADT tool package an Adobe AIR application.

AIRext.CreatePackage()

Calls the ADT tool to create a signed AIR package.

AIRext.CheckCertificatePasswor
d()

Calls the ADT tool to check a certificate password.

AIRext.SaveDigSigPassword()

Saves the password for the given digital certificate, for the current
session of Fireworks (no persistent storage).

AIRext.GetDigSigPassword()

Returns the name of the generated password file.

AIRext.GetLastErrorLogName()

Returns the name of the generated error log file if one was
created.

AIRext.GetAIRInstallPath()

Returns the full system path name and path of the generated file.

AIRext.GetJREVersion()

An object with two properties - maxVersion and minVersion; if an
error occurs the values of the maxVersion and minVersion will be
-1.

AIRext.CreateCertificate()

Calls the ADT to create a self-signed digital certificate.

isBackground

Specifies whether the document has a background image. If an
image is set in the HTML set up, returns true.

backgroundAttachment

Specifies whether the document is fixed or scrolls. Values are
Fixed or scroll.

docAlignment

Specifies the page alignment as left, center, right. Default is left.

backgroundURL

Specifies the URL of the background image as file:///)

backgroundRepeat

Specifies if the background image repeats, and if repeats in X, Y,
Repeat (Both) and No Repeat

leftMargin

Specifies the left margin of the page.

topMargin

Specifies the top margin of the page.

rightMargin

Specifies the right margin of the page.

bottomMargin

Specifies the bottom margin of the page.

exportDoc

Last updated 5/2/2011

EXTENDING FIREWORKS
Extending Fireworks Overview

Class

Property or Method

Description

SliceInfo

backgroundHorizontalPosition

Horizontal position of the background image. (Left, right, or
center, numeric value)

backgroundVerticalPosition

Horizontal position of the background image. (Left, right, or
center, numeric value)

backgroundHorizontalPositionV
al

Horizontal position value of the background image if the
argument is value.

backgroundVerticalPositionVal

Vertical position value of the background image if the argument
is value.

isBackground

Specifies whether the slice is background image or foreground
image. True = Background.

backgroundRepeat

Specifies if the background image repeats, and if repeats in X, Y,
Repeat (Both) and No Repeat.

backgroundAttachment

Specifies if the bg image is fixed or scrolls with the rest of the
page.

RectPrimitive

Mode

Specifies the roundness units which can be relative (percentage)
or exact (pixels).

instance

tranform

Specifies the transformation matrix of a symbol instance.

symbolName

Specifies the symbol name.

frame

name

Species the name of the state.

FrameNLayerIntersection

name

Specifies the name of the layer when the layers are accessed from
states.

document

dom.setRectRoundnessMode()

Specifies the mode of corner roundness of the rectangle as either
a percentage value or or exact pixel value.

dom.exportElements()

Exports an array of elements on the canvas to a 32-bit PNG image,
based on the image export settings.

dom.moveNineScaleGuide()

Moves a 9-slice scaling guide’s position by specified pixels.

dom.placeTextInPath()

Places the selected text inside the selected path. If no text and
path are selected, no action occurs.

dom.setSliceType()

Sets the slice type as image (foreground image), background
image, or empty (HTML Slice).

dom.redefineStyleByName()

Redefines the target style with the source style.

dom.snapToPixel()

Snap To Pixel is applied on the selected object on the canvas.

dom.attachTextInPath()

Attaches the selected text inside the selected path. If no text and
path are selected, no action occurs.

Last updated 5/2/2011

EXTENDING FIREWORKS
Extending Fireworks Overview

Class

Property or Method

Description

fw.saveAs()

Saves the specified document in the specified filename and
format.

fw.exportPDF()

Exports the specified document to the specified file in PDF
format.

fw.exportFXG()

Exports current page, all pages of the open document in
Fireworks, or selected objects from the current page as FXG files.

fw.exportPages()

Exports the specified pages in the specified format.

fw.shrinkPIWindow()

Minimizes the Property inspector window.

fw.setUseAGMRenderingForSele Sets the currently selected vectors to use the new AGM
ction()
Rendering.
fw.currentWorkspaceName()

Returns the name of the current workspace layout.

fw.getFamilyNameForPSFont()

Gets the family name of a PostScript font.

fw.getPlatformNameForPSFont() Returns the platform name of the PostScript font.
“fw.saveDocumentAsTemplate(a Saves the current document as a template.
rg1,arg2)” on page 233
“fw.saveDocumentAsTemplateA Works the same as fw.saveDocumentAsTemplate() except
sync(arg1,arg2)” on page 234
for the async mode of save operation.
“fw.newDocumentFromTemplat Opens up a file for selecting any template from the pre-defined
e(arg1)” on page 224
Templates folder in Fireworks installation directory.
“fw.newMobileDocument(arg1,a Creates a mobile document with the width, height, and
rg2,arg3,arg4)” on page 224
resolution details.
“fw.previewInDeviceCentral()”
on page 227

Launches Adobe Device Central and previews the current
document in it. If there is no active document, an alert message is
generated.

“fw.getDocumentDOM().InsertP
ageForImport” on page 214

Creates a compound shape from the selected vectors applying
the operation that is specified. Requires two or more vectors to be
selected.

“fw.getDocumentDOM().combin Combines the compound shape that is selected. Requires
eCompoundShape” on page 213 selection of a compound shape.
“fw.getDocumentDOM().createC Creates a compound shape from the selected vectors applying
ompoundShape” on page 214
the operation that is specified. Requires two or more vectors to be
selected.

Files

fw.appTemplatesDir (See “The
Fireworks Object” on page 191

Returns the path of the Templates directory present at the
location where you have installed Fireworks.

“fw.getDocumentDOM().Vector
Operation” on page 215

Vector operation is applied on paths created after applying this
API. A compound shape is created.

writeUTF8

Writes text in UTF8 encoding when the file is opened in UTF8
encoding.

readLineUTF8

Reads one line from the file that has been opened with UTF8
encoding.

Last updated 5/2/2011

EXTENDING FIREWORKS
Extending Fireworks Overview

Conventions used in this guide
The following typographical conventions are used in this guide:

•

Code font indicates code fragments and API literals, including class names, method names, function names, type
names, scripts, SQL statements, and HTML and XML tag and attribute names.

• Italic code font indicates replaceable items in code.
• The continuation symbol (¬ ) indicates that a long line of code has been broken across two or more lines to fit on
the page. When copying the lines of code, eliminate the continuation symbol and type the code as one line.

• Curly braces ({ }) around a function argument indicate that the argument is optional.
The following naming conventions are used in this guide:

• You refers to the developer who is responsible for writing extensions.
• The user refers to the person using Fireworks.
• The visitor refers to the person who views the graphic that the user created.

Additional resources for extension writers
To communicate with other developers who are writing extensions, you can visit the Adobe online forums at
www.adobe.com/support/forums/.

Last updated 5/2/2011

Chapter 2: The Fireworks Object Model
If you want to extend the functionality of Adobe Fireworks CS5 by writing or modifying a JavaScript extensibility file,
you must become familiar with the objects that Fireworks makes available through JavaScript. The hierarchy of these
objects comprises the Fireworks Object Model, which contains the following major components:

• Six global methods that are available from any part of the application and need not be declared as methods of a
particular object. For more information, see “Global methods” on page 14.

• Core objects: Dialogs, Document, pngText, Errors, Files, Find, and System. For more information, see “Core
objects” on page 17 and “The Document object” on page 28. (The App object that was used in Fireworks 3 is
supported for backward compatibility, but its use is deprecated in favor of the Fireworks object.)

• The Fireworks object (for more information, see “The Fireworks Object” on page 191).
• Numerous objects associated with Fireworks documents, such as ExportOptions, Guides, Path, Image, and Text.
For more information, see “Objects within Fireworks documents” on page 243.

• A set of objects that you can use to specify the format of HTML code when exporting from Fireworks. For more
information, see “HTML export objects” on page 277.

Using the Fireworks Object Model
When scripting extensions for Fireworks, you write JavaScript commands that send calls to the Fireworks Object
Model to determine or change the current settings for a Fireworks document. For example, the following command
calls the Fireworks object (fw) to obtain the path to the Export Settings directory (appExportSettingsDir), which is
expressed as a file://URL. In other words, fw references the Fireworks global object, of which appExportSettingsDir
is a property (for more information, see “The Fireworks Object” on page 191), so a JavaScript command can assign the
resulting value to a variable, as follows:
var expSetDir = fw.appExportSettingsDir;

Accessing a Fireworks document
All the functions listed in “Property inspector functions” on page 321 are methods of the Document object, which
represents a Fireworks document. To perform a function on a Document object, you must first get the Document
Object Model (DOM) of the document. You then call the functions as methods of that DOM.
When accessing a Fireworks document, consider the following points:

• To use a DOM function with a document other than the active document, use the following syntax; note that
documentIndex is a zero-based index that specifies which document the command will affect.
fw.documents[documentIndex].functionName();

• To use a DOM function with the active document, use fw.getDocumentDOM().functionName() (for more
information, see fw.getDocumentDOM()).

Passing values
For all properties that are not read-only, you can pass values to change elements of a document. For example, the
following command sets the fifth brush in the third open document to a square shape:

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

fw.documents[2].brushes[4].shape = "square";

The preceding example includes the following properties:

•

documents is a property of the Fireworks object and contains an array of Document objects.

•

brushes is a property of the Document object and contains an array of Brush objects.

•

shape is a property of the Brush object.

Note: Throughout this manual, optional arguments are enclosed in {braces}.

Fireworks Object Model calls and API calls
In some cases, you can use Fireworks Object Model calls or API calls to perform the same operations. In other cases,
a certain function might be available in either the Fireworks Object Model or the API, but not in both.
For example, if the first open document is the current document, the first code fragment has the same effect as the
second and third code fragments. The fw.getDocumentDOM() function references the current document (for more
information, see “Accessing a Fireworks document” on page 7).
fw.getDocumentDOM().setDocumentResolution({pixelsPerUnit:72, units:"inch"});
fw.documents[0].resolution =72;
fw.documents[0].resolutionUnits ="inch";

Formatting nonstandard data types
In addition to the standard data types that can be passed to functions as arguments, or used as properties, such as
integer, string, and so on, Fireworks accepts other data types.

• Some functions accept values that are Fireworks objects. For more information, see “The Fireworks Object Model”
on page 7.

• Some functions accept a string in a specific format. Others accept value types that are not Fireworks objects but are
JavaScript object types that are specific to Fireworks. These types of arguments are described next, in alphabetical
order.

Color string data type
Functions that accept colors as arguments use the HTML syntax "#rrggbb". You can specify a color with an alpha
(transparency) component by passing a longer string of the form "#rrggbbaa".

Mask data type
The format for a mask is {maskBounds:rectangle, maskKind:string, maskEdgeMode:string, featherAmount:int,
maskData:hex-string}.

• maskBounds specifies the bounding rectangle of the mask area.
• Acceptable values for maskKind are "rectangle", "oval", "zlib

compressed", "rle compressed", or

"uncompressed".

• If the value of maskKind is "rectangle" or "oval", the maskData string is ignored, and a mask of the right shape is
constructed that fills maskBounds and that has the edge specified by maskEdgeMode and featherAmount.

• If the value of maskKind is “zlib

compressed“, “rle compressed", or “uncompressed", the maskData string is
presumed to contain 8-bit mask data in hexadecimal format that precisely matches the maskBounds to define the
mask.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Matrix data type
The format for a matrix is {matrix:[float, float, float, float, float, float, float, float, float]}.
This guide assumes that you know how to use these nine values to construct a three-by-three transformation matrix;
discussion of the construction of transformation matrices is beyond the scope of this manual.

Point data type
The format for a point is {x:float, y:float}. For instance, dom.addNewLine(startPoint, endPoint) could look like
the following example:
fw.getDocumentDOM().addNewLine({x:64.5, y:279.5}, {x:393.5, y:421.5});

Rectangle data type
The format for a rectangle is {left:float, top:float, right: float, bottom: float}. For instance,
dom.addNewOval(boundingRectangle) could look like the following example:
fw.getDocumentDOM().addNewOval({left:72, top:79, right:236, bottom:228});

Resolution data type
The format for resolution is {pixelsPerUnit: float, units: string}. Acceptable values for units are “inch“ or “cm“.
For instance, dom.setDocumentResolution(resolution) could look like the following example:
fw.getDocumentDOM().setDocumentResolution({pixelsPerUnit:72, units:"inch"});

Using Fireworks API functions
Three categories of API functions are described in this book: Document functions, History panel functions, and
Fireworks functions. The following rules apply to all functions.

Zero-based indexes
Some functions take an index argument which is a zero-based, one-dimensional array. That means a value of 0
represents the first item in the array, 1 represents the second item, and so on. For example, the following command
deletes the second layer of the active Fireworks document:
fw.getDocumentDOM().deleteLayer(2);

Functions that take a frameIndex argument can be passed –1 to indicate the current frame. Similarly, functions that
take a layerIndex argument may be passed –1 to indicate the current layer.

Passing null values
In general, passing a null value to a function causes an exception to be thrown. A few functions do allow null as an
argument; such cases are noted in the function descriptions.

Working with selected elements
Many API functions in this chapter refer to a “selection” or to “selected items.” These terms refer to Fireworks
elements, such as text boxes or images, that are currently selected. In most cases, the functions work even if only one
item is selected. If a function requires more than one selected item, this is noted in the description of the function.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Palette or panel
Several API functions reference the History panel (see “History panel functions” on page 324). Throughout the
Fireworks documentation and online help, the term palette is reserved for discussions of a color palette, and the term
panel is used to refer to the floating windows that are available within Fireworks. Therefore, when the function name
contains palette, the descriptions refer to a panel.

Using the common API
You can use the common Adobe API if you want commands to use a common syntax (and thus run a single command
in multiple applications). You can access this API using app.methodName().The following methods are currently
supported in Fireworks and Dreamweaver to let developers easily create commands for both applications.

app.toggleFloater()
Identical to fw.toggleFloater().

app.setFloaterVisibility()
Identical to fw.setFloaterVisibility().

app.getRootDirectory()
Identical to the Fireworks object property appDir •.

app.browseDocument()
Identical to fw.browseDocument().
Note: The app.getRootDirectory() function is useful if you want to use app.browseDocument() to view files within the
applications’s folder.

Working with selected objects
When an object is selected, either programmatically (for example, using the dom.selectAll() function) or by a user,
you can return (get) or set the value of that object’s properties using common notation that will work on various
objects. In other words, you can write a command that will get or set the value of an object’s properties whether the
user selects a Text object, or an Image object, or any other recognized object. In Fireworks, a recognizable object is
classified as one of the following element types:

•

Hotspot

•

SliceHotspot (basically, a slice)

•

Path

•

Group

•

Instance

•

Text

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

•

RectanglePrimitive

•

PathAttrs

•

Image

To test whether a text block is selected, type the following code:
firstSelection = fw.selection[0];
if (firstSelection == "[object Text]"){
alert("I am a text block");
}

You can use the information in the following sections to return or set property values.
Note: The return value for a property may be null.

Working with properties for any selected object
You can get values for the following read-only properties of any type of selected object:

•

top

•

left

•

width

•

height

•

visible

•

opacity

•

blendMode

•

name

•

mask

To return the name of the selected object, type the following code:
objectName=fw.selection[0].name;

The following properties contain other read-only properties that you can return:

elementMask
•

element

•

linked

•

enabled

•

mode

•

showAttrs

•

autoExpandImages

effectList
•

name

•

effects

To return the name of the first effect that is applied to the selected object, type the following code:
effectName=fw.selection[0].effectList.effects[0].name;

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Working with specific properties for selected elements
Some elements have specific properties that can be returned in addition to those that can be returned for any selected
object (for more information, see “Working with properties for any selected object” on page 11). These specific
properties are available for each of the following elements when the elements are selected.

Hotspot
•

shape

•

urlText

•

altText

•

targetText

•

contour

•

behaviors (returns an array of behaviors)

•

color

To return the alt tag that has been applied to the currently selected Hotspot, type the following code:
altTag = fw.selection[0].altText;

SliceHotspot
SliceHotspot is a subclass of Hotspot. A slice has all Hotspot properties, plus the following properties:

•

baseName

•

htmlText

•

tdTagText

•

sliceKind ("image" or "empty")

•

exportOptions

•

sliceID (read-only)

To return the name of the currently selected slice, type the following code:
sliceName = fw.selection[0].baseName;

Path
•

pathAttributes

Note: For the complete list of path attributes properties, see “pathAttributes” on page 98.

•

randSeed

•

textureOffset

•

contours

To return the value of the fill color for the currently selected path, type the following code:
fillColor = fw.selection[0].pathAttributes.fillColor

Group
•

elements

•

groupType

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

To return the number of objects in a selected group, type the following code:
numOfObjectsinGroup = fw.selection[0].elements.length;

Instance
•

symbolID

•

transformMode

•

instanceType

•

urlText

•

altText

•

targetText

To return the instanceType for the currently selected instance, type the following code:
instance = fw.selection[0].instanceType;

Text
•

antiAliased

•

antiAliasMode

•

autoKern

•

orientation

•

pathAttributes

Note: For the complete list of pathAttributes properties, see “pathAttributes” on page 98.

•

randSeed

•

textRuns

•

textureOffset

•

transformMode

To return the antiAliasMode setting for the currently selected text block, type the following code:
antiAliasedSetting = fw.selection[0].antiAliasMode;

RectanglePrimitive
•

Roundness

•

pathAttributes

Note: For the complete list of path attributes properties, see “pathAttributes” on page 98.

•

originalSides

•

transform

To return the roundness setting for the currently selected rectangle, type the following code:
roundness = fw.selection[0].roundness;

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

pathAttributes
Several objects have the pathAttributes property. The following list is the valid set of pathAttributes sub
properties that can be returned or set:

•

brushColor

•

fillColor

•

brush

•

fill

•

brushTexture

•

fillTexture

•

fillHandle1

•

fillHandle2

•

fillHandle3

•

brushPlacement

•

fillOnTop

To return the name of brush on the current path, type the following code:
brush = fw.selection[0].pathAttributes.brush.name;
(b

Global methods
The following are the global Fireworks methods, along with their argument data types and, where appropriate,
acceptable values and notes.

alert(message)
Availability
Fireworks 3.
Usage
alert(message)

Arguments
message A string containing the message to display.
Returns
Nothing.
Description
Displays the message in a modal alert box, along with an OK button.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

confirm(message)
Availability
Fireworks 3.
Usage
confirm(message)

Arguments
message A string containing the message to display.
Returns
True if OK is clicked, false if Cancel is clicked.
Description
Displays a string in a modal alert box, along with OK and Cancel buttons.

prompt(caption, text)
Availability
Fireworks 3.
Usage
prompt(caption, text)

Arguments
caption A string containing the title of the dialog box.
text A string containing the prompt for the user.

Returns
The string entered if OK is clicked, null if Cancel is clicked.
Description
Prompts the user (with the string that is specified by text) to enter a string in a modal dialog box; the dialog box is titled
with the string that is specified by caption.

write(arg1, arg2, ..., argN)
Availability
Fireworks 3.
Usage
write(arg1, arg2, ..., argN)

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Arguments
arg1, arg2, ..., argN Strings containing content for output.

Returns
An output file.
Description
Same as WRITE_HTML; WRITE_HTML was created to let you differentiate HTML output calls from other JavaScript
calls in your code.

WRITE_CSS
Availability
Fireworks 3.
Usage
WRITE_CSS

Arguments
None.
Returns
An output file.
Description
Available only when exporting. Writes the CSS as an external file.

WRITE_HTML(arg1, arg2, ..., argN)
Availability
Fireworks 3.
Usage
WRITE_HTML(arg1, arg2, ..., argN)

Arguments
arg1, arg2, ..., argN Strings containing content for output.

Returns
An output file.
Description
Available only when exporting. Converts each argument to a string and writes it to the HTML output file. To enter an
end-of-line character, use “\n”; this is converted to the correct line ending for your platform. For more information,
see “HTML export objects” on page 277.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

fw.setUseAGMRenderingForSelection()
Availability
Fireworks 10.
Usage
fw. setUseAGMRenderingForSelection()

Arguments
A boolean value that defines whether AGMRendering is used or not.
Returns
Nothing.
Description
Sets the currently selected vectors to use the new AGM Rendering.
Example
fw.getDocumentDOM().setUseAGMRenderingForSelection(true);

Core objects
This section describes the set of core objects that are always available: Errors, Files, Find, and System. The Document
object is described within its own chapter: see “The Document object” on page 28.
Note: For information on how to format nonstandard data types, such as rectangle or point, see “Formatting
nonstandard data types” on page 8.

Errors object
All Errors object properties are read-only strings that are used to simplify the localizing of scripts. They return
localized error messages appropriate to the specific error. For example, the English version of Fireworks returns
"Memory is full." for the EOutOfMem property.
The following list contains the properties of the Errors object alphabetically:
EAppAlreadyRunning, EAppNotSerialized, EArrayIndexOutOfBounds, EBadFileContents,
EBadJsVersion, EBadNesting, EBadParam, EBadParamType, EBadSelection, EBufferTooSmall,
ECharConversionFailed, EDatabaseError, EDeletingLastMasterChild, EDiskFull,
EDuplicateFileName, EFileIsReadOnly, EFileNotFound, EGenericErrorOccurred, EGroupDepth,
EIllegalThreadAccess, EInternalError, ELowOnMem, ENoActiveDocument, ENoActiveSelection,
ENoFilesSelected, ENoNestedMastersOrAliases, ENoNestedPasting, ENoSliceableElems,
ENoSuchElement, ENotImplemented, ENotMyType, EOutOfMem, EResourceNotFound, ESharingViolation,
EUnknownReaderFormat, EUserCanceled, EUserInterrupted, EWrongType

Files object
The following table lists the methods of the Files object, along with their data types and, where appropriate, acceptable
values and notes.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Method

Data type

Notes

copy(docname1, docname2)

string, string

Copies the file specified in the first argument to the file
specified in the second argument. Each argument must be the
name of a file, which is expressed as file://URL. Only files (not
directories) can be copied. The files do not need to reside on
the same drive, and the method does not overwrite a file if it
already exists. Returns a value of true if the copy is successful;
false otherwise.

createDirectory(dirname)

string

Creates the specified directory. Returns true if successful;
false otherwise.

createFile(fileURL,
fileType, fileCreator)

string, string, string

Creates the specified file. The file must not already exist. The
first argument is the name of the file, which is expressed as
file://URL. The last two arguments let you specify the file type
and file creator strings. The fileType and fileCreator
strings should each be strings of exactly four characters in
length, for example:
Files.createFile(newFile,".txt","FWMX");

deleteFile(docOrDir)

string

Deletes the specified file or directory. Returns true if
successful; false if the file or directory does not exist or
cannot be deleted. Compare with
deleteFileIfExisting().

deleteFileIfExisting
(docOrDir)

string

Deletes the specified file or directory. Returns true if
successful; false if the file or directory cannot be deleted.
Unlike deleteFile(), this method returns true if the file or
directory does not exist.

enumFiles(docOrDir)

string

Returns an array of file URLs. If docOrDir is a directory, the
array contains an entry for every file or directory that is
contained in the specified directory. If docOrDir is a file, the
array contains a single entry (the file passed in).

exists(docOrDir)

string

Returns true if docOrDir refers to a directory or file that
exists; false otherwise.

getDirectory(docname)

string

Returns only the directory name from docname, which is
expressed as file://URL. For example,
Files.getDirectory("file://work/logo.png")
returns "file:///work".

getExtension(docname)

string

Returns the filename extension, if any, of docname. For
example, Files.getExtension("birthday.png")
returns ".png". If the filename has no extension, an empty
string is returned. A filename that is expressed as file://URL is
acceptable.

getFilename(docname)

string

Returns just the filename from docname, which is expressed as
file://URL. For example,
Files.getFilename("file:///work/logo.png")
returns "logo.png".

getLanguageDirectory()

string

Returns the URL of the language directory associated with the
currently running language.

getLastErrorString()

none

If the last call to a method in a Files object resulted in an error,
returns a string that describes the error. If the last call
succeeded, returns null.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Method

Data type

Notes

getTempFilePath ({dirname})

string

The argument, if used, must be expressed as file://URL. Returns
a file URL in the Temporary Files directory or in the specified
directory. This method does not create a file; it simply returns a
unique file URL that does not conflict with existing files in the
directory. If dirname is passed and is not null, the URL that is
returned indicates a file in the specified directory rather than in
the Temporary Files directory.

isDirectory(dirname)

string

The argument must be expressed as file://URL. Returns true if
the specified URL refers to a directory that exists; false
otherwise.
The first argument must be expressed as file://URL.
Concatenates the two arguments to return a file URL that
references the specified filename in the specified directory. For
example,

makePathFromDirAndFile(dirna string, string
me, plainFilename)

Files.makePathFromDirAndFile("file:///work/rep
orts", "logo.png") returns
"file:///work/reports/logo.png".
open(docname, encoding,
bWrite)

string, string, Boolean

The first argument must be expressed as file://URL. Opens the
specified file for reading or writing. The second argument
specifies the encoding. If the third argument is true, the file
opens for writing; otherwise it opens for reading. If the file
cannot be opened, returns null; otherwise, returns a File
Reference object.

rename(docname,
newPlainFilename)

string, string

The docname argument is a file path or a file URL to the file that
you want to rename.
The newPlainFilename argument is the new name to assign
to the file.
The rename method returns a URL path of the newly renamed
file if successful; otherwise Fireworks returns null.

setFilename(docname,
newPlainFilename)

string, string

The first argument must be expressed as file://URL. Returns a
file URL withdocname replaced by newPlainFilename. For
example,
Files.setFilename("file:///work/logo.png",
"oldlogo.png") returns
"file:///work/oldlogo.png". This method does not

affect the file on disk; it simply provides a convenient way to
manipulate file URLs. To change the name on disk, use
rename().
swap(docname1, docname2)

string, string

Each argument must be expressed as a file://URL. Swaps the
contents of the two specified files, so that each file contains the
contents of the other file. Only files (not directories) can be
swapped, and both files must reside on the same drive. Returns
true if the swap is successful; false otherwise.

File Reference object
The File Reference object is used to refer to a specific open file. The following table lists the methods of the File
Reference object, along with their data types and, where appropriate, acceptable values and notes.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Method

Data Type

Notes

close()

none

Closes the current File Reference object. You are not required
to use this method (the file is closed when the Files object is
destroyed), but it is useful for controlling access to a file.

readline()

none

Reads the next line from the current File Reference object and
returns it as a string. The end-of-line character(s) are not
included in the string. Returns null if end-of-file is reached or
if the line is longer than 2048 characters.

readLineUTF8

string

Reads one line from the file that has been opened with UTF8
encoding.

write(textString)

string

Writes the specified string to the current File Reference object.
No end-of-line characters are appended; to include one, use
"\n".

writeUTF8(textString)

string

Writes text in UTF8 encoding when the file is opened in UTF8
encoding.

Find object
There are several ways to specify a Find object, depending on what you want to find and replace. Use the whatToFind
property to specify the type of find operation, along with the properties that are associated with each legal value for
whatToFind. These properties are listed in the following tables. Read-only properties are marked with a bullet (•).

Finding and replacing text
Property

Data type

Notes

whatToFind

string

In the format: "text"

find

string

Text to find.

matchCase

Boolean

If set to true, the search is case-sensitive. Defaults to false.

numItemsReplaced •

Integer

Number of replacements done in a file using Find and Replace.

regExp

Boolean

If set to true, the find and replace text is interpreted as a
regular expression. The default is false.

replace

string

Text to use as replacement text.

wholeWord

Boolean

If set to true, only whole words matching the search text are
found. The default is false.

Finding and replacing fonts and styles
Property

Data type

Notes

whatToFind

string

In the format: "font"

find

string

Name of font to find.

replace

string

Name of font to use as replacement.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Property

Data type

Notes

findStyle

integer

Number that represents the style to find:
AnyStyle = -1
Plain = 0
Bold = 1
Italic = 2
BoldItalic = 3
Underline = 4
BoldUnderline = 5
ItalicUnderline = 6
BoldItalicUnderline = 7

replaceStyle

integer

Number that represents the style to be used as replacement.

findMinSize

integer

0 to 9999

findMaxSize

integer

0 to 9999

replaceSize

integer

0 to 9999, or pass -1 to leave size as is

Finding and replacing colors, fills, strokes, and effects
Property

Data type

Notes

whatToFind

string

In the format: "color"

find

string

A color string that specifies the color to find (for more
information, see “Color string data type” on page 8).

replace

string

A color string that specifies the color to use as a replacement
(for more information, see “Color string data type” on page 8).

fills

Boolean

If set to true, fills that match the specified colors are replaced.

strokes

Boolean

If set to true, strokes that match the specified colors are
replaced.

effects

Boolean

If set to true, effects that match the specified colors are
replaced.

Finding and replacing URLs
Property

Data types

Notes

whatToFind

string

In the format: "url"

find

string

URL to find, which is expressed as file://URL.

replace

string

URL to use as replacement text, which is expressed as file://URL.

wholeWord

Boolean

If set to true, only whole words that match the search text are
found. The default is false.

matchCase

Boolean

If set to true, the search is case sensitive. Defaults to false.

regExp

Boolean

If set to true, the find and replace text is interpreted as a
regular expression. The default value is false.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Finding and replacing non-websafe colors with the closest websafe color
Property

Data type

Notes

whatToFind

string

In the format: "nonwebcolor"

effects

Boolean

If set to true, colors in effects are replaced. The default value is
false.

fills

Boolean

If set to true, colors in fills are replaced. The default value is
false.

strokes

Boolean

If set to true, colors in strokes are replaced. The default value
is false.

System object
The following table lists the properties of the System object, along with their data types and, where appropriate,
acceptable values and notes. All System properties are read-only.
Property (read-only)

Data type

Notes

osName

string

Returns the name of the operating system under which
Fireworks is running.

controlFaceColor

string

Returns the system color used for the control and panel faces
(Windows®-only property).

controlHilightColor

string

Returns the system color used for control highlights (Windowsonly property).

controlShadowColor

string

Returns the system color used for control shadows (Windowsonly property).

controlDarkShadowColor

string

Returns the system color used for control dark shadows
(Windows-only property).

hilightItemColor

string

Returns the system color used for highlighting selections
(Windows-only property).

hilightTextColor

string

Returns the system color used for highlighting selected text
(Windows-only property).

textColor

string

Returns the system color used for text (Windows-only
property).

menuColor

string

Returns the system color used for menu backgrounds
(Windows-only property).

menuTextColor

string

Returns the system color used for text in menus (Windows-only
property).

Adobe AIR Extension
AIRext.PreviewDocument()
Availability
Fireworks 10.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Usage
status= AIRext.PreviewDocument(appXMLPath, siteRootPath);

Arguments
appXMLPath Path to the application descriptor.
siteRootPath Path to the site root folder in which the file that need to be previewed reside.

Returns
0 if the operation succeeded.
Description
Calls the ADL tool to preview an HTML document as an Adobe AIR application. The path to file that needs to be
previewed is not specified because it is included in the application descriptor; this path is relative to the site root.

AIRext.PackageApplication()
Availability
Fireworks 10.
Usage
status = AIRext.PackageApplication(siteFullPath, packagePath, fileList);

Arguments
siteFullPath Path to the site root folder in which all files that needs to be included in package reside.
packagePath Full path of the resulting Adobe AIR package.
fileList Array of paths to files and folders that need to be included in package; all paths need to be relative to the

site root.
Returns
0 if the operation succeeded; 1 if an error occurred; 2 if the ADT tool generated an error (this error is saved into an
error log file).
Description
Calls the ADT tool package an Adobe AIR application.

AIRext.CreatePackage()
Availability
Fireworks 10.
Usage
status = AIRext.CreatePackage(siteFullPath, packagePath, fileList, appXMLPath,
certificatePath, password);

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

site root.
appXMLPath Path to the application descriptor (if blank or missing, defaults to application.xml in site root).
certificatePath Path to the digital certificate with which to sign the package (if blank or missing, an unsigned AIRI

file will be created instead of a signed AIR file)
password Password for the specified certificate (if blank or missing, user will be prompted for the password).

Returns
0 if the operation succeeded.
Description
Calls the ADT tool to create a signed AIR package.

AIRext.CheckCertificatePassword()
Availability
Fireworks 10.
Usage
status = AIRext.CheckCertificatePassword(certificatePath, password);

Arguments
certificatePath Path to the digital certificate with which to sign the package.
password Password for the specified certificate.

Returns
Exitcode from ADT; 0 if OK, 7 if could not access certificate, and so on.
Description
Calls the ADT tool to check a certificate password.

AIRext.SaveDigSigPassword()
Availability
Fireworks 10.
Usage
AIRext.SaveDigSigPassword(certificatePath, password);

Arguments
certificatePath Path to the digital certificate whose password is being saved.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

password Password for the specified certificate.

Returns
0 if saved successfully.
Description
Saves the password for the given digital certificate, for the current session of Fireworks (no persistent storage).

AIRext.GetDigSigPassword()
Availability
Fireworks 10.
Usage
configurationPath = AIRext.GetDigSigPassword();

Arguments
None.
Returns
The previously saved password for the given digital certificate, or an empty string.
Description
Returns the name of the generated password file.

AIRext.GetLastErrorLogName()
Availability
Fireworks 10.
Usage
errLogName = AIRext.GetLastErrorLogName();

Arguments
None.
Returns
The name of the error log file if it was created, or an empty string.
Description
Returns the name of the generated error log file if one was created.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

AIRext.GetAIRInstallPath()
Availability
Fireworks 10.
Usage
configurationPath = AIRext.GetAIRInstallPath();

Arguments
None.
Returns
The full system path to the current user configuration folder (for example, "C:\Documents and
settings\...\Configuration").
Description
Returns the full system path name and path of the generated file.

AIRext.GetJREVersion()
Availability
Fireworks 10.
Usage
jreVersObj = AIRext.GetJREVersion();

Arguments
None.
Returns
An object with two properties - maxVersion and minVersion; if an error occurs the values of the maxVersion and
minVersion will be -1.
Description
Get the minimum and maximum versions of the JRE.

AIRext.CreateCertificate()
Availability
Fireworks 10.
Usage
status = AIRext.CreateCertificate(certificatePath, password, keyType, publisher, orgName,
orgUnit, country);

Last updated 5/2/2011

EXTENDING FIREWORKS
The Fireworks Object Model

Arguments
certificatePath Path to digital certificate file that will be created (required).
password Password for the created certificate (required)
keyType Encryption key type (either "1024-RSA" or "2048-RSA" (required).
publisher Name of publisher (required).
orgName Name of organization (optional).
orgUnit Organizational unit (optional).
country 2-letter code for country (optional, and length is not enforced).

Returns
0 if operation succeeded.
Description
Calls the ADT to create a self-signed digital certificate.

Last updated 5/2/2011

Chapter 3: The Document object
This chapter describes the Fireworks Document object and functions.

Document object properties
The following table lists the properties of the Document object, along with their data types, acceptable values, and
notes. Read-only properties are marked with a bullet (•). You can also use many API calls to work with documents.
For more information, see “Property inspector functions” on page 321.
Property

Data type

Notes

backgroundColor

string

A color string that specifies the document canvas color (for
more information, see “Color string data type” on page 8).

backgroundURL

string

Sets a general URL for a document that uses a hotspot.
Everything that is not covered by the hotspot has the
background URL.

brushes •

array

Array of Brush objects that are available for use in the
document (for more information, see “Brush object” on
page 243).

currentFrameNum

zero-based index

The index of the current frame.

currentLayerNum

zero-based index

The index of the current layer.

defaultAltText

string

Default Alt text for the output images. It works for single and
sliced images. Sliced images get the default, unless specific text
is specified for a slice. Corresponds to the text that is specified
in the Document-Specific tab of the HTML Setup dialog box.

docTitleWithoutExtension

string

The title of the document file, without any file extension. If the
document has not been saved, this string is empty.

exportFormatOptions

object

Identical to exportOptions. Included for backward
compatibility with Fireworks 2.

exportOptions

object

ExportOptions object (for more information, see
“ExportOptions object” on page 260).

exportSettings

object

ExportSettings object (for more information, see
“ExportSettings object” on page 263).

filePathForRevert

string

The path to the file from which this document was opened,
which is expressed as file://URL, or null if created from scratch.

filePathForSave

string

The location to which this document was saved, which is
expressed as file://URL, or null if never saved.

fills •

array

Array of Fill objects that are available for use in the document
(for more information, see “Fill object” on page 265).

frameCount

integer

The number of frames in the current document.

frameLoopingCount

integer

–1 — don’t repeat
0 — repeat forever
> 0 — repeat this number of times

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

Property

Data type

Notes

frames •

array

Array of Frame objects in the document (for more information,
see “Frame object” on page 266).

gammaPreview

Boolean

If set to true, the document should be previewed in oppositeplatform gamma. If set to false, the document colors are
unadjusted.

gradients •

array

Array of Gradient objects that are available for use in the
document (for more information, see “Gradient object” on
page 267).

gridColor

string

A color string that specifies the color of the grid display (for
more information, see “Color string data type” on page 8).

gridOrigin

point

Used to set the origin of the grid. Corresponds to the point set
when dragging the ruler origin from the upper-left of the
document when rulers are visible.

gridSize

point

gridSize.x is the horizontal grid size; gridSize.y is the

vertical grid size.
guides •

object

Guides object (for more information, see “Guides object” on
page 267).

height

integer

Total height of the document, in pixels. To find the bottom
edge of the document, use document.top +
document.height.

isDirty

Boolean

Set to true if the document was modified since the last time it
was saved.

isPaintMode •

Boolean

Set to true if the document is currently in paint-mode editing,
false otherwise.

isSymbolDocument •

Boolean

Set to true if the document is a Symbol or Button document,
false if it is an ordinary document. You might see this when
looking through the list of open documents and one is a
symbol-editing window.

isValid

Boolean

Set to true if the document is open in Fireworks; false
otherwise. (Occasionally the JavaScript object that is
associated with a document lingers after the document closes;
this property lets you check for that eventuality.)

lastExportDirectory

string

The path to the last directory to which the file was exported,
which is expressed as file://URL, or null if the file was never
exported. For instance, if the document was last exported to
“file:///files/current/logo.gif", it returns
"file:///files/current".

lastExportFile

string

The name that was used the last time the file was exported, or
null if the file was never exported. For instance, if the
document was last exported to
"file:///files/current/logo.gif", it returns
"logo.gif".

layers •

array

An array of Layer objects in the document (for more
information, see “Layer object” on page 268).

left

integer

Coordinate of the left edge of the document, in pixels. To find
the right edge of the document, use document.left +
document.width.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

Property

Data type

Notes

mapType

string

Acceptable values are "client", "server", and "both".
Corresponds to the image-map type selected in File > HTML
Setup.

matteColor

string

A color string that corresponds to the matte color specified in
the Optimize panel (for more information, see “Color string
data type” on page 8). This string is used by the
useMatteColor property.

onionSkinAfter

integer

The number of frames after the current frame to show through
onion skinning. Corresponds to the onion-skin controls in the
left edge of the Frames panel. A value of 0 indicates no onion
skinning; a very large value (such as 99,999) indicates onion
skinning of all frames after the current frame.

onionSkinBefore

integer

Similar to the onionSkinAfter property, but refers to the
number of frames to show through onion skinning before the
current frame.

pagesCount •

integer

Returns the number of pages in the current document.

pageName

string

Returns the page name of the current page.

patterns •

object

The list of internal pattern names.

pathAttributes

object

The PathAttrs object (for more information, see “PathAttrs
object” on page 268). This object specifies default attributes
that will be applied to all newly created objects.

pngText

object

A structure that can be used to store various chunks of text in a
well-known format. For more information, see “The pngText
property” on page 31.

resolution

float

Document resolution, in pixels per unit (for more information,
see resolutionUnits). The range is 1 to 5000.

resolutionUnits

string

Units to be used with the resolution property. Acceptable
values are "inch" and "cm".

savedSelections

object

Array of the saved bitmap selections in the active document.

textures

array

Array of Texture objects that are available for use in the
document (for more information, see “Texture object” on
page 259).

top

integer

Coordinate of the top edge of the document, in pixels. To find
the bottom edge of the document, use document.top +
document.height.

useMatteColor

Boolean

If set to true, the matteColor property is used when
exporting documents with transparent backgrounds. If set to
false, the matteColor property is ignored in this situation,
and the exported file is matted against the document’s canvas
color.

width

integer

The width of the document, in pixels. To find the right edge of
the document, use document.left + document.width.

currentPageNum

integer

The index of the current page.

topLayers

array

Array of top level layers within the document objects.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

The pngText property
Fireworks maintains the following fields for use with the pngText property:
Field name

Value

CreationTime

The date and time the document was created.

Software

The software used to create the document. The current version of Fireworks always sets this value to
“Adobe Fireworks CS5.”

You can edit these fields or add your own fields, and they will be preserved across file saves.
The pngText object corresponds directly to the 'tEXt' chunk of the document’s PNG structure.

Document functions
As discussed in an earlier section, you get and set document properties by calling functions as methods of the
document’s Document Object Model (DOM) (see “Accessing a Fireworks document” on page 7). Methods that
operate on a document’s DOM are listed in this section as dom.functionName(). However, you cannot simply type
dom.functionName(). In place of dom, you must type fw.getDocumentDOM() or fw.documents[documentIndex].
For example:

• How a function looks in this manual: dom.addNewHotspot()
• How you must type it:
fw.getDocumentDOM().addNewHotspot(); // operates on active document

or
fw.documents[documentIndex].addNewHotspot(); // operates on specified document

dom.addBehavior()
Availability
Fireworks 3.
Usage
dom.addBehavior(action, event, eventIndex)

Arguments
action A string that specifies the behavior to be added, such as "MM_swapImageRestore()". For a list of all the
behaviors that can be added, see “Using the dom.addBehavior() function” on page 32.
event The event that triggers the behavior. Acceptable values are "onMouseOver", "onMouseOut", "onLoad", and
"onClick".
eventIndex An integer value that specifies the location where the behavior should be added, starting with 0
(although, to specify the end location, pass –1 here).

Returns
Nothing.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

Description
Adds a specified behavior to the selected hotspots and slices.
Example
The following command adds a simple rollover behavior at the end of the selected slice or hotspot:
fw.getDocumentDOM().addBehavior("MM_simpleRollover()", "onMouseOver", -1);

See also
“dom.removeBehavior()” on page 117

Using the dom.addBehavior() function
The following code shows the syntax for dom.addBehavior():
fw.getDocumentDOM().addBehavior(action, event, eventindex);

The first argument is a string that specifies the behavior to be added; see dom.addBehavior(). The information in this
section describes the acceptable values for the action argument that is passed to dom.addBehavior().

MM_nbGroup [down]
Availability
Fireworks 3.
Arguments
type, barName, target, swapFrame, fileName, preload

• Pass "down" for type.
• Pass "navbar1" for the name of the navigation bar.
•

target specifies the slice to which the behavior is attached. Pass –1 for this value; all other values are used internally
by Fireworks.

•

swapFrame is an integer value that specifies the frame to swap, starting with 0 (although, to use fileName as a URL,

pass –1 here).

•

fileName specifies the frame or file to swap. If you specified a frame to use in swapFrame, pass an empty text string.

If you want to specify a filename and you passed –1 for swapFrame, pass the string for the relative URL of the image.

•

preload is a binary value that specifies whether to preload the swapped image (pass 1) or not (pass 0).

Description
Sets a navigation bar Down behavior.
Example
fw.getDocumentDOM().addBehavior("MM_nbGroup(\'down\',\'navbar1\',-1,2,\"\",1)", "onClick", -1);

MM_nbGroup [highlight]
Availability
Fireworks 3.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

Arguments
type, target, swapFrame, fileName, preload, downHighlight, downHighlightFrame,
downHighlightFilename

• Pass "over" for type.
• target specifies the slice to which the behavior is attached. Pass –1 for this value; all other values are used internally
by Fireworks.

•

swapFrame is an integer value that specifies the frame to swap, starting with 0 (although, to use fileName as a URL,

pass –1 here).

•

fileName specifies the frame or file to be swapped. If you specified a frame to use in swapFrame, pass an empty text
string. If you want to specify a filename and you passed –1 for swapFrame, pass the string for the relative URL of
the image.

•

preload is a binary value that specifies whether to preload the swapped image (pass 1) or not (pass 0).

•

downHighlight is a binary value that specifies whether an image should be used for highlighting on mouse down

(pass 1) or not (pass 0). If you pass 1, use the next two arguments to specify the frame or image to be used.

•

downHighlightFrame is an integer value that specifies the frame to use as a highlight image, starting with 0

(although, to use downHighlightFrame as a URL, pass –1 here).

•

downHighlightFilename specifies the frame or file to be used as the highlight image. If you specified a frame to

use in downHighlightFrame, pass an empty text string. If you want to specify a filename and you passed –1 for
downHighlightFrame, pass the string for the relative URL of the image.

Description
Sets a navigation bar highlight behavior.
Example
fw.getDocumentDOM().addBehavior("MM_nbGroup(\'over\',-1,1,\"\",1,0,3,\"\")", "onMouseOver", -1);

MM_nbGroup [image]
Availability
Fireworks 3.
Arguments
type, downHighlight, initiallyDown

• Pass "all" for type.
•

downHighlight is a binary value that specifies whether the image should be highlighted on a mouse Down action

(pass 1) or not (pass 0).

•

initiallyDown is a binary value that specifies whether the image should initially appear as in the Down state (pass
1) or not (pass 0).

Description
Sets a navigation bar image behavior.
Example
fw.getDocumentDOM().addBehavior("MM_nbGroup(\'all\',1,0)", "onMouseOver", -1);

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

MM_nbGroup [out]
Availability
Fireworks 3.
Arguments
type Pass "out" for type.
Description
Sets a navigation bar restore behavior.
Example
fw.getDocumentDOM().addBehavior("MM_nbGroup(\'out\')", "onMouseOut", -1);

MM_simpleRollover
Availability
Fireworks 3.
Arguments
None.
Description
Adds a simple rollover behavior.
Example
fw.getDocumentDOM().addBehavior("MM_simpleRollover()", "onMouseOver", -1);

MM_statusMessage
Availability
Fireworks 3.
Arguments
message A string that specifies the status message to appear.
Description
Sets a status bar message.
Example
fw.getDocumentDOM().addBehavior("MM_statusMessage(\"Status Message!\")", "onMouseOver", -1);

MM_swapImage
Availability
Fireworks 3.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

Arguments
target, swapFrame, fileName, preload, restoreOnMouseOut

•

target specifies the slice to which the behavior is attached. Pass1– for this value; all other values are used internally

by Fireworks.

•

swapFrame is an integer value that specifies the frame to swap, starting with 0 (although, to use fileName as a URL,

pass –1 here).

•

fileName specifies the frame or file to swap. If you specified a frame to use in swapFrame, pass an empty text string.

If you want to specify a filename and you passed –1 for swapFrame, pass the string for the relative URL of the image.

•

preload is a binary value that specifies whether to preload the swapped image (pass 1) or not (pass 0).

•

restore is a binary value that specifies whether to restore on a mouse out action (pass 1) or not (pass 0).

Description
Adds a swap image behavior.
Example
fw.getDocumentDOM().addBehavior("MM_swapImage(-1,1,\"\",1,1)", "onMouseOver", -1);

MM_swapImgRestore
Availability
Fireworks 3.
Arguments
None.
Example
fw.getDocumentDOM().addBehavior("MM_swapImgRestore()", "onMouseOut", -1);

Description
Adds a swap image restore behavior.

dom.addElementMask()
Availability
Fireworks 4.
Usage
dom.addElementMask(mode, {bEnterMaskEditMode})

Arguments
mode Acceptable values for mode are “reveal all", "hide all", "reveal selection", and"hide selection".
If the user is not in bitmap mode, or if there is no pixel selection, "reveal selection" and "hide selection"
operate the same as "reveal all" and "hide all", respectively.
bEnterMaskEditMode If bEnterMaskEditMode (optional) is set to true, Fireworks enters mask-edit mode on the
newly added mask; if omitted, it defaults to false.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

Returns
Nothing.
Description
Adds a new empty mask to the selected element. If the selection already has an element mask, it is replaced with the
new one. Only one element can be selected when calling this function. If selecting more than one element (or none) at
the time this function is called, Fireworks throws an exception.

dom.addFrames()
Availability
Fireworks 3, enhanced in Fireworks 4.
Usage
dom.addFrames(howMany, where, {bAdvanceActiveFrame})

Arguments
howMany An integer that specifies how many frames to add.
where The location where frames should be added. Acceptable values for where are "beginning", "before
current", "after current", and "end".
bAdvanceActiveFrame Added in Fireworks 4, specifies whether to change the active frame. If it is omitted or true,
this function sets the active frame to the first frame added. If false, the active frame does not change. For example, if
the user is adding frames at the end of a document that has two frames and bAdvanceActiveFrame is omitted or true,
then the third frame becomes the active frame.

Returns
Nothing.
Description
Adds one or more frames to the document.
Example
The following command adds one frame after the current frame but does not change the active frame:
fw.getDocumentDOM().addFrames(1, "after current", false);

dom.addGuide()
Availability
Fireworks 3.
Usage
dom.addGuide(float position, guidekind)

Arguments
position A floating-point value that specifies the x or y coordinate at which to add the guide.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

guidekind Acceptable values for guidekind are "horizontal" and "vertical". If guidekind is "horizontal", it

is assumed that position is a y coordinate; if "vertical", it is an x coordinate.
Returns
Nothing.
Description
Adds a guide to the document. If a guide already exists at the specified position, this function has no effect.
Example
The following command adds a vertical guide at the x coordinate of 217:
fw.getDocumentDOM().addGuide(217, "vertical");

dom.addMasterPageLayer()
Availability
Fireworks CS3.
Usage
dom.addMasterPageLayer()

Arguments
To add a master page layer, the document must already have a master page in it. Include the level where the master
page layer should be inserted. For example:
fw.getDocumentDOM().addMasterPageLayer(-1)

Returns
Nothing.
Description
Adds a master page layer to the bottom of the layer hierarchy for the current page.

dom.addNewHotspot()
Availability
Fireworks 3.
Usage
dom.addNewHotspot(hotspot-kind, hotspot-shape, boundingRectangle)

Arguments
hotspot-kind
hotspot-shape

Acceptable values are "hotspot" and "slice".
Acceptable values are "rectangle" and "oval".

boundingRectangle

A rectangle that specifies the bounds within which the hotspot is placed (see “Rectangle data

type” on page 9).

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

Returns
Nothing.
Description
Adds a new hotspot that fits into the specified bounding rectangle.
Example
The following command adds a new rectangle slice with the specified coordinates:
fw.getDocumentDOM().addNewHotspot("slice","rectangle",{left:0, top:0, right:50, bottom:100});

dom.addNewImage()
Availability
Fireworks 3.
Usage
dom.AddNewImage(boundRectangle, bEnterPaintMode)

Arguments
A rectangle that specifies the bounds of the image to be added (see “Rectangle data type” on
page 9). You cannot create an image that is larger than the document; therefore, if you pass in a rectangle with bounds
larger than the document size, you can create an image that is constrained to the document size.
boundRectangle

bEnterPaintMode If bEnterPaintMode is true, the application immediately enters bitmap mode for the new image.

Returns
Nothing.
Description
Adds a new empty (transparent) image to the document.
Example
The following command adds an empty image that is 500 by 500 pixels in size, and then enters bitmap mode:
fw.getDocumentDOM().addNewImage({left:0, top:0, right:500, bottom:500}, true);

dom.addNewImageViaCopy()
Availability
Fireworks MX.
Usage
dom.addNewImageViaCopy()

Arguments
None.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

Returns
Nothing.
Description
Adds a new image to the document containing the contents of the current paint-mode selection. The new image is
placed directly above the active bitmap. You must have a current pixel selection for this to succeed. The new bitmap
appears with Fireworks in paint mode.

dom.addNewImageViaCut()
Availability
Fireworks MX.
Usage
dom.addNewImageViaCut()

Arguments
None.
Returns
Nothing.
Description
Adds a new image to the document that contains the contents of the current paint mode selection. The new image is
placed directly above the active bitmap. You must have a current pixel selection for this to succeed. The selection is cut
from the previously active bitmap. The new bitmap appears with Fireworks in paint mode.

dom.addNewLayer()
Availability
Fireworks 3.
Usage
dom.addNewLayer(name, bshared)

Arguments
name A string that specifies the name for the new layer. If name is null, a new layer name is generated.
bShared

A Boolean value that specifies whether the new layer is shared.

Returns
A string value that contains the name of the new layer.
Description
Adds a new layer to the document and makes it the current layer.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

Example
The following command adds a new unshared layer with a default name that is generated by Fireworks:
fw.getDocumentDOM().addNewLayer(null, false);

dom.addNewLine()
Availability
Fireworks 3.
Usage
dom.addNewLine(startPoint, endPoint)

Arguments
startPoint and endPoint

Points that specify the x,y coordinates between which the path is added (see “Point data

type” on page 9).
Returns
Nothing.
Description
Adds a new path between two points. The new path uses the document’s current default path attributes and is added
to the current frame and layer.
Example
The following command adds a new line between the specified coordinates:
fw.getDocumentDOM().addNewLine({x:64.5, y:279.5}, {x:393.5, y:421.5});

dom.addNewOval()
Availability
Fireworks 3.
Usage
dom.addNewOval(boundingRectangle)

Arguments
boundingRectangle A rectangle that specifies the bounds of the oval to be added (see “Rectangle data type” on

page 9).
Returns
Nothing.
Description
Adds a new oval fitting into the specified bounding rectangle. The oval uses the document’s current default path
attributes and is added on the current frame and layer.

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

Example
The following command adds a new oval within the specified coordinates:
fw.getDocumentDOM().addNewOval({left:72, top:79, right:236, bottom:228});

dom.addNewPage()
Availability
Fireworks CS3.
Usage
dom.addNewPage()

Arguments
None
Returns
Nothing.
Description
Adds a new page to the current document.

dom.addNewRectangle()
Availability
Fireworks 3.
Usage
dom.addNewRectangle(boundingRectangle, roundness)

Arguments
boundingRectangle A rectangle that specifies the bounds within which the new rectangle is added (see “Rectangle
data type” on page 9).
roundness A floating-point value between 0 and 1 that specifies the roundness to use for the corners (0 is no

roundness, 1 is 100% roundness).
Returns
Nothing.
Description
Adds a new rectangle or rounded rectangle fitting into the specified bounds. The rectangle uses the document’s current
default path attributes and is added on the current frame and layer.
Example
The following command adds a new rectangle with no round corners within the specified coordinates:
fw.getDocumentDOM().addNewRectangle({left:0, top:0, right:100, bottom:100}, 0);

Last updated 5/2/2011

EXTENDING FIREWORKS
The Document object

category

string

Specifies where this fill appears in the Fill panel.

ditherColors

array

Array of two color strings (see “Color string data type” on
page 8).

edgeType

string

Acceptable values are "hard" and "antialiased".

feather

integer

0 to 1000, which represents the feathering value in pixels (0
means no feathering).

gradient

object

Gradient object (see “Gradient object” on page 267).

name

string

The name that appears in the Fill panel.

pattern

object

Pattern object (see “Pattern object” on page 269).

shape

string

Acceptable values are "solid", "linear", "radial",
"conical", "satin", "pinch", "folds", "elliptical",
"rectangular", "bars", "ripple", "waves", "pattern",
and "web dither".

Last updated 5/2/2011

266

EXTENDING FIREWORKS
Objects within Fireworks documents

Property

Data type

Notes

stampingMode

string

Acceptable values are "blend" and "blend opaque".

textureBlend

float

0 to 100

webDitherTransparent

Boolean

If set to true (and shape is set to "web dither"), then the
second color in the ditherColors array is ignored and
transparent is used instead.

Frame object
The following table lists the properties of the Frame object, along with their data types and, where appropriate,
acceptable values and notes. Read-only properties are marked with a bullet (•).
Property

Data type

Notes

delay

integer

Hundredths of a second.

disposal

string

Acceptable values are "unspecified", "none",
"background", and "previous".

layers •

array

Array of FrameNLayerIntersection objects in the document
(see “FrameNLayerIntersection object” on page 266).

name

string

Specifies the name of the state.

topLayers

array

Array of top layers returned as FrameNLayerIntersection
objects.

visible

Boolean

If set to false, this frame is hidden. Default value is true.

FrameNLayerIntersection object
The following table lists the properties of the FrameNLayerIntersection object, along with their data types and, where
appropriate, acceptable values and notes. Read-only properties are marked with a bullet (•).
Property

Data type

Notes

elements •

array

Array of Element objects (see “Element object” on page 254).

elemsandsublayers

array

Array of elements and sublayers obtained from topLayers.

locked

Boolean

If set to true, this FrameNLayerIntersection object is locked.
The default value is false.

name

string

Specifies the name of the layer when the layers are accessed
from states.

visible

Boolean

If set to false, this FrameNLayerIntersection object is hidden.
The default value is true.

Last updated 5/2/2011

267

EXTENDING FIREWORKS
Objects within Fireworks documents

Gradient object
The following table lists the properties of the Gradient object, along with their data types and, where appropriate,
acceptable values and notes.
Property

Data type

Notes

name

string

The name that appears in the Fill panel.

nodes

array

Array of GradientNode objects (see “GradientNode object” on
page 267).

opacityNodes

array

Array of GradientNode objects (see “GradientNode object” on
page 267), that identify the opacity ramp associated with a
gradient.

GradientNode object
The following table lists the properties of the GradientNode object, along with their data types and, where appropriate,
acceptable values and notes.
Property

Data type

Notes

color

string

A color string that specifies the color at this position in the
gradient (see “Color string data type” on page 8).

isOpacityNode

Boolean

If set to true, this node is part of the gradient’s opacity ramp.

position

float

0.0 to 1.0

Guides object
The following table lists the properties of the Guides object, along with their data types and, where appropriate,
acceptable values and notes.
Property

Data type

Notes

color

string

A color string that specifies the color used for the guides (see
“Color string data type” on page 8).

hGuides

array

Array of floating-point numbers that specify horizontal guide
locations.

locked

Boolean

If set to true, the user cannot select or move the guides. The
default value is false.

vGuides

array

Array of floating-point numbers that specify vertical guide
locations.

Last updated 5/2/2011

268

EXTENDING FIREWORKS
Objects within Fireworks documents

Layer object
The following table lists the properties of the Layer object, along with their data types and, where appropriate,
acceptable values and notes. Read-only properties are marked with a bullet (•).
Property

Data type

Notes

disclosure

Boolean

If set to true, the Layers list displays all the objects in the layer.
If set to false, only the name of the layer appears.

elems •

array

Array of elements inside a layer which also include sublayers.

frames •

array

An array of FrameNLayerIntersection objects (see
“FrameNLayerIntersection object” on page 266).

isLayer •

Boolean

Always true for a layer.

layerType •

string

Acceptable values are "normal" and "web".

name

string

Might be null (removes any existing name).

sharing

string

Acceptable values are "shared" and "not shared".

PathAttrs object
The following table lists the properties of the PathAttrs object, along with their data types and, where appropriate,
acceptable values and notes.
Property

Data type

Notes

brush

object

Brush object (see “Brush object” on page 243).

brushColor

string

A color string that specifies the color that is used for rendering
the Brush object, if any (see “Color string data type” on page 8).

brushPlacement

string

Acceptable values are "inside", "center", and "outside".

brushTexture

object

Texture object (see “Texture object” on page 259).

fill

object

Fill object (see “Fill object” on page 265).

fillColor

string

A color string that specifies the color used for rendering the Fill
object, if any (see “Color string data type” on page 8).

fillHandle1

point

The three fillHandle properties are used by Gradient and
Pattern fills to set the angle and size of the gradient/pattern.

fillHandle2

point

fillHandle3

point

fillOnTop

Boolean

If set to true, the fill is drawn on top of the brush; if set to
false (the default), the fill is drawn beneath the brush.

fillTexture

object

Texture object (see “Texture object” on page 259).

Last updated 5/2/2011

269

EXTENDING FIREWORKS
Objects within Fireworks documents

Pattern object
The following table lists the property of the Pattern object, along with its data type and notes.
Property

Data type

Notes

name

string

The name that appears in the Fill panel.

RectanglePrimitive object
The following table lists the properties of the RectanglePrimitive object, along with their data types and, where
appropriate, acceptable values and notes.
Property

Data type

Notes

roundness

float

A floating-point value between 0 and 1 that specifies the
“roundness” to use for the corners (0 is no roundness, 1 is 100%
roundness).

originalSides

rectangle

A rectangle that specifies the original sides of the primitive (see
“Rectangle data type” on page 9). Because rectangle primitives
remember transformations, the user might see something
different from the original sides.

mode

string

Specifies the roundness units, which can be relative
(percentage) or exact (pixels).

transform

matrix

A matrix that indicates all the transformations that were
applied to the primitive (see “Matrix data type” on page 9).

pathAttributes

object

A PathAttrs object that indicates the path attributes of the
primitive (see “PathAttrs object” on page 268).

RegisterMoveParms object
The following table lists the properties of the RegisterMoveParms object, along with their data types and, where
appropriate, acceptable values and notes.
Property

Data type

Notes

constrainAngles

Boolean

Determines whether dragging the control point constrains the
angles to the minAngle and maxAngle values.

constrainRotateKey

string

Pass in the key that you want to use to constrain the rotation. A
value of "none" means that rotation will not be constrained.
A value of "shiftKey" means that when the user holds
downs the Shift key while dragging the mouse, rotation will be
constrained. The value can be one of the following: "none",
"shiftKey", "ctrlCmdKey", "altOptKey".
Note: these points are set with minAngle and maxAngle.

constrainX

float

The value to constrain the x coordinate.
Note: the method constrainXKey must be used with this
method.

Last updated 5/2/2011

270

EXTENDING FIREWORKS
Objects within Fireworks documents

Property

Data type

Notes

constrainXKey

string

Pass in the key that you want to use to constrain the xcoordinate value. A value of "none" means that x will not be
constrained. A value of "shiftKey" means that when the user
holds downs the Shift key while dragging the mouse, x will be
constrained. The value can be one of the following: "none",
"shiftKey", "ctrlCmdKey", "altOptKey".
The value to constrain the y coordinate.

constrainY

Note: the method constrainYKey must be used with this
method.
Pass in the key that you want to use to constrain the ycoordinate value. A value of "none" means that y will not be
constrained. A value of "shiftKey" means that when the user
holds downs the Shift key while dragging the mouse, the value
of y will be constrained. The value can be one of the following:
"none", "shiftKey", "ctrlCmdKey", "altOptKey".

constrainYKey

constrain45Key

string

The key value that you want to use to constrain movement to
the nearest 45º increment. Can be one of the following:
"none", "shiftKey", "ctrlCmdKey", "altOptKey".
A key value of "none" means dragging will not be constrained,
"shiftKey" (or other value) means that when the user holds
downs Shift key (or other value) while dragging, movement
will be constrained.

constrain90Key

string

The key value that you want to use to constrain movement to
the nearest 90º increment. Can be one of the following:
"none", "shiftKey", "ctrlCmdKey", "altOptKey".
A key value of "none" means dragging will not be constrained,
"shiftKey" (or other key) means that when the user holds
downs the Shift key (or other key) while dragging, movement
will be constrained.

deltaLinearToLinear

float

Determines the ratio of mouse movement to point movement
along the line. For example, a value of 1.0 means that if the
mouse moves 1 pixel, the point moves 1 pixel along the line
specified in the method RegisterLinearMove.

deltaRtoR

float

Determines the mouse radius change relative to the point
radius change. For example, a value of 1.0 means that as the
mouse moves 1 pixel away from the center of the object, the
point also moves 1 pixel away from the center of the object.

deltaShortestSideToX

float

The ratio of shortest mouse movement to the movement of
referenced point’s x coordinate.

deltaShortestSideToY

float

The ratio of shortest mouse movement to the movement of
referenced point’s y coordinate.

deltaLongestSideToX

float

The ratio of longest mouse movement to the movement of
referenced point’s x coordinate.

deltaLongestSideToY

float

The ratio of longest mouse movement to the movement of
referenced point’s y coordinate.

deltaXtoX

float

The ratio of mouse movement to the movement of the
referenced point’s x coordinate. For example, 1.0 means that
when the mouse moves 1 pixel to the right, the referenced
point also moves 1 pixel to the right.

Last updated 5/2/2011

271

EXTENDING FIREWORKS
Objects within Fireworks documents

Property

Data type

Notes

deltaXtoY

float

The ratio of mouse movement on the x-axis to the movement
of the referenced point’s y coordinate. For example, 1.0 means
that when the mouse moves 1 pixel to the left, the referenced
point moves 1 pixel towards the top of the document.

deltaYtoX

float

The ratio of mouse movement on the y-axis to the movement
of the referenced point’s x coordinate. For example, 1.0 means
that when the mouse moves 1 pixel to the top of the
document, the referenced point moves 1 pixel to the left.

deltaYtoY

float

The ratio of mouse movement to the movement of the
referenced point’s y coordinate. For example, 1.0 means that
when the mouse moves 1 pixel toward the bottom of the
document, the referenced point also moves 1 pixel toward the
bottom of the document.

disableRotateKey

string

Pass in the key that you want to use to disable rotating around
the center. The value can be one of the following: "none",
"shiftKey", "ctrlCmdKey", "altOptKey". A value of
"none" means rotation will not be constrained. A value of
"shiftKey" means that when the user holds downs the Shift
key while dragging the mouse, rotation is not constrained.

incrementRadius

float

Constant value that is added to the radius.

incrementX

float

This amount is added to the x movement of the mouse when
calculating the total movement.

incrementY

float

This amount is added to the y movement of the mouse when
calculating the total movement.

maxAngle

point

The maximum angle that can be set.

maxLinear

float

Determines the maximum amount the point can move along a
line.

maxRadius

float

The maximum radius value.

maxX

float

The maximum value the x coordinate can move.

maxY

float

The maximum value the y coordinate can move.

minAngle

point

The minimum angle that can be set.

minLinear

float

The minimum amount the point can move along a line.

minMaxRelative

Boolean

Determines whether the min and max values are relative or
absolute. For example, if max.x=100 and minMaxRelative is
true, then x can move up 100 points to the right. If
minMaxRelative is set to false then the maximum x can be
set to is 100.

minX

float

The minimum value the x coordinate can move.

minY

float

The minimum value the y coordinate can move.

minRadius

float

The minimum radius value.

movePred

Boolean

Determines whether the predecessor point should be moved
as the user moves the mouse.

Last updated 5/2/2011

272

EXTENDING FIREWORKS
Objects within Fireworks documents

Property

Data type

Notes

movePt

Boolean

Determines whether the point itself should be moved as the
user moves the mouse.

moveSucc

Boolean

Determines whether the successor point should be moved as
the user moves the mouse.

rotate

Boolean

Determines whether the point should rotate along with the
mouse rotation.

SingleTextRun object
The following table lists the properties of the SingleTextRun object, along with their data types and, where appropriate,
acceptable values and notes.
Property

Data type

Notes

changedAttrs

object

TextAttrs object (see “TextAttrs object” on page 274).

characters

string

The text that is contained in this run.

SmartShape object
The following table lists the properties of the SmartShape object, along with their data types and, where appropriate,
acceptable values and notes. Read-only properties are marked with a bullet (•).
Property

Data type

Notes

altOptKeyDown •

Boolean

Indicates whether the Alt/Option key is pressed (true if
pressed, otherwise false).

constrainDragInsertAspect

Boolean

Determines if, while dragging a shape on the canvas, the
aspect ratio is constrained (true if constrained, otherwise
false).

constrainDragInsertAspectKey string

The key value that will cause the aspect ratio to be constrained
during a DragInsert operation.

ctrlCmdKeyDown •

Boolean

Indicates whether the Control/Command key is pressed (true
if pressed, otherwise false).

currentControlPoint •

object

Returns the current control point object.

currentControlPointIndex •

integer

Returns the index number of the current control point.

currentControlPointName •

string

Returns the name of the current control point.

currentMousePos

point

Location of the mouse during the current drag message.

elem •

object

Objects defined as part of the current Auto Shape.

getsDragEvents

Boolean

Sets notification for drag events (true notifies the smartshape
for every mouse movement, false sets no notification).

Last updated 5/2/2011

273

EXTENDING FIREWORKS
Objects within Fireworks documents

Property

Data type

Notes

livePreview

Boolean

Sets live preview. A value of true enables live preview, and
disables wire-frame preview handled by Fireworks. Live
preview is slower than wire-frame preview.
If you want the user to set this value, write a function handling
the DragControlPoint message from Fireworks (see “Fireworks
messages” on page 306.

mouseDownPos •

point

Location of the mouse during a mouse click.

operation •

string

Message received from Fireworks, see “Fireworks messages” on
page 306 for possible messages.

prevMousePos •

point

Location of the mouse at the previous drag message.

shiftKeyDown •

Boolean

Indicates whether the Shift key is pressed.

The following table lists the method of the SmartShape object, along with its parameter.
Method

Parameter

Definition

GetDefaultMoveParms()

object

Returns an object that has all of the default move parameters
set.

Style object
The following table lists the properties of the Style object, along with their data types and, where appropriate,
acceptable values and notes. All Style object properties are read-only.
Property (read-only)

Data type

Notes

effectList

object

EffectList object (see “EffectList object” on page 254).

name

string

The name displayed in the Style panel.

pathAttributes

object

PathAttrs object (see “PathAttrs object” on page 268).

tdTagText

string

A string that contains all the attributes of a table cell except
colspan and rowspan. Should be in a format similar to the
following: "bgcolor="ff0000" valign="top""

textBold

Boolean

Makes the specified text bold; used only if use_textStyles is
set to true.

textFont

string

The font to apply to text; used only if use_textFont is set to
true.

textItalic

Boolean

Makes the specified text italic; used only if use_textStyles
is set to true.

textSize

string

String of the form "#pt", where # is a numeric value.

textUnderline

Boolean

Underlines the specified text; used only if use_textStyles is
set to true.

use_brush

Boolean

If set to true, applies the brush property of the PathAttrs
object when applying the style. If set to false, ignores the
brush property. The default value is false.

Last updated 5/2/2011

274

EXTENDING FIREWORKS
Objects within Fireworks documents

Property (read-only)

Data type

Notes

use_brushColor

Boolean

If set to true, applies the brushColor property of the
PathAttrs object when applying the style. If set to false,
ignores the brushColor property. The default value is false.

use_effectList

Boolean

If set to true, applies the effects property of the EffectList
object when applying the style. If set to false, ignores the
effects property. The default value is false.

use_fill

Boolean

If set to true, applies the fill property of the PathAttrs object
when applying the style. If set to false, ignores the fill
property. The default value is false.

use_fillColor

Boolean

If set to true, applies the fillColor property of the PathAttrs
object when applying the style. If set to false, ignores the
fillColor property. The default value is false.

use_textFont

Boolean

If set to true, applies the textFont property of the PathAttrs
object when applying the style. If set to false, ignores the
textFont property. The default value is false.

use_textSize

Boolean

If set to true, applies the textSize property of the PathAttrs
object when applying the style. If set to false, ignores the
textSize property. The default value is false.

use_textStyles

Boolean

If set to true, applies the textStyles property of the
PathAttrs object when applying the style. If set to false,
ignores the textStyles property. The default value is false.

TextAttrs object
The following table lists the properties of the TextAttrs object, along with their data types and, where appropriate,
acceptable values and notes.
Property

Data type

Notes

alignment

string

Acceptable values are "left", "center", "right",
"justify", and "stretch".

baselineShift

integer

The number of pixels above (positive numbers) or below
(negative numbers) the baseline by which the characters are
shifted.

bold

Boolean

Set to true for bold text, false for normal text.

face

string

The name of the font, such as Arial.

fillColor

string

A color string that specifies the color of the text (see “Color
string data type” on page 8).

horizontalScale

float

The relative width of the characters.
1.0 — normal width
< 1 — thinner than normal
> 1 — wider than normal

italic

Boolean

Set to true for italic text, false for normal text.

Last updated 5/2/2011

275

EXTENDING FIREWORKS
Objects within Fireworks documents

Property

Data type

Notes

kerning

float

Also known as pair kerning, kerning specifies the percentage
of an em square by which to separate two characters, in
addition to the amount the font specifies. Applies to only one
pair or characters. To specify kerning for a range of text, use the
rangeKerning property.
0 — normal kerning
< 0 — move the two characters closer together
> 0 — move the two characters farther apart

leading

float

The spacing between two lines of text, measured from baseline
to baseline. Larger numbers place more space between lines of
text. Smaller numbers move the lines closer together. The
exact effect of this property number depends on the value of
the leadingMode property.

leadingMode

string

The only acceptable value is "percentage", which specifies
that the leading property is a percentage of the text’s point
size. A leading property of 1.0 means 100 percent or singlespaced, 2.0 means 200 percent or double-spaced, and so on.

rangeKerning

float

The same as the kerning property, but applies to a range of
text, not only two characters.

size

string

String of the form "#pt", where # is a numeric value.

underline

Boolean

Set to true for underlined text, false for normal text.

TextRuns object
The following table lists the properties of the TextRuns object, along with their data types and, where appropriate,
acceptable values and notes.
Property

Data type

Notes

initialAttrs

object

TextAttrs object (see “TextAttrs object” on page 274).

textRuns

array

Array of SingleTextRun objects on this TextRuns object (see
“SingleTextRun object” on page 272).

Widget object
The following table lists the properties of the Widget object, along with their data types and, where appropriate,
acceptable values and notes.
Property

Data type

Notes

element.visible

Boolean

Sets the visibility of an element to true or false.

element.opacity

integer

Sets the opacity of an element.

element.pathattrs.brushColor string

A color string that specifies the brush color for the path
attributes of the primitive (see “Color string data type” on
page 8 and “PathAttrs object” on page 268).

Last updated 5/2/2011

276

EXTENDING FIREWORKS
Objects within Fireworks documents

Property

Data type

element.pathattrs.brush.diam long
eter
element.pathattrs.fillColor

string

Notes
A value that specifies the brush diameter for the path attributes
of the primitive (see “PathAttrs object” on page 268).
A color string that specifies the fill color for the path attributes
of the primitive (see “Color string data type” on page 8 and
“PathAttrs object” on page 268).

element.pathattrs.fill.feath long
er

A value that specifies the fill feather attribute for the path
attributes of the primitive (see “PathAttrs object” on page 268).

element.pathattrs.fill.gradi object
ent.nodes

A GradientNode object (see “GradientNode object” on
page 267).

element.pathattrs.fill.gradi object
ent.opacityNodes

A GradientNode object (see “GradientNode object” on
page 267), that identifies the opacity ramp associated with a
gradient.

element.pathattrs.fill.gradi string
ent.color

A color string that specifies the color at the specified position in
the gradient (see “Color string data type” on page 8).

element.pathattrs.fill.gradi integer
ent.position

A value that specifies a position within the gradient fill.

element.pathattrs.fill.gradi Boolean
ent.isOpacityNode

If set to true, this node is part of the gradient’s opacity ramp.

text.textChars

string

A string containing the text characters.

text.italic

Boolean

Set to true for italic text, false for normal text.

text.underline

Boolean

Set to true for underlined text, false for normal text.

text.bold

Boolean

Set to true for bold text, false for normal text.

text.font

String

The name of the font, such as Arial.

text.fontsize

integer

The size of the font in points, such as 10.

text.alignment

string

Acceptable values are "left", "center", "right",
"justify", and "stretch".

The following table lists a method of the Widget object, along with its parameters.
Method

Parameter

Definition

GetObjectByName()

elemName

The elemName value specifies the element name for the object
as it is specified in the Layers panel. This method returns the
JavaScript type for the specified element name.
For example: var bound_rect =
Widget.GetObjectByName(elemName);

isWidgetSelected

Boolean

true if the selected element is a widget.

UpdateWidget

propString

Updates the rich symbol instances.

Widget.elem

elemName

Reference to the instance currently executing the widget
script.

Widget.opCode

String

A num code representing the action for the current running
widget script. 1 = setDefaultValues, 2 = applyCurrentValues.

widget.jsCode

String

The jsCode for the currently running widget script.

Last updated 5/2/2011

277

Chapter 6: HTML export objects
Fireworks provides several object types that support the output of HTML and sliced images from Fireworks. These
objects let you write JavaScript scripts that create templates to output the type of HTML that suits your specific
requirement (generic HTML, Dreamweaver-compatible HTML, and so on). For each HTML template, use a Slices.htt
file that generates the HTML for that particular template. For more information, see the Slices.htt and Metafile.htt files
that are installed with Fireworks.
Note: For information on how to format nonstandard data types, such as rectangle or point, see “Formatting
nonstandard data types” on page 8.

BehaviorInfo object
The BehaviorInfo object describes a behavior that is assigned to an element. There are seven behaviors: Status Message,
Swap Image, Button Down, Swap Image Restore, Button Highlight, Button Restore, and Popup Menu (new in
Fireworks 4). The following table lists the properties of the BehaviorInfo object, along with their data types and, where
appropriate, acceptable values and notes. All BehaviorInfo object properties are read-only.
Property (read-only)

Data type

Notes

action

integer

Specifies the type of behavior: 1 is Status Message, 2 is Swap
Image, 4 is Button Down, 5 is Swap Image Restore, 6 is Button
Highlight, 7 is Button Restore, and 9 is Popup Menu. In the
standard (default) templates, the following values are defined:
var kActionStatusMessage = 1;
var kActionSwapImage = 2;
var kActionButtonDown = 4;
var kActionSwapImageRestore = 5;
var kActionButtonHighlight = 6;
var kActionButtonRestore = 7;
var kActionPopupMenu = 9;

behaviorText

string

For roundtrip HTML from Dreamweaver, specifies the
JavaScript behaviors that don’t have an equivalent in
Fireworks.

borderColor

string

If action is set to 9 (Popup Menu), specifies the border color of
the menu, in hexadecimal.

borderSize

integer

If action is set to 9 (Popup Menu), specifies the size of the
menu border in points.

cellOverColor

string

If action is set to 9 (Popup Menu), specifies the cell color for
the Over state.

cellUpColor

string

If action is set to 9 (Popup Menu), specifies the cell color for
the Up state.

creationDate

date

Specifies the date the document was created.

dhHref

string

If action is set to 6 (Button Highlight), specifies the URL of the
highlight image used for the Down button state.

Last updated 5/2/2011

278

EXTENDING FIREWORKS
HTML export objects

Property (read-only)

Data type

Notes

dhTargetFrame

integer

If action is set to 6 (Button Highlight), specifies the target
frame number for the down highlight state.

downHighlight

Boolean

If action is set to 6 (Button Highlight), specifies if there is an
image highlight for the Down button state.

event

integer

Specifies the type of event: 0 is Mouse Over, 1 is On Click, 2
is Mouse Out, and 3 is On Load. In the standard (default)
templates, the following values are defined:
var kEventMouseOver = 0;var kEventOnClick = 1;
var kEventMouseOut = 2;var kEventOnLoad=3;

groupChecked

Boolean

Specifies whether the group option is checked.

groupName

string

Returns a constant value such as navbar1.

hasDhTargetFrame

Boolean

If action is set to 6 (Button Highlight), specifies if the highlight
image for the Down button state has a target frame.

hasDhHref

Boolean

If action is set to 6 (Button Highlight), specifies if the highlight
image for the Down button state has an href.

hasHref

Boolean

If action is set to 2 (Swap Image), specifies if an external file is
swapped in. The value of hasHref is always the opposite of
hasTargetFrame; you cannot swap from two sources.

hasStatusText

Boolean

If action is set to 1 (Status Message), specifies if the status
text is not empty.

hasTargetFrame

Boolean

If action is set to 2 (Swap Image), specifies if the swap image
swaps is in another frame in the Fireworks file. The value of
hasTargetFrame is always the opposite of hasHref; you
cannot swap from two sources.

hideTimeout

Integer

Specifies the timeout in milliseconds.

hideOnMouseout

Boolean

If action is set to 9 (Popup Menu), specifies if the menu is
hidden on a Mouse Out event.

hiliteColor

string

If action is set to 9 (Popup Menu), specifies the highlight color
in the upper-left corner of the menu cells.

horzOffset

integer

If action is set to 9 (Popup Menu), horzOffset specifies the
horizontal pixel offset for the menu.

horzSubmenuOffset

Integer

Specifies the horizontal offset value of the submenu.

href

string

If action is set to 2 (Swap Image), specifies the file URL for an
external swap image file. Value is expressed as file://URL.

menuFontFamily

string

If action is set to 9 (Popup Menu), specifies the name of the
font family to use for the menu.

menuHeight

integer

If action is set to 9 (Popup Menu), specifies the height in
points of the menu cell.

menuImagePath

string

If action is set to 9 (Popup Menu), specifies the path to the
first image.

menuImagePath2

string

If action is set to 9 (Popup Menu), specifies the path to the
second image.

menuItems

array

If action is set to 9 (Popup Menu), specifies an array that lists
the items in the menu.

Last updated 5/2/2011

279

EXTENDING FIREWORKS
HTML export objects

Property (read-only)

Data type

Notes

menuItemPadding

integer

If action is set to 9 (Popup Menu), specifies the cell padding
for the menu items.

menuItemSpacing

integer

If action is set to 9 (Popup Menu), specifies the spacing
between menu items in points.

menuWidth

integer

If action is set to 9 (Popup Menu), specifies the width, in
points, of the menu cell.

objectName

string

Name of the behavior.

opaqueBackground

Boolean

If action is set to 9 (Popup Menu), specifies if the menu cell
background is opaque.

overrideMenuHeight

Boolean

Specifies whether the menu height is overridden.

overrideMenuWidth

Boolean

Specifies whether the menu width is overridden.

preload

Boolean

If action is set to 2 (Swap Image), specifies if the image is to be
preloaded.

restoreOnMouseout

Boolean

If action is set to 2 (Swap Image), specifies if the original
image is restored on a Mouse Out event.

shadowColor

string

If action is set to 9 (Popup Menu), specifies the shadow color
in the lower-right corner of the menu cells.

soundFileName

string

URL of the sound file.

statusText

string

If action is set to 1 (Status Message), specifies the status
message text.

submenuRelativeToItem

Boolean

Specifies whether the submenu is relative to the menu item.

targetColumnNum

zero-based index

If action is set to 2 (Swap Image), specifies the column in the
slices table that is swapped.

targetFrameNum

zero-based index

If action is set to 2 (Swap Image), specifies the frame number
to be swapped if hasTargetFrame is set to true.

targetRowNum

zero-based index

If action is set to 2 (Swap Image), specifies the row in the slices
table that is swapped.

targetTable

object

If action is set to 2 (Swap Image), specifies the table of slices
in the target swap frame.

textAlignment

string

If action is set to 9 (Popup Menu), specifies the alignment for
the menu text. Acceptable values are "left", "center", and
"right".

textBold

Boolean

If action is set to 9 (Popup Menu), true if the menu text is
bold.

textFamily

string

If action is set to 9 (Popup Menu), specifies the font family to
use for the menu text.

textIndent

integer

If action is set to 9 (Popup Menu), specifies the left indent, in
points, of the menu text.

textItalic

Boolean

If action is set to 9 (Popup Menu), true if the menu text is
italic.

textOnly

Boolean

If action is set to 9 (Popup Menu), true if the pop-up menu is
to be text only.

Last updated 5/2/2011

280

EXTENDING FIREWORKS
HTML export objects

Property (read-only)

Data type

Notes

textOverColor

string

If action is set to 9 (Popup Menu), specifies the menu text
color for the over state.

textSize

integer

If action is set to 9 (Popup Menu), specifies the point size for
the menu text.

textUpColor

string

If action is set to 9 (Popup Menu), specifies the menu text
color for the Up state.

vertical

Boolean

If action is set to 9 (Popup Menu), specifies whether the menu
is vertical.

vertOffset

integer

If action is set to 9 (Popup Menu), vertOffset specifies the
vertical pixel offset for the menu.

vertSubmenuOffset

integer

Specifies the vertical offset of the submenu.

BehaviorsList object
The BehaviorsList object is an array of BehaviorInfo objects that describe the behaviors in an image map (see
“BehaviorInfo object” on page 277). The BehaviorsList object does not occur by itself. That is, all occurrences of
BehaviorsList objects are members of other objects. In the following example, behaviors is an object of type
BehaviorsList, and curBehavior is an object of type BehaviorInfo.
var curBehavior = slices[i][j].behaviors[k];

The BehaviorsList object has only one property, which is read-only and is shown in the following table.
Property (read-only)

Data type

Notes

numberOfBehaviors

integer

The number of BehaviorInfo objects in the BehaviorsList array
(0 or more) (see “BehaviorInfo object” on page 277).

exportDoc object
The following table lists the properties of the exportDoc object, along with their data types and, where appropriate,
acceptable values and notes. All exportDoc properties are read-only.
Note: This object type does not start with a capital letter.
Property (read-only)

Data type

Notes

altText

string

The alternate text description for the Fireworks document.

backgroundAttachment

string

Specifies whether the document has a background image. If an
image is set in the HTML set up, returns true.

backgroundColor

string

The hexadecimal color of the document canvas, without the #
character; for example, "FF0000" for red background.

backgroundIsTransparent

Boolean

Set to true if the Fireworks canvas color is transparent or if the
export settings specify a transparent GIF format; false
otherwise.

backgroundLink

string

The background URL, which is expressed as file://URL.

Last updated 5/2/2011

281

EXTENDING FIREWORKS
HTML export objects

Property (read-only)

Data type

Notes

backgroundRepeat

string

Specifies how the background image repeats as X, Y, Repeat
(Both) and No Repeat.

backgroundURL

string

The background image URL, which is expressed as file:///URL.

bottomMargin

long

Specifies the bottom margin of the page.

cssPopupMenus

Boolean

If this value is true, Fireworks outputs combined
CSS/JavaScript pop-up menus; if false, Fireworks outputs
JavaScript-only pop-up menus.

docAlignment

string

Specifies the page alignment as left, center, right. The default is
left.

docID

integer

A number that is assigned to a document to help identify HTML
generated from it. The docID does not change when you
change the name of a file. However, if you use File > Save As,
you can get multiple files with the same docID.

docSaveFolder

string

Contains the path of the directory into which the document
was last saved. If the document has not yet been saved, this is
an empty string.

docSaveName

string

The filename used when the document was saved, without
path information, such as "nav.gif".

documentXHTMLFormat

Boolean

Determines whether Fireworks outputs XHTML formatted files.
DO NOT USE - Use “xhtmlFormat” instead. Returns true if the
file is XHTML formatted files; false if the file is HTML
formatted when the user exports a file.

emptyCellColor

string

A color string that specifies the color of empty table cells (see
“Color string data type” on page 8).

emptyCellContents

integer

Specifies what to put into empty cells. Acceptable values are 1
(nothing), 2 (spacer image), and 3 (nonbreaking space).

emptyCellUsesCanvasColor

Boolean

If set to true (the default), empty cells are set to the
backgroundColor property. If set to false, they are set to
the emptyCellColor property.

externalCSS

Boolean

If set to true, Fireworks outputs an external CSS file.

externalCSSFileName

string

The name of the external CSS file.

filename

string

URL for the exported image, relative to the HTML output; for
example, "images/Button.gif". In the Slices.htt file, it is
the base image name plus the base extension. Unless there is
only one slice, the Slices.htt file produces filenames such as
"Button_r2_c2.gif".

generateHeader

Boolean

Set to true if an HTML file is generated; false if the output
goes to the clipboard.

hasAltText

Boolean

Set to true if the Fireworks document has an alternate text
description.

hasBackgroundLink

Boolean

Set to true if the Fireworks document has a background URL.

height

integer

Height of the image that is being exported, in pixels. In the
Slices.htt file, it is the total height of the output images.

htmlEncoding

string

Determines the encoding standard for the HTML file that
Fireworks generates during export.
Use "iso-8859-1" for ASCII or "utf-8" for Unicode.

Last updated 5/2/2011

282

EXTENDING FIREWORKS
HTML export objects

Property (read-only)

Data type

Notes

htmlOutputPath

string

File that the HTML is being written to, including the filename,
which is expressed as file://URL; for example,
"file:///C|/top/nav/navbar.htm".

imagename

string

Name of the image that is being exported, without the
extension; for example, "Button".

includeHTMLComments

Boolean

The value of the Include HTML Comments preference, which
the export script interprets as appropriate. For example, if this
value is false, the Dreamweaver export script removes all
nonessential comments.

isBackground

Boolean

Specifies whether the document has a background image. If an
image is set in the HTML set up as the background image,
returns true.

leftMargin

long

Specifies the left margin of the page.

numFrames

integer

Number of frames that are being exported from the Fireworks
document. This value is not zero-based; the value is 1 or more.

pagename

string

Name of the page.

pathBase

string

Path of the image that is being exported; for example,
"images/Button".

pathSuffix

string

Filename extension of the image that is being exported,
including a period; for example, ".gif".

rightMargin

long

Specifies the right margin of the page.

serverMap

Boolean

Specifies whether the document uses a server map.

startColumn

integer

Used only in the Metafile.htt file for generating HTML for one
slice. Specifies the column of the slice.

startRow

integer

Used only in the Metafile.htt file for generating HTML for one
slice. Specifies the row of the slice.

style

string

The HTML style that is used to export the data, such as
"Dreamweaver", "Generic", or"FrontPage".

symbols

array

List of symbols in the document.

tableAlignment

string

A string that contains the alignment of the table. If the table is
left-aligned, the string is simply a space (this is used for writing
the HTML table). If the table is center-aligned, the string is
"align="center"". If the table is right-aligned, the string is
"align="right"".

tablePctWidth

string

A string that contains the percentage width of the table. If it
returns 0, there is no percentage width and the pixel width of
the table should be used. If the table is left-aligned, the string is
simply a space (this is used for writing the HTML table). If the
table is center-aligned, the string is
“align=”center”align=”center””. If the table is right-aligned, the
string is “align=”right”align=”right””.

topMargin

long

Specifies the top margin of the page.

width

integer

Width of the image being exported, in pixels. In the Slices.htt
file, it is the total width of the output images.

xhtmlFormat

Boolean

Determines whether Fireworks outputs XHTML-formatted files
(true) or HTML-formatted files (false) when the user exports
a file.

Last updated 5/2/2011

283

EXTENDING FIREWORKS
HTML export objects

ImageMap object
The following table lists the properties and methods of the ImageMap object, along with their data types and, where
appropriate, acceptable values and notes. All ImageMap object properties are read-only.
Property (read-only) or Method

Data type

Notes

altText

string

The alternate text description for this slice, if any.

behaviors

object

BehaviorsList object that contains the behaviors for this slice
(see “BehaviorsList object” on page 280).

hasAltText

Boolean

Set to true if the slice has an alternate text description.

hasHref

Boolean

Set to true if the slice has a URL.

hasTargetText

Boolean

Set to true if the target text is not empty.

href

string

The URL link for this slice, which is expressed as file://URL.

left

string

Left coordinates of the image map.

numCoords

integer

Number of coordinates in the area. A circle always has 1 (the
center), a rectangle has 2 (top left and bottom right), and a
polygon has 1 or more.

radius

integer

Radius of the area, if shape is "circle".

shape

string

Acceptable values are "circle", "poly", and "rect".

targetText

string

Target text for this image, if any.

top

string

Top coordinates of the image map.

xCoord(index)

zero-based index

Returns the x coordinate for the specified point, in pixels. For
example, the following commands return the coordinates for
the first point:
var x = imagemap.xCoord(0);
var y = imagemap.yCoord(0);

It is possible to have negative values if the image map area is
drawn so that it crosses the left or top sides of the image (or
sliced image).
yCoord(index)

zero-based index

Returns the y coordinate for the specified point, in pixels. See
xCoord().

ImagemapList object
The ImagemapList object is an array of ImageMap objects that describe the areas in an image map (see “ImageMap
object” on page 283). To access ImageMap objects, use the ImagemapList array, as shown below:
var curImagemap = ImagemapList[i];

The ImagemapList object has only one property, which is read-only and shown in the following table.
Property (read-only)

Data type

Notes

numberOfURLs

integer

The number of image map areas in the image map list (0 or
more).

Last updated 5/2/2011

284

EXTENDING FIREWORKS
HTML export objects

SliceInfo object
The following table lists the properties and methods of the SliceInfo object, along with their data types and, where
appropriate, acceptable values and notes. All SliceInfo object properties are read-only.
Property (read-only) or method

Data type

Notes

altText

string

The alternate text description for this slice.

backgroundAttachment

string

Specifies if the background image is fixed or scrolls
with the rest of the page.

backgroundHorizontalPosition

string

Horizontal position of the background image. (Left,
right, or center, numeric value)

backgroundHorizontalPositionVal

long

Horizontal position value of the background image if
the argument is value.

backgroundRepeat

string

Specifies if the background image repeats, and if
repeats in X, Y, Repeat (Both) and No Repeat.

backgroundVerticalPosition

string

Vertical position of the background image. (Left, right,
or center, numeric value).

backgroundVerticalPositionVal

long

Vertical position value of the background image if the
argument is value.

behaviors

object

BehaviorsList object that contains the behaviors for
this slice (see “BehaviorsList object” on page 280).

cellHeight

integer

Height of this table row, in pixels.

cellWidth

integer

Width of this table column, in pixels.

columnSpan

integer

Span of the column.

downIndex

zero-based index

The index for the frame of the down state for button
slices.

getFrameFileName (frameIndex)

zero-based index

Returns a string that is the filename for the slice on the
specified frame, without directory or extension
information. For example, when exporting a file base
named Button,
Slices[0][0].getFrameFileName(0) returns
"Button_r1_c1".Generally all slices that have
images have a frame filename. For frames 1 and
higher, only slices that are rollovers or that are
targeted by a swap image have names.

hasAltText

Boolean

Set to true if the slice has an alternate text
description.

hasHref

Boolean

Set to true if the slice has a URL.

hasHtmlText

Boolean

Set to true if the cell is a text-only slice.

hasImage

Boolean

Set to true if this cell has an image. For text-only
slices, this is set to false.

hasImagemap

Boolean

Set to true if there are image map Hotspots in this
image slice.

hasTargetText

Boolean

Set to true if the target text is not empty.

height

integer

Height of the image in pixels, including row spans.

Last updated 5/2/2011

285

EXTENDING FIREWORKS
HTML export objects

Property (read-only) or method

Data type

Notes

href

string

The URL link for this slice, which is expressed as
file://URL.

htmlText

string

Text for a text-only slice.

imagemap

object

ImagemapList object containing the image map
information for this slice (see “ImagemapList object”
on page 283).

imageSuffix

string

Extension for the image in this cell, including a period
(.); for example, ".gif".

isBackground

Boolean

Specifies whether the slice is background image or
foreground image. True = Background.

isUndefined

Boolean

Set to true if the slice does not have a slice object
drawn over it. If you draw two slices that don’t cover
your document, Fireworks automatically generates
slices to cover the rest of the document. These slices
are undefined.

left

integer

Left side of the cell in pixels. The left starts at 0.

nestedTableSlices

object

A Slices object that describes a nested table occupying
the current table cell (see “Slices object” on page 286).
Set to null if the cell does not contain a nested table.

rowSpan

integer

Span of the row.

setFrameFileName (frameIndex)

zero-based index

Sets the filename for the slice on the specified frame,
without directory or extension information. You can
stop an image from being exported by setting its
name to "" (an empty string).

skipCell

Boolean

Set to true if this cell in the table is covered by a
previous row span or column span.

tableAlign

string

The table alignment for the table in the current cell.

tableBorder

integer

The table’s border width.

tablePadding

integer

The table’s padding value.

tableSpacing

integer

The table’s spacing value.

tableTagText

string

Text that contains table tag info that does not have a
direct correlation in Fireworks.

tableWidth

integer

Percentage width if the table in the current cell has a
percentage width.

targetText

string

Target text for this image, if any.

tdTagText

string

Text of the HTML tag.

top

integer

Top of the cell in pixels. The top starts at 0.

width

integer

Width of the image in pixels, including column spans.

Last updated 5/2/2011

286

EXTENDING FIREWORKS
HTML export objects

Slices object
Slices is an object that has some properties and is also a two-dimensional array of SliceInfo objects (see “SliceInfo
object” on page 284). For example, Slices[0][0] is the slice information for the first cell at row 0, column 0. The first
array is rows; the second is columns.
The following example shows a common way to access the table:
var curRow;
var curCol;
for (curRow = 0; curRow

The RPC client sends the following four types of requests, specified in the XML tag name of the envelope:

• The get operation retrieves the current object properties. The get operation can contain only the obj and name
attributes and no subelements. In the following example, the client requests the value of the appDir property of the
object whose ID is 1:

Last updated 5/2/2011

290

EXTENDING FIREWORKS
Cross-Product Extensions

• The set operation sets the object properties. The set operation can contain only the obj and name attributes and
exactly one parameter. The parameter must be the same data type as the data type of the property being set, or
Fireworks will return an error. In the following example, the client sets the property of “name” (a string providing
a directory path) to the value file://hd/foo/stuff:

• The func operation calls a method that operates on the specified object. The number and type of parameters vary
according to the method called by the func operation. In the following example, the client calls the undo method
to operate on the object with object ID 1:

• The release operation informs the server that the client has finished working on the specified object. A release
request must specify only an obj attribute and no subelements. In the following example, the client tells the server
that it is has finished working on the object with ID 1:

Note: Each type of request requires an obj attribute, and all but the release request require a name attribute. Requests
can be only of types get, set, func, or release. The RPC server rejects all other types.

Object IDs
RPC clients reference objects on the server by their object IDs. Because all functionality is exposed by means of objects,
every client request must contain a valid object ID. When an object that can be accessed through RPC is created, it is
assigned a unique object ID. The object retains that ID for its entire lifetime. This happens for all RPC server objects,
whether they are created directly by an RPC call or by an internal Fireworks function. The object IDs can be reused
after the corresponding object is destroyed.
Note: The object ID number should be treated as a string data type that could contain non-numbers, (do not treat the
object ID as an integer data type).
Fireworks has the following four reserved object IDs:

•

"0"

This is the Invalid Object ID, used for nonexistent or invalid objects. It is not frequently used for the RPC client,
but it is used in several places for the RPC server.
"fw" is the Fireworks Application Object ID. The Fireworks Application Object ID references the main application

object in Fireworks and is of the Fireworks class.
This object is used to open and create documents. In JavaScript, it is the object referenced by App or fw.
"smartShape" is the SmartShape Object ID. This object id references the global JavaScript variable smartShape
and is used to create an manipulate Auto Shapes.
"Document" is the Fireworks Document Compatibility Object ID (it is deprecated, like its JavaScript counterpart).

It was used in Fireworks 2 for cleaning up file paths, and is included here only for completeness.
"Errors" is the Fireworks Errors Object ID, used mainly for reporting and determining when errors occur in

Fireworks. Its JavaScript counterpart is Errors.
All other object IDs are generated when the object is created, and may or may not have the same IDs between
application invocations.

Last updated 5/2/2011

291

EXTENDING FIREWORKS
Cross-Product Extensions

Data node
The data node is the most important type of XML node in RPC. Methods called through the func operation need to
act on actual data or references to server objects identified in data nodes. The data nodes are used as parameters and
parts of replies. There are several types of data nodes, as described in the following table.
Data type

Node name

Example

Description

array

An array data type. It is simply a container node for the other
data nodes. There are no restrictions on how many
subelements it can contain or which types it can contain. The
contained data nodes may be of the same type or of different
types. No additional attributes have to be added to the
contained nodes.

Boolean

bool

The Boolean data type. It can contain either true or false and
nothing else. Note that the values are case sensitive.

dictionary

dict

A dictionary data type. Like the array data type, it is simply a
container for other data nodes. Each direct child node of a
dictionary node must contain an additional key attribute. The
key attribute is a string and must be unique for the given
dictionary node. The key string must start with a letter or an
underscore (_) and may followed by numbers, letters, or
underscores. Dictionary nodes can be used to pass objects by
value.

float

double

The floating-point data type. It can contain any floating-point
(real) number within the range 1.7e +/- 308.

integer

int

The integer data type. It can contain any signed integer in the
range -2,147,483,648 through 2,147,483,647.

null

The null type has only one value: null. The null type
automatically coerces into the string type, array type,
dictionary type, and the server object type. The null type
cannot have any attributes or sub-elements.

server object

obj

The server object data type. The value attribute is set to the
object ID. The class attribute is optional. The server always
specifies the object class when sending replies to the client.
The client, however, is not required to specify the class when
sending server object nodes to the server. The class attribute
tells the client what properties and methods are available on
an object.

string

A string data type. It can contain a
UTF-8-encoded string. If you include special characters, you
must “escape” them (indicate that they are part of the string)
according to the method described in the XML Data Model
(from http://www.w3.org/XML/Datamodel.html). Most XML
writing packages automatically do this.

void

No value; no type. Cannot have any attributes or subelements.

Parameters
Parameters are simply data nodes with an order attribute. The order attribute identifies the order in which the
parameters should be processed for the server. In this way, the RPC client can use any XML client library to build
parameters in any order, and the RPC server retains the correct parameter order. The first parameter should have the
order attribute set to 0; the second, to 1; and so on, as in this example:

Last updated 5/2/2011

292

EXTENDING FIREWORKS
Cross-Product Extensions

The set operation requires only one parameter, and the func operation may have zero or more parameters.

RPC server XML replies
After the RPC server processes an XML request, it packages the result as an XML fragment and sends it back to the
client. If an error occurred during processing, the server returns an error code in the result XML. Otherwise, the reply
node contains a single data node with the result of the operation. If the request doesn’t require a return value, the reply
node contains either a single void data node or no children nodes.
For example, here is a successful reply:

Here is a successful reply with a server object:

Note: When the server returns a server object, it automatically retains the object on the client's behalf. That is, the object
returned to the client is not destroyed until the client releases it with a release request, or until the client disconnects from
the server. Therefore, the client should release a server object as soon as the client has finished sending requests related to
that object (when the client is done “using” the object).

Error codes
If the server encounters an error when processing a request, the reply node (with the node name return) contains at
most one error attribute, as in this example:

The error attribute can contain one of the values listed in the following table.
Error code

Description

No error occurred, and the request completed successfully. The client should never receive an error attribute with this
value. If no error occurred, then no error attribute will be present.

An unknown, generic error occurred. The RPC server could not make enough sense of the request to give a specific error.
Check the name of the XML nodes and attributes.

No such object, invalid object ID. The object specified by the client does not exist or the object ID is invalid.

No such method. The method that the client requested does not exist on the specified object.

No such property. The property that the client requested does not exist on the specified object.

Read-only property. The set request cannot be completed because the specified property is read only.

Wrong number of parameters. The request did not specify the correct number of parameters. Either more or fewer
parameters are needed.

Wrong parameter type. One or more of the parameters given is of the wrong type.

Security violation. The method is not allowed in RPC.

RPC and the Fireworks JavaScript DOM
The RPC server does not allow for self-discovery of the server classes and their methods. Instead the client must know
the methods and properties of a given class of objects beforehand. If the client is written in ActionScript or C++, then
the client can use the generated client stubs provided by Adobe. Client stubs generated by Adobe know about all
methods and properties of every class accessible through RPC. These stubs are available for download at the Adobe
website: http://www.adobe.com/go/learn_fw_documentation_en.

Last updated 5/2/2011

293

EXTENDING FIREWORKS
Cross-Product Extensions

Generating stubs for nonstandard client types
If the client is not written in one of the languages for which Adobe provides a client RPC library, the client implementer
must create or generate the stubs. For information about how to do this, see “The Fireworks Object Model” on page 7.
The application object (with object ID fw) is of the Fireworks class (for other objects with reserved IDs, see “Object
IDs” on page 290). All objects returned by the server contain the class name as an attribute. Given an object’s class, the
client can determine what methods and properties it has based on the Fireworks JavaScript DOM. The DOM
document also gives the prototypes of the methods and properties of a class. The client can use the DOM document
to determine the number and types of method parameters. The DOM document uses more types in its prototypes than
the RPC mechanism defines. So, several of the documented types collapse to one RPC type.
In addition to static properties, objects of certain classes can also have dynamic properties. “The Fireworks Object
Model” on page 7 documents dynamic properties and specifies whether the dynamic properties are read only. Most
dynamic properties are on lists (for example, the BehaviorsList class). The properties take an integer or string as a
property name, and return a value based on the element associated with the property name.
The following table shows the mapping between the Fireworks Object Model data types and the RPC data types.
DOM data type

RPC data type

Example

Description

array

Types map identically.

Boolean

Both types are identical. Both contain only two
values: true or false.

color

string

A color is a string with nine characters. It has the

format #RRGGBBAA.
date

dictionary

A date is a dictionary with the following
subelement keys: year, month, day, hour, minutes,
and seconds. All six elements are integer data
types.

dictionary

Types map identically.

float

Types map identically.

integer

Types map identically.

Last updated 5/2/2011

294

EXTENDING FIREWORKS
Cross-Product Extensions

DOM data type

RPC data type

Example

Description

matrix

dictionary

A matrix is a dictionary that contains one
subelement key: matrix. A matrix is an array of
nine float elements. The elements start at the top
row and go in row-major order.

null

Types map identically.

object

server object, or
dictionary

For an object type, the client can simply specify a
server object. However, for certain objects (such
as objects of the Effect class) a dictionary can be
constructed and then used. If the client creates a
dictionary, all properties of the class must be
added to the dictionary with the correct type.

point

dictionary

A point is a dictionary with two subelement keys:
x and y. Both subelements are float data types.

rect

dictionary

A rect is a dictionary with four subelement keys:
top, left, bottom, and right. All four
subelements are float data types.

resolution

dictionary

A resolution is a dictionary with two subelement
keys: units and pixelsPerUnit. The units
key can be any of these strings: inch, cm, or
pixels.The pixelsPerUnit key is a float data
type.

Last updated 5/2/2011

295

EXTENDING FIREWORKS
Cross-Product Extensions

DOM data type

RPC data type

Example

Description

string

Types map identically.

URL

string

void

Types map identically.

Security
The RPC server restricts some operations to make sure that a client cannot use the RPC server maliciously to damage
the user’s system. The first security mechanism is that the RPC server binds to the loopback address, 127.0.0.1. This
means all clients must run on the same computer as the RPC server and must connect to that computer through the
loopback address. The second security mechanism prevents the exposure of “dangerous” classes that are normally on
the Fireworks JavaScript DOM, such as the JavaScript Files classes. However, the client can still have Fireworks open,
and export and save PNG and other image files. Third, certain methods and properties that could be used maliciously
are not permitted in remote procedure calls (including all methods of the File object, see “Files object” on page 17 and
the functions fw.launchApp and fw.findApp). The RPC server returns an invalid method error to the client if it
attempts to use these methods or properties. Finally, clients can release only those objects that have been retained on
their behalf. Additionally, when a client disconnects, all the server objects that have been retained on that client’s behalf
are released.
Note: Objects are not destroyed until the client releases them or until the client that created them disconnects from the
server.

RPCMethods class
To use remote procedure calls, Flash developers need to create an instance of a Fireworks object and thereafter manage
Fireworks objects carefully to save memory. In ActionScript, you should create blocks of code where you will access
the Fireworks DOM, assign a group (pool) of objects to variables, and then release those objects when you are finished.
Fireworks provides the following series of memory-management functions to support ActionScript developers
working with Fireworks objects. To learn more about using these functions, see “Creating auto-release blocks” on
page 297 and “Accessing proxy objects” on page 297. These functions are defined in the supporting RPCMethods.as
stubs file available for download from the Adobe website at www.adobe.com/go/fireworks_documentation.
Note: ActionScript remote procedure calls for Fireworks are not ActionScript 1 compatible, and must be written in
ActionScript 2.0 (using Flash MX 2004 or later).

RPCMethods.CreateAutoReleasePool()
Usage
RPCMethods.CreateAutoReleasePool()

Arguments
None.
Returns
Nothing.

Last updated 5/2/2011

296

EXTENDING FIREWORKS
Cross-Product Extensions

Description
Starts the auto-release block.

RPCMethods.DestroyAutoReleasePool()
Usage
RPCMethods.DestroyAutoReleasePool()
Arguments
None.
Returns
Nothing.
Description
Ends the auto-release block and frees all allocated remote objects in the current auto-release block function.

RPCMethods.AddToAutoReleasePool()
Usage
RPCMethods.AddToAutoReleasePool(proxyObject)

Arguments
proxyObject The object to add to the current pool.

Returns
Nothing.
Description
Adds an object to the current auto-release pool. This function is called by the auto-release block. If no object pool
exists, this function does nothing.

RPCMethods.RemoveFromAutoReleasePool()
Usage
RPCMethods.RemoveFromAutoReleasePool(proxyObject)

Arguments
proxyObject The object to remove from the current pool.

Returns
Nothing.
Description
Removes an object from the current auto-release pool so that it can be used in another code block.

Last updated 5/2/2011

297

EXTENDING FIREWORKS
Cross-Product Extensions

RPCMethods.ReleaseObject()
Usage
RPCMethods.ReleaseObject(Object)

Arguments
Object The name of the object to release from memory.
Returns
Nothing.
Description
Releases an object from memory. This function searches the specified object and all its properties for proxy objects. If
proxy objects are found, they are released from memory.

Creating auto-release blocks
Rather than constantly tracking which objects to release and how to release them, you can define blocks of code where
you access the Fireworks DOM. In these blocks of code, the ActionScript stubs can keep track of all the proxy objects
allocated. Then, at the end of the block of code, a single command will automatically release all objects allocated in the
block.
Here is an example:
RPCMethods.CreateAutoReleasePool();
var selObject = fw.selection.get(0);
RPCMethods.DestroyAutoReleasePool();

Calling the CreateAutoReleasePool() function marks the beginning of the auto-release block, and calling the
DestroyAutoReleasePool() function marks the end. Any object allocated between these two calls is released by
calling DestroyAutoReleasePool(). Using these two functions, you can write ActionScript code and not worry
about memory management.

Accessing proxy objects
If you want to access a proxy object outside of an auto-release block, you must use the
RemoveFromAutoReleasePool() function. The RemoveFromAutoReleasePool() function manually removes an
object reference from the auto-release pool before exiting the auto-release block.
In this example, the reference to the object defined as selObject is removed:
RPCMethods.CreateAutoReleasePool();
var selObject = fw.selection.get(0);
RPCMethods.RemoveFromAutoReleasePool(selObject);
RPCMethods.DestroyAutoReleasePool();

Now you can use the selObjectobject outside the auto-release block.
Note: You must remember to release the selObject object when you are done with it.
Additionally, you can nest auto-release blocks, that is, you can create an auto-release block and then call a function
that creates its own auto-release block. The ReleaseObject() function iterates through an object’s properties and
releases any proxy objects it finds.

Last updated 5/2/2011

298

EXTENDING FIREWORKS
Cross-Product Extensions

A simple RPC example
This example creates a 200 x 200 pixel rectangle in Fireworks when a button in a Flash application is clicked.
To build a Flash application that uses RPC to create a Fireworks object:
1 Download the supporting ActionScript stub files (a series of supporting ActionScript files) from the Adobe website,
you need to put them in your working directory (where the new FLA file will reside).
You can download the stub for Fireworks 8 from http://www.adobe.com/devnet/fireworks/articles/rpc.html
2 Open a new document in Flash.
3 In the first frame, add the following in the Actions panel to link the general fireworks stub file to the movie when

it is published:
#include "fwstubs.as"

4 Create a simple button which will activate the RPC script.
5 Insert the button in the first frame, in the middle of the Stage.
6 Attach the following ActionScript code to the button to activate the RPC code when the button is clicked:
on(press){
RPCMethods.CreateAutoReleasePool();
var fw = new Fireworks();
//Hide all panels - this function commented out as it will crash if run from inside
Fireworks
//fw.setHideAllFloaters(true);
//Define the document objects the long way
var res = new Object();
res.units = "inch";
res.pixelsPerUnit = 72;
var size = new Object();
size.x = 220;
size.y = 220;
//Create new doc
var fwdoc = fw.createFireworksDocument(size, res, "#0033FF");
//Define a rectangle object the short way
var rect = {left:10, top:10, right:210, bottom:210};
//Add Rectangle
fwdoc.addNewRectanglePrimitive(rect,0.20);
//Set its color
fwdoc.setFillColor("#00CC99");

RPCMethods.DestroyAutoReleasePool();
}
RPCMethods.DestroyAutoReleasePool();

7 Publish the SWF file.

When you publish the SWF file, make sure the stubs files are in the same directory as your FLA file.

Last updated 5/2/2011

299

EXTENDING FIREWORKS
Cross-Product Extensions

The SWF creates a new Fireworks document, and draws a 200 x 200 pixel green rectangle in Fireworks:

Flash panels
Fireworks contains Adobe Flash Player, which plays Shockwave files as panels and commands in the Fireworks
interface. You can also add a Adobe API wrapper extension to Adobe Flash for creating Shockwave files that
communicate with the Fireworks API. By leveraging the new API communication between Adobe Flash and
Fireworks, Fireworks extension developers can create command interfaces and dialog boxes that go beyond the
alert() and prompt() dialog boxes supported in previous versions. You can add command panels to Fireworks for
image enhancements, object manipulation, or other custom functionality.
For more information, see Mayur's articleon working with custom panels.

How Flash panels and commands work
Adobe Flash developers can create interactive movies that contain a combination of ActionScript and calls to the
Fireworks API for two types of deployment: interactive panels or modal commands. Basically, while writing
ActionScript, you can embed commands for the Fireworks API in the MMExecute() function. You can construct these
Adobe Flash animations as interactive panels that work just as the Layers panel, the Frames panel, and other built-in
panels do. For more information, see Mayur's article.
Shockwave files that are published to the Fireworks installation directory, Configuration\Command Panels folder, act
as panels in the Fireworks interface at runtime and are available through the Window menu.
Shockwave files that are published to the Configuration\Commands folder act as modal commands and are available
through the Commands menu in the Fireworks interface.
Note: On multiuser systems, Fireworks supports a Command Panels folder inside of each user’s Configuration folder, so
users can save favorite panels.

Last updated 5/2/2011

300

EXTENDING FIREWORKS
Cross-Product Extensions

At runtime, Fireworks starts Flash Player, which either plays Shockwave animations or runs commands (if the user
selects the custom command options). The Align panel (Window > Align menu option) is an example of how Flash
panels work in the Fireworks interface.

Embedding API commands
You can call any part of the Fireworks API by embedding the API commands in the following functions. These
functions communicate directly with Adobe Flash Player, which is distributed with Fireworks.

MMExecute()
Usage
MMExecute(jsToPass)

Arguments
jsToPass A string of JavaScript for Fireworks to execute.
Returns
Nothing.
Description
Declares a set of JavaScript code to pass to the Fireworks API, allowing Flash authors to embed Fireworks API
commands in a frame of a Flash movie.
Note: MMExecute supersedes the FWJavascript command. However, the FWJavascript command still works in the
current version of Fireworks.
The commands should be embedded in the same way that you would write separate JavaScript code blocks to perform
similar operations, and you can concatenate lines of JavaScript code into one MMExecute() function.
Example
The following example concatenates two lines of JavaScript code into one command:
MMExecute("dom=fw.getDocumentDOM();dom.addNewRectanglePrimitive({left:47, top:26, right:102,
bottom:87}, 0");

MMEndCommand()
Usage
MMEndCommand(endStatus, notifyString)

Arguments
endStatus A Boolean value: true to commit changes; false otherwise. If it is set to false, any pending changes
are discarded. To commit the changes, endStatus must be set to true.
notifyString A string to notify the user of errors. If the value of endStatus is false, this argument holds a string

used to notify the user of the error. If endStatus is set to true, notifyString is an empty string.
Returns
Nothing.

Last updated 5/2/2011

301

EXTENDING FIREWORKS
Cross-Product Extensions

Description
This function should be called whenever the user clicks the OK or Cancel buttons provided in the Flash content to
execute or cancel a command. This function is used only for modal commands, not for Flash panels.
Note: MMEndCommand supersedes the FWEndCommand command. However, FWEndCommand still works in the current
version of Fireworks.

Using the API wrapper extension in Adobe Flash
You can install a special extension that was developed specifically for writing Fireworks functions in ActionScript
(currently, only ActionScript 1.0) either as a replacement for the MMExecute() and MMEndCommand() functions or to
be used in conjunction with them. After it is installed, the API wrapper appears in the Adobe Flash interface. This
wrapper simplifies the writing of Fireworks commands. Instead of having to embed every Fireworks function in
MMExecute(), you can use a series of fwapi functions in the ActionScript. Then, when it is published, the wrapper
translates the fwapi functions into the expanded Fireworks functions. You can also mix the fwapi functions with
MMExecute() statements.
To install the API wrapper, make sure you have the Adobe Extension Manager installed and double-click the
Extension file. In Adobe Flash, the wrapper appears in the Components window as FWCommandComponents.
The following example shows a command without the wrapper:
var path = MMExecute("fw.appPatternsDir;");

The following example shows the same command using the wrapper:
var path =fwapi.getAppPatternsDir();

Working with ActionScript files
You can simplify the editing task by keeping a separate ActionScript file for ActionScript; in this way, you don’t need
to open and edit the FLA file directly. Your FLA file must have a #include myStringFile.as statement in the first
frame (where myStringFile is the name of your ActionScript file) to ensure that the ActionScript strings are complied
at publishing time.
Note: The FLA and ActionScript files should reside in the same folder so that the ActionScript file can be easily found for
compiling.

Guidelines for creating panels and commands
• You need to surround nested quotation marks need with backslash (\). The following example prints: John's
example is really "complex"!
MMExecute('alert("John\'s example is really \"complex\"!")';

• The movie size set in Flash is used in Fireworks as the minimum and default size of the command panel.
• To improve the appearance and positioning of a modeless panel, turn off scaling and align the panel contents with
the upper-left corner of the Stage. You can make these changes with the following ActionScript code:
Stage.align = "TC";
Stage.scaleMode = "noScale";

Events
Fireworks events for Flash panels allow developers to write event handlers for specific user interaction. For example,
a panel for creating a customized shape can respond to the user changing the stroke attribute, and make changes to the
lines in the shape accordingly.

Last updated 5/2/2011

302

EXTENDING FIREWORKS
Cross-Product Extensions

How event handlers work
When a panel is launched and the Flash movie starts, Fireworks will scan the movie script for the presence of event
handlers. If a handler is present, Fireworks automatically registers the function to receive the corresponding event.
Fireworks only looks at the SWF file to see if it needs any of these events when the panel opens (when the SWF file
runs).
Creating event handlers
To create an event handler, implement a function with the corresponding event name. Currently, Fireworks supports
the following events for Flash panels:
Event

Description

onFwStartMovie

Sent to the SWF file right after Fireworks has started (or restarted) the SWF file.

onFwStopMovie

Sent to the SWF file right before Fireworks stops the file (and possibly unloads it).

onFwUnitsChange

Sent when the user changes the type of units (inches, pixels, centimeters) in the Info panel.

onFwPICollapseOrExpand

Sent when the user switches the PI between two rows high and four rows high.

onFwDocumentNameChange

Sent when the name of the current document changes (for example, when the user performs a
save).

onFwCurrentFrameChange

Sent when the user selects a different frame.

onFwCurrentLayerChange

Sent when the user selects a different layer.

onFwHistoryChange

Sent when the user creates an non-scriptable history step.

onFwIdle0

Sent when Fireworks is in the first of a sequence of idle states. Because Fireworks may often go
through a sequence of idle states, triggering functions by this event may impair application
performance.

onFwIdle1

Sent when Fireworks is in the second of a sequence of idle states. Because Fireworks may often
go through a sequence of idle states, triggering functions by this event may impair application
performance.

onFwIdle2

Sent when Fireworks is in the third of a sequence of idle states. Because Fireworks may often go
through a sequence of idle states, triggering functions by this event may impair application
performance.

onFwApplicationDeactivate

Sent when the Fireworks application loses focus.

onFwApplicationActivate

Sent when the Fireworks application gains focus.

onFwSymbolLibraryChange

Sent when the symbol library changes in some way.

onFwURLListChange

Sent when a new URL is added to the document.

onFwFavoritesChange

Sent when the favorite URLs list is modified.

onFwPreferencesChange

Sent when the preferences are changed.

onFwDocumentOpen

Sent when the document is opened.

onFwDocumentClosed

Sent when the document is closed.

onFwDocumentSave

Sent when a save action is performed in the document.

onFwDocumentSizeChange

Sent when the document is resized.

onFwActiveViewChange

Sent when the active view changes. This happens when the user changes focus in 2- or 4-Up
view.

onFwPixelSelectionChange

Sent when the pixel selection changes.

Last updated 5/2/2011

303

EXTENDING FIREWORKS
Cross-Product Extensions

Event

Description

onFwActiveSelectionChange

Sent when the selection changes in a document.

onFwActiveDocumentChange

Sent when the user creates a new document, closes a document, opens a document, or switches
between open documents.

onFwActiveToolParamsChange

Sent when the user changes the tool stroke or fill attributes.

onFwActiveToolChange

Sent when the user changes tools.

onFwZoomChange

Sent when the zoom setting for the current document changes.

onFwObjectSettingChange

Sent when a stroke or fill setting is changed for the selected object.

Note: The event handler must be implemented in the global namespace. Any events that are in the SWF file but aren't
global, or are read only after Fireworks checks for events, will not work correctly.
Example
function onFwDocumentNameChange()
{
// your code goes here
}

Example
_global.onFwDocumentNameChange = function ()
{
// your code goes here
}

Both examples show how to implement a handler for the document name changed event. However, the second
example will only work if the assignment executes before or during the onFwStartMovie handler.

Publishing
When testing your script, use the File > Publish menu option in Adobe Flash. The Shockwave file is in the same place
as the FLA file after publishing.

Debugging
Fireworks provides two functions to help debug Flash panel ActionScript (for more information, see
fw.enableFlashDebugging()and fw.disableFlashDebugging()). Use the Flash debugging functions to show or hide
everything that the Shockwave file passes to the Fireworks API during execution. Place these debug functions around
the suspect code in your Adobe Flash ActionScript to turn the debugging functions on or off as needed. Be careful to
use these functions only around “suspect” code; otherwise, you might encounter a long series of dialog box statements.

Last updated 5/2/2011

304

Chapter 8: Auto Shapes
Auto Shapes are vector objects that contain information about how the user can interact with them on the screen. Auto
Shapes appear in the Adobe Fireworks user interface as “Auto Shapes” but are programmatically called smartShape
objects in the JavaScript code that constructs them. For example, a spiral shape consists of relationships among several
smaller objects. A spiral Auto Shape contains additional properties that enable the user to adjust the appearance
(stretch, distort, tighten the curve) of the whole spiral by clicking and dragging control points. For more information
about user interaction with Auto Shapes, see Using Fireworks Help. You can also find articles about using Auto Shapes
on the Fireworks Developer Center at http://www.adobe.com/go/learn_fw_devnet_en.

How Auto Shapes work
You can define an Auto Shape entirely in JavaScript. Auto Shapes installed with Fireworks are located in the
Configuration/Auto Shapes folder and the Configuration/Auto Shape Tools folder of the installation directory. The
JSF files in this directory contain the JavaScript for each Auto Shape. You can open the files in an editor to see the script
for each shape. The Auto Shape file contains a collection of functions that handle the communication between
Fireworks and the Auto Shape object (for more information, see “Handling the user interaction” on page 306), define
the properties of the Auto Shape, and provide supporting functionality (such as adding other shape objects or
performing calculations) as the user manipulates the Auto Shape. The Auto Shape file also contains control points and
properties (stroke, fill, color, and so on) that define the shape’s behaviors, appearance, and effects. The points and
functions defined in an Auto Shape file use the SmartShape Class and its properties and methods (for more
information, see “SmartShape object” on page 272).
Auto Shapes comprise any number of vector objects including open and closed paths and text (currently, nested Auto
Shapes are not supported). An Auto Shape can control a bitmap that has been imported into the document; however,
Fireworks cannot save a bitmap graphic as an Auto Shape on the user’s drive.
You can create Auto Shape icons for the Tools panel or Auto Shapes panel in PNG, JPG, or GIF format. For the Tools
panel, the icon image should be 16 x 16 pixels (if the image is larger than 16 x 16 pixels, Fireworks scales the image to
fit in the Tools panel). For the Auto Shapes panel, the Auto Shape icon should be 60 x 60 pixels. If the image for the
Auto Shapes panel is smaller, or larger, than 60 x 60 pixels, Fireworks will not scale the image—the icon will appear
centered in its cell, but not sized to fit, so it may appear cropped if it is too large.
Note: If the icon is missing (or named incorrectly) then Fireworks does not display an icon. However, if the Auto Shapes
folder has an icon with the same name as a shape in the Auto Shape Tools folder, then that icon will be used in the Tools
panel.

Creating an Auto Shape
To create an Auto Shape, you need to define a series of properties for the shape, define the shape’s control points, and
write functions that tell Fireworks how to handle the Auto Shape as the user interacts with the object (for more
information, see “Handling the user interaction” on page 306).

Last updated 5/2/2011

305

EXTENDING FIREWORKS
Auto Shapes

Defining the shape
The following code creates the initial shape, a rectangle (a more concise way of creating an initial shape follows this
example):
function InsertSmartShapeAt()
{
smartShape.elem.elements[0] = new Path;
smartShape.elem.elements[0].contours[0] = new Contour;
smartShape.elem.elements[0].contours[0].nodes[0] = new ContourNode;
smartShape.elem.elements[0].contours[0].nodes[0].predX = 0;
smartShape.elem.elements[0].contours[0].nodes[0].predY = 0;
smartShape.elem.elements[0].contours[0].nodes[0].x = 0;
smartShape.elem.elements[0].contours[0].nodes[0].y = 0;
smartShape.elem.elements[0].contours[0].nodes[0].succX = 0;
smartShape.elem.elements[0].contours[0].nodes[0].succY = 0;
smartShape.elem.elements[0].contours[0].nodes[1] = new ContourNode;
smartShape.elem.elements[0].contours[0].nodes[1].predX = 200;
smartShape.elem.elements[0].contours[0].nodes[1].predY = 0;
smartShape.elem.elements[0].contours[0].nodes[1].x = 200;
smartShape.elem.elements[0].contours[0].nodes[1].y = 0;
smartShape.elem.elements[0].contours[0].nodes[1].succX = 200;
smartShape.elem.elements[0].contours[0].nodes[1].succY = 0;
smartShape.elem.elements[0].contours[0].nodes[2] = new ContourNode;
smartShape.elem.elements[0].contours[0].nodes[2].predX = 200;
smartShape.elem.elements[0].contours[0].nodes[2].predY = 125;
smartShape.elem.elements[0].contours[0].nodes[2].x = 200;
smartShape.elem.elements[0].contours[0].nodes[2].y = 125;
smartShape.elem.elements[0].contours[0].nodes[2].succX = 200;
smartShape.elem.elements[0].contours[0].nodes[2].succY = 125;
smartShape.elem.elements[0].contours[0].nodes[3] = new ContourNode;
smartShape.elem.elements[0].contours[0].nodes[3].predX = 0;
smartShape.elem.elements[0].contours[0].nodes[3].predY = 125;
smartShape.elem.elements[0].contours[0].nodes[3].x = 0;
smartShape.elem.elements[0].contours[0].nodes[3].y = 125;
smartShape.elem.elements[0].contours[0].nodes[3].succX = 0;
smartShape.elem.elements[0].contours[0].nodes[3].succY = 125;
smartShape.elem.elements[0].contours[0].isClosed = true;
}

The Auto Shape is an array of ContourNode objects (see “ContourNode object” on page 246). You can write a “helper”
function to simplify the code and assign ContourNode properties, as shown in the following example:
function addPathPoint(contour, i, x, y)
{
var theNodes = contour.nodes;
// Increase the length to add a new point
if (i > 0)
theNodes.length++;
// get the new point
var node = theNodes[theNodes.length - 1];
// Set the new point's values
node.x = node.predX = node.succX = x;
node.y = node.predY = node.succY = y;
}

Last updated 5/2/2011

306

EXTENDING FIREWORKS
Auto Shapes

You can then simplify the InsertSmartShapeAt() function with the new helper function:
function InsertSmartShapeAt()
{
var elem = smartShape.elem;
var newPath = new Path;
elem.elements[0] = newPath;
newPath.contours[0] = new Contour;
var contour = newPath.contours[0];
var i = 0;
addPathPoint(contour, i++, 0, 0);
addPathPoint(contour, i++, 200, 0);
addPathPoint(contour, i++, 200, 125);
addPathPoint(contour, i++, 0, 125);
contour.isClosed = true;
}

Adding control points
After selecting an Auto Shape in a document, the user can click its control points to adjust the object. You must define the
control points for your Auto Shape before you can define what happens to the object when the user manipulates them.
The following code adds a single control point to the coordinates (0, 0):
smartShape.elem.controlPoints.length++;
// Establish the new control point
var cp=smartShape.elem.controlPoints[smartShape.elem.controlPoints.length-1];
// Place the Control Point
cp.x = 0;
cp.y = 0;

Handling the user interaction
After you define the Auto Shape properties and control points, you need to tell Fireworks how to handle user
interactions with the Auto Shape. To facilitate the interaction of the user with the Auto Shape, Fireworks sends a series
of messages to the Auto Shape object as the user performs certain operations on the Auto Shape. You can write a series
of functions to respond to these messages.

Fireworks messages
Fireworks passes the following messages to the SmartShape object as the user interacts with (inserts, moves, or
changes) the shape:

• "InsertSmartShapeAt"
Fireworks sends this message when the user selects the shape from the Tools panel and clicks on the canvas, or drags
the shape from the Auto Shapes panel to the canvas.

•

"BeginDragInsert"

Fireworks sends this message when the user drags an Auto Shape onto the canvas. This message defines a more
specific action than the “InsertSmartShapeAt” message.

•

"DragInsert"

Last updated 5/2/2011

307

EXTENDING FIREWORKS
Auto Shapes

Fireworks sends this message every time the mouse moves during a drag operation (as long as
smartshape.getsDragEvents is set to true). For more information, see “SmartShape object” on page 272.

•

"EndDragInsert"

Fireworks sends this message on a mouseUp event after a drag operation.

•

"BeginDragControlPoint"

Fireworks sends this message when the user clicks and holds the mouse button on a control point.

•

"DragControlPoint"

Fireworks sends this message every time the mouse moves during a drag operation (as long as
smartshape.getsDragEvents is set to true). For more information, see “SmartShape object” on page 272.

•

"EndDragControlPoint"

Fireworks sends this message when the drag operation is complete.

•

"SmartShapeEdited"

Fireworks sends this message when any change has been made to the Auto Shape (for example, when the user
deletes a node).

Message handler functions
Because Fireworks sends interaction messages as the user interacts with the Auto Shape, you can write functions to
define, edit, and delete the Auto Shape and its properties. Specifically, you write functions defining the effect of
manipulating the control points on the shape properties. You can define object properties at various stages of a drag
operation: at the beginning of the operation, during the operation, and at its end. (If you define only the properties for
the end result, Fireworks waits until the drag operation ends to show the changes to the user.) For example, to have
your Auto Shape respond to an “EndDragControlPoint” message, you would write the following function:
function EndDragControlPoint(){
cp.x = smartShape.currentMousePos;
cp.y = smartShape.currentMousePos;
}

The following table lists all the available Fireworks message handler functions you can create (although, you don’t have
to write a response to every Fireworks message, only the ones important to your Auto Shape):
Function

Description

InsertSmartShapeAt()

Draws the initial shape. This function is called when the user selects the shape from the Tools
panel and clicks on the canvas, or drags the shape from the Auto Shapes panel to the canvas.
Define all initial properties of the Auto Shape in this function.

BeginDragInsert()

Tells Fireworks what to do when the user drags an Auto Shape on the canvas. You can define
movements for control points and nodes that you defined in InsertSmartShapeAt().

DragInsert()

This function is called every time the mouse moves during a drag operation (as long as
smartshape.getsDragEvents is set to true). See “SmartShape object” on page 272.

EndDragInsert()

This function is called on a mouse-up event after a drag operation.

Last updated 5/2/2011

308

EXTENDING FIREWORKS
Auto Shapes

Function

Description

BeginDragControlPoint()

Tells Fireworks what to do when the user clicks and holds the mouse button on a control point.
Fireworks can change the object as the user moves the mouse (for example, using the
RegisterMove method of the SmartShape object; for more information about how to get the
properties of a smartShape object, see “ContourNode object” on page 246), or wait until after a
mouse event to change the object.
The following example uses the RegisterMove method to set the properties for the object on
the mouse-down event so that the user can preview changes during the drag operation:

function BeginDragControlPoint()
{
switch (smartShape.currentControlPointIndex) {
case 0:
var parms = smartShape.GetDefaultMoveParms();
smartShape.elem.controlPoints[0].RegisterMove(parms);
smartShape.elem.elements[0].contours[0].nodes[0].RegisterMove(parms);
break;
}
}
DragControlPoint()

This function is called every time the mouse moves during a drag operation. Fireworks can
change the object as the user moves the mouse or wait until the mouse event ends to change
the object.
If the BeginDragControlPoint() function specifies control points or other points, Fireworks
will not call the DragControlPoint() function.

EndDragControlPoint()

Tells Fireworks how to draw the final Auto Shape, after a drag operation is complete. If Fireworks
handled shape changes through the BeginDragControlPoint() function, then you can use
the end result of that function as a starting point. In that case, the code need not reflect every
change in shape, but just the changes that aren’t handled by BeginDragControlPoint().

SmartShapeEdited()

This function is called when any changes have been made to the Auto Shape that might change
the shape’s behavior (such as removing a node inside an Auto Shape object).

These functions correspond directly with the messages listed in “Fireworks messages” on page 306. To invoke your
own function names in response to Fireworks messages, you need to write a switch() statement.

Switch statements
If you take a look at some existing Auto Shapes (in the Configuration/Auto Shapes folder and in the
Configuration/Auto Shape Tools folders), you’ll notice a switch() statement near the beginning of the file. The Auto
Shape JavaScript code in these files uses a switch() statement as the initial message handler in the file. The switch()
statement sorts the messages sent by Fireworks so each message (that is useful to the particular Auto Shape) invokes a
corresponding function.
You can see this switch statement in each of the Auto Shape JavaScript files. Again, a single Auto Shape object may
not need to process every message Fireworks sends, so only the useful messages are written into the JavaScript file
using the case qualifier. Effectively, the JavaScript file states in case of a certain message, or messages, perform the
following function.
In the Frame Auto Shape, this code is used to call PlaceControlPoints() when Fireworks sends a
"SmartShapeEdited" message:

Last updated 5/2/2011

309

EXTENDING FIREWORKS
Auto Shapes

switch(smartShape.operation) {
case "BeginDragInsert":
case "InsertSmartShapeAt":
InsertSmartShapeAt(true);
break;
case "BeginDragControlPoint":
BeginDragControlPoint();
break;
case "DragControlPoint":
DragControlPoint();
break;
case "EndDragControlPoint":
EndDragControlPoint();
break;
case "SmartShapeEdited":
PlaceControlPoints();
break;
}

You don’t need a response for every message Fireworks sends; but you do need to make sure the switch statement
handles the responses required by your shape.
You can also invoke a single function for several messages:
case "BeginDragInsert":
case "InsertSmartShapeAt":
InsertSmartShapeAt(true);
break;

Supporting functions and methods
Because the Auto Shape file is written in JavaScript, your functions can use global variables, common functions, and
the Fireworks JavaScript API. The Auto Shape JavaScript file contains the definition of the shape’s points, and a series
of functions to handle the Fireworks messages as the user interacts with the shape. The file also includes a series of
commands and functions defining the shape’s properties and other functionality. These functions are often separate
from the message handling functions so they can be used by multiple message handling functions. For example, the
Cog Auto Shape JavaScript file (Configuration/Auto Shapes/Cog.jsf) contains user-defined functions near the bottom
of the file. These functions perform calculations and create shapes that are useful for the message handling functions.
The top of the file contains a series of variable statements that define useful values for tool tips, global variables, and
constants used throughout the Auto Shape JavaScript file.
You can use the Fireworks JavaScript API and the Fireworks Object Model, along with efficient JavaScript coding
practices, to create effective Auto Shapes (and continue to reuse the most useful functions from each Auto Shape
JavaScript file). For more information, see “Additional Fireworks Functions” on page 321 and the “The Fireworks
Object Model” on page 7.

Last updated 5/2/2011

310

Chapter 9: Rich symbols
Rich symbols allow you to create graphic symbols that can be intelligently scaled and given specific attributes using a
JavaScript (JSF) file. Quickly mock up a user interface by dragging these symbols on to the document and editing the
parameters associated with them using the Symbol Properties panel.
Beginning with Fireworks CS3, you can also export common library assets as known components for use in Adobe
Flex™ Builder.™ The MXML export feature allows you to create a Flex application layout in Fireworks, leveraging Flex
common library assets as MXML for loading into Flex Builder.

How Rich symbols work
When a symbol is saved as a rich symbol, a PNG file is saved by default in the \Application
Data\Adobe\Fireworks CS5\Common Library\Custom Symbols folder (Windows), or /Application
Support/Adobe/FireworksCS5/Common Library/Custom Symbols (Macintosh).
To create a rich symbol, a JavaScript file must be created and saved with a .JSF extension in the same location and with
the same name as the symbol. For example, mybutton.graphic.png would have a JavaScript file named mybutton.jsf.
The Create Symbol Script panel allows non-programmers to assign some simple symbol attributes and create the
JavaScript file automatically. To open this panel, select Create Symbol Script from the Commands menu.
The JavaScript file
Two functions in the JavaScript file must be defined in order to add editable parameters to the symbol:

•

function setDefaultValues()–defines the parameters that can be edited and the default values of these

parameters.

•

function applyCurrentValues()–applies the values entered through the Symbol Properties panel to the graphic

symbol.
The following is a sample .JSF file for creating a custom symbol:

Last updated 5/2/2011

311

EXTENDING FIREWORKS
Rich symbols

This sample JavaScript shows a rich symbol that can change colors:
function setDefaultValues()
{
var currValues = new Array();
//Name is the Parameter name that will be displayed in the Symbol Properties Panel
//Value is the default Value that is displayed when Rich symbol loads first time. In this
case, Blue will be the default color when the Rich symbol is used.
//Color is the Type of Parameter that is displayed. Color will invoke the Color Popup box
in the Symbol Properties Panel.
currValues.push({name:"BG Color", value:"#003366", type:"Color"});
Widget.elem.customData["currentValues"] = currValues;
}
function applyCurrentValues()
{
var currValues = Widget.elem.customData["currentValues"];
//color_bg is the Layer name in the PNG that will change colors
var color_bg = Widget.GetObjectByName("color_bg");
color_bg.pathAttributes.fillColor = currValues[0].value;
}
switch (Widget.opCode)
{
case 1: setDefaultValues(); break;
case 2: applyCurrentValues(); break;
default: break;
}

To better understand how the .JSF file can be used to customize symbol properties, explore the sample components
that have been included with the software.

Supported attributes for rich symbols
The following attributes are available in the Create Symbol Script panel (Commands > Create Symbol Script) for
customizing rich symbols.

Last updated 5/2/2011

312

EXTENDING FIREWORKS
Rich symbols

Attributes

Type

element.left

integer

element.width

integer

element.height

integer

element.pixelRect

rect(left,top,roght,bottom)

element.visible

boolean

element.opacity

integer

element.blendmode

string

element.effectList

object

element.name

string

element.mask

object

element.pathattrs.burshColor

color

element.pathattrs.fillColor

color

element.pathattrs.brush

object

element.pathattrs.fill

object

element.pathattrs.brushTexture

object

element.pathattrs.fillTexture

object

element.pathattrs.fillHandle1

point

element.pathattrs.fillHandle2

point

element.pathattrs.fillHandle3

point

element.pathattrs.setDefaultFillHandles

point

element.pathattrs.brushPlacement

string

element.pathattrs.fillOnTop

boolean

element.pathattrs.pathattributes

object

element.pathattrs.randSeed

object

element.pathattrs.textureOffset

point

element.pathattrs.contours

object

element.pathattrs.isEvenOddFill

boolean

element.pathattrs.fill.category

string

element.pathattrs.fill.name

string

element.pathattrs.fill.textureBlend

integer

element.pathattrs.fill.stampingMode

string

element.pathattrs.fill.edgeType

string

element.pathattrs.fill.feather

long

element.pathattrs.fill.ditherColors

object

Last updated 5/2/2011

313

EXTENDING FIREWORKS
Rich symbols

Attributes

Type

element.pathattrs.fill.webDitherTransparent

boolean

element.pathattrs.fill.shape

string

element.pathattrs.fill.gradient

object

element.pathattrs.fill.pattern

object

element.pathattrs.fill.gradient.name

string

element.pathattrs.fill.gradient.nodes

object

element.pathattrs.fill.gradient.opacityNodes

object

element.pathattrs.fill.gradient.color

color

element.pathattrs.fill.gradient.position

integer

element.pathattrs.fill.gradient.isOpacityNode

boolean

element.pathattrs.fill.pattern.name

string

element.pathattrs.fill.pattern.image

object

element.pathattrs.brush.category

string

element.pathattrs.brush.name

string

element.pathattrs.brush.angle

long

element.pathattrs.brush.aspect

integer

element.pathattrs.brush.diameter

long

element.pathattrs.brush.maxCount

long

element.pathattrs.brush.minSize

integer

element.pathattrs.brush.softness

element.pathattrs.brush.softenMode

string

element.pathattrs.brush.shape

string

element.pathattrs.brush.blackness

integer

element.pathattrs.brush.concentration

integer

element.pathattrs.brush.alphaRemap

string

element.pathattrs.brush.type

string

element.pathattrs.brush.feedback

string

element.pathattrs.brush.flowRate

integer

element.pathattrs.brush.tipCount

long

element.pathattrs.brush.antiAliased

boolean

element.pathattrs.brush.spacing

integer

element.pathattrs.brush.textureBlend

integer

element.pathattrs.brush.textureEdge

integer

element.pathattrs.brush.tipSpacing

integer

Last updated 5/2/2011

314

EXTENDING FIREWORKS
Rich symbols

Attributes

Type

element.pathattrs.brush.tipSpacingMode

string

element.pathattrs.brush.tipColoringMode

string

element.pathattrs.brush.numDashes

long

element.pathattrs.brush.dashOnSize1

long

element.pathattrs.brush.dashOffSize1

long

element.pathattrs.brush.dashOnSize2

long

element.pathattrs.brush.dashOffSize2

long

element.pathattrs.brush.dashOnSize3

long

element.pathattrs.brush.minSize

integer

element.pathattrs.brush.dashOffSize3

long

element.pathattrs.mask.element

object

element.pathattrs.mask.owner

object

element.pathattrs.mask.linkled

boolean

element.pathattrs.mask.enabled

boolean

element.pathattrs.mask.mode

string

element.pathattrs.mask.showAttrs

boolean

element.pathattrs.mask.autoExpandImages

boolean

rect.roundness

integer

rect.pathAttributes

integer

rect.originalSides

integer

rect.transform

matrix

text.antiAliased

boolean

text.antiAliasMode

string

text.autoKern

boolean

text.orientation

string

text.pathAttributes

object

text.randSeed

argLong

text.textChars

string

text.textureOffset

point

text.transformMode

string

text.rawTop

integer

text.rawLeft

integer

text.rawWidth

integer

text.rawHeight

integer

Last updated 5/2/2011

315

EXTENDING FIREWORKS
Rich symbols

Attributes

Type

text.autoExpand

boolean

text.italic

boolean

text.underline

boolean

text.bold

boolean

text.justify

string

text.font

string

text.fontsize

integer

text.alignment

string

MXML Export
The Flex application framework consists of MXML, ActionScript 3.0, and the Flex class library. Developers use MXML
to declaratively define the application user interface elements and use ActionScript for client logic and procedural
control. Developers write MXML and ActionScript source code using the Adobe Flex Builder™ IDE or a standard text
editor.
MXML is the XML-based language that developers use to lay out components in Flex applications. It provides a
declarative approach to controlling an application's visual appearance. Using MXML, developers can position
components and specify constraints to enable a more “liquid” user interface. Developers can also use View States and
Transitions to control how the application should respond to different user actions and application events.
Using Fireworks, you can export Flex code (MXML) in order to easily create a Flex application layout in Fireworks,
leveraging Flex common library assets, and export it as MXML for loading into Flex Builder.
To export MXML data
1 Choose File > Export.
2 Choose MXML and Images in the Export pop-up menu.
3 Select the Put images in subfolder option if you want to save the images in a separate folder from the MXML code.
4 Select the Current page only option to export only the currently selected page.
5 Click Save to complete the export.

Flex Component Definitions for MXML and Images Export
When exporting a Fireworks document with the MXML and Image export, Fireworks checks each element’s
customData property for definitions that dictate how that element should appear in the resulting MXML. If no
MXML-related definitions are found, the element is exported as an image. Each Flex component found in the
Fireworks common library already has unique customData definitions that allow it to be exported as MXML. If you
wish to have elements within your document export as their own custom MXML tags you can do so with the following
customData definitions.

flexClassName
Flex component symbols are associated as being Flex Components by the MXML and Images import through a
customData property called flexClassName.

Last updated 5/2/2011

316

EXTENDING FIREWORKS
Rich symbols

Format
flexClassName = "WhichClass";

When this property is present in a Fireworks element, the MXML and Images export process exports the element as a
specific MXML tag and not as an image. Its value indicates the tag name of the MXML class generated.
Example
element.customData["flexClassName"] = "ComboBox";

The above line indicates that the element object is a Flex component whose MXML class is ComboBox. For rich
symbols this code should be placed within the setDefaultValues block of code (Widget.opCode == 1) that initially
defines the rich symbol.
Example
function setDefaultValues() {
Widget.elem.customData["flexClassName"] = "ComboBox";
// additional code...
}
switch (Widget.opCode) {
case 1: setDefaultValues(); break;
// additional code...
}

All Flex widgets provided with Fireworks already have this property defined. The class name used determines the
behavior of each of those components as determined internally within the MXML and Images export.
When you create a custom rich symbol, you must define the flexClassName property if you want the MXML and
Images export to treat the rich symbol as an MXML tag and not an exported image. The class name you decide to use
will be used in the resulting MXML tag. For example, if you defined flexClassName as “Foo” the resulting MXML tag
is .

flexClassDefinition
In addition to the flexClassName property, there is an additional, optional customData property
flexClassDefinition, which can be used to further influence the resulting MXML export.
Format
flexClassDefinition = classDefinitionObject;

Example
classDefinition = new Object();
element.customData["flexClassDefinition"] = classDefinition;

A flexClassDefinition object includes any number of the following properties, all of which are themselves
optional.
margin
Rectangle. Defines the area around the element that is not part of the Flex component shape but takes up space in
Fireworks (for example, the Panel component in Flex has a drop shadow that is not included as part of the panel’s size
in Flex but is included when recreated in Fireworks). It consists of four integer properties measured in pixels: top, right,
bottom, and left.

Last updated 5/2/2011

317

EXTENDING FIREWORKS
Rich symbols

Example
margin = {top:5, right:5, bottom:5, left:5};

padding
Rectangle. Defines the area within the element that determines if another element can be seen as being a child of that
element. If defined, any other element whose bounds are completely within the area marked by padding and arranged
above the current element will be a child element within the resulting MXML. It consists of four integer properties
measured in pixels: top, right, bottom, and left; and is calculated after the margin.
Example
padding = {top:5, right:5, bottom:5, left:5};

margin.left

margin.right

MXML width

margin.top

padding.top

MXML height

Container Area

padding.bottom

margin.bottom
padding.left

padding.right

Margin and padding relationships in respect to a panel component

sizeOffset
Object. Defines a size offset to apply to the MXML definition of the exported element. It consists of two integer
properties, width and height, which are measured in pixels and are added to the MXML width and height attributes.
This does not have any affect on margin or padding properties. It simply consists of values that will be added to the
final width and height attributes of the MXML tag produced.
Example
sizeOffset = {width:10, height:10};

customValues
Object. Contains custom name-value pairs that are available to the MXML export but not accessible as visible
properties within Fireworks. During export these are translated directly to MXML attributes or styles in combination
with any properties defined within customData currentValues.
Example
customValues = {myNum:10, click:"clickHandler();"};

Last updated 5/2/2011

318

EXTENDING FIREWORKS
Rich symbols

attributeProperties
Array. A list of property names that will become attributes in the exported MXML tag. By default, all rich symbol
properties (defined as currentValues or customValues) are considered attribute properties. By defining this list, you
can restrict which properties are used as attributes. Those not provided will not be included as attributes of the
resulting MXML tag.
Example
attributeProperties = ["label", "enabled"];

styleProperties
Array. A list of property names which are to be defined in the CSS style tag for this class. If any of these properties are
also attribute properties (implicit or explicit), they will instead become style properties.
Example
styleProperties = ["color", "textSelectedColor"];

defaultProperties
Array. A list of the names of automatic attribute properties created for the MXML tag. Automatic attributes are those
properties which are not listed as currentValues or customValues but are automatically determined and generated
by the MXML export. This includes the following properties:

•

x: x position of the element on the screen

•

y: y position of the element on the screen

•

width: width of the element

•

height: height of the element

•

alpha: transparency of the element

•

id: ID tag (based on the element name)

•

source: source location of the image for objects exported as images

•

styleName: reference to the style that applies to this element, if applicable

If this list is not defined, all default properties are added to the attribute list (where applicable). If defined, only those
listed will be provided.
Note: defaultProperties cannot be style properties. Omitting styleName from defaultProperties will not
prevent a style from being created for the object if it has style properties.
Example
defaultProperties = ["x", "y", "width", "height"];

namespace
Object. The namespace to be used in the MXML tag. This object should contain one key representing the namespace
prefix whose value is the namespace URI. If this is not provided, the default namespace of mx is used.
Example
namespace = {ns:"http://www.example.com/2007/mxml"};

Last updated 5/2/2011

319

EXTENDING FIREWORKS
Rich symbols

textOnly
String. If defined, this represents the entire MXML output to be used for the export. If this is defined, no other
properties need to be set within the definition. Any properties set are ignored.
Example
textOnly = "";

ignored
Boolean. If true, the object is completely ignored during export; no MXML is created and no image is exported. If this
is set to true, no other properties need to be set within the definition. Any properties set are ignored.
Note: The ignored property has precedence over textOnly.
Example
ignored = true;

Example script
The following is an example of a custom symbol script using a custom definition object to determine the output created
by the Fireworks MXML and Images export.
function setDefaultValues() {
var currValues = new Array();
currValues.push({ name:"name",
type:"Text",
value:"star name" });
currValues.push({ name:"label",
type:"Text",
value:"Star"
});
currValues.push({ name:"color",
type:"Color",
value:"#FFFFFF"
});
currValues.push({ name:"enabled", type:"Boolean", value:"true"
});
Widget.elem.customData["currentValues"] = currValues;
Widget.elem.customData["flexClassName"] = "Star";
var classDef = new Object();
classDef.margin = {top:0, right:3, bottom:10, left:3};
classDef.padding = {top:30, right:10, bottom:10, left:10};
classDef.sizeOffset = {width:10, height:0};
classDef.customValues = {staticValue:"static"};
classDef.attributeProperties = ["staticValue", "name"];
classDef.styleProperties = ["color"];
classDef.defaultProperties = ["x","y","width","height"];
classDef.namespace = {ns:"http://www.example.com/2007/mxml"};
Widget.elem.customData["flexClassDefinition"] = classDef;
}
function applyCurrentValues() {
var vals = Widget.elem.customData["currentValues"];
Widget.GetObjectByName("label").textChars = vals[1].value;
Widget.GetObjectByName("label").pathAttributes.fillColor = vals[2].value;
Widget.GetObjectByName("disabled").visible = !vals[3].value;
}
switch (Widget.opCode) {
case 1: setDefaultValues();
break;
case 2: applyCurrentValues(); break;
}

A document containing this rich symbol that is exported using the MXML and Images export would result in the
following MXML document.

Last updated 5/2/2011

320

EXTENDING FIREWORKS
Rich symbols

Star {
color:#FFFFFF;
}

With the definition of flexClassName, the element in Fireworks exports as a Star MXML tag. Notice how the
properties defined within attributeProperties became attributes and the property (color) defined within
styleProperties became part of the Star style. The only default properties created were those defined in
defaultProperties; x, y, width, and height. Because a namespace was defined, the tag was given the correct prefix
and it's URI was defined within the Application tag.
In Fireworks, the star in this example was 147 x 138 but exported with a width and height of 157 x 138 in MXML
because of sizeOffset. Though not apparent in this example, margin and padding would also play a part in how this
element is exported.

Last updated 5/2/2011

321

Chapter 10: Additional Fireworks
Functions
This chapter lists additional JavaScript functions supported by Adobe Fireworks that let you create useful Fireworks
extensions and customized Fireworks menus. Almost any task that the user can accomplish in Fireworks with the
menus, tools, or floating panels can be done programmatically using JavaScript.

Property inspector functions
These functions control the Property inspector window, which shows details about the current document or selected
object.

fw.showPIWindow()
Availability
Fireworks MX.
Usage
fw.showPIWindow()

Arguments
None.
Returns
Nothing.
Description
Opens the Property inspector.

fw.hidePIWindow()
Availability
Fireworks MX.
Usage
fw.hidPIWindow()

Arguments
None.
Returns
Nothing.

Last updated 5/2/2011

322

EXTENDING FIREWORKS
Additional Fireworks Functions

Description
Makes the Property inspector window invisible.

fw.isPIExpanded()
Availability
Fireworks MX.
Usage
fw.isPIExpanded()

Arguments
None.
Returns
A Boolean value: true if expanded; false otherwise.
Description
Determines whether the Property inspector window is currently expanded or minimized

fw.isPIVisible()
Availability
Fireworks MX.
Usage
fw.isVisible()

Arguments
None.
Returns
A Boolean value: true if visible; false otherwise.
Description
Determines whether the Property inspector window is currently hidden or shown.

fw.growPIWindow()
Availability
Fireworks MX.
Usage
fw.growPIWindow()

Last updated 5/2/2011

323

EXTENDING FIREWORKS
Additional Fireworks Functions

Arguments
None.
Returns
Nothing.
Description
Expands the Property inspector window.

fw.shrinkPIWindow()
Availability
Fireworks MX.
Usage
fw.shrinkPIWindow()

Arguments
None.
Returns
Nothing.
Description
Minimizes the Property inspector window.

fw.setPIPosition()
Availability
Fireworks MX.
Usage
fw.setPIPosition(pt)

Arguments
pt A point in screen coordinates.
Returns
Nothing.
Description
Moves the upper-left corner of the Property inspector window to the specified location.

Last updated 5/2/2011

324

EXTENDING FIREWORKS
Additional Fireworks Functions

fw.getPIPosition()
Availability
Fireworks MX.
Usage
fw.getPIPosition()

Arguments
None.
Returns
A point object that is formatted as {x:float, y: float} (see “Point data type” on page 9 for syntax details), which
contains the location of the Property inspector.
Description
Retrieves the location, in screen coordinates, of the upper-left corner of the Property inspector window.

History panel functions
These functions control the History panel.

fw.historyPalette.clearSteps()
Availability
Fireworks 3.
Usage
fw.historyPalette.clearSteps()

Arguments
None.
Returns
Nothing.
Description
Clears the undo and redo stack.

fw.historyPalette.copySteps()
Availability
Fireworks 3.

Last updated 5/2/2011

325

EXTENDING FIREWORKS
Additional Fireworks Functions

Usage
fw.historyPalette.copySteps(array of indexes)

Arguments
array of indexes A zero-based array that specifies which steps from the History panel should be copied. If it is
null, the currently selected steps are used.

Returns
Nothing.
Description
Copies history steps to the Clipboard.

fw.historyPalette.getSelection()
Availability
Fireworks 3.
Usage
fw.historyPalette.getSelection()

Arguments
None.
Returns
A zero-based array that represents which History panel steps are selected.
Description
Determines which steps in the History panel are selected.

fw.historyPalette.getStepCount()
Availability
Fireworks 3.
Usage
fw.historyPalette.getStepCount()

Arguments
None.
Returns
The number of steps in the History panel (not a zero-based value).
Description
Gets the number of steps in the History panel.

Last updated 5/2/2011

326

EXTENDING FIREWORKS
Additional Fireworks Functions

fw.historyPalette.getStepsAsJavaScript()
Availability
Fireworks 3.
Usage
fw.historyPalette.getStepsAsJavaScript(array of indexes)

Arguments
array of indexes A zero-based array that specifies which steps from the History panel should be returned as
JavaScript. If the argument is null, the currently selected steps are returned.

Returns
A JavaScript string.
Description
Gets the JavaScript equivalent of the specified steps.
See also
fw.historyPalette.replaySteps()

fw.historyPalette.getUndoState()
Availability
Fireworks 3.
Usage
fw.historyPalette.getUndoState()

Arguments
None.
Returns
The string to use with fw.historyPalette.setUndoState().
Description
Returns a string that indicates the current undo state to be used for later calls to
fw.historyPalette.setUndoState(). This string is designed to be used internally by Fireworks only and might
change format in the future. Do not try to parse this string or construct a custom string to pass to
fw.historyPalette.setUndoState().
See also
fw.historyPalette.setUndoState()

Last updated 5/2/2011

327

EXTENDING FIREWORKS
Additional Fireworks Functions

fw.historyPalette.replaySteps()
Availability
Fireworks 3.
Usage
fw.historyPalette.replaySteps(array of indexes)

Arguments
array of indexes A zero-based array that specifies which steps from the History panel should be returned as
JavaScript and executed. If the argument is null, the currently selected steps are used.

Returns
A JavaScript string.
Description
Gets the JavaScript equivalent of the specified steps and executes them.
See also
fw.historyPalette.getStepsAsJavaScript()

fw.historyPalette.saveAsCommand()
Availability
Fireworks 3.
Usage
fw.historyPalette.saveAsCommand(array of indexes, {filename})

Arguments
array of indexes Indicates which steps from the History panel should be saved. For example, to save the first,
third, and sixth steps in the History panel, pass [0, 2, 5]. If this argument is null, the currently selected steps are used.
filename An optional string that specifies a name for the JSF command file. It can be any string, including a file://
URL. If filename is omitted or null, the user is prompted for a filename. If filename is not a file://URL, the file is saved
in the Fireworks /Configuration/Commands folder with the specified filename.

Returns
Nothing.
Description
Gets the JavaScript equivalent of the specified steps and saves them as a JSF command file.

Last updated 5/2/2011

328

EXTENDING FIREWORKS
Additional Fireworks Functions

fw.historyPalette.setSelection()
Availability
Fireworks 3.
Usage
fw.historyPalette.setSelection(array of indexes)

Arguments
array of indexes Specifies which steps in the History panel are selected. Values are zero-based. For example, to
select the first, third, and sixth steps in the History panel, pass [0, 2, 5].

Returns
Nothing.
Description
Sets the portion of the History panel that is selected.

fw.historyPalette.setUndoState()
Availability
Fireworks 3.
Usage
fw.historyPalette.setUndoState(undoStateString)

Arguments
undoStateString

The string returned by fw.historyPalette.getUndoState().

Returns
Nothing.
Description
Performs the correct number of undo or redo operations to arrive at the selected state.
See also
fw.historyPalette.getUndoState()

Static Document Functions
Fireworks has an older static Document object that has been deprecated in favor of the Document object in the DOM.
The static Document object is only accessed by two methods. You can access this API using document.methodName().

Last updated 5/2/2011

329

EXTENDING FIREWORKS
Additional Fireworks Functions

document.findExportFormatOptionsByName()
Availability
Fireworks 3.
Usage
document.findExportFormatOptionsByName(name)

Arguments
name A string that specifies the name of the set of export settings to find.
Returns
If there is a set of export settings with the specified name, the argument returns an object that represents it; otherwise,
it returns null.
Description
Looks for a set of export settings that were saved with the specified name.

document.makeGoodNativeFilePath()
Availability
Fireworks 3.
Usage
document.makeGoodNativeFilePath(fileURL)

Arguments
fileURL The name of the file, which is expressed as a file://URL, whose extension should be changed to .png.
Returns
A string that contains the file URL with a .png extension.
Description
Ensures that the specified file URL ends in a .png extension. Does not affect the name of the file on disk.
Example
The following command returns "file:///My Documents/image01.png".
document.makeGoodNativeFilePath("file:///My Documents/image01.png")

Last updated 5/2/2011

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
Tagged PDF                      : Yes
Page Mode                       : UseOutlines
XMP Toolkit                     : Adobe XMP Core 4.0-c320 44.284297, Mon Apr 16 2007 09:10:35
Format                          : application/pdf
Creator                         : Adobe Systems Incorporated
Title                           : Extending Fireworks
Description                     : Adobe Fireworks CS5
Modify Date                     : 2011:05:02 03:11:12Z
Creator Tool                    : FrameMaker 8.0
Create Date                     : 2011:05:02 03:11:12Z
Producer                        : Acrobat Distiller Server 8.1.0 (Sparc Solaris, Built: 2007-09-07)
Document ID                     : uuid:ea275cce-1dd1-11b2-0a00-001838d80016
Instance ID                     : uuid:ea275cd5-1dd1-11b2-0a00-ffbff2d0fdb2
Page Count                      : 333
Subject                         : Adobe Fireworks CS5
Author                          : Adobe Systems Incorporated

EXIF Metadata provided by EXIF.tools

Adobe Extending Fireworks CS5

Navigation menu

Versions of this User Manual:

Views

Navigation