Adobe Illustrator CS4 Software Development Kit ReadMe File ______________________________________________________________________ This file contains the latest information about the Adobe Illustrator SDK. This information applies to Illustrator CS4 (14.0). The SDK enables you to develop software modules that plug into and extend the functionality of Illustrator CS4. ______________________________________________________________________ This file has the following sections: 1. Legal 2. SDK Documentation 3. Development Environments 4. Installing the SDK 5. What's New 6. Known Issues 7. SDK Support and Adobe Partner Programs *********************************************************** 1. Legal *********************************************************** You may use this SDK only in a manner consistent with the included End User License Agreement: /legalnotices/EULAs.pdf *********************************************************** 2. SDK Documentation *********************************************************** Adobe Illustrator CS4 Getting Started Guide File: /docs/guides/getting-started-guide.pdf Describes the basics of how to get started developing plug-ins for Illustrator CS4 and provides descriptions of the sample plug-ins provided with this SDK. Adobe Illustrator CS4 Porting Guide File: /docs/guides/porting-guide.pdf Describes how to set up your development environment and port existing code to Illustrator CS4. Details changes in the public API and other aspects of the SDK since the prior release. Adobe Illustrator CS4 Programmer's Guide File: /docs/guides/programmers-guide.pdf Describes the fundamentals of writing plug-ins for Illustrator. Adobe Dialog Manager Programmer's Guide File: /docs/guides/adm-guide.pdf Describes the concepts involved in programming the cross-platform user-interface toolkit used in Illustrator. Using the Adobe Text Engine File: /docs/guides/using-adobe-text-engine.pdf Describes the components of the Illustrator Adobe Text Engine API, and provides recipes for creating, editing, deleting, styling and iterating text items in a document, with references to sample code and the Adobe Illustrator API Reference. Adobe Illustrator API Reference Reference documentation for the API can be found in the files below. File: /docs/references/index.chm API reference in compiled HTML format. This searchable help file contains reference documentation for the API. To view the contents on Windows, double-click the index.chm file icon in Windows Explorer, to open the home page. To view the contents on a Macintosh, you need a CMH viewer (for options, see "Adobe Illustrator CS4 Porting Guide"). File: /docs/references/sdkdocs.tar.gz API reference in archive HTML format. This archive contains reference documentation for the API. After installing the SDK, double-click the sdkdocs.tar.gz file to decompress the archive. View the HTML documentation in your browser. API Advisor: File: /docs/references/apiadvisor-ai13-vs-ai14.html Reports class, struct, and file differences between the API included with the Illustrator CS3 SDK and this SDK. *********************************************************** 3. Development Environments *********************************************************** The following platforms are supported for the development of plug-ins for Illustrator CS4: Macintosh: OS: Mac OS 10.4 IDE: Xcode 2.4.1 Windows: OS: Microsoft Windows XP with service pack 2 IDE: Microsoft Visual C++ 2005 For details, see "Adobe Illustrator CS4 Porting Guide." *********************************************************** 4. Installing the SDK *********************************************************** To install the SDK, download the pre-configured archive for your platform from the Adobe Illustrator Developers site: http://www.adobe.com/devnet/illustrator/ Start by expanding the archive, then follow the detailed instructions in "Getting Started with Adobe Illustrator CS4 Development" to set up your development platform. *********************************************************** 5. What's New *********************************************************** - New APIs: Annotation Drawing (see AIAnnotatorDrawerSuite), Crop Area Range (see AICropAreaRangeSuite) FXG File Format (see AIFXGFileFormatSuite) - API changes: See "Adobe Illustrator CS4 Porting Guide" and "API Advisor." - AIFilterSuite deprecated The AIFilterSuite is deprecated as of CS4. Support for filters will remain for the near future; however, we recommend you replace filters with live effects (see AILiveEffectSuite). The Filter menu item also was removed from the user interface, and any filters added are now in the Objects > Filters menu. - Sample code changes: - Annotator plug-in added This plug-in uses the AIAnnotatorSuite and AIAnnotatorDrawerSuite to add annotations to art items when the Annotator tool is selected. The sample demonstrates how to add an annotator and update the annotations on change of selection and movement of the cursor. - SnippetRunner Code Snippets Several code snippets were added to the SnippetRunner project. New content includes snippets for Artboards, Gradients, Patterns, Graphic Styles, and the new FXG file format. There also are new categories: Data Utility Snippets (contains Dictionary snippet) and XML snippet. - C++ recommended framework The recommended framework to use when developing Illustrator CS4 plug-ins is the C++ based framework, now used in all sample plug-ins except Shell. - Shell plug-in legacy The Shell sample plug-in is now legacy and will be removed from future versions of the Illustrator SDK. Common files used by this plug-in were moved to legacy folders. - EVE dialog used by MarkedObjects sample The MarkedObjects sample now uses EVE-based (Express View Engine) cross-platform layout definitions for the preferences dialog. - Binary resources removed The binary .rsrc resource files were removed from the CS4 SDK and replaced by .r files, which provide the required resource definitions in source format. *********************************************************** 6. Known Issues *********************************************************** On Mac OS, if you use StuffIt Expander to decompress the /docs/references/sdkdocs.tar.gz file, older versions may truncate filenames at 31 characters, thus breaking HTML links. Workaround: Decompress the archive: 1. Open a Terminal shell window, and type the following: cd /docs/references tar -xzf sdkdocs.tar.gz 2. After you are done decompressing, open the index.html file to see the documentation. ______________________________________________________________________ On Vista, if opening the /docs/references/index.chm file causes a security warning and once opened none of the pages can be viewed. Workaround: Open the document as follows: 1. Extract the SDK. 2. Open /docs/references/index.chm 3. Uncheck "Always ask before opening this file" in the security warning dialog. 4. Select Open. ______________________________________________________________________ On Intel-based Macintosh hardware, the Xcode debugger may fail to step over certain Illustrator API calls in your plug-in (1510374). There are situations where the frame pointer gets hijacked for other purposes and the Xcode debugger gets confused. Symbol stripping the release build of Illustrator contributes to this problem but is not the root cause. If you have problems stepping through your plug-in code in the Xcode debugger, first make sure you are using the supported version of Xcode. If you are stepping over an Illustrator API call and you see the message "Previous frame inner to this frame (corrupt stack?)", try one of the following workarounds: 1. Use the Xcode debugger’s Continue button to resume execution. 2. Use the Xcode debugger "Continue to Here" command to run to a subsequent line of code. The "Continue to Here" command is available by right-clicking the left of the code-editor pane in the Xcode debugger window. 3. Step using gdb instead of the "Step Over" button. Use Xcode’s Debug > Console Log menu to open the debugger console, and type "step" at the prompt. 4. Debug on a PowerPC-based Macintosh platform. ______________________________________________________________________ In the API Reference, there are some incorrect/misleading descriptions: 1. AISwatchGroupSuite::RemoveSwatchGroup/RemoveNthSwatchGroup. When deleting spot colors, if it is the last reference to a particular spot color used in the document, the spot color is moved to the general swatch group. Even if deleteSwatches is true, its equivalent process color is not created like the documentation says. Only AISwatchGroupSuite::RemoveSwatch with deleteCustomColor set to true will delete the last reference to a used spot color. (1569455) 2. AISwatchLibrariesSuite::SelectNthDocumentSwatchIfVisible is not fully implemented and should not be used. (1560539) 3. AIRasterSuite::ExtractOutline, this APIs documentation needs extra clarification with regard to the AIRasterOutlineParams parameter and how to reduce the impact on performance that may occur if an excessive number of paths is produced in the outline path. The following are the valid ranges of the AIRasterOutlineParams struct members: noiseFilterDegree >= 0 and <= 5 cornerAngleTolerance => -1 and <= 1 smoothnessTolerance >= 0 and <= 100 fidelityTolerance > 0 A possible way to reduce the performance impact should be to increase the smoothness and fidelity tolerance, but it is best to experiment to find optimal settings. 4. kAINewDocumentAction parameters, the descriptions for the following parameters in kAINewDocumentAction should be: kAINewDocumentSettingsFileKey - String containing the path to the new document profile file to use. These files are found in the following folders: kAIUserWritableStartupFileFolderType and kAIRequiredStartupProfilesFolderType (UnicodeString) kAINewDocumentRasterResolutionKey - The document raster resolution in PPI (integer value of 72, 150 or 300). kAINewDocumentPreviewModeKey - A bitmask with one of the following values: 0x020 (for kAIPreviewModeDefault) 0x040 (for kAIPreviewModePixelPreview) 0x100 (for kAIPreviewModeOverprintPreview) 5. ADMCustomDialogProcs. The references to ADMReloadSelector in the description for this struct are missing the "k"; they should refer to kADMReloadSelector. ______________________________________________________________________ AIActionManagerSuite::PlayActionEvent does not update document context within current plug-in call: (1348729) When creating a new document through the plug-in API, that new document should be the context under which future operations run. AIDocumentSuite::New works correctly, but using AIActionManagerSuite::PlayActionEvent with kAINewDocumentAction does not. This problem also occurs with other actions such as kAIOpenDocumentAction and kAICloseDocumentAction. Possible workarounds: 1. Use provided suite functions and not the action if possible; for instance, use the AIDocumentSuite and AIDocumentList suite to perform new, open and close operations on a document. 2. Use a timer and callback function to return control to Illustrator after performing an action using the AIActionManagerSuite. ______________________________________________________________________ In the APIAdvisor, there is some incorrect/misleading information: ADMVersion.h is listed in the Obsolete files section of the APIAdvisor; however, this file is not obsolete. There is a bug encountered during the generation of the CS4 API snapshot, and this header file is not being read, causing the file to appear to have been removed. *********************************************************** 7. SDK Support and Adobe Partner Programs *********************************************************** If you require SDK support for the Illustrator CS4 SDK, you may purchase single or multi-pack SDK support cases. Information on purchasing SDK support cases can be found at: http://partners.adobe.com/public/developer/support/index.html Information on Adobe support, in general, may be found at: http://www.adobe.com/support/programs/ If you are a partner who extends, markets, or sells Adobe products or solutions, you should consider membership in the Adobe Partner Connection Solution Partner Program. The Solution Partner Program provides development support, access to timely product information, as well as various marketing benefits. To learn more about the program, point your browser to: http://go.adobe.com/kb/cs_cpsid_50036_en-us _____________________________________________________________________________ Copyright 2008 Adobe Systems Incorporated. All rights reserved. Adobe and Illustrator are registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Windows is a registered trademark or trademark of Microsoft Corporation in the United States and/or other countries. Macintosh is a trademark of Apple Computer, Incorporated, registered in the United States and other countries. All other brand and product names are trademarks or registered trademarks of their respective holders. _____________________________________________________________________________