ADOBE® ILLUSTRATOR® CS5

ADOBE ILLUSTRATOR CS5 PORTING GUIDE

© 2010 Adobe Systems Incorporated. All rights reserved.

Adobe Illustrator CS5 Porting Guide Technical Note #10500 If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization. Adobe, the Adobe logo, and Illustrator are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Apple, Mac OS, and Macintosh are trademarks of Apple Computer, Incorporated, registered in the United States and other countries. All other trademarks are the property of their respective owners. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.

Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 SDK organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Changes in this release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ruler origin change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adobe Dialog Manager deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Plug-in framework updated in samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5 5 6 6 6

New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Stroke enhancement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Multiple artboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Perspective grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Transparent gradient mesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Text features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Symbol enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Drawing modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Pixel Perfect drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Flash interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Illustrator API changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 New AIBeautifulStrokesSuite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 New AIPerspectiveGridSuite and AIPerspectiveTransformSuite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Update of FXGFileFormatSuite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 API changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

SDK Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Outdated plug-in samples removed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 New StrokeFilter sample plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 New FreeGrid sample plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Porting Windows plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3

Adobe Illustrator CS5 Porting Guide This document describes how to update your SDK plug-in code and development environments for Adobe® Illustrator® CS5. It details changes in the public API and other aspects of the SDK since the CS4 release.

Introduction Download the Illustrator CS5 SDK from http://www.adobe.com/devnet/illustrator/, along with installation instructions and documentation. This release supports these platforms for Illustrator plug-in development. Platform

Component

Note

Windows

Windows XP Service Pack 2 or higher Illustrator CS5

Mac OS®

Visual Studio 2008 SP1 Visual C++ 9

Developing Illustrator CS5 plug-ins in Windows requires VC++ 9.0, a component of Visual Studio 2008. If you have the Professional or Standard Editions of Visual Studio 2008, you must install the Visual C++ components.

Mac OS 10.5 or higher

Mac OS 10.3 and earlier are not supported. Mac OS 10.4 will not be supported after this release.

Illustrator CS5 Xcode 3.1.1

Xcode can be downloaded from http://developer.apple.com/tools/download/

4

Adobe Illustrator CS5 Porting Guide

Introduction

5

SDK organization The SDK contains these folders and files (locations are relative to the download location, ): Documentation, including:

docs/

X

Adobe Illustrator CS5 Programmer’s Guide (guides/programmers-guide.pdf)

X

Porting Guide (this document)

X

Getting Started with Illustrator CS5 Development (guides/getting-started-guide.pdf )

X

Using the Adobe Text Engine (guides/using-adobe-text-engine.pdf )

X

API Reference This document is provided in two formats: Z

references/index.chm — This compiled HTML file allows text

searches to be performed on the content. See the Getting Started with Illustrator CS5 Development for details. Z

references/sdkdocs.tar.gz — This file contains the API

Reference in HTML format. To view the contents, decompress the archive, then open index.html in your browser. X

API Advisor (references/apiadvisor-ai14-vs-ai15.html)

legalnotices/

Licenses.

illustratorapi

The Illustrator API header files.

samplecode/

A set of samples for learning about the API. See “SDK Changes” on page 11.

Changes in this release Development environment X

X

In Windows Z

For development in Windows, this release requires VC++ 9.0 (Visual Studio 2008, Service Pack 1)

Z

Illustrator defines SECURE_SCL=0 for Release, and SECURE_SCL=1 for Debug. We recommend that developers do the same.

In Mac OS Z

Illustrator uses the Apple 10.5 SDK. You must remove any API functions that are not supported by that version.

Z

Beginning with the next release, Illustrator will no longer support Mac OS 10.4 or PPC processors.

Adobe Illustrator CS5 Porting Guide

Introduction

6

Ruler origin change In previous releases, the artboard origin, the position with coordinates (0,0), was in the bottom left corner, with positive X increments going left to right, and positive Y increments going bottom to top. In Illustrator CS5, the artboard origin is defined to be the top left corner of the artboard. Positive X increments still go left to right, but positive Y increments now go top to bottom. To show rulers, choose View > Rulers > Show Rulers. Use the Info panel (Windows > Info) to inspect the X/Y coordinates of a position.

Adobe Dialog Manager deprecated Adobe Dialog Manager (ADM) is the UI framework that has been used for the Illustrator UI, and has been available to plug-ins built with the SDK since Illustrator 7.0. ADM has been deprecated in this release, and will not be supported in future releases. The ADM sample plug-in has been removed from the SDK. If you have any existing plug-ins that use ADM, they will still run in this release, but will not run in future releases. You should remove any usage of ADM from your plug-ins and replace it with another UI framework of your choice. You can use any 3rd-party or platform-specific UI framework, or one of the UI frameworks provided by Adobe, such as Flash®/Flex®-based controls. Adobe can provide support only for Adobe products.

Plug-in framework updated in samples In previous releases, you could use either a C-style or C++-style framework for plug-ins. This release does not support the C-style framework. The Shell plug-in was the only sample that used the C-style framework; it is no longer supported, and the sample code for it has been removed. The common files that were used only by the Shell plug-in have been removed from this release. In the CS5 SDK, all sample plug-ins use the C++ framework with one exception. The Tutorial plug-in does not use any framework. It is designed to help new users of the SDK understand the basic elements of an Illustrator plug-in without the added complications of implementing a framework. All other samples now use the supported C++-style plug-in framework, in which the Plugin class constructs the basic requirements for an Illustrator plug-in, using the Suites class to acquire and release the required suites. For Windows developers: In the CS4 SDK, the sample plug-ins were developed in Visual Studio 2005 (VC++ 8.0). In this release, they were developed in Visual Studio 2008 (VC++ 9.0). If you have any projects from the previous release, you must convert them to use them with this release. See “Porting Windows plug-ins” on page 12.

Adobe Illustrator CS5 Porting Guide

New features

7

New features This section describes new features that have been added to Adobe Illustrator CS5.

Stroke enhancement This release improves and extends the stroking model for Illustrator, adding the following functionality for strokes: X

Gradients along and across strokes

X

No folding on tight corners for art brushes

X

Variable stroke width (pressure-sensitive art and pattern brushes)

X

New end cap types and miter behavior

X

Line joins at arbitrary intersections

X

Improved arrowheads

X

New dashing options

Some of these features are made available to programmers through the new AIBeautifulStrokesSuite.

Multiple artboards This release add these capabilities to enhance the use of multiple artboards: X

Re-order multiple artboards, insert new artboards into an existing set, and adjust artboard positions and spacing.

X

Interoperability of artboard rulers and coordinates with document rulers and coordinates, to make it easier to apply transformations to artboards.

X

Artboard naming.

X

Automatic mapping of pages to artboards when opening a PDF file in Illustrator.

X

Automatic resizing of artboard guides when an artboard is resized.

X

Independent bleed settings for artboards.

These features are supported by the new AIArtboardSuite and new classes ai::ArtboardList and ai::ArtboardProperties.

Perspective grid This release adds the ability to define and manipulate perspective grids. You can define and modify the positions of vanishing points, horizon lines, cell sizes, plane extent and color, and so on. Some preset grid parameters are supplied for 1-, 2-, and 3-point perspective. Some of the new functionality is made available to programmers through the new AIPerspectiveGridSuite and AIPerspectiveTransformSuite.

Adobe Illustrator CS5 Porting Guide

New features

8

You can: X

Define and modify the scale to be used on the grid (such as 1 cell = 1 foot). Rulers allow accurate measurement on the grid plane. You can show or hide, and lock or unlock the grid.

X

Draw primitive shapes directly on the grid active plane; vanishing is automatically applied, and shown in preview while drawing. The object dimensions and positions are shown.

X

Place an existing object into perspective by placing in onto the active plane.

X

Use modifier keys to change the active perspective plane while drawing.

X

Snap to grid lines.

X

Expand objects with or without perspective, and perform simple transform operations such as move and scale on objects that are in perspective.

X

Print the perspective grid.

X

Create 3D primitives with perspective, extrude 3D vector shapes in perspective, and perform 3D rotation of vector objects.

X

Rotate and tilt the grid.

X

Generate guides at any arbitrary location, Smart Guides for alignment, and constrain movements to certain planes while moving objects.

Transparent gradient mesh Gradient Mesh objects now have an opacity attribute that controls their degree of transparency. The opacity at each node is blended along with the color information. When you open an object created in an earlier version that does not contain opacity information, it is treated as 100% opaque. This feature is supported by new functions AIMeshSuite::EvalOpacity() and AIMeshVertexIteratorSuite::Get/SetOpacity().

Text features X

Higher fidelity when converting live-type text to outlines, supported by new functions in ATE::CharFeaturesSuite and ATE::CharInspectorSuite: Get/SetFillBackgroundColor Get/SetFillBackground ClearFillBackgroundColor ClearFillBackground

Symbol enhancements This release has added this behavior to symbols: X

Guides created inside symbols are now shown both in isolation mode and in normal mode.

X

You can generate smart guides and snap symbol contents to other objects, both in isolation mode and normal mode.

Adobe Illustrator CS5 Porting Guide

New features

X

Symbol selection now behaves like group selection.

X

The Flash Registration point, which was previously used only to provide a value to Flash when exporting, is now used in the same way Flash uses it, to provide a default location from which a symbol's X and Y co-ordinates are determined

X

You can create sub-layers inside symbols.

X

9-slice scaling, which was previously used only to provide a value to Flash when exporting, is now used in the same way Flash uses it, to ensure that the symbol looks correct when scaled.

9

These features are supported by the new AISymbolSuite .

Drawing modes This release has added two new drawing modes, for drawing behind and inside objects. The two new modes, DrawBehind and Draw Inside, and available on the toolbar, in addition to the default Draw Normal mode. Both of these modes depend on the current selection; if nothing else is selected when you begin drawing, the behavior is no different from the default. X

In Draw Behind mode, when you select one or more objects and start drawing, the new object is placed below the lowest selected object in the Z-order list.

X

In Draw Inside mode, any new objects you draw are placed inside the selected object. The new objects are clipped at the edges of the containing object.

This feature is supported by new functions in AIArtSuite: Get/SetDrawingMode() GetInsertionPointForDrawingMode() GetInsertionPointForCurrentDrawingMode()

Pixel Perfect drawing This release provides new tools for polishing drawings before exporting them for use in Web workflows. The new tools: X

Make it easier to draw on pixels. This feature is supported by new functions in AIArtSuite: IsPixelPerfect() SetPixelPerfect()

X

Allow greater control over anti-aliasing with new functions AITextFrameSuite: Get/SetTextAntialias()

X

Enable you to set up a web workspace in Illustrator.

X

Improve interactivity with various workflows, such as PDF, Flash, and Flex.

X

Streamline the process of exporting slices.

Adobe Illustrator CS5 Porting Guide

Illustrator API changes

10

Flash interoperability In this release, you can save artwork generated in Illustrator in FXG format, and load FXG-format files directly into Illustrator. You can open an FXG file in Illustrator using the File > Open menu. In Flash Catalyst, you can import an FXG file saved from Illustrator. This feature is supported by the new AIFXGFileFormatSuite.

Illustrator API changes This section summarizes the important changes to the API since the prior release. A detailed change list is provided with the SDK, in the API Advisor page, apiadvisor-ai14-vs-ai15.html.

New AIBeautifulStrokesSuite A new suite, AIBeautifulStrokesSuite, consolidates a number of improvement to stroking. The new Beautiful Strokes functionality: X

Improves the ability to apply arrowheads.

X

Enhances miter-ends behavior, changing the default miter limit from 4 to 10.

X

Provides variable-width strokes, allowing you to adjust and alter stroke widths across the length of a stroke.

X

Provides dash adjustment to improve control over the dashed strokes.

X

Allows you to scale brushes based on path length.

A new sample plug-in, StrokeFilter, has been added to the SDK to demonstrate the usage of this suite. See Getting Started with Illustrator CS5 Development for details.

New AIPerspectiveGridSuite and AIPerspectiveTransformSuite Two new suites, AIPerspectiveGridSuite and AIPerspectiveTransformSuite, provide an API for working with Perspective Grid features. X

AIPerspectiveGridSuite allows you to query and set parameters of a currently-defined Perspective Grid in a document. You can also use methods in this suite to convert points between Artwork and PerspectiveGrid coordinate systems.

X

AIPerspectiveTransformSuite allows you to project or reverse-project point and art objects based on the currently-defined Perspective Grid in a document.

A new sample plug-in, FreeGrid, and its extension, FreeGridUI, have been added to the SDK to demonstrate the usage of these two suites. See Getting Started with Illustrator CS5 Development for details.

Adobe Illustrator CS5 Porting Guide

SDK Changes

11

Update of FXGFileFormatSuite Some options have been modified and some methods have been added to and removed from the FXGFileFormatSuite in CS5. X

A new option, kAIFXGPreserveAuto, has been added to the AIFXGPreservePolicy enumeration. Text and Gradients use this constant to automatically decide the best preservation strategy, either by mapping directly to FXG constructs, or by expanding or rasterizing art to map the appearance.

X

A new option, kAIFXGExpandArtOptionAuto, has been added to the AIFXGExpandArtOptionEnum. It is used by Blends, and can be used for other object types.

X

The two methods Get/SetFXGSaveClipToActiveArtboard() have been removed. This option is no longer supported and artboards are always mapped to pages in FXG.

X

Two new methods, Get/SetFXGSaveExpandOptionBlends(), access the expand option for Blends in an FXG save-options object.

X

The parameters to the method ExportFXGToStream() have been modified. The old stream interface is no longer supported, and has been renamed as AI140FXGWriteStreamInterface in AI140FXGFileFormat.h.

X

In the AIFXGWriteStreamInterface structure: Z

A new method, IsExistingAsset(), has been added.

Z

The methods SetPos(), GetCurPos(), IsPositionable(), and LinkImageIntoAssetFolder() have been removed.

API changes X

Many function signatures have changed to use the ai:int32 type, instead of long or ASInt32. For details, see the API Advisor.

X

AIAnnotatorMessage::port has been deprecated, as part of a general update for Mac OS-specific usage. It is recommended that you use AIAnnotatorDrawerSuite for platform-independent drawing of annotations.

X

These functions have been removed: AIDocumentSuite::WriteDocumentWithOptions() AISymbolSuite::Get/SetSymbolRegistrationPoint()

SDK Changes This section summarizes changes to the organization of the SDK since the prior release.

Outdated plug-in samples removed The Shell plug-in framework and Adobe Dialog Manager are no longer supported, and the corresponding samples, Shell and ADMNonModalDialog, have been removed from the SDK in this release.

Adobe Illustrator CS5 Porting Guide

Porting Windows plug-ins 12

New StrokeFilter sample plug-in A new sample plug-in, StrokeFilter, has been added to the Illustrator CS5 SDK to demonstrate the usage of AIBeautifulStrokesSuite. This plug-in adds two filters to Illustrator’s Object menu: X

Dashed Stroke: demonstrates how to control dash adjustment using AIBeautifulStrokesSuite methods.

X

Waved Stroke: demonstrates how to adjust and alter stroke widths across the length of the stroke using AIBeautifulStrokesSuite methods.

A related sample, the Creative Suite extension StrokeFilterUI, provides a Flash-based user interface for this plug-in. To use this interface, select one or more art object that contain strokes, and choose Object > Filters > Aditional Filters > SDK > Dashed Stroke or Waved Stroke. You can inspect a dashed stroke using the Stroke panel, or a waved stroke using the Width tool. See Getting Started with Illustrator CS5 Development.

New FreeGrid sample plug-in A new sample plug-in, FreeGrid, has been added to the Illustrator CS5 SDK to demonstrate the usage of AIPerspectiveGridSuite and AIPerspectiveTransformSuite. It shows how to move, scale, and rotate an art object on a perspective plane, and how to move an art object from one perspective plane to another. You can perform these operations as changes to an existing object, or create a duplicate with the changes. A related sample, the Creative Suite extension FreeGridUI, provides a Flash-based user interface for this plug-in. To use this interface, show the perspective grid by choosing View > Perspective Grid > Show Grid. Select one or more art objects, then choose Windows > SDK > FreeGridUI. For details of these samples, see Getting Started with Illustrator CS5 Development.

Porting Windows plug-ins This section applies to Windows platform only. If you have existing plug-ins in a Windows development environment, you must port them from Visual Studio 2005 (VC++ 8) to Visual Studio 2008 (VC++9). To convert project files: 1.

Launch Visual Studio 2008 (VC++ 9.0).

2.

Open your plug-in's project file (.vcproj). Visual Studio 2008 launches the Conversion Wizard.

3. Follow the Wizard instructions to finish the conversion. 4.

Check the conversion log to see if there are any errors.