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 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.
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 OverviewAnatomy 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 OverviewTypes 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 TypeWhat it does
ActionPlayback or register actions.
EffectsAdd menu items to the Effects menu.
File formatAdd file types to the Open, Save, and Export commands.
FilterAdd menu items to the Filter menu.
Menu commandAdd menu items to the general menu structure.
NotifierReceive and process art-state events.
Plugin groupMaintain “display” art that is associated with another art object
SuiteImplement and publish your own suite of callback functions.
TimerReceive periodic notification.
ToolAdd tools to the Tools panel.
Transform againSet the transform-again feature.
CHAPTER 1 OverviewTypes 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 OverviewWhere 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 2017Settings\<localeCode>\Plug-ins\
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
Three arguments are passed to the PluginMain function; collectively, they make up a message.
PluginMain and is compiled with C linkage:
CHAPTER 1 OverviewPlug-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:
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.
CallerSelectorAction 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 OverviewPlug-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:
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:
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:
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
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
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.