AIToolSuite Struct Reference
[API Suite List]

This suite allows you to provide plug-in tools for Illustrator. More...

#include <AITool.h>

Public Attributes
AIAPI AIErr(*	AddTool )(SPPluginRef self, const char name, AIAddToolData data, ai::int32 options, AIToolHandle *tool)
	Installs a plug-in tool.
AIAPI AIErr(*	AddToolPrivate )(SPPluginRef self, const char name, AIAddToolDataPrivate data, ai::int32 options, AIToolHandle *tool)
	For internal use only.
AIAPI AIErr(*	GetToolName )(AIToolHandle tool, char **name)
	Retrieves the unique identifying name of a tool.
AIAPI AIErr(*	GetToolOptions )(AIToolHandle tool, ai::int32 *options)
	Retrieves the option flags of a tool.
AIAPI AIErr(*	SetToolOptions )(AIToolHandle tool, ai::int32 options)
	Sets the option flags of a tool.
AIAPI AIErr(*	GetToolPlugin )(AIToolHandle tool, SPPluginRef *plugin)
	Retrieves the plug-in that installed a tool.
AIAPI AIErr(*	GetSelectedTool )(AIToolHandle *tool)
	Retrieves the currently selected plug-in tool.
AIAPI AIErr(*	SetSelectedTool )(AIToolHandle tool)
	Selects a plug-in tool programmatically.
AIAPI AIErr(*	CountTools )(ai::int32 *count)
	Gets the number of installed plug-in tools.
AIAPI AIErr(*	GetNthTool )(ai::int32 n, AIToolHandle *tool)
	Retrieves a tool by index position.
AIAPI AIErr(*	GetToolHandleFromNumber )(AIToolType toolNum, AIToolHandle *tool)
	Retrieves a plug-in tool by its tool number, as assigned when it is created with `AddTool()`, and obtained by calling `GetToolNumberFromHandle`.
AIAPI AIErr(*	GetToolNumberFromName )(const char name, AIToolType toolNum)
	Retrieves a tool number from a tool's unique name.
AIAPI AIErr(*	GetToolNumberFromHandle )(AIToolHandle tool, AIToolType *toolNum)
	Retrieves a tool number for a tool.
AIAPI AIErr(*	GetToolNameFromNumber )(AIToolType toolNum, char **name)
	Retrieves the unique name of a tool from its number.
AIAPI AIErr(*	GetToolTitle )(AIToolHandle tool, char **title)
	Retrieves the localizable title of a tool, which appears in the UI.
AIAPI AIErr(*	SetToolTitle )(AIToolHandle tool, const char *title)
	Sets the localizable title of a tool, which appears in the UI.
AIAPI AIErr(*	GetTooltip )(AIToolHandle tool, char **tooltip)
	Retrieves the tooltip string for a tool.
AIAPI AIErr(*	SetTooltip )(AIToolHandle tool, const char *tooltip)
	Sets the tooltip string for a tool.
AIAPI AIErr(*	GetToolHelpID )(AIToolHandle tool, ASHelpID *helpID)
	Retrieves the help-system identifier for a tool.
AIAPI AIErr(*	SetToolHelpID )(AIToolHandle tool, ASHelpID helpID)
	Sets the help-system identifier for a tool.
AIAPI AIErr(*	SetToolInfoVars )(AIToolHandle tool, const ai::int32 infoVars[])
	Determines which labeled fields are displayed in the Info palette for a tool.
AIAPI AIErr(*	SetToolInfoVarValues )(const ai::int32 infoVars, void *values)
	Sets field values in the Info palette.
AIAPI AIErr(*	SystemHasPressure )(AIBoolean *hasPressure)
	Reports whether a pressure-sensitive device such as a graphics tablet was available on application startup.
AIAPI AIErr(*	GetToolNullEventInterval )(AIToolHandle tool, AIToolTime *outTime)
AIAPI AIErr(*	SetToolNullEventInterval )(AIToolHandle tool, AIToolTime inTime)
AIAPI AIErr(*	SetSoftSelectedTool )(AIToolHandle tool)
	Selects a plug-in tool, but does not highlight it in the palette or show its tool name in the status bar of the document window.
AIAPI AIErr(*	IsSoftModeSelection )(AIBoolean *isSoftMode)
	Reports whether there is currently a soft tool selection.
AIAPI AIErr(*	GetAlternateSelectionToolName )(AIToolHandle tool, char **name)
	Retrieves the name of the tool that will be temporarily selected by pressing Ctrl (in Windows) or Cmd (in MacOS) key while using this tool.
AIAPI AIErr(*	SetAlternateSelectionToolName )(AIToolHandle tool, const char *alternateTool)
	Sets the tool that will be temporarily selected by pressing Ctrl (in Windows) or Cmd (in Mac OS) key while using this tool.
AIAPI AIErr(*	GetCurrentToolName )(const char **name)
	Retrieves the unique name of the currently selected tool.
AIAPI AIErr(*	GetCurrentEffectiveToolName )(const char **name)
	Retrieves the unique name of the currently active tool.
AIAPI AIToolType(*	GetLastUsedSelectionTool )(const char **name)
	Retrieves the numerical identifier of the most recently used built-in selection tool, and optionally retrieves the unique name of the tool, from `AIToolNames.h`.
AIAPI AIErr(*	SetSelectedToolByName )(const char *name)
	Select a tool by its unique name identifier.
AIAPI AIErr(*	GetTabletHardwareCapabilities )(ai::int32 *hardwareCapabilities)
	Reports the hardware capabilities of a graphical tablet or integrated digitizer.
AIAPI AIErr(*	SetToolIcons )(AIToolHandle tool, const char normalIconResourceName, const char darkNormalIconResourceName)
	Sets tool icons to be used with light and dark UI themes.
AIAPI AIErr(*	GetToolIcons )(const AIToolHandle tool, char normalIconResourceName, char darkNormalIconResourceName)
	Retrieves the base filenames (without extension) of the PNG icon resources associated with a tool.
AIAPI AIErr(*	SetDocumentInkParams )(const AIToolHandle tool, const AIDocumentInkParams &inDocInkParams)

Detailed Description

This suite allows you to provide plug-in tools for Illustrator.

Plug-in tools can work on existing artwork or create new objects. Tools that you add appear in the Illustrator Tool palette in their own set, or as part of an existing tool set. Use the functions in this suite to add tools, set options, and control the tool�s appearance in the palette.

Typically, you set the options that control the behavior of a plug-in tool when you install the tool with AIToolSuite::AddTool(). You can modify them later with AIToolSuite::SetToolOptions().

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIToolSuite and kAIToolVersion.

Toolsets and Groups in the Tools Palette

In the Tools palette, a toolset is a collection related tools. When there is more than one tool in a toolset, only the frontmost tool's icon is shown in the palette, with a triangle in the lower left corner to indicate the presence of additional tools. The entire toolset is shown when the user holds the mouse button down on the topmost tool.

A group is a collection of toolsets. Groups are separated by vertical space in the palette.

To create a new group or toolset, pass kNoTool for AIAddToolData::sameGroupAs or AIAddToolData::sameToolsetAs. For example, to create a new tool group:

toolData.title = "MyTool1";
toolData.tooltip = "MyTool1 Tooltip";
toolData.sameGroupAs = kNoTool;
toolData.sameToolsetAs = kNoTool;

To add a new toolset to this group:

toolData.title = "MyTool2";
toolData.tooltip = "MyTool2 Tooltip";
error = sTool->GetToolNumberFromName("MyTool1", &toolData.sameGroupAs);
toolData.sameToolsetAs = kNoTool;

To add tools to this toolset:

toolData.title = "MyTool2a";
toolData.tooltip = "Tool2a Tooltip";
error = sTool->GetToolNumberFromName("MyTool1", &toolData.sameGroupAs);
error = sTool->GetToolNumberFromName("MyTool2", &toolData.sameToolsetAs);

Tool Behavior

Implement tool behavior by defining handlers for the caller/selector pairs and messages that plug-in tools receive, particularly the mouse selectors. Check for selectors in the plug-in's main function.

Your mouse selector handlers can create or modify art objects directly. A tool can select and work on several art objects at once. The application updates the window between calls to the plug-in, so the new or changed artwork appears as the mouse moves. Use AIUndoSuite::UndoChanges() before processing the tool drag, in order to maintain a known artwork state from which to redraw changes.

Because multiple plug-ins can be running at once, the artwork state can change in the course of using your tool. To verify that a specific artwork state exists, you can use a plug-in notifier to indicate that the artwork selection or properties have been changed. See the AINotifierSuite.

The caller for tool plug-ins is kCallerAITool.

These selectors are sent:
kSelectorAIEditToolOptions
kSelectorAITrackToolCursor
kSelectorAIToolMouseDown
kSelectorAIToolMouseDrag
kSelectorAIToolMouseUp
kSelectorAISelectTool
kSelectorAIDeselectTool
kSelectorAIReselectTool

These notifiers are related to tools:
kAIUserToolChangedNotifier
kAIToolSelectedNotifier
kAIToolDeselectedNotifier
kAIToolClearStateNotifier
kAIToolTitleChangedNotifier
kAIToolTooltipChangedNotifier
kAIToolHelpIDChangedNotifier
kAIToolChangedNotifier
kAIToolWindowChangedNotifier
kAIToolSuspendNotifier
kAIToolResumeNotifier
kAIEyedropperDragNotifier

Member Data Documentation

AIAPI AIErr(* AIToolSuite::AddTool)(SPPluginRef self, const char *name, AIAddToolData *data, ai::int32 options, AIToolHandle *tool)

Installs a plug-in tool.

Use at startup.

Parameters:

	self	This plug-in.
	name	The unique name of this tool.
	data	Information on how to display this tool in the Tool palette.
	options	Option flags that control the tool's behavior, a logical OR of `AIToolOptions` constants.
	tool	[out] A buffer in which to return the tool reference. If you install multiple tools, save to compare to the tool reference in tool message data.

AIAPI AIErr(* AIToolSuite::AddToolPrivate)(SPPluginRef self, const char *name, AIAddToolDataPrivate *data, ai::int32 options, AIToolHandle *tool)

For internal use only.

AIAPI AIErr(* AIToolSuite::CountTools)(ai::int32 *count)

Gets the number of installed plug-in tools.

Use with GetNthTool() to iterate through plug-in tools.

Parameters:

count

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

AIAPI AIErr(* AIToolSuite::GetAlternateSelectionToolName)(AIToolHandle tool, char **name)

Retrieves the name of the tool that will be temporarily selected by pressing Ctrl (in Windows) or Cmd (in MacOS) key while using this tool.

Effective only if the tool has set the option kToolWantsAlternateSelectionTool.

Parameters:

	tool	This tool.
	name	A buffer in which to return the name of the alternate selection tool.

AIAPI AIErr(* AIToolSuite::GetCurrentEffectiveToolName)(const char **name)

Retrieves the unique name of the currently active tool.

This is the same name you get from currentToolName from AIEffectiveToolChangeData.

Parameters:

name

[out] A pointer to point to the name string. Do not modify this string. Copy it immediately to use it.

AIAPI AIErr(* AIToolSuite::GetCurrentToolName)(const char **name)

Retrieves the unique name of the currently selected tool.

This is the same name you get from calling AIToolboxSuite::GetCurrentToolType() followed by GetToolNameFromNumber().

Parameters:

name

[out] A pointer to point to the name string. Do not modify this string. Copy it immediately to use it.

AIAPI AIToolType(* AIToolSuite::GetLastUsedSelectionTool)(const char **name)

Retrieves the numerical identifier of the most recently used built-in selection tool, and optionally retrieves the unique name of the tool, from AIToolNames.h.

(Note that this function returns an AIToolType, not an error code.)

Parameters:

name

[out][optional] A buffer in which to return the name string. Do not modify this string. Copy it immediately to use it.

Returns:: The numerical identifier.

AIAPI AIErr(* AIToolSuite::GetNthTool)(ai::int32 n, AIToolHandle *tool)

Retrieves a tool by index position.

Use with CountTools() to iterate through plug-in tools.

Parameters:

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

AIAPI AIErr(* AIToolSuite::GetSelectedTool)(AIToolHandle *tool)

Retrieves the currently selected plug-in tool.

If the current tool is a built-in tool, returns NULL. See AIToolboxSuite::GetCurrentToolType() or GetCurrentToolName() for retrieving the current tool including built-in tools.

Parameters:

tool

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

AIAPI AIErr(* AIToolSuite::GetTabletHardwareCapabilities)(ai::int32 *hardwareCapabilities)

Reports the hardware capabilities of a graphical tablet or integrated digitizer.

Parameters:

hardwareCapabilities [out] A buffer in which to return a logical OR of AITabletCapabilities contants.

AIAPI AIErr(* AIToolSuite::GetToolHandleFromNumber)(AIToolType toolNum, AIToolHandle *tool)

Retrieves a plug-in tool by its tool number, as assigned when it is created with AddTool(), and obtained by calling GetToolNumberFromHandle.

See Toolsets and Groups in the Tools Palette. If the toolNum is the number of a built-in tool, returns NULL, since built-in tools do not have an AIToolHandle.

Parameters:

	toolNum	The tool number.
	tool	[out] A buffer in which to return the tool reference.

AIAPI AIErr(* AIToolSuite::GetToolHelpID)(AIToolHandle tool, ASHelpID *helpID)

Retrieves the help-system identifier for a tool.

Parameters:

	tool	The tool reference.
	helpID	[out] A buffer in which to return the help ID, which can be an integer or a pooled string.

AIAPI AIErr(* AIToolSuite::GetToolIcons)(const AIToolHandle tool, char **normalIconResourceName, char **darkNormalIconResourceName)

Retrieves the base filenames (without extension) of the PNG icon resources associated with a tool.

Parameters:

	tool[in]	The tool reference.
	normalIconResource[out]	A buffer in which to return the resource name for light UI theme icon.
	darkNormalIconResource[out]	A buffer in which to return the resource name for dark UI theme icon.

AIAPI AIErr(* AIToolSuite::GetToolName)(AIToolHandle tool, char **name)

Retrieves the unique identifying name of a tool.

To get the localizable title that appears in the UI, use GetToolTitle().

Parameters:

	tool	The tool reference.
	name	[out] A pointer to point to the name string. Do not modify this string.

AIAPI AIErr(* AIToolSuite::GetToolNameFromNumber)(AIToolType toolNum, char **name)

Retrieves the unique name of a tool from its number.

To get the localizable title that appears in the UI, use GetToolTitle().

Parameters:

	toolNum	The tool number.
	name	[out] A pointer to point to the name string. Do not modify this string. Copy it immediately to use it.

AIAPI AIErr(* AIToolSuite::GetToolNullEventInterval)(AIToolHandle tool, AIToolTime *outTime)

Deprecated:: Obsolete. Do not use.

AIAPI AIErr(* AIToolSuite::GetToolNumberFromHandle)(AIToolHandle tool, AIToolType *toolNum)

Retrieves a tool number for a tool.

Use to find the numbers of plug-in tools, in order to place your tool in an existing group or toolset. See Toolsets and Groups in the Tools Palette.

Parameters:

	tool	The tool reference.
	toolNum	[out] A buffer in which to return the tool number.

AIAPI AIErr(* AIToolSuite::GetToolNumberFromName)(const char *name, AIToolType *toolNum)

Retrieves a tool number from a tool's unique name.

Use to find the numbers of built-in tools, in order to place your tool in an existing group or toolset. See Toolsets and Groups in the Tools Palette.

Parameters:

	name	The tool name. The names of Illustrator's built-in tools can be found in `AIToolNames.h`.
	toolNum	[out] A buffer in which to return the tool number.

AIAPI AIErr(* AIToolSuite::GetToolOptions)(AIToolHandle tool, ai::int32 *options)

Retrieves the option flags of a tool.

To retain the existing flags when setting options with SetToolOptions(), obtain them with this function and do a logical OR with the new flags.

Parameters:

	tool	The tool reference.
	options	[out] A buffer in which to return the options value, a logical OR of `AIToolOptions` constants.

AIAPI AIErr(* AIToolSuite::GetToolPlugin)(AIToolHandle tool, SPPluginRef *plugin)

Retrieves the plug-in that installed a tool.

Parameters:

	tool	The tool reference.
	plugin	[out] A buffer in which to return the plug-in reference, which can be used with `AIPluginSuite` functions.

AIAPI AIErr(* AIToolSuite::GetTooltip)(AIToolHandle tool, char **tooltip)

Retrieves the tooltip string for a tool.

Parameters:

	tool	The tool reference.
	tooltip	[out] A pointer to point to the tooltip string. Do not modify this string.

AIAPI AIErr(* AIToolSuite::GetToolTitle)(AIToolHandle tool, char **title)

Retrieves the localizable title of a tool, which appears in the UI.

To get the unique, identifying name, use GetToolName().

Parameters:

	tool	The tool reference.
	title	[out] A pointer to point to the title string. Do not modify this string.

AIAPI AIErr(* AIToolSuite::IsSoftModeSelection)(AIBoolean *isSoftMode)

Reports whether there is currently a soft tool selection.

Soft mode is entered when a tool, such as the rectangle tool, is selected and the user implicitly overrides this by drawing with the eraser end of a tablet stylus.

Parameters:

isSoftMode

[out] A buffer in which to return true if there is a soft tool selection.

AIAPI AIErr(* AIToolSuite::SetAlternateSelectionToolName)(AIToolHandle tool, const char *alternateTool)

Sets the tool that will be temporarily selected by pressing Ctrl (in Windows) or Cmd (in Mac OS) key while using this tool.

Effective only if the tool has set the option kToolWantsAlternateSelectionTool.

Parameters:

	tool	This tool.
	name	The name of the alternate selection tool.

AIAPI AIErr(* AIToolSuite::SetDocumentInkParams)(const AIToolHandle tool, const AIDocumentInkParams &inDocInkParams)

AIAPI AIErr(* AIToolSuite::SetSelectedTool)(AIToolHandle tool)

Selects a plug-in tool programmatically.

This is the same as the user selecting the tool in the Tool palette. To select built-in tools, see SetSelectedToolByName()

Parameters:

tool

The tool reference.

AIAPI AIErr(* AIToolSuite::SetSelectedToolByName)(const char *name)

Select a tool by its unique name identifier.

Can be either the name of a plug-in tool, returned by GetToolName(), or one of the tool name constants from AIToolNames.h.

Parameters:

name

The name of the tool to be selected.

AIAPI AIErr(* AIToolSuite::SetSoftSelectedTool)(AIToolHandle tool)

Selects a plug-in tool, but does not highlight it in the palette or show its tool name in the status bar of the document window.

Indicates this soft selection by setting the isSoftMode flag. SetSelectedTool() turns this flag off.

Parameters:

tool

The tool reference.

AIAPI AIErr(* AIToolSuite::SetToolHelpID)(AIToolHandle tool, ASHelpID helpID)

Sets the help-system identifier for a tool.

Parameters:

	tool	The tool reference.
	helpID	The new help ID, which can be an integer or a pooled string.

AIAPI AIErr(* AIToolSuite::SetToolIcons)(AIToolHandle tool, const char *normalIconResourceName, const char *darkNormalIconResourceName)

Sets tool icons to be used with light and dark UI themes.

Parameters:

	tool[in]	The tool reference.
	normalIconResource[in]	Base file name (without extension) of the PNG icon resource for the light UI theme.
	darkNormalIconResource[in]	Base file name (without extension) of the PNG icon resource for the dark UI theme.

AIAPI AIErr(* AIToolSuite::SetToolInfoVars)(AIToolHandle tool, const ai::int32 infoVars[])

Determines which labeled fields are displayed in the Info palette for a tool.

Typically called once at startup to initialize the Info palette.

Parameters:

	tool	The tool reference.
	infoVars	A pointer to the first member of an array of information variables, which correspond to labeled fields in Illustrator�s Info palette, as defined in `AIToolInfoVariable`. Only the fields included in this array are shown for the tool. To initialize or set the values in the fields, use `SetToolInfoVarValues()`.

AIAPI AIErr(* AIToolSuite::SetToolInfoVarValues)(const ai::int32 *infoVars, void **values)

Sets field values in the Info palette.

Only those fields specified by SetToolInfoVars() are displayed in the palette.

Parameters:

	infoVars	A pointer to the first member of an array of information variables, which correspond to labeled fields in Illustrator�s Info palette. This is the same array specified by `SetToolInfoVars()`.
	values	A pointer to the first member of an array of values, whose positions match those in the `infoVars` array.

Example:

AIErr UpdateInfoPalette( AIToolHandle tool, AIRealPoint origin, AIArtHandle art )
{
        ASErr error = kNoErr;
        if (art) {
                static const long infoVars = { kInfoDocX, kInfoDocY, kInfoSizeX, kInfoSizeY, kInfoEndOfList };
                AIReal *infoValues[4];
                AIReal temp[2];
                AIRealRect artBounds;
                error = sAIArt->GetArtTransformBounds( art,0, kStroke, &artBounds);
                if ( error )
                        return error;
                temp[0] = artBounds.right - artBounds.left;
                temp[1] = artBounds.bottom - artBounds.top;
                infoValues[0] = &origin.h;
                infoValues[1] = &origin.v;
                infoValues[2] = temp;
                infoValues[3] = temp +1;
                error = sAITool->SetToolInfoVarValues( infoVars, (void**)infoValues);
                if ( error )
                        return error;
        }
}

AIAPI AIErr(* AIToolSuite::SetToolNullEventInterval)(AIToolHandle tool, AIToolTime inTime)

Deprecated:: Obsolete. Do not use.

AIAPI AIErr(* AIToolSuite::SetToolOptions)(AIToolHandle tool, ai::int32 options)

Sets the option flags of a tool.

To retain the existing flags when setting options, obtain them with GetToolOptions() and do a logical OR with the new flags.

Parameters:

	tool	The tool reference.
	options	The new options value, a logical OR of `AIToolOptions` constants.

AIAPI AIErr(* AIToolSuite::SetTooltip)(AIToolHandle tool, const char *tooltip)

Sets the tooltip string for a tool.

Parameters:

	tool	The tool reference.
	tooltip	The new tooltip string.

AIAPI AIErr(* AIToolSuite::SetToolTitle)(AIToolHandle tool, const char *title)

Sets the localizable title of a tool, which appears in the UI.

Parameters:

	tool	The tool reference.
	title	The new title string.

AIAPI AIErr(* AIToolSuite::SystemHasPressure)(AIBoolean *hasPressure)

Reports whether a pressure-sensitive device such as a graphics tablet was available on application startup.

Parameters:

hasPressure

[out] A buffer in which to return true if a pressure-sensitive device is in use.

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

AITool.h

AIToolSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Toolsets and Groups in the Tools Palette

Tool Behavior

Member Data Documentation

AIToolSuite Struct Reference
[API Suite List]