version Adobe Illustrator Plug-in Software Development Kit Programmer s Guide for Macintosh and Windows Revised: September2003

Transcription

1 version Adobe Illustrator TM CS Plug-in Software Development Kit Programmer s Guide for Macintosh and Windows Revised: September2003

2 FrontMatter Adobe Illustrator Software Development Kit Copyright Adobe Systems Incorporated. All rights reserved. The information in this document 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 this document. The software described in this document is furnished under license and may only be used or copied in accordance with the terms of such license. Adobe, Adobe Premiere, Adobe Photoshop, Adobe Illustrator, Adobe Type Manager, ATM and PostScript are trademarks of Adobe Systems Incorporated that may be registered in certain jurisdictions. Macintosh and Apple are registered trademarks, and Mac OS is a trademark of Apple Computer, Inc. Microsoft, Windows, and Visual C++ are registered trademarks of Microsoft Corporation. CodeWarrior is a registered trademark of Metrowerks. All other products or name brands are trademarks of their respective holders. Adobe Illustrator SDK Programmers Guide 2

3 AI Programmers Guide TOC About This Document 6 Viewing and Printing This Document Sample Code Supporting Documentation Chapter 1 - Overview 7 Introduction What is a Plug in? A Brief History of the Adobe Illustrator API Plug in Categories Anatomy of a Plug in Types of Plug ins Action Plug-ins Plug in File Formats Plug in Filters Plug in Menu Commands Plug in Notifiers and Timers Plugin Group Plug-ins Plug in Tools Combining Multiple Plug in Types Where Plug ins Live PiPL Resources Required Properties Exporting Functions Plug in Loading Order Illustrator's Artwork as Seen by a Plug in Plug in Messages Message Actions Strings Core Message Actions Reload and Unload Messages Startup and Shutdown Messages About Messages Notifiers Handling Callers and Selectors Message Data Illustrator Suites Publishing Suites Adobe Illustrator SDK Programmers Guide 3

4 AI Programmers Guide TOC Acquiring and Releasing Suites Where to Now? Chapter 2 - Tutorial 19 Illustrator Plug-ins What Defines a Plug-in? PiPLs The Plug-in Entry Point Message Actions: Callers and Selectors Handling Callers and Selectors Message Data Using Suites and Callback Functions Acquiring and Releasing Suites Calling a Suite Function A Simple Example Callers and Selectors Caller: kspinterfacecaller, Selector: kspinterfacestartupselector26 Caller: kspinterfacecaller, Selector: kspinterfaceshutdownselector27 Caller: kspaccesscaller, Selector: kspaccessreloadselector28 Caller: kspaccesscaller, Selector: kspaccessunloadselector29 Caller: kspinterfacecaller, Selector: kspinterfaceaboutselector29 Plug-in Type Specific Messages Filter Plug-ins Tool Plug-ins Action Plug-ins Continuing On Chapter 3 - PipLs 39 PiPLs in Illustrator The PiPL Structure Properties Notes Types General properties Plug-in Kind (OSType) Version of kind specific API (int32) Code Descriptor Properties PowerPC code fragment descriptor (AICFMCodeDesc)42 Import and Export Properties Imports List Property Descriptor AIImportsList Exports List Property Descriptor AIExportsList Adobe Illustrator SDK Programmers Guide 4

5 AI Programmers Guide TOC AIIEListsDesc Dynamically Declared Properties Working with PiPLs Sample PiPLs Chapter 4 - Porting Plug-ins 46 Cross Platform Support Cross Platform Considerations Memory Resources Byte Information and Structures Project Considerations Changes Since Adobe Illustrator 6.0 (Macintosh only)48 The Entry Point The Main Function Messages The Basic Suite Properties Basics Properties - Imports, Exports & Plug-in Loading Order51 Summary of Changing a AI 6.0 plug-in to AI Support for Adobe Illustrator 6.0 Plug-ins Chapter 5 - Project Workspace 54 Create Project Folders Microsoft Visual C Debugging Windows Plug-Ins Metrowerks CodeWarrior Project Debugging Macintosh Plug-Ins Adobe Illustrator SDK Programmers Guide 5

6 About this Document About This Document This document introduces the Adobe Illustrator Plug-in API. Chapter 1, entitled Introduction, describes the basic concepts behind what plug-ins are and how they work. Chapter 2, entitled Tutorial, takes you through the stages of developing a plug-in. Chapter 3 discusses PiPL resources (which are introduced in chapter 1) in more detail. Chapter 4 contains information for converting an older Illustrator 6, 7 or 8 plug-in to the latest version of Illustrator. Viewing and Printing This Document This document was designed to be usable on the screen and on paper. When viewing on screen, a reduction of 90% will make it fit on half a 17 inch monitor. When printing, choose the Shrink to Fit option. This will give a printed page layout suitable for use in a 3-ring bind, even with double sided pages. Sample Code Chapter 2, entitled Tutorial, takes you through the stages of developing a plug-in. The cross-platform sample project which is described in Chapter 2 is on the SDK. Look for the Tutorial project in the Sample Code folder. Supporting Documentation There are three companion documents to this Programmers Guide: Table 1: Supporting Documentation Document Title AI Function Reference The Adobe Dialog Manager API The Adobe PICA API AI File Format Description Reference to suites and functions in the Adobe Illustrator API Reference manual for the ADM API. This is the crossplatform user interface toolkit used in Illustrator. Reference manual for the PICA API. This documents the plug-in loading mechanism for Illustrator File format specification for Illustrator 7.0 files Adobe Illustrator SDK Programmers Guide 6

7 Chapter 1 - Overview 1 Overview Introduction This chapter provides a brief introduction to the Illustrator plug in architecture. It will show you how plug ins interact with Illustrator and give you an idea of the amazing power of plug ins. The later chapters contain additional tutorial and reference information to get you started. What is a Plug in? A plug in for Adobe Illustrator is a special type of software program that adds features and functions to Illustrator. The plug in architecture in Illustrator is extremely powerful. Plug ins have complete 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 completely new tools to the drawing, shading, and raster tools already in Illustrator. Plug ins can turn Illustrator into a powerful CAD, cartigraphic, or other custom design application. Users can add or remove plug ins to quickly and easily customize Illustrator to their needs. The Adobe Illustrator application programming interface (API) offer several benefits to plug in developers. Because Illustrator handles the larger 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. Your plug in can also take advantage of the Adobe Dialog Manager (ADM), Adobe s cross platform user interface API. Plug ins that use ADM floating palettes are completely integrated with Illustrator the palettes can be docked, undocked, and controlled as if they were built right into Illustrator. A Brief History of the Adobe Illustrator API The Adobe Illustrator application programming interface (API) first appeared in version 5.0. It supported a single 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 functionality 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 Adobe Illustrator SDK Programmers Guide 7

8 Introduction abstraction was minimal, and interaction with the user was restricted to modal only. The Adobe Illustrator 6.0 API began to address these limitations. A modular and extensible approach was used to export the application s functionality. Callback functions were organized into suites that could easily be 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 Adobe Illustrator 7.0 API refined these previous efforts. The API was extended to be truly cross-platform (the Windows version of Adobe Illustrator jumped from 4.2 directly to 7.0), including a complete set of user interface suites. The plug in management core was generalized for not only cross platform, but cross product as well. More of Illustrator s core functionality was implemented through plug ins, allowing the application s behavior to change without modifying the application itself. The most significant change in the Illustrator 8.0 API was the switch from fixed numbers to floating point numbers. All suites that used fixed parameters were updated to use floating point parameters; in some cases, Adobe changed function names to reflect this. The Illustrator 8.0 API also included more than a dozen new suites, many corresponding to new user features such as plug in groups, cursor snapping, and actions. The Japanese version of Adobe Illustrator 5.0 had the same version of the API as its US counterpart. This unfortunately did not allow for full manipulation of Japanese text, though the graphic elements worked. Extensions for Japanese text appeared in the 5.5J version of the API. These are available in the 8.0J application as well, using the new suite based architecture. Plug in Categories Illustrator plug ins fall into four categories: Adobe Illustrator 9 plug ins Adobe Illustrator 8 plug ins Adobe Illustrator 7 plug ins Adobe Illustrator 6.0, 5.5 or 5.0 plug ins (Mac only) Adobe Photoshop Filter or Format plug ins This document only discusses Adobe Illustrator 9 plug ins in detail. For information about Adobe Photoshop Filter and Format plug ins, refer to the Adobe Photoshop SDK. Support for older plug ins, as well as for Photoshop plug ins, is provided through plug in adapters, plug ins that map API calls between Illustrator 9.0 and the older or non native APIs of the other plug ins. Adapters will not be discussed in detail in this document. Adobe Illustrator SDK Programmers Guide 8

9 Anatomy of a Plug in Introduction Like most programs, Adobe 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 will also unload plug ins that are no longer needed. 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 various different types of Illustrator plug ins you can create. A single plug in file can contain more than one plug in type. For example, a shape creation plug in may implement several Plug in Filters and a Plug in Tool. Table 2: Types of plug ins Plug in Type Action File Format Effects Filter Menu Command Notifier Plugin Group Suite Timer Tool Transform again What it does Playback or register actions. Add file types to the open and save commands. Add menu items to the Effects menu. Add menu items to the Filters menu. Add menu items to the general menu structure. Receive and process art state events. Maintain display art which is associated with another art object Implement and publish your own suite of callback functions. Receive periodic notification. Add tools to the tool palette. Set transform again feature. Adobe Illustrator SDK Programmers Guide 9

10 Introduction Action Plug-ins Action plug-ins are used to execute Illustrator menu commands in a programmatic fashion, much like that of the Actions Palette. An Action plugin can register itself so that it can be recordable via the Actions Palette. 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 it wants. Once a file format plug in has registered a file type, files of that type will appear in the file list of the Open dialog. All file format plug ins that support saving will appear in the format menu of the Save As dialog. Figure 1: The Save As Dialog Plug in Filters Plug in filters appear under the Filter menu and are used to create or manipulate Illustrator artwork. Filters typically present a modal interface to the user, who can set parameters before executing. Illustrator 9.0 still supports version 7.0, 6.0 and 5.5 filter plug ins. Note: In other applications (including Adobe PageMaker and FrameMaker), the term filter or filter plug in is sometimes used to describe software that reads and writes non native files (e.g. TIFF or JPEG). In Adobe 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. 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 to Illustrator's Window menu. Plug in menu commands can be added at a variety of places in the menu structure. Adobe Illustrator SDK Programmers Guide 10

11 Introduction Plug in Notifiers and Timers Plug in notifiers and timers are used by a plug in to have Adobe Illustrator inform it of certain events. A timer plug in is notified at regular time intervals. For example, a timer plug in may request to be notified once a second. A notifier plug in is notified when the state of an Illustrator document changes. For example, a plug in may request that it be notified when the selection state has changed. A notifier plug in registers for one or more notifications during startup. Plugin Group Plug-ins Plugin Group plug-ins maintain one or more plugin groups. A plug-in group is a special art object which 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. Plugin groups are utilized to make special art types like Live Blends and Brushes. Plug in Tools Plug in tools add an icon to the main tool palette., expanding the number of tools available to the user. Many of the standard Illustrator tools, including the knife tool, the shape tools, and the 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 upon it. For example, a tool might create or distort objects. Some things are handled automatically for plug in tools, such as scrolling the window. Combining Multiple Plug in Types As mentioned before, it is quite likely that a single plug in file will implement multiple plug in types. A plug in may also need to add multiple instances of a single plug in type. The plug in API supports both of these cases. Where Plug ins Live Plug ins reside in the Plug ins folder. In general, each plug in type is located in a specific sub-folder, for example, tool plug ins are located in a folder named Tools. Adobe Illustrator SDK Programmers Guide 11

12 Introduction On both Mac and Windows platforms, Illustrator will only consider files with PiPL resources (PiPLs are introduced later in this chapter) to be plug ins. The type and extension are not important, however, by convention Macintosh plug ins have a creator/type of ART5 / ARPI, and on Windows an.aip extension. PiPL Resources PiPL resources contain metadata used by the Illustrator plug in manager, including: the type of the plug in, the calling mechanism for the plug in code, and the entry point name. It may also contain other information about the plug in. Refer to Plug in Property Lists on page 39 for more information about PiPL resources. The PiPL resource contains information about your plug in s type and how it is to be called. Illustrator will only consider files with PiPL resources to be potential plug ins. The type or extension of a file is not important, although most plug ins follow a standard convention for type and extension. Required Properties Your plug in s PiPL resource must include three required properties: The kind property indicates the type of the plug in file; it is akin to a file type. All Illustrator version 7 or 9 plug ins must contain a kind PiPL of SPEA. The interface version property ivrs describes to Illustrator the calling conventions expected by the plug in. It is currently 2. A code descriptor property indicates to Illustrator where your plug in code resides. Code descriptor values are defined for PowerPC Macintosh and Windows based plug ins. Adobe Illustrator SDK Programmers Guide 12

13 Introduction Exporting Functions Plug ins can export one or mores suites of functions (suites are discussed later in this chapter) for use by other plug ins. To ensure that the interdependencies of plug ins are handled correctly, plug ins declare in advance what they export. The loading order of plug ins becomes important when one plug in depends on a suites provided by another plug in. This export information is declared in PiPL export properties, expt, which contain the names and API version numbers of the suites that a plug in provides. The plug in manager uses this information to load and execute plug ins, ensuring that suites and other resources are available when needed. Plug in Loading Order 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. To ensure that the interdepencies of plug ins are handled correctly, plug ins that export one or more suites must declare what they export. Illustrator will use this information when loading and executing plug ins, ensuring that suites and other resources are available. The export information is declared in the PiPL resource as mentioned above. Illustrator's Artwork as Seen by a Plug in Most plug ins manipulate Illustrator artwork (including paths, text, and raster art) in some manner. Illustrator artwork objects are presented to plug ins as a hierarchical tree, which plug ins can freely modify. Plug ins can create, remove, and change the characteristics of artwork objects. For example, plug ins can: group objects, move or distort paths, adjust colors, search and change text. Plug in Messages The Illustrator plug in manager communicates with your plug in by loading the plug in code into memory if necessary, then calling its entry point. By convention, the entry point is called main on Mac OS, and PluginMain on Windows: #if Macintosh SPAPI SPErr main( char *caller, char *selector, void *data ) #else SPAPI SPErr PluginMain( char *caller, char *selector, void *data ) #endif {... Three arguments are passed to the main( ) routine, collectively they make up a message. The first two parameters represent the message action, describing what the plug in is supposed to do. The caller string identifies the sender of the message and a general category of action. The selector string specifies the action to take within the category of action. All plug ins will receive at least five message actions: reload, unload, startup, shutdown, and about. In addi- Adobe Illustrator SDK Programmers Guide 13

14 Introduction tion, your plug in may receive additional message actions specific to the plug in type. For example, plug ins that publish suites will receive acquire and release message actions when clients use a suite. The third parameter is a pointer to a data structure, which varies depending on the message action. Each time your plug in is called, it receives a message action from Illustrator. The message action notifies your plug in that an event has happened or tells your plug in to perform an action. Message Actions Strings By convention, caller strings begin with the name or abbreviation of the caller s application or company. For example, all action identifiers sent by the plug in manager begin with SP (short for Suite Pea, a now obsolete term used to describe Illustrator s plug in architecture). Illustrator message actions use four callers with many associated selectors. The standard Illustrator callers and selectors are described further below. Core Message Actions Table 3, Core Messages, on page 14 contains the set of core message actions received by all plug ins, and corresponding actions your plug in should take. Table 3: Core Messages Caller Selector Action to Perform kspaccesscaller ( SP Access ) kspinterfacecaller ( SP Interface ) kspaccessreloadselector ( Reload ) kspaccessunloadselector ( Unload ) kspinterfacestartupselector ( Startup ) Save any state information (globals) kspinterfaceshutdownselector ( Shutdown ) kspinterfaceaboutselector ( About ) Restore any state information (globals) Initialize globals, add features to the application Free globals, remove features from the application, and save preferences Show a dialog with information about your plug in Reload and Unload Messages Whenever a plug in is loaded into memory or unloaded from memory, the plug in manager sends an access message (caller SP Access ). This is your plug in s opportunity to setup, restore, or save state information. Access messages bracket all other messages. Reload will be the first message your plug in receives, Unload will be the last. Your plug in should not acquire or release suites other than those built into Illustrator at these times. Startup and Shutdown Messages When Illustrator is first 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. Adobe Illustrator SDK Programmers Guide 14

15 Introduction When the user quits Illustrator, it sends each plug in a Shutdown message. Shutdown is intended for flushing files and preserving preferences, not for destruction. A plug in that exports a suite should not dispose its plug in globals or suite information, since it may be called after its own shutdown by another plug in s shutdown. For example, if your plug in implements a preferences suite that other plug ins use, they may call you in their shutdown handlers after you ve already shut down. About Messages The About message action is used to display information about your plug in on the screen. Notifiers Some message actions are also referred to as notifiers, indicating that something in Illustrator has been changed by the user, for example when the user selects an object. Plug ins must register for notifiers (it would be very inefficient for Illustrator to notify every plug in when the user clicks on a object). The Notifier Suite is used to register and remove notification requests. Plug ins can also create their own notifiers, which can be used to broadcast changes to other plug ins. Handling Callers and Selectors Your plug in s organization is largely based 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: SPAPI SPErr main( char *caller, char *selector, void *data ) { SPErr error = kspnoerror; if ( strcmp( caller, kspaccesscaller ) == 0 ) { if ( strcmp( selector, kspaccessunloadselector ) == 0 ) error = MyPreserveGlobals( data ); else if ( strcmp( selector, kspaccessreloadselector ) == 0 ) error = MySetupGlobals( data ); ) else if ( strcmp( caller, kspinterfacecaller ) == 0 ) { if ( strcmp( selector, kspinterfacestartupselector ) == 0 ) error = MyStartupPlugin( data ); else if ( strcmp( selector, kspinterfaceaboutselector ) == 0 error = MyAboutPlugin( data ); // check for each of the other callers and selectors... else if ( strcmp( caller, kmyappmenucaller ) == 0 && strcmp( selector, kmyappgomenuselector ) == 0 ) error = MyHandleMenu( data ); // else if... 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 Adobe Illustrator SDK Programmers Guide 15

16 Introduction message action. For example, when a mouse clicked message action is received, the message data structure will contain the mouse position. While the contents of the message data varies, by convention all message data structures begin with three common fields, which are grouped into the SPMessageData structure: typedef struct { SPPluginRef self; void *globals; SPBasicSuite *basic; SPMessageData; The self field is a reference to the plug in being called. It is only needed when registering plug in suites, adapters, and other plug in data to Illustrator. The globals pointer is for use by your plug in. It is used to preserve any information between calls that it needs, and is usually a pointer to a block of memory allocated by your plug in at startup. Globals is preserved by Illustrator if your plug in is unloaded and reloaded. The basic field is a pointer to the Basic Suite, which allows your plug in to acquire and use other suites (suites are described in the next section.) Illustrator Suites The Illustrator plug in manager calls a plug in through the plug in s entry point, sending various messages as described in the previous section. When a plug in is active, it needs a way to perform actions within Illustrator. The mechanism for this is through plug in suites, which are one or more related functions grouped together in a C structure. Functions are grouped into suites based on the services they provide, for example the Path Suite contains functions that create and manipulate paths and segments. Typical suites contain 6 8 functions, although some suites may contain as few as one or more than 30 functions. In all, the Illustrator API offers more than 40 suites containing over 500 functions. Illustrator s suite architecture, known as the Plug in Component Architecture (PiCA) is also found in the latest versions of Adobe Photoshop and other Adobe applications. Conceptually, PiCA is similar to other software component architectures such as Microsoft s COM. Suites fall into two general categories. A suite either implements a plug in type (see Types of Plug ins on page 9) or it provides general functions. Suites which provide general functions make up the majority of the API; they provide a wide range of capabilities for manipulating text, gradients or raster images, or performing math functions. The following table lists several of the major suites and what they do: Adobe Illustrator SDK Programmers Guide 16

17 Introduction Table 4: Core Suites Suite Name Art Suite Block Suite Custom Color Suite Document Suite Fixed Math Suite Gradient Suite Group Suite Layer Suite Path Suite Random Suite Raster Suite Tag Suite Text Suite Services Provided access the artwork tree allocate and free memory create or work with custom colors get and set document information many useful math functions create or work with gradients make clipped groups get information about layers work with Illustrator paths generate random numbers work with raster objects associate information with art objects work with text objects Please refer to the Adobe Illustrator Suite Reference for a detailed description of each suite and its associated functions. Publishing Suites All plug ins will use suites, since they are the fundamental mechanism of the Illustrator API. Plug ins can also publish suites of their own, for use by other plug ins. This feature, where plug ins may be both clients of suites and publishers of suites, is extremely powerful. Several of the plug ins that are included with the Adobe Illustrator application (including all in the Required folder) publish suites that are used by many other plug ins. From the plug in s perspective, it is unimportant whether a particular suite is implemented within the Illustrator application itself or as a plug in. The Illustrator plug in manager is responsible for managing suites among various plug ins and the application. For more information on how to publish suites, refer to the Adobe Illustrator Suite Reference. Acquiring and Releasing Suites Before you can use a function in a suite, you must first acquire the suite. When the suite s functions are no longer needed, your plug in must release the suite. It is important to release suites so that the Illustrator plug in manager can run optimally. The plug in manager uses the acquire/release mechanism to determine when plug ins can be unloaded to free memory. When your plug in is first called, it only knows about the Basic Suite, which was introduced earlier in this chapter (as part of the SPMessageData structure). The Basic Suite is used to acquire and release other suites. The following code snippet shows how to use the Art suite (note that this code snippet is only intended to show the concepts of acquiring, using and releasing a suite, this is not the preferred way to acquire and release suites. Adobe Illustrator SDK Programmers Guide 17

18 Introduction Refer to the sample project source code to see how suites are normally acquired and released): SPAPI SPErr main( char *caller, char *selector, void *data ) { SPBasicSuite * sbasic = ((SPMessageData *) data)->basic; AIArtSuite *sart; sbasic->acquiresuite(kaiartsuite, kaiartsuiteversion, &sart); // use the Art suite functions. sart->getartfirstchild(...); sart->getartsibling(...);... sbasic->releasesuite(kaiartsuite, kaiartsuiteversion); return error; Where to Now? In this chapter we introduced plug ins for Adobe Illustrator, and defined a number of key concepts including: plug in manager plug in types messages and message actions notifiers loading and unloading acquiring, using and releasing suites The next chapter, Plug in Tutorial will explain the process of writing a plug in in more detail. The Adobe Illustrator Suite Reference describes each function in detail, and provides information on the various artwork objects and data structures you will need to complete the job. Finally, the sample projects in the SDK provides concrete examples and are a good starting point for your actual project. Adobe Illustrator SDK Programmers Guide 18

19 2Tutorial Chapter 2 - Tutorial Illustrator Plug-ins A plug-in is a piece of stand alone code that interfaces with the Illustrator application. The plug-in file is located in the application s plug-in folder. Your plug-in should have at least two properties: a resource of type PiPL, and a code entry point conforming to the one described below. Your plug-in will have the behavior and functionality provided by the Illustrator API. This would allow it to load and unload, provide suites of its own, and manage other plug-ins, for instance, sending other plug-ins messages. The capabilities of a plug-in beyond this will primarily depend on the API suites provided by Illustrator. What Defines a Plug-in? An Illustrator plug-in must have two characteristics. It must have a valid Plug-in Property List ( PiPL ) resource and it must have a code entry point described by the PiPL. A PiPL resource contains information about your plug-in s type and how it is to be called. Illustrator will only consider files with PiPL resources to be potential plug-ins. The type or extension of a file is not important in this regard. Files with the correct properties as described in the next section will be added to the plug-in list. The second characteristic of an Illustrator plug-in is that it must have code native to the platform on which it is to run. The entry point of the code is specified in the PiPL resource. While early plug-in APIs from Adobe would run 68k plug-ins from a PowerPC application or vice-versa, this mechanism is not provided to Illustrator 9 plug-ins. The entry point of the plug-in code will be called with a variety of messages telling it actions to take. Only plug-ins with the Illustrator 9 version information in the PiPL are recognized and included in Illustrator 9 s initial startup process. However, Illustrator version 6 and 5.5 plug-ins are supported by Adapters. A plug-in will be loaded into and unloaded from memory as needed by Illustrator. Your plug-in needs to be written assuming it will not always be kept in memory. This is why your plug in should save and restore state information during unload and reload. Your plug-in can expect certain services from the application. Because your plug-in may be unloaded, Illustrator provides it a means of storing important data when it is unloaded. Each time the plug-in is called it will be given enough information to accomplish the action to be performed. In most cases, this will include the basic suite so that it can acquire other suites. Adobe Illustrator SDK Programmers Guide 19

20 Tutorial PiPLs The PiPL is a resource critical to Illustrator 9 plug-ins as it contains the information needed to use the plug-in. As a minimum, it informs the Illustrator 9 plug-in manager about the type of the plug-in, the calling mechanism for the plug-in code, and where that code exists. It may also contain other information about the plug-in. PiPL stands for Plug-in Property List and PiPLs are described fully in the document "PiPLs in Adobe Illustrator.pdf". Your plug-in s PiPL must contain 3 properties: The kind property indicates the type of the plug-in file; it is akin to a file type. Illustrator 9 will find and use plug-ins with a PiPL kind of SPEA. The interface version property ivrs describes to Illustrator the calling conventions expected by the plug-in. It is currently 2. A code descriptor property indicates to Illustrator where your plug-in code resides. Code descriptors are available for 68k-based Macintosh, PowerPC Macintosh, and Windows based plug-ins. Your plug-in can have multiple code descriptor resources if is to run on several platforms. For example, a fat Macintosh plug-in would have 68k and PowerPC code descriptors. If your plug-in exports one or mores suites of functions it must have a fourth property to indicate this. The export property, expt, lists the names and api version numbers of the suites that a plug-in provides. When a request for an external suite is made, Illustrator will use the export PiPL to find the providing plug-in. When this has been done, the now available suite reference will be returned to the requesting code. The kind, version, and code descriptor properties described above should be in a standard platform resource. Examples are provided with the source code accompanying this document. Illustrator also provides a means of creating resources at runtime. The Plug-in Entry Point The compiled plug-in code referenced by the code descriptor is written in C. Illustrator communicates with your plug-in by calling its entry point (e.g. main( ) ), which is defined by the platform code descriptor in the PiPL. Here s what and entry point looks like: SPAPI SPErr PluginMain( char *caller, char *selector, void *data ) { SPErr error = kspnoerror;... return error; Three arguments are passed to the main( ) routine regardless of the reason it is called; together they make up a message. The first two are C style strings which identify the message action. The third is a pointer to a data structure. It is undefined at main( ) because it s content depends on the message action received. When you determine the message action, you will type cast the data as needed. The result of main( ) is a 4-byte error code. Message Actions: Callers and Selectors The message action passed to your plug-in consists of two identifiers, a caller and a selector. The caller indicates the sender of the message (the Suite Pea Adobe Illustrator SDK Programmers Guide 20

21 Tutorial API, the host application, or a plug-in) and a general category of action. The selector defines the action to take within that category. For instance, Adobe Illustrator will send a plug-in a message action based on these two unidentified strings: // Caller and Selector from the Menu Suite #define kcalleraimenu AI Menu #define kselectoraigomenuitem "Go Menu" The caller and selector identifiers are C style strings. This is so that new message actions can be easily defined by other applications and plug-ins with little chance of conflict. The convention used is as follows: for the caller to have a name or abbreviation of the caller s application or company at the start of the string. Since Illustrator 9 uses the Suite Pea API, all action identifiers begin with SP. Illustrator message actions use four callers with many associated selectors. The standard Illustrator callers and selectors are described further below. Whenever a plug-in is loaded into memory or unloaded from memory, Illustrator will send it an access message. The action will be the access caller and a reload or unload selector. This is your plug-ins opportunity to setup, restore, or save state information. The access caller/selectors bracket all other callers and selectors. The access/reload will be the first message received. The access/unload will be the last message received. A plug-in should not acquire or release suites other than those built into Illustrator at this time. #define kspaccesscaller "SP Access" #define kspaccessunloadselector"unload" #define kspaccessreloadselector"reload" Illustrator has three interface actions, where the plug-in can interact with the application. Illustrator will supplement these with its own interface-like actions. When Illustrator is first launched, it will startup all the plug-ins it finds. This is an opportunity for your plug-in to allocate global memory, add user interface items to Illustrator, and do other initialization. A plug-in adding components to Illustrator, such as suites and adapters, would do it at this time. The startup message action is received at this time: the interface caller and the startup selector. When the user quits Illustrator, it tells all of its plug-ins that it is shutting down. It will send each a shutdown message action, consisting of an interface caller and shutdown selector. Shutdown is intended for flushing files and preserving preferences, not for destruction. A plug-in that exports a suite should not dispose its plug-in globals or suite information, since it may be called after its own shutdown by another plug-in s shutdown. For example, if your plug-in implements a preferences suite that other plug-ins use, they may call you in their shutdown handlers after you ve already shut down. A third message action received by your plug-in is an opportunity to display information about a plug-in on the screen. The action is indicated by the interface caller and the about selector. #define kspinterfacecaller #define kspinterfacestartupselector #define kspinterfaceshutdownselector #define kspinterfaceaboutselector "SP Interface" "Startup" "Shutdown" "About" Adobe Illustrator SDK Programmers Guide 21

22 Tutorial The remaining Illustrator message actions are used by plug-ins to specify properties at runtime and by plug-ins that add API adapters. More information on using these selectors is in the related chapters. Handling Callers and Selectors Your plug-in s organization is largely based on the messages received by its main( ). The main routine of your plug-in basically becomes a switch implemented as a series of string compares that call functions appropriate for the message action caller and selector. For example: SPAPI SPErr main( char *caller, char *selector, void *message ) { SPErr error = kspnoerror; if ( strcmp( caller, kspaccesscaller ) == 0 ) { if ( strcmp( selector, kspaccessunloadselector ) == 0 ) error = UnloadPlugin( message ); else if ( strcmp( selector, kspaccessreloadselector ) == 0 ) error = ReloadPlugin( message ); else if ( strcmp( caller, kspinterfacecaller ) == 0 ) { if ( strcmp( selector, kspinterfacestartupselector ) == 0 ) error = StartupPlugin( message ); else if ( strcmp( selector, kspinterfaceshutdownselector)==0) error = ShutdownPlugin( message ); else if ( strcmp( selector, kspinterfaceaboutselector ) == 0) error = AboutPlugin( message ); // check for each of the other callers and selectors... else if ( strcmp( caller, kcalleraimenu ) == 0 && strcmp( selector, kselectoraigomenuitem ) == 0 ) error = GoMenuItem( message ); // else if... return error; Message Data The other argument passed to your plug-in entry point is a pointer to a message data structure. This structure contains enough information for the plug-in to handle the message. For example, if the message action was that a mouse was clicked, the message data structure would contain the mouse position. The contents of the message data structure depend on the message action and are not completely known until your plug-in has identified this. Most Suite PEA messages will have a minimum set of information embedded in the structure, the SPMessageData structure at the beginning of the message data structure. Illustrator plug-ins expect that the message data is embedded. typedef struct { SPPluginRef self; void *globals; SPBasicSuite *basic; SPMessageData; typedef struct { SPMessageData d; SPcallerMessage; Adobe Illustrator SDK Programmers Guide 22

23 Tutorial The core of any plug-in message data is set by Illustrator and includes the basic information for the plug-in to operate. The self member is a reference to the plug-in being called. The globals member is a 4-byte value specified by and preserved for your plug-in. The basic member is a reference to the Basic Suite. 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 will store this value with the added data. It will then be used to recall your plug-in as needed. Your plug-in can set the globals member to any four byte value; most likely this will be a pointer to a block of memory allocated by your plug-in. This value will be 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. The SPBasic suite reference basic contains functions with which the plug-in can acquire and release any other suites it needs to run. The message data structure received by your plug-in when the message action s caller is kspinterfacecaller is an SPIntefaceMessage structure. This is simply a container for the SPMessageData: typedef struct SPInterfaceMessage { SPMessageData d; SPInterfaceMessage; The message data structure received by your plug-in when the message action s caller is kspaccesscaller is an SPAccessMessage structure. This is simply a container for the SPMessageData: typedef struct SPAccessMessage { SPMessageData d; SPAccessMessage; When Illustrator or a plug-in wishes to send a message to your plug-in, it will pass in a relevant message data structure. Each caller has a unique message structure. For example, Illustrator s Menu Suite has the following message structure: typedef struct { SPMessageData d; AIMenuItemHandle menuitem; AIMenuMessage; It includes the SPMessageData at the beginning of the structure followed by a reference to a menu item that has been executed. Using Suites and Callback Functions Illustrator s API is composed of callback functions organized into suites. Before your plug-in can use a function that is part of a suite, the suite containing it must first be acquired. A function suite is a structure filled with function pointers and when your plug-in acquires a suite, a pointer to this structure is returned. Adobe Illustrator SDK Programmers Guide 23

24 Tutorial When the function suite is no longer needed, the acquired suite is released. It is important to do this so that the Illustrator plug-in manager can run optimally. For instance, Illustrator keeps track of how many times a suite has been acquired. If a suite added by plug-in is no longer in use (its access count is 0), the plug-in may be unloaded to free memory. Acquiring and Releasing Suites When your plug-in is first called it only knows about one suite. The message data structure passed to all plug-ins has a member variable basic, which points to the SP Basic Suite. The basic suite is used to access other suites and contains two important functions for doing so: SPAPI SPErr (*AcquireSuite)( char *name, long version,void **suite ); SPAPI SPErr (*ReleaseSuite)( char *name, long version ); A plug-in uses the first function, AcquireSuite( ), to gain access to a suite of functions. All acquired suites must be released with the ReleaseSuite( ) function when the suite is unneeded. To acquire a suite, you first need to declare a suite pointer. For instance, suppose you need to use Illustrator s Menu Suite which defines the following: #define kaimenusuite "AI Menu Suite" #define kaimenuversion 5 typedef struct { AIAPI AIErr (*AddMenuItem) ( SPPluginRef self, char *name, AIPlatformAddMenuItemData *data, long options, AIMenuItemHandle *menuitem ); AIAPI AIErr (*GetMenuItemName) ( AIMenuItemHandle menuitem, char **name ); AIAPI AIErr (*GetMenuItemOptions) ( AIMenuItemHandle menuitem, long *options ); AIAPI AIErr (*SetMenuItemOptions) ( AIMenuItemHandle menuitem, long options ); AIAPI AIErr (*GetMenuItemPlugin) ( AIMenuItemHandle menuitem, SPPluginRef *plugin ); AIMenuSuite; The plug-in s reference to the above suite would be: AIMenuSuite *saimenu; // The "AI" stands for Adobe Illustrator // because it is an AI suite A suite is acquired and released using its name and version number, found in its public header file. So to acquire the above menu, you would do something like this: SPErr error; error = (*message)->d.basic->acquiresuite( kaimenusuite, kaimenusuiteversion, &saimenu ); A pointer to the acquired suite s functions is returned in saimenu. Adobe Illustrator SDK Programmers Guide 24

25 Tutorial Calling a Suite Function The example above calls a function in the basic suite. Functions in other suites are called using a pointer to an acquired suite. For instance, the above variable saimenu points to the structure with the AI menu suite function pointers. The suite function pointer is dereferenced and used as a function pointer using the calling form: saimenu->somefunction(); Since they are used throughout the plug-in code, it is convenient to make suite variables global. The convention used for these global variables is a small s followed by the owner of the suite, followed by the suite name, e.g. sbasic as shown above, saimenu for the menu suite, etc. A Simple Example Suppose your plug-in is going to add a menu item to Illustrator. To do this it must use the AddMenu( ) function, which is a part of the AI Menu Suite, version 5. The suite name and version number are passed to the Acquire- Suite( ) function. After the function is used, the suite is release. This whole process is demonstrated below. SPBasicSuite *sbasic = message->d.basic; AIMenuSuite *saimenu; SPErr error; // request the needed suite error = sbasic->acquiresuite( kaimenusuite, 5, &saimenu ); if ( error ) goto error; // use the suite error = saimenu->addmenu( message->plugin, nil ); // release the suite sbasic->releasesuite( kaimenusuite, 5 ); error: handleerror( error ); Suite.h Files Every suite will have the suite name and version in the suite header file as well as other definitions, such as error strings, particular to their function. If the suite defines plug-in messages they will also be found in the header file. At the end are the suite functions. The function pointers should be fully prototyped. Callers and Selectors This section will describe and illustrate what the various caller/selector pairs mean and what your plug-in is expected to do in response to receiving them. There will be references to the Tutorial sample throughout this section. The Tutorial sample can be found in the Sample Code folder on the SDK. Adobe Illustrator SDK Programmers Guide 25