AIAnnotatorSuite Struct Reference
[API Suite List]

The annotator suite allows plug-ins to draw annotations into the document window that are not a part of the artwork. More...

#include <AIAnnotator.h>

List of all members.

Public Attributes
AIAPI AIErr(*	AddAnnotator )(SPPluginRef self, const char name, AIAnnotatorHandle notifier)
	Adds a new annotator to your plug-in.
AIAPI AIErr(*	GetAnnotatorName )(AIAnnotatorHandle notifier, const char **name)
	Retrieves the display name of this annotator.
AIAPI AIErr(*	GetAnnotatorActive )(AIAnnotatorHandle notifier, AIBoolean *active)
	Reports whether an annotator is currently active.
AIAPI AIErr(*	SetAnnotatorActive )(AIAnnotatorHandle notifier, AIBoolean active)
	Activates or deactivates an annotator.
AIAPI AIErr(*	GetAnnotatorPlugin )(AIAnnotatorHandle notifier, SPPluginRef *plugin)
	Retrieves the plug-in that defines this annotator.
AIAPI AIErr(*	CountAnnotators )(ai::int32 *count)
	Gets the number of currently registered annotators.
AIAPI AIErr(*	GetNthAnnotator )(ai::int32 n, AIAnnotatorHandle *notifier)
	Retrieves a registered annotator by position index.
AIAPI AIErr(*	InvalAnnotationRect )(AIDocumentViewHandle view, const AIRect *annotationBounds)
	Invalidates a rectangular area of the document so that drawing can be performed.
AIAPI AIErr(*	SetAnnotatorAlternatePlugin )(AIAnnotatorHandle notifier, SPPluginRef plugin)
	Adds an annotator to a different plug-in (for instance, one that does on-screen drawing).
AIAPI AIErr(*	GetAnnotatorAlternatePlugin )(AIAnnotatorHandle notifier, SPPluginRef *plugin)
	Retrieves the alternate plug-in for the annotator, to which it was added with `SetAnnotatorAlternatePlugin()`.
AIAPI AIErr(*	GetAnnotatorOptions )(AIAnnotatorHandle notifier, AIAnnotatorOptionsFlags *flags)
	Retrieves annotator options, which determine how the annotation is drawn.
AIAPI AIErr(*	SetAnnotatorOptions )(AIAnnotatorHandle notifier, const AIAnnotatorOptionsFlags flags)
	Sets annotator options, which determine how the annotation is drawn.

Detailed Description

The annotator suite allows plug-ins to draw annotations into the document window that are not a part of the artwork.

These annotations are drawn on top after all artwork has been drawn. For example, selection handles are annotations.

In order to be given an opportunity to draw annotations a plug-in must first call AddAnnotator() to register itself as an annotator. Typically this is done at plug-in startup but it may be done at any time. An annotator may be active or inactive. Only active annotators receive requests to draw.

A plug-in annotator can receive two messages via its main entry point. These messages have caller kCallerAIAnnotation. The messages are:

kSelectorAIDrawAnnotation A request for the annotator to draw its annotations. In this case the message structure is an AIAnnotatorMessage that supplies information about the document view to be drawn.
kSelectorAIInvalAnnotation A request to invalidate the bounds of any annotations in the current document view. In response the plug-in should call InvalAnnotationRect() for each annotation.

In addition to responding to the previous two messages a plug-in annotator typically calls InvalAnnotationRect() whenever its set of annotations changes. This indicates the parts of the document view that need to be redrawn as a consequence of the changes.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIAnnotatorSuite and kAIAnnotatorVersion.

Member Data Documentation

AIAPI AIErr(* AIAnnotatorSuite::AddAnnotator)(SPPluginRef self, const char *name, AIAnnotatorHandle *notifier)

Adds a new annotator to your plug-in.

Typically called during startup.

Parameters:

	self	The startup plug-in.
	name	The annotator�s display name.
	notifier	[out] A buffer in which to return a unique identifier for the new annotator.

AIAPI AIErr(* AIAnnotatorSuite::CountAnnotators)(ai::int32 *count)

Gets the number of currently registered annotators.

Use with GetNthAnnotator() to iterate through all annotators.

Parameters:

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

AIAPI AIErr(* AIAnnotatorSuite::GetAnnotatorActive)(AIAnnotatorHandle notifier, AIBoolean *active)

Reports whether an annotator is currently active.

Parameters:

	notifier	The notifier for the annotator, as returned by `AddAnnotator()` or `GetNthAnnotator()`.
	active	[out] A buffer in which to return the result, true if the annotator is active.

AIAPI AIErr(* AIAnnotatorSuite::GetAnnotatorAlternatePlugin)(AIAnnotatorHandle notifier, SPPluginRef *plugin)

Retrieves the alternate plug-in for the annotator, to which it was added with SetAnnotatorAlternatePlugin().

Parameters:

	notifier	The notifier for the annotator, as returned by `AddAnnotator()` or `GetNthAnnotator()`.
	plugin	[out] A buffer in which to return the alternate plug-in reference.

AIAPI AIErr(* AIAnnotatorSuite::GetAnnotatorName)(AIAnnotatorHandle notifier, const char **name)

Retrieves the display name of this annotator.

Parameters:

	notifier	The notifier for the annotator, as returned by `AddAnnotator()` or `GetNthAnnotator()`.
	name	[out] A pointer to point to the display name.

AIAPI AIErr(* AIAnnotatorSuite::GetAnnotatorOptions)(AIAnnotatorHandle notifier, AIAnnotatorOptionsFlags *flags)

Retrieves annotator options, which determine how the annotation is drawn.

Parameters:

	notifier	The notifier for the annotator, as returned by `AddAnnotator()` or `GetNthAnnotator()`.
	flags	[out] A buffer in which to return the options, a logical OR of `AIAnnotatorOptionsFlagValues`.

AIAPI AIErr(* AIAnnotatorSuite::GetAnnotatorPlugin)(AIAnnotatorHandle notifier, SPPluginRef *plugin)

Retrieves the plug-in that defines this annotator.

Parameters:

	notifier	The notifier for the annotator, as returned by `AddAnnotator()` or `GetNthAnnotator()`.
	plugin	[out] A buffer in which to return the plug-in reference.

AIAPI AIErr(* AIAnnotatorSuite::GetNthAnnotator)(ai::int32 n, AIAnnotatorHandle *notifier)

Retrieves a registered annotator by position index.

Use with CountAnnotators() to iterate through all registered annotators.

Parameters:

	n	The index, in the range [1..numAnnotators].
	notifier	[out] A buffer in which to return the annotator reference.

AIAPI AIErr(* AIAnnotatorSuite::InvalAnnotationRect)(AIDocumentViewHandle view, const AIRect *annotationBounds)

Invalidates a rectangular area of the document so that drawing can be performed.

After using this function to determine the area in which to draw, you can call ADMDrawer to perform platform-independent drawing. For example:

        portBounds.left = _AIRealRoundToShort(updateRect.left) - 1;
        portBounds.top = _AIRealRoundToShort(updateRect.top) + 1;
        portBounds.right = _AIRealRoundToShort(updateRect.right) + 1;
        portBounds.bottom = _AIRealRoundToShort(updateRect.bottom) - 1;

        sAIAnnotator->InvalAnnotationRect(fDocumentView, &portBounds);

Parameters:

	view	The document view. See `apiAIDocumentView.h`
	annotationBounds	A pointer to rectangle structure that specifies the area boundaries.

AIAPI AIErr(* AIAnnotatorSuite::SetAnnotatorActive)(AIAnnotatorHandle notifier, AIBoolean active)

Activates or deactivates an annotator.

Parameters:

	notifier	The notifier for the annotator, as returned by `AddAnnotator()` or `GetNthAnnotator()`.
	active	True to activate the annotator, false to deactivate it.

AIAPI AIErr(* AIAnnotatorSuite::SetAnnotatorAlternatePlugin)(AIAnnotatorHandle notifier, SPPluginRef plugin)

Adds an annotator to a different plug-in (for instance, one that does on-screen drawing).

This is the alternate plug-in; you can retrieve the handle to it using GetAnnotatorAlternatePlugin().

Parameters:

	notifier	The notifier for the annotator, as returned by `AddAnnotator()` or `GetNthAnnotator()`.
	plugin	The handle for the alternate plug-in.

AIAPI AIErr(* AIAnnotatorSuite::SetAnnotatorOptions)(AIAnnotatorHandle notifier, const AIAnnotatorOptionsFlags flags)

Sets annotator options, which determine how the annotation is drawn.

Parameters:

	notifier	The notifier for the annotator, as returned by `AddAnnotator()` or `GetNthAnnotator()`.
	flags	The new options value, a logical OR of `AIAnnotatorOptionsFlagValues`.

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

AIAnnotator.h

AIAnnotatorSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIAnnotatorSuite Struct Reference
[API Suite List]