Macromedia Illustrator - CC Programmer’s Guide

ADOBE® ILLUSTRATOR® CC 2017
ADOBE ILLUSTRATOR CC 2017
PROGRAMMER’S GUIDE
2016 Adobe Systems Incorporated. All rights reserved.
Adobe Illustrator CC 2017 Programmer’s Guide
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, Illustrator, PageMaker, Photoshop, FrameMaker, Flash, Flex, and ActionScript 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 and Mac OS 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.

Preface

This document introduces the Adobe® Illustrator® API for plug-ins.
Chapter 1, “Overview” describes the basic concepts behind Illustrator plug-in programming.
Chapter 2, “Tutorial” describes plug-in programming fundamentals using an example project.
Chapter 3, “Creating an HTML/JS UI for Plug-ins" describes how to create a user interface for your
plug-in using Adobe Flash®.
Chapter 3, “Plug–in Techniques” describes Plug-in property lists (PiPL resources) in detail, and explains
how to handle Live Effects in plug-ins.

Terminology and notational conventions

API — Application programming interface.
Application — Illustrator CC 2017, unless otherwise specified.
PiPL — Plug-in property list.
SDK — Software development kit for the application.
folder. The actual root location depends on the installation and operating system.

Supporting documentation

The following documents are companions to this guide:
Getting Started with Adobe Illustrator CC 2017 Development — Describes platforms supported for
plug-in development, how to set up the development environment, and the code samples included in the SDK. Provides step by step guides on creating new projects either from scratch or from the templates provided with the SDK.
Adobe Illustrator CC 2017 Porting Guide — Describes issues related to porting plug-ins across different
versions of the Illustrator API. See
Adobe Illustrator API Reference — Describes the suites and functions in the Illustrator API in detail. See
<SDK>/docs/references/ folder.
the
Using the Adobe Text Engine with Illustrator CC 2017 — Describes how to use the Adobe text engine—
the text API provided by the Adobe® Illustrator® CC 2017 SDK—in your Illustrator plug-ins.

Sample code

<SDK> indicates your locally installed SDK root
<SDK>/docs/guides/porting-guide.pdf.
Sample plug-ins are provided in the sample code folder in the SDK, and described in Getting Started with Adobe Illustrator CC 2017 Development.
fundamentals using the Tutorial sample project.
Chapter 2, “Tutorial,” describes plug-in programming
3
1

Overview

This chapter introduces the Adobe® Illustrator® plug-in architecture. It shows how plug-ins interact with Illustrator and gives an idea of the power of plug-ins.

What is a plug-in?

A plug-in is a library that extends or changes the behavior of Illustrator. On Windows, a plug-in is built as a DLL (dynamic-link library). On Mac OS, a plug-in is built as a bundle that contains a shared library.
The plug-in architecture in Illustrator is very powerful. Plug-ins have access to Illustrator’s elegant vector, text, and raster engines, as well as Illustrator’s user interface. The API is a fundamental part of the application; in fact, most of Illustrator itself is implemented as plug-ins.
You can create plug-ins that add new tools to the drawing, shading, and raster tools already in Illustrator. Plug-ins can turn Illustrator into a powerful CAD, cartographic, or other custom design application. Users can add or remove plug-ins to quickly and easily customize Illustrator to their needs.
The Illustrator API offers several benefits to plug-in developers. Because Illustrator handles large application tasks like printing and saving files, you can concentrate on the implementation of your plug-in’s unique features. Plug-ins do not need to support undo or window updating; these are handled by the API and are invisible to the plug-in. This translates into shorter development cycles.

A brief history of the Adobe Illustrator API

The Illustrator API first appeared in version 5.0. It supported one type of plug-in, filters. This was extended in Adobe Illustrator 5.5 to include file formats. The 5.x APIs displayed characteristics of many early API design efforts: the interface was monolithic, incorporating enough function to achieve its intended purpose, but not allowing for future expansion. A single callback function table was provided, with no means to extend or update it. Platform abstraction was minimal, and interaction with the user was restricted to modal.
The Illustrator 6.0 API began addressing these limitations, using a modular and extensible approach . Callback functions were organized into suites that could be easily replaced or extended. The plug-in types were abstracted and extended to include tools, floating windows, menu items, events, and combinations of these types. The first steps towards platform abstraction were taken.
The Illustrator 7.0 API refined prior efforts. The API was extended to be truly cross-platform (the Windows version of Adobe Illustrator jumped from version 4.2 directly to 7.0), including a complete set of user-interface suites. The plug-in management core was generalized for both cross-platform and cross-product use. More of Illustrator’s core functionality was implemented through plug-ins, allowing the application’s behavior to change without modifying the application itself.
The Illustrator 8.0 API switched from fixed to floating-point numbers and included more than a dozen new suites, many corresponding to new user features like plug-in groups, cursor snapping, and actions.
Illustrator 9.0 stopped loading Mac OS plug-ins containing Motorola 68K code. Only plug-ins with the Illustrator 9 version information in the PiPL were recognized and included in Illustrator 9’s initial start-up process; however, Illustrator 6 and 5.5 plug-ins were supported by adapters.
4
CHAPTER 1 Overview Anatomy of a plug-in 5
The Illustrator 10.0 API changed API structures in Mac OS to use PowerPC (4-byte) alignment instead of 68K (2-byte) alignment, requiring Mac OS plug-ins to be rebuilt. Illustrator plug-ins for Windows built with the Illustrator 9 SDK or earlier were not affected and remained compatible with Illustrator 10.
Illustrator CS1 (Illustrator version 11.0) integrated a new text engine, the Adobe Text Engine (ATE). This change broke backward compatibility. Illustrator plug-ins that used the obsolete text API had to be rebuilt with the Illustrator 11 SDK and ported to use the new ATE API.
The Illustrator CS2 API (Illustrator version 12.0) introduced Unicode support. In Mac OS, the object-file format for Illustrator plug-ins changed from PEF to Mach-O.
The Illustrator CS3 API (Illustrator version 13.0) introduced support for universal binary plug-ins in Mac OS. The plug-in development environment in Mac OS switched to Xcode from CodeWarrior.
The Illustrator CS4 API (Illustrator version 14.0) introduced support for multiple artboards and the FXG file format.
In Illustrator CS5 API (Illustrator version 15.0), Adobe Dialog Manager (ADM) was deprecated. This release introduced the Beautiful Strokes feature, and improved and enhanced existing features, such as perspective grids.
In Illustrator CS6 API (Illustrator version 16.0), ADM was removed. A new vectorization engine replaced the former tracing functionality; the ability to create patterns and gradients on strokes was added; and the API provided support for UI color themes. This release supported the 64-bit Windows platforms, with the development environments Visual Studio 2010 and Xcode 3.2.5.
In Illustrator CC 2014 API (Illustrator version 18.0), the The development environment in Mac OS was updated to Xcode 5.1.1 with LLVM GCC4.2
In Illustrator CC 2015 API (Illustrator version 19.0), the development environment in Windows is updated to Visual Studio 2013, and in Mac OS to Xcode 6.2. For documentation on these changes and other API changes, see the Adobe Illustrator CC 2015 Porting Guide.
In Illustrator CC 2017 API (Illustrator version 21.0), the development environment in Windows is updated to Visual Studio 2015, and in Mac OS is updated to XCode 7.3. For documentation on other API changes, see the Adobe Illustrator CC 2017 Porting Guide.

Anatomy of a plug-in

Like most programs, Illustrator plug-ins contain both code and data. The Illustrator plug-in manager loads and executes a plug-in’s code when required, sending various messages to the plug-in. The plug-in manager also unloads plug-ins that are no longer needed. See the following figure.
ASReal data types was removed in favor of AIReal.
CHAPTER 1 Overview Types of plug-ins 6
Required plug-ins
Adobe Illustrator
Plug-in manager
Additional plug-ins
Plug-ins are notified by Illustrator when they have just been loaded or are about to be unloaded, permitting them to restore or save any state information.

Types of plug-ins

This section describes the different types of Illustrator plug-ins you can create. A single plug-in file can contain multiple plug-in types. For example, a shape creation plug-in may implement several plug-in filters and a plug-in tool. Plug-in types are listed in the following table and described more fully after the table.
Plug-in Type What it does
Action Playback or register actions.
Effects Add menu items to the Effects menu.
File format Add file types to the Open, Save, and Export commands.
Filter Add menu items to the Filter menu.
Menu command Add menu items to the general menu structure.
Notifier Receive and process art-state events.
Plugin group Maintain “display” art that is associated with another art object
Suite Implement and publish your own suite of callback functions.
Timer Receive periodic notification.
Tool Add tools to the Tools panel.
Transform again Set the transform-again feature.
CHAPTER 1 Overview Types of plug-ins 7

Action plug-ins

Action plug-ins are used to execute Illustrator commands. An action plug-in can register itself so it can be recordable via the Actions panel. For more information, see API Reference.
AIActionManagerSuite in Adobe Illustrator

Plug-in file formats

Plug-in file formats are used to extend the number of file types Illustrator can read and write. Plug-ins indicate which file formats they support during initialization, specifying the supported names and file types (or extensions). One plug-in can register as many formats as desired.
The file types supported by a file-format plug-in can appear in Illustrator's Export, Save, and Open dialogs, depending on the options specified when the new file type is added.
For more information, see
AIFileFormatSuite in Adobe Illustrator API Reference

Plug-in filters

Plug-in filters appear under the Object menu and are used to create or manipulate Illustrator artwork. Typically, filters present a modal interface to the user, who can set parameters before executing.
OTE: In other applications (including Adobe PageMaker® and Adobe FrameMaker®), the term “filter” or
N
“filter plug-in” sometimes is used to describe software that reads and writes non-native files (e.g., TIFF or JPEG files). In Illustrator, these are called file-format plug-ins. Illustrator uses the term “filter plug-in” in a way similar to Adobe Photoshop: a filter plug-in modifies the artwork in an algorithmic fashion.
Illustrator updates the Repeat and Undo menus automatically, making filters one of the simplest plug-in types to create.
For more information, see
N
OTE: AIFilterSuite is deprecated in favor of AILiveEffectSuite. We recommend that you change
plug-ins which implement filters to use live effects instead, as point in the future.
AIFilterSuite in Adobe Illustrator API Reference.

Plug-in menu commands

Plug-in menus are used to add menu items to Illustrator's menu structure other than the Filter menu. A typical use of this plug-in type is to add a Hide/Show Window menu item to Illustrator's Window menu.
AIFilterSuite will be removed at some
Plug-in menu commands can be added at several places in the menu structure.
For more information, see
AIMenuSuite in Adobe Illustrator API Reference.

Plug-in notifiers and timers

Plug-in notifiers and timers are used by a plug-in to have Illustrator inform it of certain events.
A notifier plug-in is notified when the state of an Illustrator document changes. For example, a plug-in may request to be notified when the selection state changes. A notifier plug-in registers for one or more notifications during start-up.
CHAPTER 1 Overview Where plug-ins live 8
A timer plug-in is notified at regular time intervals. For example, a timer plug-in may request to be notified once a second.
For more information, see

Plugin-group plug-ins

Plugin-group plug-ins maintain one or more plug-in groups. A plug-in group is a special art object that contains editable art as well as art that is displayed but not editable. A plugin-group plug-in is responsible for regenerating the display art (or result art) whenever there is a change in the edit art. Plug-in groups are used to make special art types like Live Blends and Brushes.
For more information, see

Plug-in tools

Plug-in tools add an icon to the Tools panel, expanding the number of tools available to the user. Many standard Illustrator tools, including the knife tool, shape tools, and twirl tool, are implemented as plug-in tools.
When selected, a tool plug-in can track the mouse, determine which artwork was selected, and act on it. For example, a tool might create or distort objects. Some things are handled automatically for plug-in tools, like scrolling the window.
For more information, see
AINotifierSuite and AITimerSuite in Adobe Illustrator API Reference.
AIPluginGroupSuite in Adobe Illustrator API Reference.
AIToolSuite in Adobe Illustrator API Reference.

Combining multiple plug-in types

As mentioned before, it is likely one plug-in file implements multiple plug-in types. A plug-in also may need to add multiple instances of a single plug-in type. The plug-in API supports both these cases.

Where plug-ins live

Illustrator's Plug-ins folder is in the following locations:
Windows:
Mac OS:
A user-specific follows:
Windows 7:
Mac OS
Optionally, an additional folder can be specified using Illustrator's Additional Plug-ins Folder preference.
In general, each plug-in type is in a specific subfolder; for example, tool plug-ins are in a folder named
Tools.
C:\Program Files\Adobe\Adobe Illustrator CC 2017\Plug-ins\
/Applications/Adobe Illustrator CC 2017/Plug-ins/
Plug-ins folder, which may be appropriate to use in multi-user systems, is located as
C:\Users\<username>\AppData\Roaming\Adobe\
Illustrator CC 2017 Settings\<localeCode>\Plug-ins\
Adobe
/Users/{username}/Library/Application Support/Adobe/
Illustrator CC 2017/<localeCode>/Plug-ins
Adobe
CHAPTER 1 Overview What defines a plug-in? 9

What defines a plug-in?

On Windows, an Illustrator plug-in is a DLL (dynamic-link library). In Mac OS, an Illustrator plug-in is a bundle that contains a shared library. An Illustrator plug-in has the following characteristics:
A file extension of .aip; for example, CoolEffect.aip.
A valid plug-in PiPL resource. The PiPL resource contains information about your plug-in. Illustrator
considers only those files with PiPL resources to be potential plug-ins. Files with the correct properties are added to the plug-in list.
A code entry point containing binary code that can run on the target platform. The entry point is
specified in the PiPL resource and is called with several messages telling it which actions to take.

PiPL resources

A plug-in property list (PiPL) resource contains properties used by the Illustrator plug-in manager, including the following:
The type of the plug-in, given by the kind property.
The calling mechanism for the plug-in code, given by the ivrs property.
The entry point of the plug-in, given by a code descriptor property.
Illustrator considers only files with a valid PiPL to be potential plug-ins. PiPL properties are defined using native platform resources. For more information about PiPL resources and samples, see
in Property Lists.

Plug-in management

When Illustrator is launched, only plug-ins with a valid PiPL and code entry point are recognized and included in the initial start-up process. Each plug-in is loaded into and unloaded from memory as needed by Illustrator. A plug-in needs to be written assuming it is not always in memory. This is why a plug-in should save and restore state information during unload and reload. A plug-in can expect certain services from the application. Because a plug-in may be unloaded, Illustrator provides a means of storing important data when the plug-in is unloaded. Each time a plug-in is called, it is given enough information to accomplish the action to be performed.
The loading order of plug-ins becomes important when one plug-in depends on a resource provided by another, as the resource providing plug-in must be loaded first. As mentioned above, plug-ins that export one or more suites must declare (in the PiPL resource) what they export. Illustrator uses this information when loading and executing plug-ins, ensuring that suites and other resources are available.
Chapter 4, “Plug–

Plug-in entry point and messages

The Illustrator plug-in manager communicates with your plug-in by loading the plug-in code into memory if necessary, then calling the entry point given by the code-descriptor property in the PiPL. By convention, the entry point is called
extern "C" ASAPI ASErr PluginMain(char* caller, char* selector, void* message);
Three arguments are passed to the PluginMain function; collectively, they make up a message.
PluginMain and is compiled with C linkage:
CHAPTER 1 Overview Plug-in entry point and messages 10
The first two parameters represent the message action, describing what the plug-in is supposed to do, as described in the following section. The third parameter is a pointer to a data structure, which varies depending on the message action. When you determine the message action, you typecast the data in the
message parameter as needed.
The result of the function is an error code.

Message actions: callers and selectors

Each time your plug-in is called, it receives a message action from Illustrator. The message action notifies your plug-in that an event happened or tells your plug-in to perform an action.
The message action passed to your plug-in consists of two identifiers:
The caller identifies the sender of the message (PICA, the host application, or a plug-in) and a general
category of action.
The selector specifies the action to take within the category of action. All plug-ins receive at least four
message actions: reload, unload, startup and shutdown. In addition, your plug-in may receive additional message actions specific to the plug-in type.
For example, Illustrator sends a plug-in a message action based on these two strings, when the plug-in is unloaded and reloaded:
#define kSPAccessCaller "SP Access" #define kSPAccessUnloadSelector "Unload" #define kSPAccessReloadSelector "Reload"
The caller and selector identifiers are C strings. By convention, each caller string has a prefix. This is so new message actions can be easily defined by other plug-ins, with little chance of conflict. For example, callers and selectors from Illustrator suites use the prefix “AI”, while those from PICA use the prefix “SP.”
Illustrator message actions are used to indicate events in which a plug-in has interest. Information on the callers and selectors supported by the API is given by the Plug-in Callers and Plug-in Selectors pages in Adobe Illustrator API Reference.

Core message actions

The following table contains the set of core message actions received by all plug-ins and corresponding actions your plug-in should take.
Caller Selector Action to perform
kSPAccessCaller
(“SP Access”)
kSPAccessReloadSelector
(“Reload”)
kSPAccessUnloadSelector
(“Unload”)
Restore any state information (globals).
Save any state information (globals).
kSPInterfaceCaller
(“SP Interface”)
kSPInterfaceStartupSelector
(“Startup”)
kSPInterfaceShutdownSelector
(“Shutdown”)
Initialize globals and add features to the application.
Free globals, remove features from the application, and save preferences.
CHAPTER 1 Overview Plug-in entry point and messages 11

Reload and unload messages

Whenever a plug-in is loaded into memory or unloaded from memory, Illustrator sends it an access message action:
#define kSPAccessCaller "SP Access" #define kSPAccessUnloadSelector "Unload" #define kSPAccessReloadSelector "Reload"
The message action contains the access caller and a reload or unload selector. This is your plug-in’s opportunity to set up, restore, or save state information. The access caller/selectors bracket all other callers and selectors.
Access messages bracket all other messages. Reload is the first message your plug-in receives; unload is the last. At these times, your plug-in should not acquire or release suites other than those built into Illustrator.

Start-up and shut-down messages

Illustrator has two core interface message actions, where the plug-in can interact with the application:
#define kSPInterfaceCaller "SP Interface" #define kSPInterfaceStartupSelector "Startup" #define kSPInterfaceShutdownSelector "Shutdown"
When Illustrator is launched, it sends a “startup” message to each plug-in it finds. This allows your plug-in to allocate global memory, add user-interface items to Illustrator, register suites, or perform other initialization. The start-up message action consists of the interface caller ( start-up selector (
When the user quits Illustrator, it sends each plug-in a “shutdown” message. The shut-down message action
kSPInterfaceShutdownSelector
( not destruction. A plug-in that exports a suite should not dispose of its plug-in globals or suite information, since it may be called after its own shut-down by another plug-in’s shut-down. For example, if your plug-in implements a preferences suite that other plug-ins use, they may call you in their shut-down handlers after you already shut down.

Notifiers

Some message actions also are referred to as notifiers, indicating something in Illustrator was changed by the user; for example, when the user selects an object.
Plug-ins must register for the notifiers in which they are interested. The Notifier suite is used to register and remove notification requests (see
Plug-ins also can create their own notifiers, which can be used to broadcast changes to other plug-ins.
kSPInterfaceStartupSelector).
comprises the interface caller (
AINotifierSuite).
kSPInterfaceCaller) and
kSPInterfaceCaller
).
Shut-down is intended for flushing files and preserving preferences,
) and s
hut-down
selector

Handling callers and selectors

Your plug-in’s organization is based largely on the messages it receives. The main routine of your plug-in must first determine the message action, using the caller and selector parameters. For example:
extern "C" ASAPI ASErr PluginMain(char* caller, char* selector, void* message)
CHAPTER 1 Overview Plug-in entry point and messages 12
{
ASErr error = kNoErr; if ( strcmp( caller, kSPAccessCaller ) == 0 ) {
// Handle Reload and Unload if ( strcmp( selector, kSPAccessReloadSelector ) == 0 )
error = MyRestoreGlobals( message );
else if ( strcmp( selector, kSPAccessUnloadSelector ) == 0 )
error = MySaveGlobals( message );
} else if ( strcmp( caller, kSPInterfaceCaller ) == 0 ) {
// Handle Startup and Shutdown if ( strcmp( selector, kSPInterfaceStartupSelector ) == 0 )
error = MyStartupPlugin( message );
else if ( strcmp( selector, kSPInterfaceShutdownSelector ) == 0 )
error = MyShutdownPlugin( message );
} else if ( strcmp( caller, kCallerAIMenu ) == 0 &&
strcmp( selector, kSelectorAIGoMenuItem ) == 0 ) ){ // Handle menu message
error = MyHandleMenu( message ); } return error;
}

Message data

The last argument passed to your plug-in entry point is a pointer to a message data structure, which contains information appropriate to the message action. For example, when a mouse-clicked message action is received, the message data structure contains the mouse position.
The contents of the message data structure depend on the message action and are not completely known until your plug-in identifies this. While the contents of the message data vary, by convention all message data structures begin with the common fields that are grouped into the
typedef struct SPMessageData {
ai::int32 SPCheck; struct SPPlugin *self; void *globals; struct SPBasicSuite *basic;
} SPMessageData;
SPMessageData structure:
If this is a valid message, the SPCheck field contains kSPValidSPMessageData.
The
self field is a reference to the plug-in being called. The reference to the running plug-in’s self is used
to add plug-in suites, adapters, and other plug-in data to Illustrator. Illustrator stores this value with the added data. It is used to recall your plug-in as needed.
globals pointer is for use by your plug-in, to preserve any information between calls that it needs.
The Usually, it is a pointer to a block of memory allocated by your plug-in at start-up. This value is preserved by Illustrator when your plug-in is unloaded and passed back to the plug-in each time it is called. Plug-ins use this block to store any state information they need to maintain between unload and reload.
OTE: It is important that the memory for globals be allocated using Illustrator's memory-allocation APIs;
N
otherwise, the memory may be destroyed by the operating system when a plug-in is unloaded.
basic field is a pointer to the Basic suite (see SPBasicSuite), which allows your plug-in to acquire
The other suites and provides basic memory management. See
“Suites” on page 13.
Loading...
+ 27 hidden pages