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. Copyright © 2003 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, 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 103 104 241 275 278 283 Using Fireworks API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fireworks functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Property inspector functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . History panel functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the common API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 3 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. 5 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, select 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 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.) · · 6 Chapter 1: 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 Fireworks Online Forums. The Fireworks Online Forums are available through www.macromedia.com/ support/fireworks/ts/documents/fwnewsgroup.htm. Additional resources for extension writers 7 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 Firewor ...