ADOBE Fireworks CS5 User Manual

Download

Extending

ADOBE® FIREWORKS

Legal notices

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

Last updated 5/17/2012

Chapter 1: Extending Fireworks Overview

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Installing an extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

What’s new in Extending Fireworks CS5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Additional resources for extension writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2: The Fireworks Object Model

Using the Fireworks Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Using Fireworks API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Using the common API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Working with selected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Global methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Core objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Adobe AIR Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

iii

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

ControlPoint object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Effect object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

EffectList object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Element object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

ElementMask object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

ExportFrameInfo object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

ExportOptions object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

ExportPaletteInfo object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

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

Fill object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Frame object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

FrameNLayerIntersection object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Gradient object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

GradientNode object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Guides object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Last updated 5/17/2012

EXTENDING FIREWORKS

Contents

Layer object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

PathAttrs object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Pattern object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

RectanglePrimitive object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

RegisterMoveParms object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

SingleTextRun object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

SmartShape object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Style object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

SliceInfo object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Slices object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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/17/2012

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 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).

substring() or subString()?). Useful JavaScript references include JavaScript Bible by Danny

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 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.

(www.adobe.com/go/exchange). By installing an existing extension,

Last updated 5/17/2012

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/17/2012

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

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()

AIRext.SaveDigSigPassword() Saves the password for the given digital certificate, for the current

AIRext.GetDigSigPassword() Returns the name of the generated password file.

AIRext.GetLastErrorLogName() Returns the name of the generated error log file if one was

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

AIRext.CreateCertificate() Calls the ADT to create a self-signed digital certificate.

exportDoc isBackground Specifies whether the document has a background image. If an

backgroundAttachment Specifies whether the document is fixed or scrolls. Values are

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

application.

Calls the ADT tool to check a certificate password.

session of Fireworks (no persistent storage).

created.

error occurs the values of the maxVersion and minVersion will be

-1.

image is set in the HTML set up, returns true.

Fixed or scroll.

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

backgroundRepeat Specifies if the background image repeats, and if repeats in X, Y,

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.

Repeat (Both) and No Repeat

Last updated 5/17/2012

EXTENDING FIREWORKS

Extending Fireworks Overview

Class Property or Method Description

SliceInfo backgroundHorizontalPosition Horizontal position of the background image. (Left, right, or

backgroundVerticalPosition Horizontal position of the background image. (Left, right, or

backgroundHorizontalPositionValHorizontal position value of the background image if the

backgroundVerticalPositionVal Vertical position value of the background image if the argument

isBackground Specifies whether the slice is background image or foreground

backgroundRepeat Specifies if the background image repeats, and if repeats in X, Y,

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

RectPrimitive Mode Specifies the roundness units which can be relative (percentage)

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

center, numeric value)

argument is value.

is value.

image. True = Background.

Repeat (Both) and No Repeat.

page.

or exact (pixels).

states.

document dom.setRectRoundnessMode() Specifies the mode of corner roundness of the rectangle as either

dom.exportElements() Exports an array of elements on the canvas to a 32-bit PNG image,

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

dom.setSliceType() Sets the slice type as image (foreground image), background

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

a percentage value or or exact pixel value.

based on the image export settings.

path are selected, no action occurs.

image, or empty (HTML Slice).

path are selected, no action occurs.

Last updated 5/17/2012

EXTENDING FIREWORKS

Extending Fireworks Overview

Class Property or Method Description

fw fw.saveAs() Saves the specified document in the specified filename and

fw.exportPDF() Exports the specified document to the specified file in PDF

fw.exportFXG() Exports current page, all pages of the open document in

fw.exportPages() Exports the specified pages in the specified format.

fw.shrinkPIWindow() Minimizes the Property inspector window.

fw.setUseAGMRenderingForSele ction()

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

rg1,arg2)” on page 233

“fw.saveDocumentAsTemplateA

sync(arg1,arg2)” on page 234

“fw.newDocumentFromTemplat

e(arg1)” on page 224

“fw.newMobileDocument(arg1,a

rg2,arg3,arg4)” on page 224

format.

Fireworks, or selected objects from the current page as FXG files.

Sets the currently selected vectors to use the new AGM Rendering.

Saves the current document as a template.

Works the same as fw.saveDocumentAsTemplate() except for the async mode of save operation.

Opens up a file for selecting any template from the pre-defined Templates folder in Fireworks installation directory.

Creates a mobile document with the width, height, and resolution details.

“fw.previewInDeviceCentral()” on page 227

“fw.getDocumentDOM().InsertP

ageForImport” on page 214

“fw.getDocumentDOM().combin

eCompoundShape” on page 213

“fw.getDocumentDOM().createC

ompoundShape” on page 214

fw.appTemplatesDir (See “The

Fireworks Object” on page 191

“fw.getDocumentDOM().Vector

Operation” on page 215

Files writeUTF8 Writes text in UTF8 encoding when the file is opened in UTF8

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

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

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

Combines the compound shape that is selected. Requires selection of a compound shape.

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

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

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

encoding.

Last updated 5/17/2012

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/17/2012

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

• 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

• 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.

“Objects within Fireworks documents” on page 243.

“Global methods” on page 14.

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 ( expressed as a file://URL. In other words, is a property (for more information, see 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) to obtain the path to the Export Settings directory (appExportSettingsDir), which is

fw references the Fireworks global object, of which appExportSettingsDir

“The Fireworks Object” on page 191), so a JavaScript command can assign the

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/17/2012

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 information, see

fw.getDocumentDOM().setDocumentResolution({pixelsPerUnit:72, units:"inch"}); fw.documents[0].resolution =72; fw.documents[0].resolutionUnits ="inch";

“Accessing a Fireworks document” on page 7).

fw.getDocumentDOM() function references the current document (for more

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

Mask data type

The format for a mask is {maskBounds:rectangle, maskKind:string, maskEdgeMode:string, featherAmount:int, maskData:

• maskBounds specifies the bounding rectangle of the mask area.

• Acceptable values for maskKind are "rectangle", "oval", "zlib compressed", "rle compressed", or

• If the value of maskKind is "rectangle" or "oval", the maskData string is ignored, and a mask of the right shape is

• If the value of maskKind is “zlib compressed“, “rle compressed", or “uncompressed", the maskData string is

hex-string}.

"uncompressed".

constructed that fills maskBounds and that has the edge specified by maskEdgeMode and featherAmount.

presumed to contain 8-bit mask data in hexadecimal format that precisely matches the maskBounds to define the mask.

"#rrggbbaa".

Last updated 5/17/2012

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, 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 –

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.

1 represents the second item, and so on. For example, the following command

1 to indicate the current layer.

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/17/2012

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 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.methodName().The following methods are currently

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/17/2012

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/17/2012

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 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;

“Working with properties for any selected object” on page 11). These specific

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/17/2012

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/17/2012

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/17/2012

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/17/2012

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,

“HTML export objects” on page 277.

see

Last updated 5/17/2012

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

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.

“The Document object” on page 28.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Fireworks Object Model

Method Data type Notes

copy(docname1, docname2)

createDirectory(dirname)

createFile(fileURL, fileType, fileCreator)

deleteFile(docOrDir)

deleteFileIfExisting (docOrDir)

enumFiles(docOrDir)

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

false otherwise.

true if the copy is successful;

string Creates the specified directory. Returns true if successful;

false otherwise.

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");

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().

string Deletes the specified file or directory. Returns true if

successful; Unlike

false if the file or directory cannot be deleted.

deleteFile(), this method returns true if the file or

directory does not exist.

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)

getDirectory(docname)

getExtension(docname)

getFilename(docname)

getLanguageDirectory()

getLastErrorString()

string Returns true if docOrDir refers to a directory or file that

false otherwise.

exists;

string Returns only the directory name from docname, which is

expressed as file://URL. For example,

Files.getDirectory("file://work/logo.png")

"file:///work".

returns

string Returns the filename extension, if any, of docname. For

example, returns

Files.getExtension("birthday.png")

".png". If the filename has no extension, an empty

string is returned. A filename that is expressed as file://URL is acceptable.

string Returns just the filename from docname, which is expressed as

file://URL. For example,

Files.getFilename("file:///work/logo.png")

"logo.png".

returns

string Returns the URL of the language directory associated with the

currently running language.

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/17/2012

EXTENDING FIREWORKS

The Fireworks Object Model

Method Data type Notes

getTempFilePath ({dirname})

isDirectory(dirname)

makePathFromDirAndFile(dirna me, plainFilename)

open(docname, encoding, bWrite)

rename(docname, newPlainFilename)

string The argument, if used, must be expressed as file://URL. Returns

string The argument must be expressed as file://URL. Returns true if

string, string The first argument must be expressed as file://URL.

string, string, Boolean The first argument must be expressed as file://URL. Opens the

string, string The docname argument is a file path or a file URL to the file that

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 returned indicates a file in the specified directory rather than in the Temporary Files directory.

the specified URL refers to a directory that exists; otherwise.

Concatenates the two arguments to return a file URL that references the specified filename in the specified directory. For example,

Files.makePathFromDirAndFile("file:///work/rep orts", "logo.png") "file:///work/reports/logo.png".

specified file for reading or writing. The second argument specifies the encoding. If the third argument is opens for writing; otherwise it opens for reading. If the file cannot be opened, returns Reference object.

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

dirname is passed and is not null, the URL that is

false

returns

true, the file

null; otherwise, returns a File

null.

setFilename(docname, newPlainFilename)

swap(docname1, docname2)

string, string The first argument must be expressed as file://URL. Returns a

file URL with example,

Files.setFilename("file:///work/logo.png", "oldlogo.png") "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().

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.

docname replaced by newPlainFilename. For

returns

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/17/2012

EXTENDING FIREWORKS

The Fireworks Object Model

Method Data Type Notes

close()

readline()

readLineUTF8

write(textString)

writeUTF8(textString)

none Closes the current File Reference object. You are not required

none Reads the next line from the current File Reference object and

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

string Writes the specified string to the current File Reference object.

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

to use this method (the file is closed when the Files object is destroyed), but it is useful for controlling access to a file.

returns it as a string. The end-of-line character(s) are not included in the string. Returns if the line is longer than 2048 characters.

encoding.

No end-of-line characters are appended; to include one, use

"\n".

encoding.

null if end-of-file is reached or

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

replace string Text to use as replacement text.

wholeWord Boolean If set to true, only whole words matching the search text are

regular expression. The default is

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/17/2012

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

replace string A color string that specifies the color to use as a replacement

(for more information, see

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

“Color string data type” on page 8).

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/17/2012

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

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

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

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

controlFaceColor string Returns the system color used for the control and panel faces

controlHilightColor string Returns the system color used for control highlights (Windows-

controlShadowColor string Returns the system color used for control shadows (Windows-

controlDarkShadowColor string Returns the system color used for control dark shadows

Fireworks is running.

(Windows®-only property).

only property).

(Windows-only property).

hilightItemColor string Returns the system color used for highlighting selections

hilightTextColor string Returns the system color used for highlighting selected text

textColor string Returns the system color used for text (Windows-only

menuColor string Returns the system color used for menu backgrounds

menuTextColor string Returns the system color used for text in menus (Windows-only

(Windows-only property).

property).

(Windows-only property).

property).

Adobe AIR Extension

AIRext.PreviewDocument()

Availability

Fireworks 10.

Last updated 5/17/2012

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/17/2012

EXTENDING FIREWORKS

The Fireworks Object Model

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.

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/17/2012

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/17/2012

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/17/2012

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/17/2012

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 Data type Notes

“Property inspector functions” on page 321.

backgroundColor

backgroundURL

brushes •

currentFrameNum

currentLayerNum

defaultAltText

docTitleWithoutExtension

exportFormatOptions

exportOptions

exportSettings

filePathForRevert

string A color string that specifies the document canvas color (for

more information, see

string Sets a general URL for a document that uses a hotspot.

Everything that is not covered by the hotspot has the background URL.

array Array of Brush objects that are available for use in the

document (for more information, see page 243).

zero-based index The index of the current frame.

zero-based index The index of the current layer.

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.

string The title of the document file, without any file extension. If the

document has not been saved, this string is empty.

object Identical to exportOptions. Included for backward

compatibility with Fireworks 2.

object ExportOptions object (for more information, see

“ExportOptions object” on page 260).

object ExportSettings object (for more information, see

“ExportSettings object” on page 263).

string The path to the file from which this document was opened,

which is expressed as file://URL, or

“Color string data type” on page 8).

“Brush object” on

null if created from scratch.

filePathForSave

fills •

frameCount

frameLoopingCount

string The location to which this document was saved, which is

expressed as file://URL, or

array Array of Fill objects that are available for use in the document

(for more information, see

integer The number of frames in the current document.

integer –1 — don’t repeat

0 — repeat forever

> 0 — repeat this number of times

null if never saved.

“Fill object” on page 265).

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Property Data type Notes

frames •

gammaPreview

gradients •

gridColor

gridOrigin

gridSize

guides •

height

isDirty

isPaintMode •

array Array of Frame objects in the document (for more information,

“Frame object” on page 266).

see

Boolean If set to true, the document should be previewed in opposite-

platform gamma. If set to

false, the document colors are

unadjusted.

array Array of Gradient objects that are available for use in the

document (for more information, see

“Gradient object” on

page 267).

string A color string that specifies the color of the grid display (for

more information, see

“Color string data type” on page 8).

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.

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

vertical grid size.

object Guides object (for more information, see “Guides object” on

page 267).

integer Total height of the document, in pixels. To find the bottom

edge of the document, use

document.height.

document.top +

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

was saved.

Boolean Set to true if the document is currently in paint-mode editing,

false otherwise.

isSymbolDocument •

isValid

lastExportDirectory

lastExportFile

layers •

left

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.

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.)

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".

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".

array An array of Layer objects in the document (for more

information, see

“Layer object” on page 268).

integer Coordinate of the left edge of the document, in pixels. To find

the right edge of the document, use

document.width.

document.left +

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Property Data type Notes

mapType

matteColor

onionSkinAfter

onionSkinBefore

pagesCount •

pageName

patterns •

pathAttributes

pngText

string Acceptable values are "client", "server", and "both".

Corresponds to the image-map type selected in File > HTML Setup.

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.

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 skinning; a very large value (such as

0 indicates no onion

99,999) indicates onion

skinning of all frames after the current frame.

integer Similar to the onionSkinAfter property, but refers to the

number of frames to show through onion skinning before the current frame.

integer Returns the number of pages in the current document.

string Returns the page name of the current page.

object The list of internal pattern names.

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.

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

resolutionUnits

savedSelections

textures

top

useMatteColor

width

currentPageNum

topLayers

float Document resolution, in pixels per unit (for more information,

resolutionUnits). The range is 1 to 5000.

see

string Units to be used with the resolution property. Acceptable

values are

"inch" and "cm".

object Array of the saved bitmap selections in the active document.

array Array of Texture objects that are available for use in the

document (for more information, see

“Texture object” on

page 259).

integer Coordinate of the top edge of the document, in pixels. To find

the bottom edge of the document, use

document.height.

document.top +

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.

integer The width of the document, in pixels. To find the right edge of

the document, use

document.left + document.width.

integer The index of the current page.

array Array of top level layers within the document objects.

Last updated 5/17/2012

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 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

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

“Accessing a Fireworks document” on page 7). Methods that

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

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 –

Returns

Nothing.

“Using the dom.addBehavior() function” on page 32.

1 here).

Last updated 5/17/2012

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,

1 here).

pass –

• 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/17/2012

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,

1 here).

pass –

• 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

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

(pass

• 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

downHighlightFrame, pass an empty text string. If you want to specify a filename and you passed –1 for

use in

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

1) or not (pass 0).

(pass

• 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/17/2012

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/17/2012

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,

1 here).

pass –

• 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/17/2012

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 the user is adding frames at the end of a document that has two frames and

false, the active frame does not change. For example, if

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/17/2012

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 Acceptable values are "hotspot" and "slice".

hotspot-shape 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/17/2012

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

boundRectangle 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.

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/17/2012

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/17/2012

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/17/2012

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/17/2012

EXTENDING FIREWORKS

The Document object

See also

dom.addNewRectanglePrimitive()

Availability

Fireworks 4.

Usage

dom.addNewRectanglePrimitive(boundingRectangle, roundness)

Arguments

boundingRectangle A rectangle that specifies the bounds within which the new rectangle primitive 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, and 1 is 100% roundness).

Returns

Nothing.

Description

Adds a new rectangle primitive that fits in the specified bounds. The rectangle primitive uses the document’s current default path attributes, is added on the current frame and layer, and has several editable properties, such as corner roundness and transformation. The difference between a rectangle and a rectangle primitive is that a rectangle is a path that is shaped like a rectangle, and a rectangle primitive preserves its rectangular quality; that is, if you drag a corner, it remains a rectangle rather than becoming a quadrilateral.

Example

The following command adds a new rectangle primitive with no round corners within the specified coordinates:

fw.getDocumentDOM().addNewRectanglePrimitive({left:0, top:0, right:100, bottom:100}, 0);

See also

dom.addNewRectangle(), fw.ungroupPrimitives()

dom.addNewSinglePointPath()

Availability

Fireworks 3.

Usage

dom.addNewSinglePointPath(controlPointFirst, mainpoint, controlPointLast, bCopyAttrs)

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Arguments

controlPointFirst, mainpoint, and controlPointLast Points that specify the x,y coordinates of the preceding

control point, the main point, and the following control point of the Bezier path (see

bCopyAttrs If bCopyAttrs is false, the path’s stroke and fill are copied directly from the document’s current stroke

“Point data type” on page 9).

and fill settings. If it is true, the path’s fill is set to None, and the brush is set to something other than None.

Returns

Nothing.

Description

Adds a new path that consists of a single Bezier point. The path uses the default fill, stroke, and so on, and is added on the current frame and layer. The point is selected after it is added.

Example

The following command adds a new path that consists of a single Bezier point at the specified coordinates and copies the path’s stroke and fill from the document’s current stroke and fill settings:

fw.getDocumentDOM().addNewSinglePointPath({x:150, y:63}, {x:150, y:63}, {x:150, y:63}, false);

dom.addNewStar()

Availability

Fireworks 3

Usage

dom.AddNewStar(numSides, spikiness, bIsStar, centerPoint, outsidePoint)

Arguments

numSides An integer that specifies the number of sides of the new path.

spikiness A floating-point value that controls the regularity of the star or polygon. Pass -1 to have Fireworks

calculate a good value, or pass a value between 0 and 1 for manual control.

bIsStar If bIsStar is true, a star with the specified number of points is created. If it is false, a regular polygon with

the specified number of sides is created.

centerPoint Specifies the center point of the star or polygon (see “Point data type” on page 9).

outsidePoint Specifies a point on the radius of the star or polygon.

Returns

Nothing.

Description

Adds a new star- or polygon-shaped path.

Example

The following command adds a five-sided star:

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

fw.getDocumentDOM().addNewStar(5, -1, true, {x:186, y:72}, {x:265, y:89});

dom.addNewSubLayer()

Availability

Fireworks CS3.

Usage

dom.addNewSubLayer(index, name, shared)

Arguments

index A long value that specifies the index of the parent layer for the new sub layer.

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

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

Returns

A string value that contains the name of the new sub layer.

Description

Adds a new sub layer to the document and makes it the current layer.

Example

The following command adds a new unshared sub layer to layer index 0 with a default name that is generated by Fireworks:

fw.getDocumentDOM().addNewSubLayer(0, null, false);

dom.addNewSymbol()

Availability

Fireworks 3.

Usage

dom.addNewSymbol(type, name, bAddToDoc, status)

Arguments

type Acceptable values are "graphic", "button", or "animation".

name A string that specifies the name of the symbol.

bAddToDoc A Boolean value. If bAddToDoc is true, an instance of the symbol is inserted into the center of the

document. If document.

false, the symbol is created in the document’s library, but no instance of the symbol is inserted into the

status A Boolean value that toggles 9-slice scaling between enabled and disabled.

Returns

Nothing.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Description

Adds a new symbol to the library and opens the symbol document for editing. Optionally adds an instance of the symbol to the document.

Example

The following command adds a new graphic symbol called text to the library and places an instance of it in the document:

fw.getDocumentDOM().addNewSymbol("graphic", "text", true, false);

dom.addNewText()

Availability

Fireworks 3.

Usage

dom.AddNewText(boundingRectangle, bInitFromPrefs)

Arguments

boundingRectangle A rectangle that specifies the bounds within which to place the new text box (see “Rectangle data

type” on page 9).

bInitFromPrefs If bInitFromPrefs is false, the default values for all style properties are used. If it is true, the

most recent values set by the user are used.

Returns

Nothing.

Description

Adds a new empty text block within the specified bounding rectangle. (To place text in the box, use

dom.setTextRuns().)

Example

The following command adds a text box with the most recently used style properties:

fw.getDocumentDOM().addNewText({left:43, top:220, right:102, bottom:232}, true);

dom.addSwapImageBehaviorFromPoint()

Availability

Fireworks 3.

Usage

dom.AddSwapImageBehaviorFromPoint(where)

Arguments

where A point that specifies the x,y coordinates of the hotspot or slice that contains the swap image behavior to be

added (see

“Point data type” on page 9).

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Returns

true if the swap image behavior was added; false if no suitable hotspot was at the specified location.

Description

If a single hotspot or slice is selected, this function adds to it a swap image behavior from the hotspot or slice located

where in the document.

dom.adjustExportToSize()

Availability

Fireworks 3.

Usage

dom.AdjustExportToSize(sizeInBytes, bOkToIncreaseSize)

Arguments

sizeInBytes An integer that specifies the size to be used for exporting. It is used as described in the following list:

• If a document has no slices, sizeInBytes adjusts the export settings for the current frame so that the image is less

than or equal to

• If a document has slices, sizeInBytes adjusts the size of all exported images so that the sum of the sizes is greater

than or equal to

bOkToIncreaseSize Specifies whether the export file size can be increased.

sizeInBytes.

• If bOkToIncreaseSize is true, and the current size is less than sizeInBytes, the argument increases the quality

of the export settings as much as possible, making the export size larger if necessary.

• If bOkToIncreaseSize is false, the argument increases the quality of the export settings as much as possible

without increasing the export size.

Description

Adjusts the export settings as specified.

dom.adjustFontSize()

Availability

Fireworks MX.

Usage

dom.adjustFontSize(amount)

Arguments

amount The amount, specified in points, by which to change the font size. Positive values (such as "2pt") increase the

size, while negative values (such as

Returns

Nothing.

"-1pt") decrease the size.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Description

Increases (positive values) or decreases (negative values) the font size of selected text elements. If a text element has multiple font sizes, each size is adjusted independently.

dom.align()

Availability

Fireworks 3. Align to canvas parameter is only available in Fireworks 8.

Usage

dom.align(alignmode, alignToCanvas)

Arguments

alignmode Acceptable values are "left", "right", "top", "bottom", "center vertical", and "center horizontal".

alignToCanvas Boolean. Determines if the alignment is to the canvas or items. The default value is false.

Returns

Nothing.

Description

Aligns the selection.

dom.appendPointToHotspot()

Availability

Fireworks 3.

Usage

dom.appendPointToHotspot(pt, tolerance)

Arguments

pt A point that specifies the x,y coordinates of the point to be added (see “Point data type” on page 9).

tolerance A floating-point value > = 0 that specifies the tolerance between the new point and the starting point of

the polyline path. If the new point is within

Returns

Nothing.

Description

Appends a point to the selected unclosed polygon hotspot. If an unclosed polygon hotspot is not selected, a new polygon hotspot is created with the single point that passed in.

tolerance of the starting point, the polyline path is closed.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.appendPointToPath()

Availability

Fireworks 3.

Usage

dom.appendPointtoPath(ontourIndex, ptToInsertBefore, controlPointFirst, mainPoint, controlPointLast)

Arguments

contourIndex An zero-based index value that specifies the contour to which the Bezier point is appended. For paths

with multiple contours, the contours are in an arbitrary order.

ptToInsertBefore A zero-based index value that specifies where on the path the new point should be placed. The

new point is appended in front of the point that this integer represents. To add a point to the beginning of the path,

0; to add a point to the end of the path, pass a large number.

pass

controlPointFirst, mainPoint, and controlPointLast Points that specify the x,y coordinates of the preceding

control point, the main point, and the following control point of the new point (see

“Point data type” on page 9).

Returns

Nothing.

Description

Appends a Bézier point to the selected path.

See also

dom.insertPointInPath()

dom.appendPointToSlice()

Availability

Fireworks 3.

Usage

dom.appendPointToSlice(pt, tolerance)

Arguments

pt A point that specifies the x,y coordinates of the point to be added (see “Point data type” on page 9).

tolerance A floating-point value > = 0 that specifies the tolerance between the new point and the starting point of

the polyline path. If the new point is within

tolerance of the starting point, the polyline path is closed.

Returns

Nothing.

Description

Appends a point to the selected unclosed polygon slice. If an unclosed polygon slice is not selected, then a new polygon slice is created with the single point that passed in.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.applyCharacterMarkup()

Availability

Fireworks 3, updated in Fireworks 4.

Usage

dom.applyCharacterMarkup(tag)

Arguments

tag Acceptable values for tag are "b", "i", and "u", for bold, italic, and underline: and "fwplain", which was added

in Fireworks 4, for text with no character markup.

Returns

Nothing.

Description

Applies the specified character markup to the selected text.

dom.applyCurrentFill()

Availability

Fireworks 3.

Usage

dom.applyCurrentFill(NoNullFills)

Arguments

bNoNullFills If bNoNullFills is true and the current fill is None, then a default fill is applied instead of no fill.

Returns

Nothing.

Description

Applies the document’s current fill to the selection.

Example

The following command applies the current fill to the selection:

fw.getDocumentDOM().applyCurrentFill(true);

dom.applyEffects()

Availability

Fireworks 3.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Usage

dom.ApplyEffects(effectList)

Arguments

effectList An EffectList object (see “EffectList object” on page 254). If effectList is null, this function removes

all effects from the selection.

Returns

Nothing.

Description

Applies the specified effects to the selection.

Example

The following command applies a drop shadow with an angle of 315, a blur of 4, a color of black, and a distance of 7

“Drop Shadow object” on page 251):

(see

fw.getDocumentDOM().applyEffects({category:"Untitled", effects:[ { EffectIsVisible:true, EffectMoaID:"{a7944db8-6ce2-11d1-8c76000502701850}", ShadowAngle:315, ShadowBlur:4, ShadowColor:"#000000a6", ShadowDistance:7, ShadowType:0, category:"Shadow and Glow", name:"Drop Shadow" } ], name:"Untitled" });

dom.applyFontMarkup()

Availability

Fireworks 3.

Usage

dom.applyFontMarkup(fontAttribute, value)

Arguments

fontAttribute Acceptable values for fontAttribute are "size" and "face".

value If fontAttribute is "size", value must be of the form "XXXpt" to specify a point size; a simple numeric

value is not allowed.

Returns

Nothing.

Description

Applies the specified font markup attribute to the selected text.

dom.applyStyle()

Availability

Fireworks 3.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Usage

dom.applyStyle(styleName, styleIndex)

Arguments

styleName A string that specifies the style name to be applied. The style group from which the style is being applied

should be selected.

styleIndex An index to the style to apply. This is usually zero. However, if there are multiple styles with the same

styleIndex is used to resolve the ambiguity (0 references the first style with that name, 1 references the second,

name, and so on).

Returns

Nothing.

Description

Applies the specified style to the selection.

Example

The following command applies the first style that Fireworks encounters named “Style 7”, which, in this case, is a default style:

fw.getDocumentDOM().applyStyle("Style 7", 0);

dom.arrange()

Availability

Fireworks 3.

Usage

dom.arrange(arrangemode)

Arguments

arrangemode Acceptable values for arrangemode are "back", "backward", "forward", and "front".

Returns

Nothing.

Description

Arranges the selection.

Example

The following command brings the selected items to the front:

fw.getDocumentDOM().arrange("front");

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.attachTextInPath()

Availability

Fireworks CS5.

Usage

dom.attachtTextInPath()

Arguments

None.

Returns

Nothing.

Description

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

Example

When two items are selected (one a text block and the other a shape), the following command attaches the text block inside the shape's path:

fw.getDocumentDOM().attachTextInPath();

dom.attachTextToPath()

Availability

Fireworks 3.

Usage

dom.attachtTextToPath()

Arguments

None.

Returns

Nothing.

Description

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

Example

When two items are selected (one a text block and the other a shape), the following command attaches the text block to the shape’s path:

fw.getDocumentDOM().attachTextToPath();

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.breakLink()

Availability

Fireworks 3.

Usage

dom.breakLink()

Arguments

None.

Returns

Nothing.

Description

Breaks the link between the symbol and the instance.

dom.changeCurrentPage()

Availability

Fireworks CS3.

Usage

dom.changeCurrentPage(pageNum)

Arguments

pageNum An long value that specifies the page number of the page that will become the active page.

Returns

Nothing.

Description

Changes the currently active page to the specified page number. The page number is in an array and the first page is numbered 0.

dom.changeGuide()

Availability

Fireworks 3.

Usage

dom.changeGuide(currentPosition, newPosition, guidekind)

Arguments

currentPosition A floating-point value that specifies the current position of the guide.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

newPosition A floating-point value that specifies the new position of the guide.

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

is assumed that the specified positions are y coordinates; if guidekind is

"vertical", it is assumed that the specified

positions are x coordinates.

Returns

Nothing.

Description

Moves a guide’s position to a new location.

Example

The following command moves a vertical guide from position 135 to position 275:

fw.getDocumentDOM().changeGuide(135, 275, "vertical");

dom.changeNineScaleGuide()

Availability

Fireworks CS3.

Usage

dom.changeNineScaleGuide(oldpos, newpos, guidekind)

Arguments

oldpos A double precision value that specifies the current position of the guide.

newpos A double precision value that specifies the new position of the guide.

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

assumed that the specified positions are y coordinates; if

guidekind is "vertical", it is assumed that the specified

positions are x coordinates.

Returns

Nothing.

Description

Moves a 9-slice scaling guide’s position to a new location.

Example

The following command moves a vertical guide from position 135 to position 275:

fw.getDocumentDOM().changeNineScaleGuide(135, 275, "vertical");

dom.changeSliceGuide()

Availability

Fireworks MX.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Usage

dom.changeSliceGuide(currentPosition, newPosition, guidekind, isMagneticDrag, isSingleDrag)

Arguments

currentPosition A floating-point value that specifies the current position of the slice guide to be moved.

newPosition A floating-point value that specifies the new position of the slice guide.

guidekind Acceptable values are "horizontal" and "vertical". If the value of guidekind is “horizontal” ,

Fireworks assumes that the specified positions are y coordinates; if

"vertical", the specified positions are x

coordinates.

isMagneticDrag A Boolean value that determines whether to move other slice guides between the old and new

positions. If

isMagneticDrag is true, Fireworks also moves slice guides between the old guide position and the new

position. This action resizes and possibly deletes rectangular slices that do not abut the slice guide at

currentPosition.

isSingleDrag A Boolean value that determines whether the operation is performed only on the selected slice or on

all slices that are affected by the slice guide. If

changeSliceGuide() action on the selected slice.

isSingleDrag is true, Fireworks performs only the

Returns

Nothing.

Description

Moves a slice guide’s position to a new location, which resizes any rectangular slices that abut the guide. An argument controls whether slice guides that exist between the old position and the new one are also moved.

If a slice is resized so that it has zero width or height, the slice is deleted.

This function does not change slices that are not rectangular.

Example

The following command moves a vertical slice guide from position 135 to position 275, and moves all vertical slice guides between 135 and 275 to 275:

fw.getDocumentDOM().changeGuide(135, 275, "vertical", true);

dom.clearJPEGMask()

Availability

Fireworks 4.

Usage

dom.clearJPEGMask()

Arguments

None.

Returns

Nothing.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Description

Clears the “Selective JPEG mask” for the document.

dom.clipCopy()

Availability

Fireworks 3.

Usage

dom.clipCopy()

Arguments

None.

Returns

Nothing.

Description

Copies the selection to the clipboard.

Example

The following command copies the selected items to the clipboard:

fw.getDocumentDOM().clipCopy();

dom.clipCopyAsPaths()

Availability

Fireworks MX.

Usage

dom.clipCopyAsPaths()

Arguments

None.

Returns

Nothing.

Description

Copies the selection to the clipboard in Adobe Illustrator format.

Example

The following command copies the selected items to the clipboard in Adobe Illustrator format:

fw.getDocumentDOM().clipCopyAsPaths();

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.clipCopyFormats()

Availability

Fireworks MX.

Usage

dom.clipCopyFormats(format)

Arguments

format The graphics format for the selection. For example, "AICB" is the Adobe Illustrator format.

Returns

Nothing.

Description

Copies the selection to the clipboard using the specified format.

dom.clipCopyJsToExecute()

Availability

Fireworks 9.

Usage

dom.clipCopyJsToExecute(string)

Arguments

string The JavaScript code that is copied on to the clipboard that you want to execute.

Returns

Nothing.

Description

Copies the JavaScript command on to the clipboard.

dom.clipCut()

Availability

Fireworks 3.

Usage

dom.clipCut()

Arguments

None.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Returns

Nothing.

Description

Cuts the selection to the clipboard.

Example

The following command cuts the selected items and places them on the clipboard:

fw.getDocumentDOM().clipCut();

dom.clipPaste()

Availability

Fireworks 3, updated in Fireworks 4.

Usage

dom.clipPaste({whatIfResolutionDifferent}, {whatIfPastingIntoElementMask})

Arguments

whatIfResolutionDifferent An optional string that specifies how resampling should be done if the resolution of

the clipboard contents doesn’t match the resolution of the document. Acceptable values for

whatIfResolutionDifferent are "resample", "do not resample", and "ask user" (displays a dialog box to let

the user decide). If

whatIfPastingIntoElementMask An optional argument, added in Fireworks 4, that applies only if the user is

whatIfResolutionDifferent is omitted or null, "ask user" is assumed.

editing an element mask, and that element mask is an empty image mask. In this case, the pasted elements replace the existing mask (because it is essentially a mask that doesn’t mask anything). If the image mask isn’t empty, the pasted elements are added to the existing mask, rather than replacing it. Acceptable values for

whatIfPastingIntoElementMask are "image", "vector", and "ask user". If whatIfPastingIntoElementMask is omitted or null, "ask user" is assumed.

Returns

Nothing.

Description

Pastes the clipboard contents into the document.

Example

The following command pastes the clipboard contents into the document. If there is a need for resampling, Fireworks asks the user to decide how to resample.

fw.getDocumentDOM().clipPaste();

dom.clipPasteAsMask()

Availability

Fireworks 4.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Usage

dom.clipPasteAsMask(whatIfResolutionDifferent, masktype, maskReplaceOptions)

Arguments

whatIfResolutionDifferent A string that specifies how resampling should be done if the resolution of the

clipboard contents doesn’t match the resolution of the document. Acceptable values for

whatIfResolutionDifferent are "resample", "do not resample", and "ask user" (displays a dialog box to let

the user decide). If

masktype Specifies how to paste the mask. Acceptable values are “image“ (always paste as an image mask), “vector“

(always paste as a vector mask), and “ single image, it is pasted as an image mask, even if you pass “

maskReplaceOptions Acceptable values for maskReplaceOptions are “replace“ (if an element mask already exists,

replace it with the pasted one), “

whatIfResolutionDifferent is omitted or null, "ask user" is assumed.

ask“ (displays a dialog box to let the user decide). If the clipboard contains a

vector“.

add“ (if an element mask already exists, add the pasted mask to it), and “ask“ (displays

a dialog box to let the user decide).

Returns

Nothing.

Description

Pastes the clipboard contents into the document as an element mask. Only one element can be selected when calling this function. If more than one element (or none) is selected when this function is called, Fireworks throws an exception. An exception is also thrown if there is nothing on the clipboard.

dom.clipPasteAttributes()

Availability

Fireworks 3.

Usage

dom.clipPasteAttributes()

Arguments

None.

Returns

Nothing.

Description

Pastes the attributes from the clipboard onto the selection.

Example

The following command applies the attributes that were copied to the clipboard onto the selected items:

fw.getDocumentDOM().clipPasteAttributes();

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.clipPasteFromChannelToChannel()

Availability

Fireworks MX.

Usage

dom.clipPasteFromChannelToChannel(fromChannel, toChannel)

Arguments

fromChannel If the current selection is not a single bitmap, a new opaque bitmap is created and the fromChannel is

pasted in to all three color channels of the new bitmap, resulting in a grayscale image. This first argument is ignored if the current selection is not a single bitmap.

toChannel If the currently selected element is a bitmap, the toChannel argument is used to specify where to paste

the color data.

Returns

Nothing.

Description

Pastes the specified color channel on the clipboard into each of the RGB channels of a new image or into the specified channel of the selected image, if any.

Example

The following command copies the red data from the clipboard into the red channel:

fw.getDocumentDOM().clipPasteFromChannelToChannel("red", "red");

The following command copies the green data from the clipboard into the alpha channel:

fw.getDocumentDOM().clipPasteFromChannelToChannel("green", "alpha");

dom.clipPasteInside()

Availability

Fireworks 3, deprecated in 4 in favor of dom.clipPasteAsMask() (see dom.clipPasteAsMask()).

Usage

dom.clipPasteInside({whatIfResolutionDifferent})

Arguments

whatIfResolutionDifferent An optional string that specifies how resampling should be done if the resolution of

the clipboard contents doesn’t match the resolution of the document. Acceptable values for

whatIfResolutionDifferent are "resample", "do not resample", and "ask user" (displays a dialog box to let

the user decide). If

whatIfResolutionDifferent is omitted or null, "ask user" is assumed.

Returns

Nothing.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Description

Pastes the clipboard contents into the selection, and places the selected element into the element mask for the pasted elements. If the selected element already has a mask, this function groups the pasted elements with the selected element and applies the existing element mask to the group.

Example

The following command pastes the clipboard contents inside the selected items. If the resolution of the clipboard contents doesn’t match the resolution of the document, Fireworks resamples the clipboard contents to match the document.

fw.getDocumentDOM().clipPasteInside("resample");

dom.cloneSelection()

Availability

Fireworks 3.

Usage

dom.cloneSelection()

Arguments

None.

Returns

Nothing.

Description

Makes exact duplicates of the selection, placing the duplicated items directly on top of the original items.

Example

The following command copies the selected items on top of the original items:

fw.getDocumentDOM().cloneSelection();

See also

dom.duplicateSelection()

dom.close()

Availability

Fireworks 3.

Usage

dom.close(bPromptToSaveChanges)

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Arguments

bPromptToSaveChanges If bPromptToSaveChanges is true, and the document was changed since the last time it

was saved, the user is prompted to save any changes to the document. If

bPromptToSaveChanges is false, the user is

not prompted, and changes to the document are discarded.

Returns

Nothing.

Description

Closes the document.

dom.convertAnimSymbolToGraphicSymbol()

Availability

Fireworks 4.

Usage

dom.converAnimSymbolToGraphicSymbol()

Arguments

None.

Returns

Nothing.

Description

If a single animation symbol is selected, this function converts it from an animation symbol to a graphics symbol.

See also

dom.convertToAnimSymbol(), dom.convertToSymbol()

dom.convertMarqueeToPath()

Availability

Fireworks 7.

Usage

dom.convertMarqueeToPath()

Arguments

None.

Returns

Nothing.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Description

Converts marquee selection to path.

dom.convertPathToMarquee()

Availability

Fireworks 7.

Usage

dom.convertPathToMarquee(mode, featherAmount)

Arguments

mode Sets the mode. Acceptable values are "hard edge", "antialias", and "feather".

featherAmount Sets the amount of feathering for the marquee selection. This value is ignored if mode is not set to

"feather"

Returns

Nothing.

Description

Converts path to marquee selection.

dom.convertToAnimSymbol()

Availability

Fireworks 4.

Usage

dom.convetToAnimSymbol(name, numFrames, offsetDistPt, rotationAmount, scaleAmount, startOpacity, endOpacity)

Arguments

name A string that specifies a name for the new animation symbol.

numFrames An integer that specifies the number of frames through which the symbol animates.

offsetDistPt A point that specifies the distance the animation will move in pixels (see “Point data type” on page 9).

For example, passing ({x:100, y:25}) animates the symbol to the right 100 pixels and 25 pixels down.

rotationAmount A floating-point value that specifies the degrees of rotation to be applied to the animation symbol.

For example, passing a value of animation counter-clockwise, pass a negative number.

scaleAmount A positive floating-point value that specifies the amount of scaling to be applied to the animation

symbol. For example, passing a value of its current size. To specify no scaling, pass

720 specifies an animation that does two complete clockwise rotations. To rotate the

50 scales the symbol to 50% of its current size, and passing 200 scales it to twice

100.

startOpacity and endOpacity Float values between 0 and 100 that specify the starting and ending opacity for the

animation symbol.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Returns

Nothing.

Description

Converts the selected items to a new animation symbol.

See also

dom.convertAnimSymbolToGraphicSymbol(), dom.convertToSymbol(), dom.setAnimInstanceNumFrames()

dom.convertToPaths()

Availability

Fireworks 3.

Usage

dom.convertToPaths()

Arguments

None.

Returns

Nothing.

Description

Converts the selected text items into editable paths.

Example

The following command converts the selected text items into editable paths:

fw.getDocumentDOM().convertToPaths();

dom.convertToSymbol()

Availability

Fireworks 3.

Usage

dom.convertToSymbol(type, name, status)

Arguments

type Acceptable values are "graphic", "button", and "animation".

name A name for the new symbol.

status A Boolean value that toggles 9-slice scaling between enabled and disabled.

Returns

Nothing.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Description

Converts the selected items to a new symbol.

Example

The following command creates a graphic symbol from the selected item and names it “star”:

fw.getDocumentDOM().convertToSymbol("graphic", "star");

See also

dom.convertToAnimSymbol(), dom.convertAnimSymbolToGraphicSymbol()

dom.convolveSelection()

Availability

Fireworks MX 2004.

Usage

dom.convolveSelection( kernelWidth, kernelHeight, kernelValues, affectsAlpha)

Arguments

kernelWidth An integer that defines the width of the filter coefficients.

kernelHeight An integer that defines the height of the filter coefficients.

kernelValues An array of integers that defines the values for specific filter patterns.

affectsAlpha A Boolean value: true means the convolution filter affects the transparency of the bitmap; false

means that the bitmap transparency isn’t affected by the filter.

Returns

Nothing

Description

Applies convolution, or irregular, filters to the selected bitmap based on the pattern defined by the argument values.

Example

The following example applies an edge-detection filter to the bitmap:

// width of convolution kernel var w = 3; // height of convolution kernel var h = 3; // Edge detection kernel var k = new Array(0, 1, 0, 1, -4, 1, 0, 1, 0);

fw.getDocumentDOM().convolveSelection(w, h, k, false);

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.copyHtmlWizard()

Availability

Fireworks MX.

Usage

dom.copyHtmlWizard()

Arguments

None.

Returns

Nothing.

Description

Opens the Copy HTML Wizard dialog box.

Example

The following command opens the Copy HTML Wizard dialog box:

fw.getDocumentDOM().copyHtmlWizard();

dom.copyToHotspot()

Availability

Fireworks 3.

Usage

dom.copyToHotspot(hotspotType, {whatIfMultipleSelected}, {makeRectangular})

Arguments

hotspotType Acceptable values are "hotspot" and "slice".

whatIfMultipleSelected An optional string that specifies how to create hotspots if multiple items are selected.

Acceptable values for rectangle as the selection), let the user decide). If

makeRectangular An optional Boolean value that determines if the slice for the hotspot will be a rectangle or

polygon. If

true (the default), Fireworks creates a rectangular slice; otherwise, the slice is a polygon if the shape being

copied to the slice is a polygon.

Returns

Nothing.

whatIfMultipleSelected are "single" (creates a single hotspot that has the same bounding

"multiple" (creates one hotspot for each item), and "ask user" (displays a dialog box to

whatIfMultipleSelected is omitted or null, "ask user" is assumed.

Description

Creates one or more hotspots from the selection.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Example

The following command adds a hotspot to the selected item. If more than one item is selected, Fireworks creates one hotspot for each item.

fw.getDocumentDOM().copyToHotspot("hotspot", "multiple");

dom.cropSelection()

Availability

Fireworks 3.

Usage

dom.cropSelection(boundingRectangle)

Arguments

boundingRectangle A rectangle that specifies the bounds within which the selection should be cropped (see

“Rectangle data type” on page 9).

Returns

Nothing.

Description

Crops the selection to the specified rectangle.

dom.deleteAllInDocument()

Availability

Fireworks MX.

Usage

dom.deleteAllInDocument()

Arguments

None.

Returns

Nothing.

Description

Deletes all of the objects in the document.

dom.deleteFrames()

Availability

Fireworks 3.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Usage

dom.deleteFrames(frameIndex, howMany)

Arguments

frameIndex An integer value that specifies the location at which to begin deleting frames, starting with 0 (although,

to specify the current frame, pass –1).

howMany Specifies how many frames to delete.

Returns

Nothing.

Description

Deletes one or more frames.

dom.deleteLayer()

Availability

Fireworks 3.

Usage

dom.deleteLayer(layerIndex)

Arguments

layerIndex An integer value that specifies the layer to be deleted, starting with 0 (although, to specify the current

layer, pass –

1 here).

Returns

Nothing.

Description

Deletes a layer.

Example

The following command deletes the current layer:

fw.getDocumentDOM().deleteLayer(-1);

dom.deletePageAt()

Availability

Fireworks CS3.

Usage

dom.deletePageAt(pageNum)

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Arguments

pageNum A long value that indicates the page number of the page to be deleted.

Returns

Nothing.

Description

Deletes a specified page from the current document. For example:

fw.getDocumentDOM().deletePageAt(0)

dom.deletePointOnPath()

Availability

Fireworks 4.

Usage

dom.deletePointOnPath(contourIndex, pointIndex)

Arguments

contourIndex An integer value that specifies the contour that contains the point to be deleted, starting with 0

(although, to specify the current contour, pass –

pointIndex An integer value that specifies the point to be deleted, starting with 0 (although, to specify the current

point, pass –

1 here).

Returns

Nothing.

Description

Deletes the specified point on the currently selected path. If the point is the only one on its contour, the entire contour is deleted. If the point is the only one in the path, the entire path is deleted. The specified point does not need to be selected.

Example

The following command deletes the currently selected point:

fw.getDocumentDOM().deletePointOnPath(-1, -1);

dom.deleteSavedSelection()

Availability

Fireworks 3.

Usage

dom.deleteSavedSelection(selection)

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Arguments

selection The name of the saved bitmap selection.

Returns

Nothing.

Description

Deletes the selection or the pixel selection if Fireworks is in bitmap mode.

Example

If Fireworks is not in bitmap mode, the following command deletes the selected items. If Fireworks is in bitmap mode, the following command fills the selected items to transparent.

fw.getDocumentDOM().deleteSavedSelection(false);

dom.deleteSelection()

Availability

Fireworks 3.

Usage

dom.deleteSelection(bFillDeletedArea)

Arguments

bFillDeletedArea This argument is ignored if Fireworks is not in bitmap mode. If Fireworks is in bitmap mode and

bFillDeletedArea is true, the deleted pixels are filled with the current fill color. If false, the deleted pixels are filled

to transparent.

Returns

Nothing.

Description

Deletes the selection, or the pixel selection if Fireworks is in bitmap mode.

Example

If Fireworks is not in bitmap mode, the following command deletes the selected items. If Fireworks is in bitmap mode, the following command fills the selected items to transparent.

fw.getDocumentDOM().deleteSelection(false);

dom.deleteSymbol()

Availability

Fireworks 3.

Usage

dom.deleteSymbol(symbolName)

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Arguments

symbolName The name of the symbol to delete from the library. If more than one symbol exists with this name, only

the first symbol is deleted.

• To delete all the selected symbols from the library (not document), pass null.

• If the deleted symbols contain any active instances in the document, the instances are also deleted.

Returns

Nothing.

Description

Deletes the specified symbols from the library.

Example

The following command deletes the selected symbols from the library as well as any active instances from the document:

fw.getDocumentDOM().deleteSymbol(null);

dom.detachInstanceFromSymbol()

Availability

Fireworks 3.

Usage

dom.detachInstanceFromSymbol()

Arguments

None.

Description

Breaks the links between the selected instances and the owning symbols.

Returns

Nothing.

dom.detachTextFromPath()

Availability

Fireworks 3.

Usage

dom.detachTextFromPath()

Arguments

None.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Returns

Nothing.

Description

Splits the selected text-on-a-path items into its original text and path items.

dom.detachSharedLayer()

Availability

Fireworks CS3.

Usage

dom.detachSharedLayer(layerNum, pageNum)

Arguments

layerNum A long value that specifies the layer number for the layer that is to be detached.

pageNum A long value that specifies the page number of the page from which the layer will be detached.

Returns

Nothing.

Description

Detaches the specified shared layer from the specified page. You can only detach a parent layer, not a sub layer. When the parent later is detached, the sub layers are automatically detached as well.

Example:

fw.getDocumentDOM().detachSharedLayer(1, 1)

dom.distribute()

Availability

Fireworks 3, updated with distributeToCanvas parameter in Fireworks 8.

Usage

dom.distribute(distmode, distributeToCanvas)

Arguments

distmode Acceptable values are "vertical" and "horizontal".

distributeToCanvas A Boolean value that determines whether items are distributed to the canvas. Default value is

"false".

Returns

Nothing.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Description

Distributes the selection along a vertical or horizontal dimension.

dom.distributeLayerToFrames()

Availability

Fireworks 3.

Usage

dom.distributeLayerToFrames(layerIndex)

Arguments

layerIndex An integer value that specifies the layer that contains the items to be distributed, starting with 0

(although, to specify the current layer, pass –1 here).

Returns

Nothing.

Description

Distributes the items on the specified layer to the frames of the document, adding frames if necessary. The first item on the layer goes to the first frame, the second item to the second frame, and so on. New frames are added to the document, if necessary. If there is only one item in the specified layer, this function has no effect.

dom.distributeSelectionToFrames()

Availability

Fireworks 3.

Usage

dom.distributeSelectionToFrames()

Arguments

None.

Returns

Nothing.

Description

Distributes the selected items to the frames of the document, adding frames if necessary. The first item goes to the current frame, the second item to the next frame, and so on. If only one item is selected, this function has no effect.

dom.dragControlPoint()

Availability

Fireworks MX 2004.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Usage

dom.dragControlPoint(index, newLoc, shiftKeyDown, ctrlCmdKeyDown, altOptKeyDown)

Arguments

index The index of the control point to move.

newLoc Specifies the new location of the point.

shiftKeyDown Specifies whether the Shift key is pressed.

ctrlCmdKeyDown Specifies whether the Control key (Windows) or Command key (Macintosh) is pressed.

altOptKeyDown Specifies whether the Alt key (Windows) or Option key (Macintosh) is pressed.

Returns

Nothing.

Description

Drags the specified control point to the new location.

dom.duplicateFrame()

Availability

Fireworks 3.

usage

dom.duplicateFrame(frameIndex, howMany, where, bDupeSelectionOnly)

Arguments

frameIndex An integer value that specifies the frame to duplicate, starting with 0 (although, to specify the current

frame, pass –

howMany An integer that specifies how many copies of the frame to make.

where Acceptable values are "beginning", "before current", "after current", and "end".

bDupeSelectionOnly If bDupeSelectionOnly is true, only items in the specified frame that are selected are

1 here).

duplicated to the new frame.

Returns

Nothing.

Description

Duplicates a frame.

Example

The following command makes one copy of the current frame and places the new frame after the current frame:

fw.getDocumentDOM().duplicateFrame(-1, 1, "after current", false);

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.duplicateLayer()

Availability

Fireworks 3.

Usage

dom.duplicateLayer(layerIndex, {howMany}, {where})

Arguments

layerIndex An integer value that specifies the layer to duplicate, starting with 0 (although, to specify the current

layer, pass –

howMany An optional integer that specifies how many times to duplicate the layer. If omitted, the layer is duplicated

once.

where An optional argument that specifies where to put the new layer(s) in relation to the source layer. Acceptable

values are assumed.

Returns

Nothing.

1 here).

"beginning", "before current", "after current", and "end". If omitted, "before current" is

Description

Duplicates a layer.

Example

The following command places three copies of the current layer at the end of the document:

fw.getDocumentDOM().duplicateLayer(-1, 3, "end");

dom.duplicatePage()

Availability

Fireworks CS3.

Usage

dom.duplicatePage(pageNum)

Arguments

pageNum An long value that specifies the page number of the page to be duplicated.

Returns

Nothing.

Description

Duplicates a page. For example:

fw.getDocumentDOM().duplicatePage(1)

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.duplicateSelection()

Availability

Fireworks 3.

Usage

dom.duplicateSelection()

Arguments

None.

Returns

Nothing.

Description

Makes a duplicate of the selection, offsetting it slightly from the original.

Example

The following command duplicates the selected items:

fw.getDocumentDOM().duplicateSelection();

See also

dom.cloneSelection()

dom.duplicateSelectionToFrameRange()

Availability

Fireworks 3.

Usage

dom.duplicateSelectionToFrameRange(frameIndexFirst, frameIndexLast)

Arguments

frameIndexFirst and frameIndexLast Integer values that specify the range of frames (inclusive) to which the

items should be copied, starting with

• If both arguments are the same, duplicates are placed only on that frame.

• If the range includes the current frame, duplicates are not placed on that frame.

Returns

Nothing.

0 (although, to specify the current frame, pass –1 here).

Description

Duplicates the selection to a range of frames of the document.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.duplicateSelectionToFrames()

Availability

Fireworks 3.

Usage

dom.cuplicateSelectionToFrames(whichFrames)

Arguments

whichFrames Acceptable values are "all", "previous", "next", and "end". Note that "end" means the last frame

of the document; it does not add a new frame.

Returns

Nothing.

Description

Duplicates the selection to specified frames of the document.

dom.duplicateSymbol()

Availability

Fireworks 3.

Usage

dom.duplicateSymbol(symbol)

Arguments

symbol The symbol to duplicate.

• To duplicate all selected symbols in the library (not the document), pass a null-value.

• Duplicating a linked symbol results in a nonlinked duplicate.

Returns

Nothing.

Description

Duplicates the specified symbol.

dom.duplicateSymbolForAlias()

Availability

Fireworks 3.

Usage

dom.duplicateSymbolForAlias()

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Arguments

None.

Returns

Nothing.

Description

If any symbol instances are selected, this function makes duplicate symbols of all the symbols that are pointed to by those instances. The selected instances are updated to point to the new duplicate copies of the symbols. Duplicate symbols always result in nonlinked duplicates. (The use of the word “alias” in the function name corresponds to an “instance” in a Fireworks document.)

dom.elementsAt()

Availability

Fireworks MX 2004.

Usage

dom.elementsAt(where)

Arguments

where Specifies which rectangle to check for elements. To find the elements under a single point (similar to selecting

with the Subselection tool), set left equal to right and top equal to bottom. To find elements within a rectangle (similar to drag-selecting with the Pointer tool), set the values to the desired rectangle.

Returns

An array of zero of more elements.

Description

Returns a list of zero or more elements at the given location. Similar to selecting with the Subselection tool or dragselecting with the Pointer tool.

dom.enableElementMask()

Availability

Fireworks 4, updated with new arguments in Fireworks MX.

Usage

dom.enableElementMask(enable, selectAndEnterPaintModeIfPossible, {newSelectionMask})

Arguments

enable A Boolean value that toggles the element mask between enabled (true) and disabled (false).

selectAndEnterPaintModeIfPossible A Boolean value that determines the mode for the mask. If

selectAndEnterPaintModeIfPossible is true, and the mask is a bitmap mask, then bitmap mode is entered for

the mask. It is

false by default.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

newSelectionMask An optional bitmap selection mask. If newSelectionMask is not null, and selectAndEnterPaintModeIfPossible is true, the selection will be set on the mask after entering paint mode. This

argument is

null by default.

Returns

Nothing.

Description

Enables or disables the element mask on the selected element. If more than one element (or no elements) are selected when this function is called, Fireworks throws an exception.

dom.enableNineScale()

Availability

Fireworks CS3

Usage

dom.enableNineScale(status)

Arguments

status A Boolean value that toggles 9-slice scaling between enabled and disabled.

Returns

Nothing.

Description

Enables or disables 9-slice scaling for the selected symbol.

Example

The following command enables 9-slice scaling for the selected symbol:

fw.getDocumentDOM().enableNineScale(true);

dom.enableTextAntiAliasing()

Availability

Fireworks MX.

Usage

dom.enableTextAntiAliasing(antiAlias)

Arguments

antiAlias A Boolean value to turn anti-aliasing on (true) or off (false).

Returns

Nothing.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Description

Turns anti-aliasing on or off for the selected blocks of text.

dom.enterPaintMode()

Availability

Fireworks 3, with the argument newSelectionMask added in Fireworks MX.

Usage

dom.enterPaintMode({newSelectionMask})

Arguments

newSelectionMask An optional bitmap selection mask. When newSelectionMask is not null, the selection is set

on the currently selected bitmap after entering paint mode. This argument is null by default.

Returns

Nothing.

Description

Enters image edit mode on the selected items. Has no effect if nothing is selected or if a non-image item is selected.

dom.exitPaintMode()

Availability

Fireworks 3.

Usage

dom.exitPaintMode()

Arguments

None.

Returns

Nothing.

Description

Leaves bitmap mode. Has no effect if Fireworks is not in bitmap mode.

dom.exitSymbolEdit()

Availability

Fireworks 9.

Usage

dom.exitSymbolEdit(level)

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Arguments

level Integer that specifies the number of levels back to exit symbol edit mode, especially when exiting Nested

Symbols.

Returns

Nothing.

Description

Exits the symbol edit mode through the number of levels specified.

dom.exportElements()

Availability

Fireworks 10.

Usage

dom.exportElements(elements, imagesUrl, name)

Arguments

elements An array that contains the objects to be exported.

imagesUrl Folder name to which the image is exported. Specified as file:///.

name Name of the image.

Returns

Nothing.

Description

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

dom.exportOptions.loadColorPalette()

Availability

Fireworks 3.

Usage

dom.exportOptions.loadColorPalette(fileURL)

Arguments

fileURL A string, which is expressed as a file://URL, that specifies the GIF or ACT file that is used to replace the color

panel.

Returns

true if the file is read successfully; false if the file is not the expected format or is not read successfully for any other

reason.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Description

Replaces the values in dom.exportOptions.paletteEntries with those in the specified GIF or ACT file. This function also sets

dom.exportOptions.paletteMode to "custom". For more information, see “ExportOptions

object” on page 260.

dom.exportOptions.saveColorPalette()

Availability

Fireworks 3.

Usage

dom.exportOptions.saveColorPalette(fileURL)

Arguments

fileURL A string, which is expressed as a file://URL, that specifies the name of the file to which the color panel should

be saved. Do not specify a file extension; the .act extension is added automatically.

Returns

Nothing.

Description

Saves the values in dom.exportOptions.paletteEntries to the specified color panel (ACT file). This function does not modify the document. For more information, see

“ExportOptions object” on page 260.

dom.exportTo()

Availability

Fireworks 3.

Usage

dom.exportTo(fileURL, {exportOptions})

Arguments

fileURL A string, which is expressed as a file://URL, that specifies the name of the exported file.

exportOptions An ExportOptions object (see “ExportOptions object” on page 260). This argument is optional. If

this argument is omitted or null, the document’s current Export Options settings are used. If values are passed in with

exportOptions, they are used for this export operation only; they do not change the document’s exportOptions

property.

Returns

true if the file is successfully exported; false otherwise.

Description

Exports the document as specified.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.fillSelectedPixels()

Availability

Fireworks 3.

Usage

dom.fillSelectedPixels(clickPt, p1, p2, p3, bFillSelectionOnly, tolerance, edgemode, featherAmt)

Arguments

clickPt A point that specifies the x,y coordinates of the pixel to be filled or generated (see “Point data type” on

page 9).

p1, p2, and p3 Points that specify the fill-vector. These arguments are ignored if the current fill does not use a fillvector.

bFillSelectionOnly If bFillSelectionOnly is true, the remaining arguments are ignored. If it is false, the

current pixel selection is ignored, and a new one is generated using the values passed for

featherAmt. (This behavior is the same as if the Magic Wand tool were used at the clickPt location.)

tolerance An integer between 0 and 255, inclusive, that specifies the tolerance for selecting pixels.

tolerance, edgemode, and

edgemode Acceptable values are "hard edge", "antialias", and "feather".

featherAmt An integer between 0 and 32,000, inclusive, that specifies the number of pixels to feather. This value is

ignored if the value of

edgemode is not "feather".

Returns

Nothing.

Description

When the selection is an image and Fireworks is in bitmap mode, this method fills the selected pixels with the current fill or generates a new pixel selection.

Example

The following command fills the selection with a hard edge, and the tolerance set to 32:

fw.getDocumentDOM().fillSelectedPixels({x:207, y:199}, {x:207, y:199}, {x:207, y:199}, {x:207, y:199}, false, 32, "hard edge", 0);

dom.filterSelection()

Availability

Fireworks 3.

usage

dom.filterSelection(LiveEffect)

Arguments

LiveEffect An Effect object (see “Effect object” on page 248).

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Returns

Nothing.

Description

Applies the specified pixel filter to the selection. Items that are not images are converted into images before the filter is applied. Only external filters that are capable of also being Live Effects can be applied using this function. To apply other types of external filters, use

dom.filterSelectionByName().

Example

The following command runs the selected pixels through the hue/saturation filter and then sets hue to 30 and saturation to 20:

fw.getDocumentDOM().filterSelection({ EffectMoaID:"{3439b08d-1922-11d3-9bde00e02910d580}", hls_colorize:true, hue_amount:30, lightness_amount:0, saturation_amount:20 });

dom.filterSelectionByID()

Availability

Fireworks 8.

Usage

dom.filterSelectionByID(ID)

Arguments

ID The EffectMoaID of the filter you want applied.

Returns

Nothing.

Description

Applies the specified pixel filter to the selection as a permanent action, not as a Live Effect. (To apply filters that can also be Live Effects, you can use

dom.filterSelection().) This function always displays a dialog box.

dom.filterSelectionByName()

Availability

Fireworks 3.

Usage

dom.filterSelectonByName(category, name)

Arguments

category A string that specifies the category of the pixel filter to be applied. Acceptable values depend on which filters

you have installed.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

name A string that specifies the name of the pixel filter to be applied. Acceptable values depend on which filters you

have installed.

Returns

Nothing.

Description

Applies the specified pixel filter to the selection as a permanent action, not as a Live Effect. (To apply filters that can also be Live Effects, you can use dom.filterSelection().) This function always displays a dialog box.

dom.findNamedElements()

Availability

Fireworks 4.

Usage

dom.findNamedElements(name)

Arguments

name

A case-sensitive string that specifies the exact element name to find. To specify elements that have no name, pass

Returns

An array of elements that have the specified name, or null if no objects have the specified name.

Description

Looks for elements that have the specified name.

See also

dom.setElementName()

dom.flattenDocument()

Availability

Fireworks 3.

Usage

dom.flattenDocument()

Arguments

None.

null

Returns

Nothing.

Description

Flattens the entire document into a single pixel image. This is the same behavior as the Merge Layers command.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.flattenSelection()

Availability

Fireworks 3.

Usage

dom.flattenSelection()

Arguments

None.

Returns

Nothing.

Description

Flattens the selection into a single pixel image. This action is the same behavior as the Merge Images command.

dom.getFontMarkup()

Availability

Fireworks 3.

Usage

dom.getFontMarkup(fontAttribute)

Arguments

fontAttribute Acceptable values for fontAttribute are "size", "color", and "face".

Returns

A string that specifies the markup value. Returns null if the text has multiple attributes or if the selection contains no text.

Description

Gets a font markup attribute for the selected text.

dom.getLockGuides()

Availability

Fireworks 8.

Usage

dom.getLockGuides()

Arguments

None.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Returns

True if the guides are locked; false otherwise.

Description

Determines if the guides are locked.

dom.getPageSetter()

Availability

Fireworks 9.

Usage

dom.getPageSetter()

Arguments

None.

Returns

The PageSetter object which helps in changing pages without refreshing.

Description

Gets the pageSetter object of type SetCurrentPage, with the pageNum, which is a zero-based index of the current page.

dom.getParentLayerNum()

Availability

Fireworks CS3.

Usage

dom.getParentLayerNum(currentLayer)

Arguments

currentLayer A long value that specifies the index of the current layer.

Returns

The layer index number of the parent layer. If the specified layer is a top-level layer, it returns a value of -1.

Description

Gets the parent layer index number for the specified layer.

dom.getPixelMask()

Availability

Fireworks 3, deprecated in 4.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Usage

dom.getPixelMask()

Arguments

None.

Returns

The mask for the current pixel selection. Returns null if Fireworks is not in bitmap mode, or if there is no pixel selection. For information on the format of mask variables, see

“Mask data type” on page 8.

Description

Gets the current pixel-selection mask. The result of this call could be used to call dom.enableElementMask() or

dom.enterPaintMode().

dom.getSelectionBounds()

Availability

Fireworks 3.

Usage

dom.getSelectionBounds()

Arguments

None.

Returns

A rectangle (see “Rectangle data type” on page 9). Returns null if nothing is selected.

Description

Gets the bounding rectangle of the selection.

dom.getShowGrid()

Availability

Fireworks 3.

Usage

dom.getShowGrid()

Arguments

None.

Returns

true if the grid is visible; false otherwise.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Description

Determines whether the grid is visible.

dom.getShowGuides()

Availability

Fireworks 8.

Usage

dom.getShowGuides()

Arguments

None.

Returns

true if the guides are visible; false otherwise.

Description

Determines if the guides are visible.

dom.getShowRulers()

Availability

Fireworks 3.

Usage

dom.getShowRulers()

Arguments

None.

Returns

true if the rulers are visible; false otherwise.

Description

Determines whether the rulers are visible.

dom.getSnapToGuides()

Availability

Fireworks 8.

Usage

dom.getSnapToGuides()

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Arguments

None.

Returns

true if the Snap to Guides function is available; false otherwise.

Description

Determines if the Snap to Guides function is available.

dom.getSnapToGrid()

Availability

Fireworks 3.

Usage

dom.getSnapToGrid()

Arguments

None.

Returns

true if the Snap to Grid function is active; false otherwise.

Description

Determines whether the Snap to Grid function is active.

dom.getTextAlignment()

Availability

Fireworks 3.

Usage

dom.getTextAlignment()

Arguments

None.

Returns

One of the following strings: "left", "center", "right", "justify", "stretch", "vertical left", "vertical

center", "vertical right", "vertical justify", or "vertical stretch". Returns null if the text has multiple

alignments or if the selection contains no text.

Description

Gets the alignment of selected text.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

dom.group()

Availability

Fireworks 3, argument deprecated in 4.

Usage

dom.group({type})

Arguments

type An optional string that specifies how to group the items. Acceptable values are "normal", "mask to image",

"mask to path". If the argument is omitted, "normal" is assumed. In Fireworks 4, "mask to image" and "mask

and

to path"

Returns

Nothing.

Description

Groups the selection. To ungroup elements use dom.ungroup() (see dom.ungroup()).

are deprecated.

Example

The following command sets the selected group to mask to the image:

replace with fw.getDocumentDOM().group("normal");

dom.hasCharacterMarkup()

Availability

Fireworks 3, updated in Fireworks 4.

Usage

dom.hasCharacterMarkup(tag)

Arguments

tag Acceptable values are "b", "i", and "u", for bold, italic, and underline; and "fwplain", which was added in

Fireworks 4, for text without character markup.

Returns

true if the text has the specified character markup; false if it does not or if only part of the text has the markup.

Description

Determines whether the selected text has the specified character markup.

dom.hasMasterPage()

Availability

Fireworks CS3.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Usage

dom.hasMasterPage()

Arguments

None.

Returns

A Boolean value of true if the current document has a master page, or false if there is no master page.

Description

Indicates whether or not a master page exists for the specified document. For example:

fw.getDocumentDOM().hasMasterPage()

dom.hideSelection()

Availability

Fireworks 3.

Usage

dom.hideSelection()

Arguments

None.

Returns

Nothing.

Description

Hides the selection. To redisplay it, use dom.showAllHidden().

dom.importFile()

Availability

Fireworks 3.

Usage

dom.importFile(fileURL, boundingRectangle, bMaintainAspectRatio)

Arguments

fileURL The filename of the file to be imported, which is expressed as a file://URL.

boundingRectangle A rectangle that specifies the size to make the imported file (see “Rectangle data type” on

page 9). If boundingRectangle is specified with left == right and top == bottom, the file is brought in unscaled with its top-left corner at the specified location, and the third argument is ignored.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

bMaintainAspectRatio If bMaintainAspectRatio is true, the file is scaled to the largest size that fits within boundingRectangle while retaining the file’s current aspect ratio. (This is a handy option for creating thumbnails.)

false, the file is scaled to fill boundingRectangle.

If it is

Returns

Nothing.

Description

Imports the specified file at the specified location.

Example

The following command imports the specified file and maintains its aspect ratio:

fw.getDocumentDOM().importFile("file:///C|/images/foo.psd", {left:25, top:50, right:100, bottom:250}, true);

dom.importSymbol()

Availability

Fireworks 3.

Usage

dom.importSymbol(fileURL, bAddToDoc, bAllowUI)

Arguments

fileURL The name of the file to be imported into the library, which is expressed as a file://URL.

bAddToDoc If bAddToDoc is true, the symbol is added to the library and an instance of the symbol is inserted into the

center of the document. If it is

bAllowUI If bAllowUI is true, and fileURL is a Fireworks document that contains symbols, then a dialog box lets the

user specify which symbols to import from the external file. If it is

false, the symbol is added only to the library.

false, all the symbols in the external file are

imported.

Returns

Nothing.

Description

Imports the specified external graphics file (for example, GIF, JPEG, or Fireworks document) into the library of the document.

dom.importSymbolButNotAsAlias()

Availability

Fireworks MX.

Usage

dom.importSymbolButNotAsAlias(filepath, whichSymbol)

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Arguments

filepath The fileURL of the file that contains the symbol to be copied.

whichSymbol The index of the symbol within the document, which is specified in the filepath.

Returns

Nothing.

Description

Extracts the component elements from the selected symbol and places copies of those elements in the document.

This function is similar to the dom.importSymbol API. dom.importSymbol places an instance of a symbol in your document—for example, when you select Edit > Libraries > Buttons, and

dom.importSymbolButNotAsAlias extracts

the component elements from the selected symbol and places copies of those elements in the document.

dom.importSymbolButNotAsAlias does not place in an instance in the document.

dom.inLaunchAndEdit()

Availability

Fireworks MX.

Usage

dom.inLaunchAndEdit()

Arguments

None.

Returns

A Boolean value: true if opened by a launch-and-edit operation; false otherwise.

Description

Specifies whether document was opened by a launch-and-edit operation.

dom.insertPointInPath()

Availability

Fireworks 3.

Usage

dom.insertPointInPath(contourIndex, ptToInsertBefore, tParameter, controlPointFirst, mainPoint, controlPointLast)

Arguments

contourIndex A zero-based index that specifies the contour into which the Bézier point is inserted. For paths with

multiple contours, the contours are in an arbitrary order.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

ptToInsertBefore A zero-based index that specifies where the new point should be placed on the path. The new

point is appended in front of the point that this integer represents: To add a point to the beginning of the path, pass

to add a point to the end of the path, pass a large number.

tParameter A floating-point value between 0 and 1 that specifies where to insert the new point in the Bézier segment.

controlPointFirst, mainPoint, and controlPointLast Points that specify the x,y coordinates of the preceding

control point, the main point, and the following control point of the new point (see

“Point data type” on page 9).

Returns

Nothing.

Description

Inserts a Bézier point in the selected path. This function is similar to dom.appendPointToPath() but includes a

tParameter argument, which lets you control where the point is inserted.

See also

dom.appendPointToPath()

dom.insertSmartShapeAt()

Availability

Fireworks MX 2004.

Usage

dom.insertSmartShapeAt(name, location, useToolBlendModeOpacity)

Arguments

name A string specifying the name of the Auto Shape.

location The upper-left point of the Auto Shape.

useToolBlendModeOpacity Determines whether the new shape object should have the blend mode and opacity

settings set for the Auto Shape Tools (set by the user in the Property inspector), or use standard values. The

bUseToolBlendModeOpacity argument is a Boolean value: true if the shape will use the blend mode and opacity set

for the Auto Shape Tools;

false if the shape will use the standard values (alpha blend mode and 100% opacity).

Returns

Nothing.

Description

Inserts an Auto Shape at the specified location.

dom.insertSymbolAt()

Availability

Fireworks 8.

Last updated 5/17/2012

EXTENDING FIREWORKS

The Document object

Usage

dom.insertSymbolAt(uiName, locationPoint)

Arguments

uiName The name of the symbol in the library. If more than one symbol exists with the specified name, Fireworks

inserts the first symbol named.

locationPoint The center of the symbol expressed as x, y coordinates.

Returns

Nothing.

Description

Inserts a symbol instance at the specified location.

dom.insertText()

Availability

Fireworks 8.

Usage

dom.insertText(text)

Arguments

text The text to insert.

Returns

Nothing.

Description

Inserts the given text into a selected text block at the current text insertion point. If no text is selected it does nothing.

dom.isMasterPageLayer()

Availability

Fireworks CS3.

Usage

dom.isMasterPageLayer(layerNum)

Arguments

layerNum A long value that specifies the layer number.

Returns

A Boolean value: true if the specified layer is a master page layer; false otherwise.

Last updated 5/17/2012

ADOBE Fireworks CS5 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Legal notices

Contents

Chapter 1: Extending Fireworks Overview

Prerequisites

Installing an extension

What’s new in Extending Fireworks CS5

Conventions used in this guide

Additional resources for extension writers

Chapter 2: The Fireworks Object Model

Using the Fireworks Object Model

Accessing a Fireworks document

Passing values

Fireworks Object Model calls and API calls

Formatting nonstandard data types

Color string data type

Mask data type

Matrix data type

Point data type

Rectangle data type

Resolution data type

Using Fireworks API functions

Zero-based indexes

Passing null values

Working with selected elements

Palette or panel

Using the common API

app.toggleFloater()

app.setFloaterVisibility()

app.getRootDirectory()

app.browseDocument()

Working with selected objects

Working with properties for any selected object

elementMask

effectList

Working with specific properties for selected elements

Hotspot

SliceHotspot

Path

Group

Instance

Text

RectanglePrimitive

pathAttributes

Global methods

alert(message)

confirm(message)

prompt(caption, text)

write(arg1, arg2, ..., argN)

WRITE_CSS

WRITE_HTML(arg1, arg2, ..., argN)

fw.setUseAGMRenderingForSelection()

Core objects

Errors object

Files object

File Reference object

Find object

Finding and replacing text

Finding and replacing fonts and styles

Finding and replacing colors, fills, strokes, and effects

Finding and replacing URLs

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

System object

Adobe AIR Extension

AIRext.PreviewDocument()

AIRext.PackageApplication()

AIRext.CreatePackage()

AIRext.CheckCertificatePassword()

AIRext.SaveDigSigPassword()

AIRext.GetDigSigPassword()

AIRext.GetLastErrorLogName()

AIRext.GetAIRInstallPath()

AIRext.GetJREVersion()

AIRext.CreateCertificate()

Chapter 3: The Document object

Document object properties

The pngText property