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. Copyright © 2005 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 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 3 4 Contents 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. 1 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). 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. 2. 3. 4. 5. 6. Download and install the Extension Manager, which is available on the Macromedia Downloads website (www.macromedia.com/software/downloads). Log on to the Macromedia Exchange website (www.macromedia.com/exchange). Click the Fireworks Exchange link. From the available extensions, choose one that you want to use. Click the Download link to download the extension package. Save the extension package in a directory on your machine. 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). 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. 7. 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. 6 Extending Fireworks Overview 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. 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. Lock individual objects within a layer 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. font indicates replaceable items in code. Italic 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. 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. The following naming conventions are used in this guide: Conventions used in this guide 7 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. 8 Extending Fireworks Overview 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: 2 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 Firewor ...