MACROMEDIA FIREWORKS 8-EXTENDING FIREWORKS User manual

Extending Fireworks

Trademarks

1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central,

ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite,

FlashPaper, Flash Video Encoder, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder,

Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit,

Studio MX, UltraDev, and WebHelp are either registered trademarks or 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, service marks, or trade names of Macromedia, Inc. or other entities and

may be registered in certain jurisdictions including internationally.

Third-Party Information

This guide contains links to third-party websites 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 website 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.

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

Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which

this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole

purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be

printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation,

commercial purposes, such as selling copies of this documentation or providing paid-for support services.

Acknowledgments

Project Management: Debi Robson, Charles Nadeau

Writing: David Sullivan

Editing Management: Rosana Francescato

Editors: Melba Lancaster, Mary Kraemer

Production Management: Patrice O'Neill

Production: John Francis, Adam Barnett, Mario Reynoso, Geeta Karmarkar

Special thanks to Peter Moody, Mike Thrall, David Spells, Alan Musselman, Sheila McGinn, Andrew Wilson, and

Maureen Keating.

First Edition: September 2005

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

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

Additional resources for extension writers . . . . . . . . . . . . . . . . . . . . . . . . . 8

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

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

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

Core objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

The Fireworks object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Objects within Fireworks documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

HTML export objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Working with selected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Chapter 3: Cross-Product Extensions . . . . . . . . . . . . . . . . . . . . . 99

Cross-product architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Flash panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 4: Auto Shapes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

How Auto Shapes work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

Creating an Auto Shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

Chapter 5: Fireworks JavaScript API. . . . . . . . . . . . . . . . . . . . . . 131

Using Fireworks API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Document functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132

Fireworks functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Property inspector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

History panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Static Document Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Using the common API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

4Contents

CHAPTER 1

Extending Fireworks

Overview

To extend Macromedia Fireworks 8, 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).

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

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

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

2. Log on to the Macromedia Exchange website (www.macromedia.com/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 Macromedia 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.

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 8

Fireworks 8 includes the following new features and interfaces that you can use to develop

extensions for the product:

Marquee-to-path and path-to-marquee conversions In Fireworks 8 you can convert

marquees drawn with any of the marquee tools to a vector path. You can also convert any

vector path to a marquee and set its edge to hard, anti-aliased, or feathered.

Conventions used in this guide 7

Vector path compatibility with Macromedia FreeHand Although Fireworks 8 imports

winding fills from FreeHand MX, it does not provide a user interface that lets you create a

winding fill. However, Fireworks 8 has APIs that let third-party developers create an interface

where a user can specify if a path uses an even/odd or winding fill.

Lock individual objects within a layer Instead of having to create a new layer specifically

for an object you want to lock, Fireworks 8 lets you lock specific objects on a layer without

locking the other objects on the same layer. Three new APIs let you specify which object to

lock.

New panels and commands Fireworks 8 introduces three new panels and a new

command. Several new APIs let you set selections within these panels and access the new

command.

Access dialog boxes Fireworks 8 introduces a new Dialogs class as a property of the

Fireworks object. The APIs in this class let you run standard application dialog boxes that are

usually accessible only through the menu.

Get system information The new System class in Fireworks 8 provides APIs that let you

query for information about the operating system.

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.

8 Extending Fireworks Overview

Additional resources for extension writers

To communicate with other developers who are writing extensions, you can visit the

Fireworks online forums at www.macromedia.com/go/13012.

CHAPTER 2

The Fireworks Object Model

If you want to extend the functionality of Macromedia Fireworks 8 by writing or modifying a

JavaScript extensibility file, you must become familiar with the objects that Fireworks makes

available through JavaScript. The hierarchy of these objects comprises the Fireworks Object

Model, which contains the following major components:

■Six global methods that are available from any part of the application and need not be

declared as methods of a particular object. For more information, see “Global methods”

on page 12.

■Six core objects: Dialogs, Document, Errors, Files, Find, and System. For more

information, see “Core objects” on page 13. (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 26).

■Numerous objects associated with Fireworks documents, such as ExportOptions, Guides,

Path, Image, and Text. For more information, see “Objects within Fireworks documents”

on page 32.

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

Using the Fireworks Object Model

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

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

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

path to the Export Settings directory (appExportSettingsDir), which is expressed as a file:/

/URL. In other words, fw references the Fireworks global object, of which

appExportSettingsDir is a property (for more information, see “The Fireworks object”

on page 26), so a JavaScript command can assign the resulting value to a variable, as follows:

var expSetDir = fw.appExportSettingsDir;

10 The Fireworks Object Model

Accessing a Fireworks document

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

■To use a DOM function with a document other than the active document, use the

following syntax; note that documentIndex is a zero-based index that specifies which

document the command will affect.

fw.documents[documentIndex].functionName();

■To use a DOM function with the active document, use

fw.getDocumentDOM().functionName() (for more information, see

fw.getDocumentDOM()).

Passing values

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

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

document to a square shape:

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.

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.

NOTE

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

NOTE

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

This manual suits for next models

Table of contents

Other MACROMEDIA Software manuals

MACROMEDIA

MACROMEDIA FLEX-FLEX BUILDER Operation instructions

MACROMEDIA

MACROMEDIA FIREWORKS 8-USING FIREWORKS Mounting instructions

MACROMEDIA

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

MACROMEDIA

MACROMEDIA CONTRIBUTE 3-CONTRIBUTE PUBLISHING SERVER User manual

MACROMEDIA

MACROMEDIA BREEZE 5 Quick setup guide

MACROMEDIA

MACROMEDIA COLDFUSION 4.5-DEVELOPING WEB User manual

MACROMEDIA

MACROMEDIA FLASH 8-LEARNING ACTIONSCRIPT 2.0 IN FLASH User manual

MACROMEDIA

MACROMEDIA COLDFUSION 5-CFML Service manual

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-GETTING STARTED WITH... User manual

MACROMEDIA

MACROMEDIA DRUMBEAT 2000 ECOMMERCE EDITION User manual

MACROMEDIA

MACROMEDIA COLDFUSION 4.5- TO CFML User manual

MACROMEDIA

MACROMEDIA FIREWORKS 2-USING FIREWORKS Mounting instructions

MACROMEDIA

MACROMEDIA FLASH MX 2004-DATA Operation instructions

MACROMEDIA

MACROMEDIA COLFUSION MX 7 - INSTALLING AND USING COLDFUSION... User manual

MACROMEDIA

MACROMEDIA FLASH 8-GETTING STARTED WITH FLASH User manual

MACROMEDIA

MACROMEDIA COLDFUSION 4.5-CFML LANGUAGE Service manual

MACROMEDIA

MACROMEDIA CONTRIBUTE User manual

MACROMEDIA

MACROMEDIA FLASH MX 2004-FLASH JAVASCRIPT DICTIONARY User manual

MACROMEDIA

MACROMEDIA FLASH 8-INTRODUCTION TO FLASH LITE 2.X... Reference manual

MACROMEDIA

MACROMEDIA BREEZE 5 User manual

MACROMEDIA

MACROMEDIA FLASH MX 2004 - ACTIONSCRIPT User manual

MACROMEDIA

MACROMEDIA DIRECTOR MX-LINGO DICTIONARY User manual

MACROMEDIA

MACROMEDIA FIREWORKS 2-USING FIREWORKS Mounting instructions

MACROMEDIA

MACROMEDIA FLASH 8-COMPONENTS LANGUAGE Service 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