AIAppContextSuite Struct Reference
[API Suite List]

Use these functions to manage the application context. More...

#include <AIContext.h>

List of all members.

Public Attributes
AIAPI AIErr(*	GetPlatformAppWindow )(AIWindowRef *appWindow)
	Retrieves the parent application window in Windows.
AIAPI AIErr(*	PushAppContext )(SPPluginRef plugin, AIAppContextHandle *appContext)
	Stores an application context for the calling plug-in.
AIAPI AIErr(*	PopAppContext )(AIAppContextHandle appContext)
	Restores the previous application context.
AIAPI AIErr(*	MacGetAppQDGlobal )(void **appQD)
AIAPI AIErr(*	SuspendAppContext )(AISuspendedAppContext *appContext)
	Suspends the current application context stack.
AIAPI AIErr(*	ResumeAppContext )(AISuspendedAppContext appContext, AIDocumentHandle document)
	Resumes the application context stack for the document of the frontmost window.
AIAPI AIErr(*	AllowAllChanges )(ASBoolean allowAllChanges, ASBoolean *previousState)
	Allows or disallows plug-ins to operate on artwork within locked and/or hidden parent contexts.
AIAPI AIErr(*	AllowProgress )(bool showProgress)
	Allows or disallows use of the progress bar for the current context.
AIAPI AIErr(*	GetPlatformAppMenu )(AIAppMenuContext *appMenu)
	Retrieves the main menu application handle in Windows.
AIAPI AIErr(*	SetAppContextKind )(AIAppContextKind kind)
	Sets the ContextKind for current context.
AIAPI AIErr(*	SyncAndDraw )()
	Synchronize the current global context and then draws.
AIAPI AIErr(*	GetRulerWidthOffsetOnActiveDocument )(AIRect *horzRulerBounds, AIRect *vertRulerBounds, AIRect *cntrRulerBounds)
	Get Ruler width for the current document.
AIAPI AIBoolean(*	DoesAppContextExist )()
	Tells if Application context is present or not.
AIAPI AIErr(*	GetAppContextKind )(AIAppContextKind &kind)
	Gets the current AppContextKind.
AIAPI AIErr(*	IsProgressBarAllowed )(AIBoolean &result)
	Tells if kAPIContextShowProgressOption flag is set or not in APIContext options.

---

Detailed Description

Use these functions to manage the application context.

The application context does two things:

• It establishes the current document and view. Most SDK functions do not take a document or a view as a parameter, but use the current document or view as defined by the application context.

• It establishes the scope of a single undoable operation. All the changes that occur during a single application context are grouped together into a single operation, which can then be undone and redone.

Most plug-ins don't need to use these functions, because Illustrator manages the context. In rare situations, however, a plug-in may need to make changes to the context. For example, if a plug-in is called directly by the operating system, Illustrator has not established the context. If the plug-in wants to make SDK calls in response, it should use PushAppContext() and PopAppContext().

• Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIAppContextSuite and kAIAppContextVersion.

---

Member Data Documentation

AIAPI AIErr(* AIAppContextSuite::AllowAllChanges)(ASBoolean allowAllChanges, ASBoolean *previousState)

Allows or disallows plug-ins to operate on artwork within locked and/or hidden parent contexts.

The call modifies the allow-changes state of the current context. The state persists until you specifically reset it, or until the context is popped. This allows you to make modifications without having to save, set, and restore visibility and locked attributes on the whole parent chain.

Parameters:

	allowAllChanges	True to allow changes, false to disallow changes.
	previousState	[out] A buffer in which to return true if changes were previously allowed, false if they were not.

AIAPI AIErr(* AIAppContextSuite::AllowProgress)(bool showProgress)

Allows or disallows use of the progress bar for the current context.

Parameters:

showProgress

True to show the progress bar, false to hide it.

AIAPI AIBoolean(* AIAppContextSuite::DoesAppContextExist)()

Tells if Application context is present or not.

Returns:

A buffer returning whether application context is present or not.

AIAPI AIErr(* AIAppContextSuite::GetAppContextKind)(AIAppContextKind &kind)

Gets the current AppContextKind.

Parameters:

kind

[out] A buffer in which to return the kind kAIAppContextStandardKind, kAIAppContextUndoRedoKind, kAIAppContextBetaUpdateKind which are mutually exclusive. See enum AIAppContextKind

AIAPI AIErr(* AIAppContextSuite::GetPlatformAppMenu)(AIAppMenuContext *appMenu)

Retrieves the main menu application handle in Windows.

Does nothing in Mac OS.

Parameters:

appMenu

[out] A buffer in which to return the menu reference.

AIAPI AIErr(* AIAppContextSuite::GetPlatformAppWindow)(AIWindowRef *appWindow)

Retrieves the parent application window in Windows.

Does nothing in Mac OS.

Parameters:

appWindow

[out] A buffer in which to return the window reference.

AIAPI AIErr(* AIAppContextSuite::GetRulerWidthOffsetOnActiveDocument)(AIRect *horzRulerBounds, AIRect *vertRulerBounds, AIRect *cntrRulerBounds)

Get Ruler width for the current document.

Returns width of the vertical ruler and height of the horizontal ruler Returns 0 if rulers are hidden

AIAPI AIErr(* AIAppContextSuite::IsProgressBarAllowed)(AIBoolean &result)

Tells if kAPIContextShowProgressOption flag is set or not in APIContext options.

returns true/false whether progress bar is allowed or not.

AIAPI AIErr(* AIAppContextSuite::MacGetAppQDGlobal)(void **appQD)

Deprecated:

No longer needed.

AIAPI AIErr(* AIAppContextSuite::PopAppContext)(AIAppContextHandle appContext)

Restores the previous application context.

Parameters:

appContext

The application context reference, as returned by PushAppContext().

AIAPI AIErr(* AIAppContextSuite::PushAppContext)(SPPluginRef plugin, AIAppContextHandle *appContext)

Stores an application context for the calling plug-in.

Parameters:

	plugin	This plug-in.
	appContext	[out] A buffer in which to return the application context reference. Pass this to PopAppContext() upon completion of the context-sensitive procedure.

AIAPI AIErr(* AIAppContextSuite::ResumeAppContext)(AISuspendedAppContext appContext, AIDocumentHandle document)

Resumes the application context stack for the document of the frontmost window.

This might be a different document from the one at the time the context stack was suspended.

Parameters:

appContext

The application context stack reference, as returned by SuspendAppContext().

AIAPI AIErr(* AIAppContextSuite::SetAppContextKind)(AIAppContextKind kind)

Sets the ContextKind for current context.

Parameters:

kind

The Context kind can either be kAIAppContextStandardKind, kAIAppContextUndoRedoKind, kAIAppContextBetaUpdateKind which are mutually exclusive. See enum AIAppContextKind

AIAPI AIErr(* AIAppContextSuite::SuspendAppContext)(AISuspendedAppContext *appContext)

Suspends the current application context stack.

This is equivalent to popping all current open contexts, except that they can later be restored all at once by ResumeAppContext(). Use before an operation that may change the current document.

Parameters:

appContext

[out] A buffer in which to return the application context stack reference. Pass this to ResumeAppContext() upon completion of the context-sensitive procedure.

AIAPI AIErr(* AIAppContextSuite::SyncAndDraw)()

Synchronize the current global context and then draws.

---

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

• AIContext.h