Macromedia Illustrator - CC Development User Guide
ADOBE® ILLUSTRATOR® CC
GETTING STARTED WITH
ADOBE ILLUSTRATOR CC
DEVELOPMENT
© 2013 Adobe Systems Incorporated. All rights reserved.
Getting Started with Adobe Illustrator CC Development
Technical Note #10501
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
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Setting up your development platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Exploring the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Samples guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Using this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Terminology and conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Exploring the documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Document viewers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Exploring the samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Creating a plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Building and running the samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Annotator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
DrawArt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
EmptyPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
FreeGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
LiveDropShadow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
MarkedObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
MenuPlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
MultiArrowTool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
ScriptMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
SnippetRunner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Running and testing snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Exploring the API using code snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
StrokeFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Dashed Strokes Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Waved Stroke Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
TextFileFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
TransformButtons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
TwirlFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Webter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Debugging plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Debugging a plug-in under Visual Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3
Contents 4
Debugging a plug-in under Xcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Adding Illustrator to the executable group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Setting the debug information format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Formatting program data for the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Problems stepping through code in the Xcode debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Using the plug-in project templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Visual C++ template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Xcode template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Creating a plug-in in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Create a new project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Add a source file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Add a resource file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Configure the project settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Build the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Creating a plug-in in Mac OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Create a new project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Add a target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Add a source file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Add project dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Add a resource file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Configure the project settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Build the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Getting Started with Adobe Illustrator CC Development
This document describes how to start developing plug-ins for Adobe® Illustrator® CC, using the Software
Development Kit (SDK). The target audience for this document is developers who need to develop
plug-ins for Illustrator.
Preface
The Illustrator CC SDK is available for download from:
http://www.adobe.com/devnet/illustrator/
Using this document
To start developing plug-ins for Illustrator, follow these steps:
1. Set up your machine for development. Follow the instructions in “
platform” on page 6.
2. Explore the documentation; see “
3. Explore, compile, and run the samples; see “
4. Continue exploring the API using code snippets; see “
page 17.
5. Write a new plug-in using the supplied SDK plug-in project templates; see “
templates” on page 25.
6. Write a “HelloWorld” plug-in from scratch to learn about configuring your development environment;
Creating a plug-in” on page 9.
see “
Exploring the documentation” on page 7.
Terminology and conventions
<SDK> refers to your locally installed SDK root folder. The actual root location depends on the
installation and operating system.
<AI> refers to the installed location of Illustrator CC. The actual location depends on the installation
and operating system.
<VS> indicates the installed location of Microsoft Visual Studio 2010 (also known as VC++ 10.0). The
actual location depends on the installation; the default is
Studio 10.0/
.
Setting up your development
Exploring the samples” on page 8.
Exploring the API using code snippets” on
Using the plug-in project
C:\Program Files\Microsoft Visual
5
Getting Started with Adobe Illustrator CC Development Setting up your development platform 6
Setting up your development platform
1. Check that your platform meets the basic requirements:
Platform Component
Windows XP Windows XP Service Pack 2 or higher
Visual Studio 2010 SP1
Visual C++ 10
Mac OS Mac OS 10.7 or higher
Xcode 4.5.2
LLVM Clang
(
com.apple.compilers.llvm.clang.1_0)
Apple 10.7 SDK
Apple 10.6 OS X Deployment Target
2. Download the Illustrator CC SDK for your platform from:
http://www.adobe.com/devnet/illustrator/
In Windows, extract the contents of the downloaded zip archive to a location of your choice.
In Mac OS, mount the downloaded disk image file (DMG) as a new volume, and copy the Illustrator
CC SDK folder to a location of your choice.
3. For detailed instructions on configuring the development environment for plug-in creation, see:
Developing Illustrator CC plug-ins in Windows
requires VC++ 10.0, a component of Visual
Studio 2010. If you have the Professional or
Standard Editions of Visual Studio 2010, you
must install the Visual C++ components.
Xcode can be downloaded from
http://developer.apple.com/tools/download/
“Creating a plug-in in Windows” on page 28
“Creating a plug-in in Mac OS” on page 32
Exploring the SDK
The SDK contains documentation and code samples to help you in developing your own Illustrator CC
plug-ins, and in porting plug-ins from previous releases.
Getting Started with Adobe Illustrator CC Development Exploring the SDK 7
Exploring the documentation
The following documents are included with the SDK:
Title Description
Adobe Illustrator CC
Programmer’s Guide
Describes the basic concepts of developing plug-ins for Illustrator CC. It is
aimed at all developers and is the recommended resource for plug-in
developers after reading this document.
<SDK>/docs/guides/programmers-guide.pdf
Adobe Illustrator CC
Porting Guide
This document is in the file
Describes how to update CS6 SDK plug-in code for Illustrator CC; it is aimed at
developers with pre-existing plug-ins. It lists new features and changes in the
API since the previous release.
Using the Adobe Text
Engine
This document is in the file
Describes how to configure your plug-in to use the Adobe text engine API,
provided with the Illustrator CC SDK. It describes procedures for creating,
<SDK>/docs/guides/porting-guide.pdf.
editing, deleting, styling, and iterating text, with references to sample code and
the API Reference.
This document is in the file
<SDK>/docs/guides/using-adobe-text-engine.pdf.
API Reference Provides reference documentation for the suites, classes, structures, functions,
variables, and constants available in the API. It is a key resource for all
developers.
This document is provided in two formats:
<SDK>/docs/references/index.chm — This compiled HTML file allows
text searches to be performed on the content.
To view the contents in 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 CHM viewer; see
Document viewers.
<SDK>/docs/references/sdkdocs.tar.gz — This file contains the API
Reference in HTML format. This format does not support text searches, but it
provides the ability to view individual HTML files if desired. To view the
contents, first decompress the archive, then open
index.html in your
browser.
API Advisor Reports the class, structure, and file differences between the API included in the
CS6 SDK and CC SDK. It is aimed at all developers using the API, but it is most
useful for developers updating plug-in code for Illustrator CC.
This document is in the file
<SDK>/docs/references/apiadvisor-ai16-vs-ai17.html.
Getting Started with Adobe Illustrator CC Development Exploring the SDK 8
Document viewers
To view PDF-based documentation, you need Adobe Reader or Adobe Acrobat.
To view HTML-based documentation, you need a web browser.
To view compiled HTML documentation (CHM) in Mac OS, you need a CHM viewer. Two such viewers
chmox (http://chmox.sourceforge.net/) and xCHM (http://sourceforge.net/projects/xchm/).
are
Exploring the samples
The samples provided show how to implement key Illustrator plug-in features like tools, filters, menus, and
file formats. The following table shows which features are implemented by each sample:
Feature
Action X X
AGM Port X
Annotator X X
File Format X
Filter X X
Flash/Flex UI
Effect
Menu Item
Notifier
Panel
Plug-in Group
Scripting X
Theme Sync X X X
Timer X
Annotator
DrawArt
EmptyPanel
FreeGrid
LiveDropShadow
MarkedObjects
MenuPlay
MultiArrowTool
ScriptMessage
SnippetRunner
StrokeFilter
Te x tF i l eF o r ma t
TransformButtons
Tut oria l
X X X XXX XX X
X XXXXXX X XXXXXX
X X X X
X X X X X
X
TwirlFilter
Webter
X
Tool Palette X X X X
Transform X X
Getting Started with Adobe Illustrator CC Development Exploring the SDK 9
Use this table to identify the sample most suitable as a starting point for your own plug-in: the sample that
implements the most features your plug-in requires will give you the best base from which to work.
For a more detailed description of each sample, see “Samples guide” on page 10
For a more detailed description of these plug-in features and what they do, see the “Types of Plug-ins”
section in Adobe Illustrator CC Programmer’s Guide.
Creating a plug-in
The SDK samples are based on the Plugin and Suites classes. The Plugin class constructs the basic
requirements for an Illustrator plug-in, using the
To create your own plug-in using this framework:
Create a new project, and add Plugin.cpp and Suites.cpp to your new project from
<SDK>/samplecode/common/source/.
Create a class in your project that is a subclass of the Plugin class. This class should implement the
required functionality of the plug-in.
For a step-by-step example of configuring the development environment and creating a basic plug-in, see:
Suites class to acquire and release the required suites.
“Creating a plug-in in Windows” on page 28
“Creating a plug-in in Mac OS” on page 32
Building and running the samples
To build all the samples, use the projects provided in the <SDK>/samplecode/MasterProjects/ folder.
After compiling and linking, the plug-in binaries can be found in the
We recommend you use the Additional Plug-ins Folder preference when developing and debugging
plug-ins. Set this preference in the application’s Preferences > Plug-ins & Scratch Disk dialog.
For a complete list of the locations where Illustrator looks for plug-ins, see Adobe Illustrator CC
Programmer’s Guide.
To debug a sample (or your own plug-in), see “
<SDK>/samplecode/Output/ folder.
Debugging plug-ins” on page 22.
Getting Started with Adobe Illustrator CC Development Samples guide 10
Samples guide
This section describes the individual samples in more detail.
Annotator
Uses the AIAnnotatorSuite and AIAnnotatorDrawerSuite to annotate artwork in the document and
update the annotations as selection or cursor position changes.
Adds a tool to the toolbar, using this icon:
When the annotator tool is selected and the cursor is over an item on the artboard, the item becomes
selected, an annotation displaying the bounds of the art appears at the right-hand side of the art item. A
smaller annotation displaying the cursor position appears next to the cursor, which updates as the cursor
moves within the art.
DrawArt
The DrawArt sample demonstrates how to use the AIDrawArtSuite to obtain preview bitmap images to
display in Flash panels. The sample draws a swatch to an AGM port, retrieves a bitmap from that port, and
passes the bitmap to a Flash panel for display as an image.
This sample is a CS Extension; to run it, choose Window > Extensions > DrawArt.
Getting Started with Adobe Illustrator CC Development Samples guide 11
Panel and Control Bar using native Mac OS components
Panel and Control Bar using native Windows components
EmptyPanel
The EmptyPanel sample demonstrates how to use native Windows or Mac OS components in a control bar
or panel, combining native controls with bars and panels created with
AIPanelSuite. The bar and panel that the sample creates contain controls that are implemented using
native window components.
In the panel, the native controls implement a simple calculator. In the control bar, the values in the native
controls are tied to the dimensions of the container, allowing you to resize the control bar dynamically.
The Mac OS examples demonstrate loading a native NIB or XIB file into a panel, so that you can use all the
standard Xcode Interface Builder features, and mix objective-C and C++.
AIControlBarSuite and
Getting Started with Adobe Illustrator CC Development Samples guide 12
FreeGrid
The FreeGrid sample demonstrates the usage of the AIPerspectiveGridSuite and
AIPerspectiveTransformSuite API to manipulate the Perspective Grid, a feature that was added in CS5.
AIPerspectiveGridSuite allows you to query and set parameters of the currently defined Perspective
Grid in a document, and to convert points between the Artwork and Perspective Grid coordinate systems.
AIPerspectiveTransformSuite allows you to project or reverse-project points and art objects according
to the Perspective Grid.
The FreeGridUI extension provides a user interface for the FreeGrid sample, demonstrating how to create a
UI for a plug-in using the Flash/Flex-based Creative Suite Extension Builder, which is recommended as a
replacement for the deprecated ADM UI solution.
To use this plug-in, first show perspective grid by choosing View > Perspective Grid > Show Grid or by
selecting the Perspective Grid Tool in the Tools panel. Draw or select a path art object on the active plane,
then choose Window > SDK > FreeGrid.
The resulting dialog allows you to perform one of four operations:
Translate the art object's position by specifying X and Y offsets.
Scale the art object's size by specifying a zoom percentage.
Rotate the art object by specifying an angle.
Move the art object from one perspective plane to another.
Loading...