AILiveEffect.h File Reference

#include "AITypes.h"
#include "AIArt.h"
#include "AIDictionary.h"
#include "AIFilter.h"
#include "AIMenu.h"
#include "AIPlugin.h"
#include "AIXMLElement.h"
#include "AIHeaderBegin.h"
#include "AIHeaderEnd.h"

Go to the source code of this file.

Classes
struct	AddLiveEffectMenuData
	Defines the menu item for a Live Effect. More...
struct	AILiveEffectData
	Information supplied when registering a Live Effect with AILiveEffectSuite::AddLiveEffect(). More...
struct	AILiveEffectGoMessage
	Sent when the user chooses your registered effect from the Effects menu, after the Edit parameters message that allows you to collect parameter values from the user. More...
struct	AILiveEffectEditParamMessage
	Sent when the user chooses a your registered effect from the Effects menu, or when the user later edits the effect using the appearance palette. More...
struct	AILiveEffectInterpParamMessage
	Sent when the user chooses to interpolate a new point into the parameter set for an effect. More...
struct	AILiveEffectInputTypeMessage
	Sent when the user selects an effect whose input type is kInputArtDynamic. More...
struct	AILiveEffectConvertColorMessage
	Sent with a request to convert any private color data the plug-in has stored in a dictionary to a new color space. More...
struct	AILiveEffectAdjustColorsMessage
	Sent with kSelectorAILiveEffectAdjustColors to allow another plug-in that does color manipulations to extract and/or modify any private color data that the effect plug-in has stored in its parameter dictionary, including colors contained indirectly in art objects, art styles or symbol references. More...
struct	AILiveEffectScaleParamMessage
	Sent with a request to scale effect parameters. More...
struct	AILiveEffectHandleMergeMessage
	Sent to a plug-in that has initiated a merge with AILiveEffectSuite::MergeLiveEffectIntoSelection(), so that the plug-in can handle the merge operation. More...
struct	AILiveEffectGetSVGFilterMessage
	Sent with a request to obtain an SVG filter representation of an effect. More...
struct	AILiveEffectIsCompatibleMessage
	Sent when saving a file to allow the live effect to make a detailed check for legacy compatibility. More...
struct	AILiveEffectSuite
	This suite allows your plug-in to implement a Live Effect. More...
Defines
#define	kAILiveEffectSuite   "AI Live Effect Suite"
#define	kAILiveEffectSuiteVersion   AIAPI_VERSION(6)
#define	kAILiveEffectVersion   kAILiveEffectSuiteVersion
#define	kCallerAILiveEffect   "AI Live Effect"
	The Live Effect caller.
#define	kAILiveEffectParamsExpandBeforeKey   "Adobe Effect Expand Before Version"
	If your effect gets new options in a later version that are not supported by earlier versions, such that the objects carrying the new options should be expanded (output as the styled art only) upon legacy save, while objects with options supported by the older versions should NOT be expanded, then set the value of this key in the effect's parameter dictionary to the app version which first supports the new option values (as an integer, e.g., CS 5 = 15).
#define	kAILiveEffectParamsWriteAlternateVersionMajorKey   "Adobe Effect Expand Write Alternate Version Major"
#define	kAILiveEffectParamsWriteAlternateVersionMinorKey   "Adobe Effect Expand Write Alternate Version Minor"
#define	kSelectorAIEditLiveEffectParameters   "AI Live Effect Edit Parameters"
	Sends an AILiveEffectEditParamMessage.
#define	kSelectorAIGoLiveEffect   "AI Live Effect Go Live"
	Sends an AILiveEffectGoMessage.
#define	kSelectorAILiveEffectInterpolate   "AI Live Effect Interpolate Parameters"
	Sends an AILiveEffectInterpParamMessage.
#define	kSelectorAILiveEffectInputType   "AI Live Effect Input Type"
	Sends an AILiveEffectInputTypeMessage.
#define	kSelectorAILiveEffectConverColorSpace   "AI Live Effect Convert Color Space"
	Sends an AILiveEffectConvertColorMessage.
#define	kSelectorAILiveEffectScaleParameters   "AI Live Effect Scale Parameters"
	Sends an AILiveEffectScaleParamMessage.
#define	kSelectorAILiveEffectHandleMerge   "AI Live Effect Handle Merge"
	Sends an AILiveEffectHandleMergeMessage.
#define	kSelectorAILiveEffectGetSVGFilter   "AI Live Effect Get SVG Filter"
	Sends an AILiveEffectGetSVGFilterMessage.
#define	kSelectorAILiveEffectAdjustColors   "AI Live Effect Adjust Colors"
	Sends an AILiveEffectAdjustColorsMessage.
#define	kSelectorAILiveEffectIsCompatible   "AI Live Effect Is Compatible"
	Sends an AILiveEffectIsCompatibleMessage.
#define	kDisplayStringKey   "DisplayString"
	Dictionary key for a Live Effect parameter.
#define	kExtraStringKey   "ExtraString"
	Dictionary key for a Live Effect parameter.
#define	kFillStyleKey   "FillStyle"
	Dictionary key for a Live Effect parameter.
#define	kTransformedFillStyleKey   "TransformedFillStyle"
	Dictionary key for a Live Effect parameter.
#define	kFillStyleMatrixKey   "FillStyleMatrix"
	Dictionary key for a Live Effect parameter.
#define	kEvenOddKey   "UseEvenOdd"
	Dictionary key for a Live Effect parameter.
#define	kStrokeStyleKey   "StrokeStyle"
	Dictionary key for a Live Effect parameter.
#define	kTransformedStrokeStyleKey   "TransformedStrokeStyle"
	Dictionary key for a Live Effect parameter.
#define	kStrokeStyleMatrixKey   "StrokeStyleMatrix"
	Dictionary key for a Live Effect parameter.
#define	kScaleFactorKey   "ScaleFactorString"
	Dictionary key for a Live Effect parameter.
Typedefs
typedef struct _t_AILiveEffectOpaque *	AILiveEffectHandle
	Opaque reference to a Live Effect.
typedef struct _t_AILiveEffectParamContext *	AILiveEffectParamContext
	Opaque reference to a Live Effect parameter context.
typedef AIDictionaryRef	AILiveEffectParameters
	The parameters for a Live Effect, stored in a dictionary.
typedef ConstAIDictionaryRef	ConstAILiveEffectParameters
Enumerations
enum	AIStyleFilterFlags {   kNoFlags = 0, kPreEffectFilter = 0x1, kPostEffectFilter = 0x2, kStrokeFilter = 0x3,   kFillFilter = 0x4, kFilterTypeMask = 0x0ffff, kSpecialGroupPreFilter = 1 << 16, kHasScalableParams = 1 << 17,   kUsesAutoRasterize = 1 << 18, kCanGenerateSVGFilter = 1 << 19, kHandlesAdjustColorsMsg = 1 << 20, kHandlesIsCompatibleMsg = 1 << 21 }
	Bit flags for Live Effect style properties, which specify how the filter is applied and what features it supports. More...
enum	AIStyleFilterPreferredInputArtType {   kInputArtDynamic = 0, kGroupInputArt = 1 << ((ai::int32) kGroupArt - 1), kPathInputArt = 1 << ((ai::int32) kPathArt - 1), kCompoundPathInputArt = 1 << ((ai::int32) kCompoundPathArt - 1),   kTextInputArtUnsupported = 1 << ((ai::int32) kTextArtUnsupported - 1), kTextPathInputArtUnsupported = 1 << ((ai::int32) kTextPathArtUnsupported - 1), kTextRunInputArtUnsupported = 1 << ((ai::int32) kTextRunArtUnsupported - 1), kPlacedInputArt = 1 << ((ai::int32) kPlacedArt - 1),   kMysteryPathInputArt = 1 << ((ai::int32) kMysteryPathArt - 1), kRasterInputArt = 1 << ((ai::int32) kRasterArt - 1), kPluginInputArt = 1 << ((ai::int32) kPluginArt - 1), kMeshInputArt = 1 << ((ai::int32) kMeshArt - 1),   kTextFrameInputArt = 1 << ((ai::int32) kTextFrameArt - 1), kSymbolInputArt = 1 << ((ai::int32) kSymbolArt - 1), kForeignInputArt = 1 << ((ai::int32) kForeignArt - 1), kLegacyTextInputArt = 1 << ((ai::int32) kLegacyTextArt - 1),   kChartInputArt = 1 << ((ai::int32) kChartArt - 1), kAnyInputArt = 0xFFFF, kAnyInputArtButPluginArt = kAnyInputArt & ~kPluginInputArt, kOutlinedStrokeInputArt = 0x10000,   kNoClipMasksInputArt = 0x20000 }
	The kinds of objects in input art that an effect can operate on. More...
enum	AILiveEffectMergeAction { kAppendLiveEffectToStyle, kReplaceFillWithLiveEffect, kReplaceStrokeWithLiveEffect, kSendHandleMergeMessage = 0x10000 }
	Ways that a Live Effect can be merged with the existing styles of selected objects. More...

---

Detailed Description

---

Define Documentation

#define kAILiveEffectParamsExpandBeforeKey   "Adobe Effect Expand Before Version"

If your effect gets new options in a later version that are not supported by earlier versions, such that the objects carrying the new options should be expanded (output as the styled art only) upon legacy save, while objects with options supported by the older versions should NOT be expanded, then set the value of this key in the effect's parameter dictionary to the app version which first supports the new option values (as an integer, e.g., CS 5 = 15).

See also c\ AILiveEffectSuite::SetLiveEffectAppVersion for situations where the version compatibility is not dependent upon the effect options.

#define kAILiveEffectParamsWriteAlternateVersionMajorKey   "Adobe Effect Expand Write Alternate Version Major"

#define kAILiveEffectParamsWriteAlternateVersionMinorKey   "Adobe Effect Expand Write Alternate Version Minor"

#define kAILiveEffectSuite   "AI Live Effect Suite"

#define kAILiveEffectSuiteVersion   AIAPI_VERSION(6)

#define kAILiveEffectVersion   kAILiveEffectSuiteVersion

---

Typedef Documentation

typedef struct _t_AILiveEffectOpaque* AILiveEffectHandle

Opaque reference to a Live Effect.

It is never dereferenced.

typedef struct _t_AILiveEffectParamContext* AILiveEffectParamContext

Opaque reference to a Live Effect parameter context.

typedef AIDictionaryRef AILiveEffectParameters

The parameters for a Live Effect, stored in a dictionary.

typedef ConstAIDictionaryRef ConstAILiveEffectParameters

---

Enumeration Type Documentation

enum AILiveEffectMergeAction

Ways that a Live Effect can be merged with the existing styles of selected objects.

Enumerator:

kAppendLiveEffectToStyle	Append this effect to the current style.
kReplaceFillWithLiveEffect	Replace the current fill style with this effect.
kReplaceStrokeWithLiveEffect	Replace the current stroke style with this effect.
kSendHandleMergeMessage	Bit flag can be ORed with replacement styles to send a kSelectorAILiveEffectHandleMerge message to handle the parameters of the merge. Not used with kAppendLiveEffectToStyle

enum AIStyleFilterFlags

Bit flags for Live Effect style properties, which specify how the filter is applied and what features it supports.

An effect must be registered with exactly one of the first four values, which denote the filter type. The last three values can be ORed together with the filter type. Pass to AILiveEffectSuite::AddLiveEffect() in AILiveEffectData::styleFilterFlags.

Enumerator:

kNoFlags	Clears all flags.
kPreEffectFilter	Applied by default before the object is painted with fill or stroke.
kPostEffectFilter	Applied by default after the object is painted with fill or stroke.
kStrokeFilter	Replaces the default stroke behavior. Brushes are an example of an effect of this type.
kFillFilter	Replaces the default fill behavior.
kFilterTypeMask	A mask to OR with the filter-style value to retrieve specific bit flags. Do not use with AILiveEffectSuite::AddLiveEffect().
kSpecialGroupPreFilter	Internal. Do not use.
kHasScalableParams	Parameters can be scaled.
kUsesAutoRasterize	Supports automatic rasterization.
kCanGenerateSVGFilter	Supports the generation of an SVG filter.
kHandlesAdjustColorsMsg	Has parameters that can be modified by a kSelectorAILiveEffectAdjustColors message.
kHandlesIsCompatibleMsg	Handles kSelectorAILiveEffectIsCompatible messages. If this flag is not set the message will not be sent.

enum AIStyleFilterPreferredInputArtType

The kinds of objects in input art that an effect can operate on.

If input art contains objects the effect does not handle, Illustrator looks for a conversion filter to convert the input art to a type that is handled. If no such filter is available, the input art is passed unchanged. The effect should pass through unchanged any art that it cannot handle,

Enumerator:

kInputArtDynamic	The kSelectorAILiveEffectInputType message is sent to the plug-in to determine the input type.
kGroupInputArt	Handles groups.
kPathInputArt	Handles paths.
kCompoundPathInputArt	Handles compound paths.
kTextInputArtUnsupported	Obsolete.
kTextPathInputArtUnsupported	Obsolete.
kTextRunInputArtUnsupported	Obsolete.
kPlacedInputArt	Handles placed objects.
kMysteryPathInputArt	Handles mystery paths.
kRasterInputArt	Handles raster art.
kPluginInputArt	Handles plug-in groups. If not set, the effect receives the result group instead of the plug-in group itself.
kMeshInputArt	Handles meshes.
kTextFrameInputArt	Handles text frames.
kSymbolInputArt	Handles symbols.
kForeignInputArt	Handles foreign objects.
kLegacyTextInputArt	Handles legacy text.
kChartInputArt	Handles charts.
kAnyInputArt	Handles any input art.
kAnyInputArtButPluginArt	Handles any input art other than plug-in groups, which are replaced by their result art.
kOutlinedStrokeInputArt	Not implemented.
kNoClipMasksInputArt	Does not handle clipping paths or clipping text. Not needed if paths are not handled.