AIFilterSuite Struct Reference
[API Suite List]

This suite provides functions to add and manage menu items in the Filter menu. More...

#include <AIFilter.h>

Public Attributes
AIAPI AIErr(*	AddFilter )(SPPluginRef self, char name, PlatformAddFilterData data, ai::int32 options, AIFilterHandle *filter)
	Installs a filter plug-in.
AIAPI AIErr(*	GetFilterName )(AIFilterHandle filter, char **name)
	Retrieves the unique name of a filter.
AIAPI AIErr(*	GetFilterOptions )(AIFilterHandle filter, ai::int32 *options)
	Retrieves the option flags of a filter.
AIAPI AIErr(*	SetFilterOptions )(AIFilterHandle filter, ai::int32 options)
	Sets the option flags of a filter.
AIAPI AIErr(*	GetFilterParameters )(AIFilterHandle filter, PlatformFilterParameters *parameters)
	Retrieves the stored reference to a parameter block for a filter.
AIAPI AIErr(*	SetFilterParameters )(AIFilterHandle filter, PlatformFilterParameters parameters)
	Sets the stored reference to a parameter block for a filter.
AIAPI AIErr(*	GetFilterMenuItem )(AIFilterHandle filter, AIMenuItemHandle *menuItem)
	Retrieves the menu-item reference for a filter.
AIAPI AIErr(*	GetFilterPlugin )(AIFilterHandle filter, SPPluginRef *plugin)
	Retrieves a reference to the plug-in that installed a filter.
AIAPI AIErr(*	CountFilters )(ai::int32 *count)
	Gets number of installed filters.
AIAPI AIErr(*	GetNthFilter )(ai::int32 n, AIFilterHandle *filter)
	Retrieves a plug-in filter reference by position index.

Detailed Description

This suite provides functions to add and manage menu items in the Filter menu.

Plug-in filters are added to the Filter menu in a separate section from native Illustrator filters and Photoshop filters supported by Illustrator. You can specify a category, or submenu, for a group of filters.

When the user selects a filter, it typically displays an options dialog and then manipulates the artwork in some fashion according to those options.

Filter plug-ins are similar in many ways to the more general menu plug-ins (see AIMenuSuite). Filters differ in that:

Filters are added to the Filter menu, while menu plug-ins can add commands to any menu.
Menu plug-ins can set command keys and control their appearance.
Both plug-in types receive a Go selector, but filters also receive kSelectorAIGetFilterParameters. The user interface is typically a modal dialog, while a menu plug-in can interact with other plug-in types, or trigger other events.
Filters automatically set the Repeat and Undo menus, while menu plug-ins must set the Undo menu item text. The filter plug-in must remove the Undo context if the user cancels the action. Use AIUndoSuite::UndoChanges() to remove any changes to the artwork the plug-in made, and do any other necessary clean up, such as disposing of allocated memory.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIFilterSuite and kAIFilterVersion.

Member Data Documentation

AIAPI AIErr(* AIFilterSuite::AddFilter)(SPPluginRef self, char *name, PlatformAddFilterData *data, ai::int32 options, AIFilterHandle *filter)

Installs a filter plug-in.

Call this during startup to place the name of your filter in the Filter menu.

Parameters:

	self	A reference to this plug-in, which adds the filter.
	name	The unique name of the new filter. You can use your company name with a descriptor to make it unique. Not displayed or localized.
	data	The structure containing the category (submenu) and localizable menu-item label.
	options	Not currently used. Pass 0.
	filter	[out] A buffer in which to return the filter reference. If you install multiple filters, store this reference in the plug-in�s `globals` record, so that your plug-in can use it to determine which filter command is to be processed.

AIAPI AIErr(* AIFilterSuite::CountFilters)(ai::int32 *count)

Gets number of installed filters.

Use this with GetNthFilter() to iterate through installed filters.

Parameters:

count

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

AIAPI AIErr(* AIFilterSuite::GetFilterMenuItem)(AIFilterHandle filter, AIMenuItemHandle *menuItem)

Retrieves the menu-item reference for a filter.

Your plug-in can then modify the menu item�s appearance using the AIMenuSuite functions.

Parameters:

	filter	The filter reference.
	menuItem	[out] A buffer in which to return the menu item reference.

AIAPI AIErr(* AIFilterSuite::GetFilterName)(AIFilterHandle filter, char **name)

Retrieves the unique name of a filter.

Parameters:

	filter	The filter reference.
	name	[out] A buffer in which to return the name string, as originally passed to `AddFilter()`. Do not modify this string.

AIAPI AIErr(* AIFilterSuite::GetFilterOptions)(AIFilterHandle filter, ai::int32 *options)

Retrieves the option flags of a filter.

(The options flags are not currently used, and the returned value is always 0).

Parameters:

	filter	The filter reference.
	options	[out] A buffer in which to return the options value.

AIAPI AIErr(* AIFilterSuite::GetFilterParameters)(AIFilterHandle filter, PlatformFilterParameters *parameters)

Retrieves the stored reference to a parameter block for a filter.

This block contains the parameter values that were set by the user in the most recent call to this filter.

Parameters:

	filter	The filter reference.
	parameters	[out] A buffer in which to return the stored parameters block.

AIAPI AIErr(* AIFilterSuite::GetFilterPlugin)(AIFilterHandle filter, SPPluginRef *plugin)

Retrieves a reference to the plug-in that installed a filter.

Parameters:

	filter	The filter reference.
	plugin	[out] A buffer in which to return the plug-in reference.

AIAPI AIErr(* AIFilterSuite::GetNthFilter)(ai::int32 n, AIFilterHandle *filter)

Retrieves a plug-in filter reference by position index.

Use with CountFilters() to iterate through all installed filters.

Parameters:

	n	The index, in the range `[1..numFilters]`.
	filter	[out] A buffer in which to return the filter reference.

AIAPI AIErr(* AIFilterSuite::SetFilterOptions)(AIFilterHandle filter, ai::int32 options)

Sets the option flags of a filter.

(The options flags are not currently used.)

Parameters:

	filter	The filter reference.
	options	The options value.

AIAPI AIErr(* AIFilterSuite::SetFilterParameters)(AIFilterHandle filter, PlatformFilterParameters parameters)

Sets the stored reference to a parameter block for a filter.

The plug-in manager normally keeps this reference to the parameter values that were set by the user in the most recent call to a filter. You can use this function after a call to AIPluginSuite::CallPlugin(), to store a new set of parameters.

Parameters:

	filter	The filter reference.
	parameters	The new parameters block.

See also:: GetFilterParameters()

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

AIFilter.h

AIFilterSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIFilterSuite Struct Reference
[API Suite List]