MACROMEDIA DREAMWEAVER MX 2004-EXTENDING DREAMWEAVER User manual

Extending Fireworks

Trademarks

Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver,

Authorware, Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage

Designer, Backstage Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, Contribute, Design in Motion,

Director, Director Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000,

Extreme 3D, Fireworks, Flash, Fontographer, FreeHand, FreeHand Graphics Studio, Generator, Generator Developer's Studio,

Generator Dynamic Graphics Server, Knowledge Objects, Knowledge Stream, Knowledge Track, LikeMinds, Lingo, Live Effects,

MacRecorder Logo and Design, Macromedia, Macromedia Contribute, Macromedia Coursebuilder for Dreamweaver,

Macromedia M Logo & Design, Macromedia Flash, Macromedia Xres, Macromind, Macromind Action, MAGIC, Mediamaker,

Multimedia is the Message, Object Authoring, Power Applets, Priority Access, Roundtrip HTML, Scriptlets, SoundEdit,

ShockRave, Shockmachine, Shockwave, shockwave.com, Shockwave Remote, Shockwave Internet Studio, Showcase, Tools to

Power Your Ideas, Universal Media, Virtuoso, Web Design 101, Whirlwind and Xtra are trademarks of Macromedia, Inc. and

may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs,

titles, words or phrases mentioned within this publication may be trademarks, servicemarks, or tradenames of Macromedia, Inc.

or other entities and may be registered in certain jurisdictions including internationally.

This guide contains links to third-party Web sites that are not under the control of Macromedia, and Macromedia is not

responsible for the content on any linked site. If you access a third-party Web site mentioned in this guide, then you do so at your

own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia

endorses or accepts any responsibility for the content on those third-party sites.

Apple Disclaimer

APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE

ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY

PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES.

THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC

LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO

STATE.

translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of

Macromedia, Inc. Part Number ZFW70M300

Acknowledgments

Project Management: Gary White

Writing: David Jacowitz and Gary White

Editing Management: Rosana Francescato

Editors: Linda Adler, Rosana Francescato, Mary Kraemer, Noreen Maher, Antonio Padial, Lisa Stanziano, Anne Szabla

Production Management: Patrice O'Neill

Multimedia Development: Aaron Begley

Production: Adam Barnett, John Francis, Jeff Harmon

Special thanks to Hiroshi Miyazawa, Brian Edgin, Robbie San Juan, and Andy Finnell

First Edition: September 2003

Macromedia, Inc.

600 Townsend St.

San Francisco, CA 94103

CONTENTS

CHAPTER 1: Extending Fireworks Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Installing an extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

What’s new in Extending Fireworks MX 2004 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Additional resources for extension writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

CHAPTER 2: The Fireworks Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Using the Fireworks Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Global methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Core objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

The Fireworks object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Objects within Fireworks documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

HTML export objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Working with selected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

CHAPTER 3: Cross-Product Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Cross-product architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Flash panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

CHAPTER 4: Auto Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

How Auto Shapes work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Creating an Auto Shape. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

CHAPTER 5: Fireworks JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Using Fireworks API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Document functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Fireworks functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Property inspector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

History panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Using the common API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

4 Contents

CHAPTER 1

Extending Fireworks Overview

To extend Macromedia Fireworks MX 2004, 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 Macromedia applications), and discusses the

JavaScript Auto Shape construction. The final chapter is a reference to the Fireworks JavaScript

application programming interface (API)—the custom JavaScript functions that are built

into Fireworks.

Prerequisites

Because Fireworks extensions must be written in JavaScript, this guide assumes that readers are

familiar with JavaScript syntax and with basic programming concepts such as functions,

arguments, and data types. It also assumes that readers understand the concept of working with

objects and properties. This guide does not attempt to teach programming in general or

JavaScript in particular.

Anyone who wants to extend Fireworks should have a good JavaScript reference to help with

syntax questions (for example, is it substring() or subString()?). Useful JavaScript references

include JavaScript Bible by Danny Goodman (IDG), JavaScript: The Definitive Guide by David

Flanagan (O’Reilly), and Pure JavaScript by R. Allen Wyke, Jason D. Gilliam, and Charlton Ting

(Sams). For a free JavaScript reference, see: http://devedge.netscape.com/library/manuals/2000/

javascript/1.5/reference.

6 Chapter 1: Extending Fireworks Overview

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 Macromedia Exchange website

(www.macromedia.com/exchange). By installing an existing extension, you will become familiar

with some of the tools that you need to work with your own extensions.

To install an extension:

1Download and install the Extension Manager, which is available on the Macromedia

Downloads website (www.macromedia.com/software/downloads).

2Log on to the Macromedia Exchange website (www.macromedia.com/exchange).

3Click the Fireworks Exchange link.

4From the available extensions, select one that you want to use. Click the Download link to

download the extension package.

5Save the extension package in a directory on your machine.

6In Fireworks, choose Commands > Manage Extensions to start the Extension Manager (or,

you can start Extension Manager, located in the Macromedia program group, independently

from Fireworks).

7In the Extension Manager, choose File > Install Extension, and choose the extension package

you just saved.

The Extension Manager automatically installs the extension into Fireworks.

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

Fireworks MX 2004 includes the following new features and interfaces that you can use to

develop extensions for the product:

•Cross-product JavaScript communication

Cross-product JavaScript communication allows any application to control Fireworks by

sending JavaScript instructions directly to Fireworks encoded in XML through a local socket.

Through this connection, Fireworks can do anything that is supported in the Fireworks API.

•Event handling for SWF panels

Third-party command panels developed in Flash for Fireworks (SWF command panels) can

listen and respond to events that happen inside Fireworks MX 2004. So, if you develop a SWF

command panel that creates a specific object for the user (such a spiral pattern), you can also

leverage the new Fireworks event handling so the user can inspect the object and adjust the

object properties.

•Auto Shapes

Along with the new Auto Shapes implementation, the Fireworks M X 2004 API lets you define

an Auto Shape entirely in JavaScript. (For information about working with Auto Shapes in

Fireworks, see Using Fireworks Help.)

Additional resources for extension writers 7

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 Fireworks

Online Forums. The Fireworks Online Forums are available through www.macromedia.com/

support/fireworks/ts/documents/fwnewsgroup.htm.

8 Chapter 1: Extending Fireworks Overview

CHAPTER 2

The Fireworks Object Model

If you want to extend the functionality of Macromedia Fireworks MX 2004 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 makes up the

Fireworks Object Model, containing the following major components:

•Five global methods that are available from any part of the application and need not be

declared as methods of a particular object. These methods are described in “Global methods”

on page 12.

•Four core objects: Document, Errors, Files, and Find. These objects and their properties and

methods are described in detail in “Core objects” on page 12. (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, which is described in “The Fireworks object” on page 22.

•Numerous objects associated with Fireworks documents, such as ExportOptions, Guides, Path,

Image, and Text. These objects and their properties are described in “Objects within Fireworks

documents” on page 26.

•A set of objects that you can use to specify the format of HTML code when exporting from

Fireworks. These are described in “HTML export objects” on page 64.

Using the Fireworks Object Model

When scripting extensions for Fireworks, you write JavaScript commands that send calls to the

Fireworks Object Model to determine or change the current settings for a Fireworks document.

For example, the following command calls the Fireworks object (fw) to obtain the path to the

Export Settings directory (appExportSettingsDir), which is expressed as a file://URL. In other

words, fw references the Fireworks global object, of which appExportSettingsDir is a property

(see “The Fireworks object” on page 22), so a JavaScript command can assign the resulting value

to a variable, as follows:

var expSetDir = fw.appExportSettingsDir;

10 Chapter 2: The Fireworks Object Model

Accessing a Fireworks document

All the functions listed in “Document functions” on page 104 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.

Note: You can use methods that operate on a document’s DOM only on open documents.

•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(), see fw.getDocumentDOM().

Passing values

For all properties that are not read-only, you can pass values to change elements of a document.

For example, the following command sets the fifth brush in the third open document to a

square shape:

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

The preceding example includes the following properties:

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

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

•shape is a property of the Brush object.

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

Fireworks Object Model calls and API calls

In some cases, you can use Fireworks Object Model calls or API calls to perform the same

operations. In other cases, a certain function might be available in either the Fireworks Object

Model or the API, but not in both.

For example, if the first open document is the current document, the first code fragment has the

same effect as the second and third code fragments. The fw.getDocumentDOM() function

references the current document (see “Accessing a Fireworks document” on page 10).

fw.getDocumentDOM().setDocumentResolution({pixelsPerUnit:72, units:"inch"});

fw.documents[0].resolution =72;

fw.documents[0].resolutionUnits ="inch";

Other manuals for DREAMWEAVER MX 2004-EXTENDING DREAMWEAVER

This manual suits for next models

Table of contents

Other MACROMEDIA Software manuals

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-USING DIRECTOR Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION STUDIO 5-USING COLDFUSION 5... Mounting instructions

MACROMEDIA

MACROMEDIA FLEX-FLEX ACTIONSCRIPT LANGUAGE Service manual

MACROMEDIA

MACROMEDIA FLASH MEDIA SERVER 2-SERVER-SIDE ACTIONSCRIPT... Service manual

MACROMEDIA

MACROMEDIA DREAMWEAVER 8 User manual

MACROMEDIA

MACROMEDIA BREEZE PRESENTER User manual

MACROMEDIA

MACROMEDIA FLASH 8-FLASH Service manual

MACROMEDIA

MACROMEDIA FLASH 8-FLASH Service manual

MACROMEDIA

MACROMEDIA FLASH 8-LEARNING ACTIONSCRIPT 2.0 IN FLASH User manual

MACROMEDIA

MACROMEDIA BREEZE-MANAGING EXTERNAL BREEZE REPORTS User manual

MACROMEDIA

MACROMEDIA FLASH 8-ACTIONSCRIPT 2.0 LANGUAGE Service manual

MACROMEDIA

MACROMEDIA FLEX-FLEX BUILDER Operation instructions

MACROMEDIA

MACROMEDIA CONTRIBUTE 3 - USING AND ADMINISTERING... Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION 4.5-ADMINISTRING COLDFUSION... User manual

MACROMEDIA

MACROMEDIA FLASH 8-COMPONENTS LANGUAGE Service manual

MACROMEDIA

MACROMEDIA FIREWORKS 2-USING FIREWORKS Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION 4.5- TO CFML User manual

MACROMEDIA

MACROMEDIA FLASH MX 2004 - ACTIONSCRIPT User manual

MACROMEDIA

MACROMEDIA BREEZE User manual

MACROMEDIA

MACROMEDIA FLASH MEDIA SERVER 2-INSTALLING FLASH MEDIA SERVER... User manual

MACROMEDIA

MACROMEDIA COLDFUSION MX 61 - CONFIGURING AND ADMINISTERING COLDFUSION... User manual

MACROMEDIA

MACROMEDIA FLEX-GETTING STARTED WITH FLEX User manual

MACROMEDIA

MACROMEDIA FLASH 8-GETTING STARTED WITH FLASH User manual

MACROMEDIA

MACROMEDIA CONTRIBUTE 3 - DEPLOYING AND PUBLISHING... User manual

Popular Software manuals by other brands

COMPRO

COMPRO COMPROFM manual

Muratec

Muratec OFFICEBRIDGE ONLINE user guide

Oracle

Oracle Contact Center Anywhere 8.1 installation guide

Adobe

Adobe 65007312 - Photoshop Lightroom Programmer's guide

Avaya

Avaya NULL One-X for RIM Blackberry user guide

HP ProLiant BL420c user guide

PS Audio

PS Audio PowerPlay Programming manual

Brady

Brady LOCKOUT PRO 3.0 Administrator's guide

Avaya

Avaya Interaction Center user guide

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Guide book

Novell

Novell GROUPWISE 8 - INTERNET AGENT manual

Oracle

Oracle Application 9i Configuration guide

Acer

Acer RDM user guide

Canon

Canon Vixia HF21 instruction manual

Canon

Canon ZR950 instruction manual

Samsung

Samsung Auto Backup user manual

Polycom

Polycom Vortex EF2201 Application note

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c user manual