C
HAPTER
2: Tutorial
Plug-in type-specific messages
26
else if ( strcmp( selector, kSelectorAIGoFilter ) == 0 )
error = GoFilter( ( AIFilterMessage* )message );
}
When the user chooses your filter in the Object menu, your plug-in is first called with
kSelectorAIGetFilterParameters
. You should get whatever parameters you need from the user and
place them in a handle, storing the handle in the
parameters
field of
AIFilterMessage
. This is similar to
how the
globals
field is used, only
parameters
must be a handle if it is not nil. The
parameters
handle is
given back to you on subsequent calls; therefore, it is necessary to create this handle only once. Each time
you receive the get-filter-parameters selector, you can use the previous parameters to set the default
dialog values. If your plug-in places more than one filter in the Object menu, a separate
parameters
handle is kept for each one. Illustrator does not care about the specific contents of the
parameters
handle,
but the handle must be self contained; that is, you cannot include pointers or handles to more data inside
the
parameters
handle. This is because Illustrator may make copies of the parameters and does not know
how to copy blocks of memory referenced by the structure. If you do not have any parameters, leave this
field zero.
The parameters used by the Tutorial plug-in’s filter are shown below:
typedef struct {
ASInt32 corners;
// number of corners on the polygon
ASInt32 size;
// the maximum size, in points
} MyFilterParameters;
These parameters are obtained from the user by the
GetFilterParameters
function in
Tutorial.cpp
.
The return result from
GetFilterParameters
should be
kNoErr
if the user hit OK (or if you do not have
any parameters) or
kCanceledErr
if the user cancels the filter.
Immediately after the plug-in returns from
GetFilterParameters
, it is sent the go-filter selector pair
(
kCallerAIFilter
/
kSelectorAIGoFilter
). When the plug-in receives this, it performs whatever the
filter does, using the globals and parameters the plug-in set up previously. The Tutorial plug-in’s
GoFilter
function in
Tutorial.cpp
creates a random polygon each time it is called, by creating a new path art
object and adding path segments to it.
Tool plug-ins
Illustrator allows plug-ins to add new tools to the Tools panel. To add a tool, your plug-in must do the
following:
X
Provide an icon to represent the tool in the Tools panel.
X
Call
AIToolSuite::AddTool
on start-up, to add the tool to Illustrator.
X
Handle tool-related messages relating to mouse events. For example, when the plug-in’s tool is
selected in the Tools panel and the mouse button goes down and is released, the plug-in is notified by
a selector message (
kCallerAITool
/
kSelectorAIToolMouseDown
). A similar approach is used to
communicate mouse drag events, and so on.
The Tutorial plug-in adds a line-drawing tool by calling
AIToolSuite::AddTool
on start-up. For sample
code, see the
AddTool
function in
Tutorial.cpp
.
The added tool appears in the Tools panel. When it is selected and used, Illustrator calls the plug-in with
the tool selectors listed above. To create a minimal straight-line tool, the plug-in needs to handle only the
mouse-down selector. The Tutorial plug-in’s
PluginMain
function handles this as follows: