AINotifierSuite Struct Reference
[API Suite List]

This suite provides functions that allow your plug-in to use Illustrator's event notification system. More...

#include <AINotifier.h>

List of all members.

Public Attributes
AIAPI AIErr(*	AddNotifier )(SPPluginRef self, const char *name, const char *type, AINotifierHandle *notifier)
	Registers interest in a notification.
AIAPI AIErr(*	GetNotifierName )(AINotifierHandle notifier, const char **name)
	Retrieves the unique identifying name of a notifier.
AIAPI AIErr(*	GetNotifierType )(AINotifierHandle notifier, const char **type)
	Retrieves the type of a notifier.
AIAPI AIErr(*	GetNotifierActive )(AINotifierHandle notifier, AIBoolean *active)
	Reports whether a notifier is active.
AIAPI AIErr(*	SetNotifierActive )(AINotifierHandle notifier, AIBoolean active)
	Turns a notifier on or off.
AIAPI AIErr(*	GetNotifierPlugin )(AINotifierHandle notifier, SPPluginRef *plugin)
	Retrieves the plug-in that installed a notifier.
AIAPI AIErr(*	CountNotifiers )(ai::int32 *count)
	Gets the number of installed notifiers.
AIAPI AIErr(*	GetNthNotifier )(ai::int32 n, AINotifierHandle *notifier)
	Retrieves a notifier by index position.
AIAPI AIErr(*	Notify )(const char *type, void *notifyData)
	Broadcasts a notification to all the plug-ins that have subscribed to the specified type.

---

Detailed Description

This suite provides functions that allow your plug-in to use Illustrator's event notification system.

Illustrator sends a notifier to plug-in to inform it of an events for which it has registered an interest. These functions allow you to request particular notifications, turn them on and off, and find out which plug-ins are listening to notifications.

Notifiers can be used by themselves as a background process or with other plug-in types, such as a menus or windows, to learn when an update is needed. Specific notifier type definitions are not a part of this suite, but are found in the suites to which they are related. For instance, the AIArtSuite defines the kAIArtSelectionChangedNotifier and kAIArtPropertiesChangedNotifier.

Illustrator notifies a plug-in of an event by sending a message to its main entry point with the caller kCallerAINotify and selector kSelectorAINotify. The message data is defined by AINotifierMessage.

Notifications are sometimes sent during an idle loop, so a plug-in should not rely on receiving them synchronously with a document state change. Some notifications are sent when something might have changed, but do not guarantee that something has changed.

• Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAINotifierSuite and kAINotifierVersion.

---

Member Data Documentation

AIAPI AIErr(* AINotifierSuite::AddNotifier)(SPPluginRef self, const char *name, const char *type, AINotifierHandle *notifier)

Registers interest in a notification.

Use at startup.

Parameters:

	self	This plug-in.
	name	The unique identifying name of this plug-in.
	type	The notification type, as defined in the related suite. See Plug-in Notifiers.
	notifier	[out] A buffer in which to return the notifier reference. If your plug-in installs multiple notifications, store this in ' globals to compare when receiving a notification.

AIAPI AIErr(* AINotifierSuite::CountNotifiers)(ai::int32 *count)

Gets the number of installed notifiers.

Use this with GetNthNotifier() to iterate through notifiers.

Parameters:

count

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

AIAPI AIErr(* AINotifierSuite::GetNotifierActive)(AINotifierHandle notifier, AIBoolean *active)

Reports whether a notifier is active.

An active notifier can receive events.

Parameters:

	notifier	The notifier reference.
	active	[out] A buffer in which to return true if the notifier is active.

AIAPI AIErr(* AINotifierSuite::GetNotifierName)(AINotifierHandle notifier, const char **name)

Retrieves the unique identifying name of a notifier.

Parameters:

	notifier	The notifier reference.
	name	[out] A buffer in which to return the name. Do not modify this string.

AIAPI AIErr(* AINotifierSuite::GetNotifierPlugin)(AINotifierHandle notifier, SPPluginRef *plugin)

Retrieves the plug-in that installed a notifier.

You can pass this reference to functions in the AIPluginSuite.

Parameters:

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

AIAPI AIErr(* AINotifierSuite::GetNotifierType)(AINotifierHandle notifier, const char **type)

Retrieves the type of a notifier.

Parameters:

	notifier	The notifier reference.
	type	[out] A buffer in which to return the type. Do not modify this string.

AIAPI AIErr(* AINotifierSuite::GetNthNotifier)(ai::int32 n, AINotifierHandle *notifier)

Retrieves a notifier by index position.

Use this with CountNotifiers() to iterate through notifiers.

Parameters:

	n	The 0-based position index of the notifier.
	notifier	[out] A buffer in which to return the notifier reference.

AIAPI AIErr(* AINotifierSuite::Notify)(const char *type, void *notifyData)

Broadcasts a notification to all the plug-ins that have subscribed to the specified type.

Use this mechanism for communicating with other plug-ins.

Parameters:

	type	The notification type, as defined in the related suite. See Plug-in Notifiers.
	notifyData	Type-specific data to pass to the notification.

AIAPI AIErr(* AINotifierSuite::SetNotifierActive)(AINotifierHandle notifier, AIBoolean active)

Turns a notifier on or off.

When a notifier is active (on) it receives notification of events from Illustrator.

Parameters:

	notifier	The notifier reference.
	active	True to turn the notifier on, false to turn it off.

---

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

• AINotifier.h