AILiveEffectSuite Struct Reference
[API Suite List]

This suite allows your plug-in to implement a Live Effect. More...

#include <AILiveEffect.h>

Public Attributes
AIAPI AIErr(*	AddLiveEffect )(AILiveEffectData effectInfo, AILiveEffectHandle liveEffectHandle)
	Registers a Live Effect.
AIAPI AIErr(*	AddLiveEffectFilterItem )(AILiveEffectHandle liveEffectHandle, AIFilterHandle filterHandle, AIMenuItemHandle menuItem, AIMenuGroup menuGroup)
	Adds a menu item for a Live Effect to the Effects menu, using a predefined filter.
AIAPI AIErr(*	AddLiveEffectMenuItem )(AILiveEffectHandle liveEffectHandle, const char menuName, AddLiveEffectMenuData menuData, AIMenuItemHandle menuItem, AIMenuGroup menuGroup)
	Adds a menu item for a Live Effect to the Effects menu.
AIAPI AIErr(*	ExecuteLiveEffect )(AILiveEffectHandle effect, AILiveEffectParameters parameters, AIArtHandle art)
	Not implemented.
AIAPI AIErr(*	EditParameters )(AILiveEffectParamContext context, AIBoolean enablePreview)
AIAPI AIErr(*	UpdateParameters )(AILiveEffectParamContext context)
	If previews are enabled for an effect, call this after modifying the parameters to update the associated artwork.
AIAPI AIErr(*	InterpolateEffectParameters )(AILiveEffectHandle effect, AILiveEffectParameters startParams, AILiveEffectParameters endParams, AIReal percent, AILiveEffectParameters resultParams)
	Interpolates a point into the current parameter set for an effect.
AIAPI AIErr(*	CountLiveEffects )(ai::int32 *count)
	Gets the number of registered effects available to the application.
AIAPI AIErr(*	GetNthLiveEffect )(ai::int32 n, AILiveEffectHandle *effect)
	Retrieves an effect reference by position index.
AIAPI AIErr(*	GetLiveEffectName )(AILiveEffectHandle effect, const char **name)
	Retrieves the unique identifying name of an effect.
AIAPI AIErr(*	GetLiveEffectTitle )(AILiveEffectHandle effect, const char **name)
	Retrieves the localizable display name of an effect.
AIAPI AIErr(*	GetLiveEffectVersion )(AILiveEffectHandle effect, ai::int32 major, ai::int32 minor)
	Retrieves the version information for a registered effect.
AIAPI AIErr(*	GetInputPreference )(AILiveEffectHandle effect, ai::int32 *inputPreference)
	Retrieves the preferred input art types of a registered effect.
AIAPI AIErr(*	GetStyleFilterFlags )(AILiveEffectHandle effect, ai::int32 *styleFilterFlags)
	Retrieves the style flags of a registered effect.
AIAPI AIErr(*	MergeLiveEffectIntoSelection )(AILiveEffectHandle effect, AILiveEffectMergeAction action)
	Merges an effect into the existing style of all selected objects.
AIAPI AIErr(*	NewArtStyleByMergingLiveEffect )(AIArtStyleHandle artStyle, AILiveEffectHandle effect, AILiveEffectParameters params, AILiveEffectMergeAction action, AIArtStyleHandle *newArtStyle)
	Creates a new art style by merging live effect into an existing art style.
AIAPI AIMenuItemHandle(*	GetMenuItem )(AILiveEffectParamContext context)
	While handling an `AILiveEffectEditParamMessage`, retrieves the menu item used to invoke the effect.
AIAPI AIErr(*	CreateLiveEffectParameters )(AILiveEffectParameters *params)
	Creates a parameter dictionary to be used in constructing a style with the `AIArtStyleParserSuite`.
AIAPI AIErr(*	GetLiveEffectAppVersion )(AILiveEffectHandle effect, AIVersion appVersionRGB, AIVersion appVersionCMYK)
	Retrieves the earliest Illustrator version that an effect supports.
AIAPI AIErr(*	SetLiveEffectAppVersion )(AILiveEffectHandle effect, AIVersion appVersionRGB, AIVersion appVersionCMYK)
	Sets the earliest Illustrator version that an effect supports.
AIAPI AIErr(*	GetLiveEffectHandleByName )(const char liveEffectName, AILiveEffectHandle outLiveEffect)

Detailed Description

This suite allows your plug-in to implement a Live Effect.

A Live Effect is a filter that can be attached to an art object as part of its style. Any time the art object is changed, the filter is automatically re-executed. More than one filter can be attached to an object, which allows filter chains and stacks.

A chain is a pipeline where the output of one filter becomes the input to the next.
A stack passes the same input art to a set of filters, stacking the output of each filter.

If a document contains a Live Effect that is not available, the document can be opened, but art with that effect applied cannot be edited.

Your Live Effect plug-in must respond to the caller kCallerAILiveEffect and the following selectors:
kSelectorAIEditLiveEffectParameters
kSelectorAIGoLiveEffect
kSelectorAILiveEffectInterpolate
kSelectorAILiveEffectInputType
kSelectorAILiveEffectConverColorSpace
kSelectorAILiveEffectScaleParameters
kSelectorAILiveEffectHandleMerge
kSelectorAILiveEffectGetSVGFilter

Most Live Effects have a set of parameters that control their behavior. For example, the Roughen effect has parameters for the size and detail of the roughening. You can store these in the parameter dictionary that is associated with the effect in the style. Use the AIDictionarySuite to access the contents of the dictionary. You can store any information in the parameter dictionary; however the following keys are predefined:
kDisplayStringKey
kExtraStringKey
kFillStyleKey
kEvenOddKey
kStrokeStyleKey
kScaleFactorKey
kAILiveEffectParamsExpandBeforeKey

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAILiveEffectSuite and kAILiveEffectVersion.

Member Data Documentation

AIAPI AIErr(* AILiveEffectSuite::AddLiveEffect)(AILiveEffectData *effectInfo, AILiveEffectHandle *liveEffectHandle)

Registers a Live Effect.

Parameters:

	effectInfo	A pointer to the structure that defines the effect. You must allocate and fill the structure before making the call.
	liveEffectHandle	[out] A buffer in which to return the effect object.

AIAPI AIErr(* AILiveEffectSuite::AddLiveEffectFilterItem)(AILiveEffectHandle liveEffectHandle, AIFilterHandle filterHandle, AIMenuItemHandle *menuItem, AIMenuGroup *menuGroup)

Adds a menu item for a Live Effect to the Effects menu, using a predefined filter.

Parameters:

	liveEffectHandle	The effect object.
	filterHandle	The filter containing the category, title, and options, as returned by `AIFilterSuite::AddFilter()`. If no filter exists with the correct data, use `AddLiveEffectMenuItem()`.
	menuItem	[out] A buffer in which to return the new menu item, or `NULL` if you do not need the object.
	menuGroup	[out] A buffer in which to return the menu group to which the item was added, or `NULL` if you do not need the object.

AIAPI AIErr(* AILiveEffectSuite::AddLiveEffectMenuItem)(AILiveEffectHandle liveEffectHandle, const char *menuName, AddLiveEffectMenuData *menuData, AIMenuItemHandle *menuItem, AIMenuGroup *menuGroup)

Adds a menu item for a Live Effect to the Effects menu.

Parameters:

	liveEffectHandle	The effect object.
	menuName	The unique identifying name for the new menu item. Not localized.
	menuData	A pointer to the structure that defines the menu. You must allocate and fill the structure before making the call. If a filter already exists with the correct data, use `AddLiveEffectFilterItem()`.
	menuItem	[out] A buffer in which to return the new menu item, or `NULL` if you do not need the object.
	menuGroup	[out] A buffer in which to return the menu group to which the item was added, or `NULL` if you do not need the object. Returns `NULL` if the item was added at the top level of the Effects menu.

AIAPI AIErr(* AILiveEffectSuite::CountLiveEffects)(ai::int32 *count)

Gets the number of registered effects available to the application.

Use with GetNthLiveEffect() to iterate through all installed effects.

Parameters:

count

[out] A buffer in which to return the number of registered effects.

AIAPI AIErr(* AILiveEffectSuite::CreateLiveEffectParameters)(AILiveEffectParameters *params)

Creates a parameter dictionary to be used in constructing a style with the AIArtStyleParserSuite.

Do not use in any other context. If you are using the AIArtStyleParserSuite to construct a new style from scratch, and you need to create a parameter dictionary for an effect, use this function to create the parameter dictionary, rather than AIDictionarySuite::CreateDictionary(). The dictionary created by this function supports Undo operations, which the generic one does not.

Dictionaries are reference counted; the initial reference count for this dictionary is 1. When there are no remaining references, free the associated memory using AIDictionarySuite::Release().

Parameters:

params

[out] A buffer in which to return the new parameters block.

AIAPI AIErr(* AILiveEffectSuite::EditParameters)(AILiveEffectParamContext context, AIBoolean enablePreview)

Note:: Internal. Do not use.

Displays a dialog box in which the use can enter parameter values.

Parameters:

	context	[in, out] The parameter context passed in the `AILiveEffectEditParamMessage`. Modify in place with new values.
	enablePreview	True if previews are enabled for this effect. When true, pass the returned context to `UpdateParameters()` to update the associated artwork.

AIAPI AIErr(* AILiveEffectSuite::ExecuteLiveEffect)(AILiveEffectHandle effect, AILiveEffectParameters parameters, AIArtHandle art)

Not implemented.

AIAPI AIErr(* AILiveEffectSuite::GetInputPreference)(AILiveEffectHandle effect, ai::int32 *inputPreference)

Retrieves the preferred input art types of a registered effect.

Parameters:

	effect	The effect object.
	name	[out] A buffer in which to return the input art preferences, a logical OR of `AIStyleFilterPreferredInputArtType` values.

AIAPI AIErr(* AILiveEffectSuite::GetLiveEffectAppVersion)(AILiveEffectHandle effect, AIVersion *appVersionRGB, AIVersion *appVersionCMYK)

Retrieves the earliest Illustrator version that an effect supports.

If you do not use this call, the version defaults to 9 (the first version to support Live Effects). If an object with this effect is saved to an earlier version, only the styled art is written out. For some effects, the earliest version supported for RGB or for CMYK can be different.

Parameters:

	effect	The effect object.
	appVersionRGB	[out] A buffer in which to return the earliest version number that the effect supports for RGB documents. May be `NULL`.
	appVersionCMYK	[out] A buffer in which to return the earliest version number that the effect supports for CMYK documents. May be `NULL`.

AIAPI AIErr(* AILiveEffectSuite::GetLiveEffectHandleByName)(const char *liveEffectName, AILiveEffectHandle *outLiveEffect)

AIAPI AIErr(* AILiveEffectSuite::GetLiveEffectName)(AILiveEffectHandle effect, const char **name)

Retrieves the unique identifying name of an effect.

To get the localizable display name, use GetLiveEffectTitle().

Parameters:

	effect	The effect object.
	name	[out] A buffer in which to return the name string.

AIAPI AIErr(* AILiveEffectSuite::GetLiveEffectTitle)(AILiveEffectHandle effect, const char **name)

Retrieves the localizable display name of an effect.

To get the unique identifying name, use GetLiveEffectName().

Parameters:

	effect	The effect object.
	name	[out] A buffer in which to return the display name string.

AIAPI AIErr(* AILiveEffectSuite::GetLiveEffectVersion)(AILiveEffectHandle effect, ai::int32 *major, ai::int32 *minor)

Retrieves the version information for a registered effect.

Parameters:

	effect	The effect object.
	major	[out] A buffer in which to return the major version number.
	minor	[out] A buffer in which to return the minor version number.

AIAPI AIMenuItemHandle(* AILiveEffectSuite::GetMenuItem)(AILiveEffectParamContext context)

While handling an AILiveEffectEditParamMessage, retrieves the menu item used to invoke the effect.

(Note that this function returns an object value, not an error code.)

Parameters:

context The parameter context, as passed in the AILiveEffectEditParamMessage.

Returns:: The menu item object, or NULL if the message was not invoked by a menu item. Returns NULL if not called while handling an Edit message.

AIAPI AIErr(* AILiveEffectSuite::GetNthLiveEffect)(ai::int32 n, AILiveEffectHandle *effect)

Retrieves an effect reference by position index.

Use with CountLiveEffects() to iterate through all installed effects.

Parameters:

	n	The index, in the range `[0..numEffects-1]`.
	effect	[out] A buffer in which to return the effect object.

AIAPI AIErr(* AILiveEffectSuite::GetStyleFilterFlags)(AILiveEffectHandle effect, ai::int32 *styleFilterFlags)

Retrieves the style flags of a registered effect.

Parameters:

	effect	The effect object.
	name	[out] A buffer in which to return the style flags, a logical OR of `AIStyleFilterFlags` values.

AIAPI AIErr(* AILiveEffectSuite::InterpolateEffectParameters)(AILiveEffectHandle effect, AILiveEffectParameters startParams, AILiveEffectParameters endParams, AIReal percent, AILiveEffectParameters resultParams)

Interpolates a point into the current parameter set for an effect.

Sends the plug-in that owns the effect the AILiveEffectInterpParamMessage.

Parameters:

	effect	The effect object.
	startParams	A parameters block for the starting point.
	endParams	A parameters block for the ending point.
	percent	A percentage of the distance between the start and end parameters, expressed as a value in the range [0..1]. The new value is interpolated at this point.
	resultParams	[out] A parameters block in which the new interpolated point is returned.

AIAPI AIErr(* AILiveEffectSuite::MergeLiveEffectIntoSelection)(AILiveEffectHandle effect, AILiveEffectMergeAction action)

Merges an effect into the existing style of all selected objects.

Parameters:

	effect	The effect object.
	action	The merge method (append, or replace fill and/or stroke), and whether to send a `kSelectorAILiveEffectHandleMerge` message to handle the parameters for a replacement method.

AIAPI AIErr(* AILiveEffectSuite::NewArtStyleByMergingLiveEffect)(AIArtStyleHandle artStyle, AILiveEffectHandle effect, AILiveEffectParameters params, AILiveEffectMergeAction action, AIArtStyleHandle *newArtStyle)

Creates a new art style by merging live effect into an existing art style.

Parameters:

	artStyle	The input art style.
	effect	The effect object.
	params	The Live Effect parameters.
	action	The merge method (append, or replace fill and/or stroke), and whether to send a `kSelectorAILiveEffectHandleMerge` message to handle the parameters for a replacement method.
	newArtStyle	[out] A buffer in which to return the new art style reference.

AIAPI AIErr(* AILiveEffectSuite::SetLiveEffectAppVersion)(AILiveEffectHandle effect, AIVersion appVersionRGB, AIVersion appVersionCMYK)

Sets the earliest Illustrator version that an effect supports.

If an object with this effect is saved to an earlier version, only the styled art is written out. For some effects, the earliest version supported for RGB or for CMYK can be different. See also kAILiveEffectParamsExpandBeforeKey for situations where the compatibility decision is dependent upon the effect options.

Parameters:

	effect	The effect object.
	appVersionRGB	The earliest version number that the effect supports for RGB documents. Must be 9 or later.
	appVersionCMYK	The earliest version number that the effect supports for CMYK documents. Must be 9 or later.

AIAPI AIErr(* AILiveEffectSuite::UpdateParameters)(AILiveEffectParamContext context)

If previews are enabled for an effect, call this after modifying the parameters to update the associated artwork.

The plug-in receives an AILiveEffectGoMessage after updating parameters.

Parameters:

context The parameter context, as received in a AILiveEffectEditParamMessage.

See also:: AILiveEffectInterpParamMessage

The documentation for this struct was generated from the following file:

AILiveEffect.h

AILiveEffectSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AILiveEffectSuite Struct Reference
[API Suite List]