AIUserSuite Struct Reference
[API Suite List]

This suite provides utility functions for working with Illustrator, including unit conversion utilities and a progress bar. More...

#include <AIUser.h>

List of all members.

Public Attributes
AIAPI AIBoolean(*	Cancel )(void)
	Reports whether a user has canceled the current operation.
AIAPI void(*	UpdateProgress )(ai::int32 current, ai::int32 max)
	Updates the progress bar.
AIAPI void(*	SetUpdateProgressCallback )(UpdateProgressProc func)
	Registers the progress callbacks.
AIAPI void(*	SetProgressText )(const ai::UnicodeString &text)
	Sets the text message displayed in the progress bar.
AIAPI void(*	CloseProgress )(void)
	Explicitly close the progress bar if one is currently shown.
AIAPI void(*	AIRealToString )(AIReal value, ai::int16 precision, ai::UnicodeString &string)
	Converts a number of document points to a Unicode string, using the period as a decimal separator.
AIAPI void(*	StringToAIReal )(const ai::UnicodeString &string, AIReal *value)
	Converts a Unicode string containing a number to an `AIReal` value, using the period as a decimal separator.
AIAPI void(*	IUAIRealToString )(AIReal value, ai::int16 precision, ai::UnicodeString &string)
	Converts a number of document points to a Unicode string, using the localized international utilities (IU) decimal separator.
AIAPI void(*	IUAIRealToStringWithLocale )(AIReal value, ai::int16 precision, ai::UnicodeString &string, const ai::LocaleID locale)
	Converts a number of document points to a Unicode string modified according to the scale of the document, using the localized international utilities (IU) decimal separator.
AIAPI void(*	IUAIRealToStringWithLocaleWithoutScale )(AIReal value, ai::int16 precision, ai::UnicodeString &string, const ai::LocaleID locale)
	Converts a number of document points to a Unicode string, using the localized international utilities (IU) decimal separator.
AIAPI void(*	IUStringToAIReal )(const ai::UnicodeString &string, AIReal *value)
	Converts a Unicode string containing a number to an `AIReal` value, using the localized international utilities (IU) decimal separator.
AIAPI AIErr(*	IUAIRealToStringUnits )(AIReal value, ai::int32 precision, ai::UnicodeString &string)
	Converts a number of document points to a formatted Unicode string containing a number and ruler units modified according to the scale of the document, using the localized international utilities (IU) decimal separator, and the passed preference for precision.
AIAPI AIErr(*	IUAIRealToStringUnitsWithoutScale )(AIReal value, ai::int32 precision, ai::UnicodeString &string)
	Converts a number of document points to a formatted Unicode string containing a number and ruler units, using the localized international utilities (IU) decimal separator, and the passed preference for precision.
AIAPI void(*	IUStringUnitsToAIReal )(const ai::UnicodeString &string, AIReal *value)
	Converts a formatted Unicode string containing a number expressed in ruler units to an `AIReal` value in points according to the current scale of the document.
AIAPI void(*	IUStringUnitsToAIRealWithoutScale )(const ai::UnicodeString &string, AIReal *value)
	Converts a formatted Unicode string containing a number expressed in ruler units to an `AIReal` value in points {ignores the scale of the document}.
AIAPI AIErr(*	GetUnitsString )(ai::int16 format, ai::UnicodeString &string)
	Retrieves a string representing the current ruler units.
AIAPI AIErr(*	GetGlobalObjectDisplayName )(ai::UnicodeString &name)
	Retrieves the base name of a global object, stripping off any additional token that was added to make the name unique (by a function such as `AICustomColorSuite::NewCustomColorName()`, for example).
AIAPI AIErr(*	EditInOriginalApp )(AIArtHandle art)
	Opens the appropriate application to edit a placed or raster object.
AIAPI AIErr(*	AppIdle )(void)
	Runs an "Idle Event" that allows the application to do various idle-time things like update its selection view and state.
AIAPI AIErr(*	BuildDirectoryMenu )(AIPlatformMenuHandle menu, const ai::FilePath &fileSpec)
	Builds a directory menu.
AIAPI AIErr(*	GetIndexedDirectorySpec )(ai::FilePath &fileSpec, ai::int32 index)
	Retrieves a directory.
AIAPI AIErr(*	RevealTheFile )(const ai::FilePath &fileSpec)
	Reveals a file in the Finder.
AIAPI void(*	DisableProgressCancel )(void)
	Disables (dims) the cancel or stop button in the progress bar.
AIAPI AIBoolean(*	OKToAllocateMemory )(void)
	Reports whether it is safe to allocate memory.
AIAPI AIErr(*	GetDateAndTime )(AIUserDateTime *outValue)
	Retrieves the current date and time.
AIAPI AIErr(*	GetDateString )(const AIUserDateTime *inValue, const ai::int32 formatFlag, ai::UnicodeString &dateStringUS)
AIAPI AIErr(*	GetTimeString )(const AIUserDateTime *inValue, const ai::int32 formatFlag, ai::UnicodeString &dateStringUS)
AIAPI AIErr(*	GetYear )(const AIUserDateTime inValue, int year)
	Retrieves the year value from a date-time.
AIAPI AIErr(*	GetMonth )(const AIUserDateTime inValue, int month)
	Retrieves the month value from a date-time.
AIAPI AIErr(*	GetDay )(const AIUserDateTime inValue, int day)
	Retrieves the day value from a date-time.
AIAPI AIErr(*	GetHour )(const AIUserDateTime inValue, int hour)
	Retrieves the hour value from a date-time.
AIAPI AIErr(*	GetMinute )(const AIUserDateTime inValue, int minute)
	Retrieves the minute value from a date-time.
AIAPI AIErr(*	GetSecond )(const AIUserDateTime inValue, int second)
	Retrieves the second value from a date-time.
AIAPI AIErr(*	GetDayOfWeek )(const AIUserDateTime inValue, int dayOfWeek)
	Retrieves the day-of-week value from a date-time.
AIAPI AIErr(*	LaunchApp )(const ai::FilePath &spFileSpec, ASBoolean openDoc)
	Launches an application, and optionally opens the current document in it.
AIAPI AIErr(*	NextName )(AIAutoNameGenerator &set, ai::UnicodeString &name)
	Generates an appropriate name for a named object, such as a layer, swatch, or style, according to the naming rules for that collection.
AIAPI AIErr(*	CopyOfName )(AIAutoNameGenerator &set, const ai::UnicodeString &original, ai::UnicodeString &copy)
	Generates an appropriate name for a copy of a named object, such as a layer, swatch, or style, according to the naming rules for that collection.
AIAPI AIErr(*	SameName )(const ai::UnicodeString &name1, const ai::UnicodeString &name2, AIBoolean &same)
	Tests for equality of names within a collection of named objects.
AIAPI AIErr(*	PutFileDialog )(const ai::UnicodeString &title, const AIFileDialogFilters *, const ai::UnicodeString &defaultName, ai::FilePath &ioFilePath)
	Opens a platform-specific dialog for saving a file.
AIAPI AIErr(*	GetFileDialog )(const ai::UnicodeString &title, const AIFileDialogFilters *, ai::FilePath &ioFilePath)
	Opens a platform-specific dialog for opening a file.
AIAPI AIErr(*	GetDirectoryDialog )(const ai::UnicodeString &title, ai::FilePath &ioFilePath)
	Opens a platform-specific dialog for choosing a folder.
AIAPI AIBoolean(*	OKCancelAlert )(const ai::UnicodeString &msg, AIBoolean defaultOk, const char *dontShowKey)
	Displays an alert dialog with a warning icon and OK and Cancel buttons.
AIAPI void(*	WarningAlert )(const ai::UnicodeString &msg, const char *dontShowKey)
	Displays an alert dialog with a warning icon and an OK button.
AIAPI void(*	MessageAlertEx )(const ai::UnicodeString &msg, const char *dontShowKey)
	Displays an modal alert dialog with a warning icon and an OK button which doesnot get dismissed on ESC key.
AIAPI AIAnswer(*	QuestionAlert )(const ai::UnicodeString &msg)
	Displays a predefined dialog with a yes/no question.
AIAPI AIAnswer(*	YesNoAlert )(const ai::UnicodeString &msg)
	Displays a predefined dialog with a yes/no question.
AIAPI void(*	ErrorAlert )(const ai::UnicodeString &msg)
	Displays a predefined dialog that informs the user that an error occurred.
AIAPI void(*	MessageAlert )(const ai::UnicodeString &msg)
	Displays a predefined dialog with an informational message.
AIAPI AIBoolean(*	ChooseFromOSColorPicker )(const AIPoint &inLocation, const AIRGBColor &inColor, AIRGBColor *outColor)
	Invokes the platform-specific color picker dialog.
AIAPI AIErr(*	EvaluateExpression )(const ai::UnicodeString &expr, const AIExpressionOptions &options, ai::UnicodeString &evaluatedExpr, AIBoolean &isChanged, AIDouble &numericValue)
	Evaluates a numeric expression to create a formatted string suitable [This had already the document scale of the document applied] for display.
AIAPI AIErr(*	EvaluateExpressionWithoutScale )(const ai::UnicodeString &expr, const AIExpressionOptions &options, ai::UnicodeString &evaluatedExpr, AIBoolean &isChanged, AIDouble &numericValue)
	Evaluates a numeric expression to create a formatted string suitable for display.
AIAPI AIErr(*	GetInputFromUser )(const ai::UnicodeString &title, const ai::UnicodeString messageText, const ai::UnicodeString &label, ai::UnicodeString &ioField, IsValidInputProc validator, void userdata, ai::int32 maxInputChars)
	Invokes a modal dialog in which the user must input text.
AIAPI AIErr(*	CreateCursorResourceMgr )(SPPluginRef, AIResourceManagerHandle *inRscMgr)
	Creates a singleton resource manager instance to be used for cursors.
AIAPI AIErr(*	SetCursor )(ai::int32 cursorID, AIResourceManagerHandle inRscMgr)
	Sets the image to be used for the plug-in's cursor.
AIAPI AIErr(*	SetSVGCursor )(ai::int32 cursorID, AIResourceManagerHandle inRscMgr)
	Sets the SVG image to be used for the plug-in's cursor.
AIAPI AIErr(*	DisposeCursorResourceMgr )(AIResourceManagerHandle)
	Disposes of the plug-in's singleton resource manager.
AIAPI AIErr(*	GetAILanguageCode )(ai::UnicodeString &lang)
	Reports the current language in use.
AIAPI AIReal(*	GetMaximumScaleFactorOnSystem )()
	Reports the maximum scale factor for all the screens in a Mac OS system, or the application's UI scale factor in a Windows system.
AIAPI AIReal(*	GetArtToViewScaleFactor )(AIDocumentViewHandle view)
	Reports the ratio of Art Scale factor and View Scale Factor.
AIAPI AIReal(*	GetAppScaleFactor )()
	This API returns the actual application scale factor when Illustrator is launched.
AIAPI AIErr(*	LaunchFolder )(ai::FilePath folderPath)
	Launches a folder.

Detailed Description

This suite provides utility functions for working with Illustrator, including unit conversion utilities and a progress bar.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIUserSuite and kAIUserSuiteVersion.

Member Data Documentation

AIAPI void(* AIUserSuite::AIRealToString)(AIReal value, ai::int16 precision, ai::UnicodeString &string)

Converts a number of document points to a Unicode string, using the period as a decimal separator.

(Note that this function does not return an error code.)

Parameters:

	value	The value to convert.
	precision	The number of digits to the right of the decimal, in the range [0..4].
	string	[out] A buffer in which to return the converted value, at least 12 characters.

AIAPI AIErr(* AIUserSuite::AppIdle)(void)

Runs an "Idle Event" that allows the application to do various idle-time things like update its selection view and state.

Can be useful if you have code that has its own message processing.

AIAPI AIErr(* AIUserSuite::BuildDirectoryMenu)(AIPlatformMenuHandle menu, const ai::FilePath &fileSpec)

Builds a directory menu.

Available only in Mac OS. Builds a menu consisting of the specified path as well as all parent directories of that path.

Parameters:

	menu	The platform-specific menu object.
	fileSpec	The file object for the directory.

AIAPI AIBoolean(* AIUserSuite::Cancel)(void)

Reports whether a user has canceled the current operation.

(Note that this function returns a boolean value, not an error code.)

Returns:: True if the user has canceled an operation by pressing Command-dot or clicking Cancel or Stop in the progress bar.

AIAPI AIBoolean(* AIUserSuite::ChooseFromOSColorPicker)(const AIPoint &inLocation, const AIRGBColor &inColor, AIRGBColor *outColor)

Invokes the platform-specific color picker dialog.

Parameters:

	inLocation[int]	The position of the dialog. (-1, -1) centers the dialog on the screen.
	inColor[in]	The initially selected color value.
	outColor	[out] A buffer in which to return the selected color.

Returns:: True if the user selected a color, false otherwise.

AIAPI void(* AIUserSuite::CloseProgress)(void)

Explicitly close the progress bar if one is currently shown.

(Note that this function does not return an error code.)

AIAPI AIErr(* AIUserSuite::CopyOfName)(AIAutoNameGenerator &set, const ai::UnicodeString &original, ai::UnicodeString &copy)

Generates an appropriate name for a copy of a named object, such as a layer, swatch, or style, according to the naming rules for that collection.

Parameters:

	set	The naming rules.
	original	Original name to copy (may be an empty string).
	copy	[out] An ai::UnicodeString in which to return the generated name.

AIAPI AIErr(* AIUserSuite::CreateCursorResourceMgr)(SPPluginRef, AIResourceManagerHandle *inRscMgr)

Creates a singleton resource manager instance to be used for cursors.

Call once for a plugin, after startup is completed. Destroy the instance on application shutdown (not plug-in shutdown).

Parameters:

inRscMgr

[out] A buffer in which to return the resource-manager handle.

See also:: DisposeCursorResourceMgr()

AIAPI void(* AIUserSuite::DisableProgressCancel)(void)

Disables (dims) the cancel or stop button in the progress bar.

(Note that this function does not return an error code.)

AIAPI AIErr(* AIUserSuite::DisposeCursorResourceMgr)(AIResourceManagerHandle)

Disposes of the plug-in's singleton resource manager.

Call once when kAIApplicationShutdownNotifier is received. Do not call as part of plug-in shutdown.

Parameters:

The

resource manager handle, as returned on creation.

AIAPI AIErr(* AIUserSuite::EditInOriginalApp)(AIArtHandle art)

Opens the appropriate application to edit a placed or raster object.

This is equivalent to an option-double-click on the object with the selection tool.

Parameters:

art

The placed or raster art object.

Returns:: kApplicationNotFoundErr error if the application is not found.
kObjectNotLinkedErr error if the object is not a placed or raster object.

AIAPI void(* AIUserSuite::ErrorAlert)(const ai::UnicodeString &msg)

Displays a predefined dialog that informs the user that an error occurred.

The dialog displays text specified with a unicodeString, with the platform-specific error icon at the left, and an OK button.

Parameters:

msg

The text string.

Returns:: Nothing.It doesnot return an AIErr

See also:: MessageAlert(), QuestionAlert(), YesNoAlert()

AIAPI AIErr(* AIUserSuite::EvaluateExpression)(const ai::UnicodeString &expr, const AIExpressionOptions &options, ai::UnicodeString &evaluatedExpr, AIBoolean &isChanged, AIDouble &numericValue)

Evaluates a numeric expression to create a formatted string suitable [This had already the document scale of the document applied] for display.

Call, for example, when a numeric edit control loses focus or the user presses "=". If the result of evaluation is not a valid numeric value as per options specified, it is recommended that the associated control display the last known-good value, or a blank string accompanied by a beep or other error indicator.

Parameters:

	expr	[in] The expression to be evaluated (typically entered by the user in the control).
	options	[in] An `AIExpressionOptions` structure that determines how a numeric result is obtained. Specifies the units for the result, a range to which the result is clipped, and the precision.
	evaluatedExpr	[out] A buffer in which to return the formatted display string.
	isChanged	[out] A buffer in which to return true if the result of evaluation is different from result of user input. Example in case of non numeric input or out of bounds input.
	numericValue	[out] A buffer in which to return the numeric value, according to the specified options.

AIAPI AIErr(* AIUserSuite::EvaluateExpressionWithoutScale)(const ai::UnicodeString &expr, const AIExpressionOptions &options, ai::UnicodeString &evaluatedExpr, AIBoolean &isChanged, AIDouble &numericValue)

Evaluates a numeric expression to create a formatted string suitable for display.

Call, for example, when a numeric edit control loses focus or the user presses "=". If the result of evaluation is not a valid numeric value as per options specified, it is recommended that the associated control display the last known-good value, or a blank string accompanied by a beep or other error indicator.

Parameters:

	expr	[in] The expression to be evaluated (typically entered by the user in the control).
	options	[in] An `AIExpressionOptions` structure that determines how a numeric result is obtained. Specifies the units for the result, a range to which the result is clipped, and the precision.
	evaluatedExpr	[out] A buffer in which to return the formatted display string.
	isChanged	[out] A buffer in which to return true if the result of evaluation is different from result of user input. Example in case of non numeric input or out of bounds input.
	numericValue	[out] A buffer in which to return the numeric value, according to the specified options.

AIAPI AIErr(* AIUserSuite::GetAILanguageCode)(ai::UnicodeString &lang)

Reports the current language in use.

Parameters:

lang

[out] A buffer in which to return the language code.

AIAPI AIReal(* AIUserSuite::GetAppScaleFactor)()

This API returns the actual application scale factor when Illustrator is launched.

If the application scale factor preference for the current OS exceeds the maximum application scale factor supported by the Illustrator for the current monitor resolution, the application scale factor is automatically reset to the maximum scale factor.

AIAPI AIReal(* AIUserSuite::GetArtToViewScaleFactor)(AIDocumentViewHandle view)

Reports the ratio of Art Scale factor and View Scale Factor.

(ArtScaleFactor/ ViewScaleFactor)

AIAPI AIErr(* AIUserSuite::GetDateAndTime)(AIUserDateTime *outValue)

Retrieves the current date and time.

Parameters:

outValue

[out] A buffer in which to return the current date-time value.

AIAPI AIErr(* AIUserSuite::GetDateString)(const AIUserDateTime *inValue, const ai::int32 formatFlag, ai::UnicodeString &dateStringUS)

AIAPI AIErr(* AIUserSuite::GetDay)(const AIUserDateTime *inValue, int *day)

Retrieves the day value from a date-time.

Parameters:

	inValue	The date-time value, or `NULL` to get the current date-time.
	year	[out] A buffer in which to return the value.

AIAPI AIErr(* AIUserSuite::GetDayOfWeek)(const AIUserDateTime *inValue, int *dayOfWeek)

Retrieves the day-of-week value from a date-time.

Parameters:

	inValue	The date-time value, or `NULL` to get the current date-time.
	year	[out] A buffer in which to return the value.

AIAPI AIErr(* AIUserSuite::GetDirectoryDialog)(const ai::UnicodeString &title, ai::FilePath &ioFilePath)

Opens a platform-specific dialog for choosing a folder.

Parameters:

	title	Dialog title.
	ioFilePath	[in, out] A buffer in which to pass the folder to browse or `NULL`, and return the full path of the folder chosen by the user.

AIAPI AIErr(* AIUserSuite::GetFileDialog)(const ai::UnicodeString &title, const AIFileDialogFilters *, ai::FilePath &ioFilePath)

Opens a platform-specific dialog for opening a file.

Parameters:

	title	Dialog title.
	AIFileDialogFilters	File types to open. Can be `NULL`.
	ioFilePath	[in, out] A buffer in which to pass the directory to browse or `NULL`, and return the full path of the file chosen by the user.

AIAPI AIErr(* AIUserSuite::GetGlobalObjectDisplayName)(ai::UnicodeString &name)

Retrieves the base name of a global object, stripping off any additional token that was added to make the name unique (by a function such as AICustomColorSuite::NewCustomColorName(), for example).

Parameters:

name

[in, out] A string in which to pass a unique name and return the base name. The string is modified in place.

AIAPI AIErr(* AIUserSuite::GetHour)(const AIUserDateTime *inValue, int *hour)

Retrieves the hour value from a date-time.

Parameters:

	inValue	The date-time value, or `NULL` to get the current date-time.
	year	[out] A buffer in which to return the value.

AIAPI AIErr(* AIUserSuite::GetIndexedDirectorySpec)(ai::FilePath &fileSpec, ai::int32 index)

Retrieves a directory.

Available only in Mac OS. Returns a filespec pertaining to the 'index' item inside of the menu returned by BuildDirectoryMenu.

Parameters:

	fileSpec	The file object for the directory.
	index	The 0-based index of the directory.

AIAPI AIErr(* AIUserSuite::GetInputFromUser)(const ai::UnicodeString &title, const ai::UnicodeString *messageText, const ai::UnicodeString &label, ai::UnicodeString &ioField, IsValidInputProc validator, void *userdata, ai::int32 maxInputChars)

Invokes a modal dialog in which the user must input text.

The dialog cannot be dismissed until text is entered. If default text is provided, however, the user can dismiss the dialog without changing that text.

Parameters:

	title	The title for the dialog
	messageText	A text message to display above the input field, or NULL to display no message.
	label	The label for the text field.
	ioName	[in/out] On input, a default string for the text field. This is replaced by text that the user enters, if any.
	IsValidInputProc	A function pointer to a validation callback that validates the input as typed by the user. The first parameter to this call is a `AIValidationStage` constant that reports whether the call is made upon text entry, or upon dismissal of the dialog.
	userdata	Developer-defined user data to be passed to the validation callback.
	maxInputChars	The maximum number of characters that user can enter in the text field.

AIAPI AIReal(* AIUserSuite::GetMaximumScaleFactorOnSystem)()

Reports the maximum scale factor for all the screens in a Mac OS system, or the application's UI scale factor in a Windows system.

Returns:: The scale factor.

AIAPI AIErr(* AIUserSuite::GetMinute)(const AIUserDateTime *inValue, int *minute)

Retrieves the minute value from a date-time.

Parameters:

	inValue	The date-time value, or `NULL` to get the current date-time.
	year	[out] A buffer in which to return the value.

AIAPI AIErr(* AIUserSuite::GetMonth)(const AIUserDateTime *inValue, int *month)

Retrieves the month value from a date-time.

Parameters:

	inValue	The date-time value, or `NULL` to get the current date-time.
	year	[out] A buffer in which to return the value.

AIAPI AIErr(* AIUserSuite::GetSecond)(const AIUserDateTime *inValue, int *second)

Retrieves the second value from a date-time.

Parameters:

	inValue	The date-time value, or `NULL` to get the current date-time.
	year	[out] A buffer in which to return the value.

AIAPI AIErr(* AIUserSuite::GetTimeString)(const AIUserDateTime *inValue, const ai::int32 formatFlag, ai::UnicodeString &dateStringUS)

AIAPI AIErr(* AIUserSuite::GetUnitsString)(ai::int16 format, ai::UnicodeString &string)

Retrieves a string representing the current ruler units.

Parameters:

	format	The format for the result, one of: `kShortUnits` `kLongSingularUnits` `kLongPluralUnits` If, for instance, the current unit is inches, the returned string would be "in", "inch", or "inches".
	string	[out] A buffer in which to return the units string, at least 20 characters.

AIAPI AIErr(* AIUserSuite::GetYear)(const AIUserDateTime *inValue, int *year)

Retrieves the year value from a date-time.

Parameters:

	inValue	The date-time value, or `NULL` to get the current date-time.
	year	[out] A buffer in which to return the value.

AIAPI void(* AIUserSuite::IUAIRealToString)(AIReal value, ai::int16 precision, ai::UnicodeString &string)

Converts a number of document points to a Unicode string, using the localized international utilities (IU) decimal separator.

(Note that this function does not return an error code.)

Parameters:

	value	The value to convert.
	precision	The number of digits to the right of the decimal, in the range [0..4].
	string	[out] A buffer in which to return the converted value, at least 12 characters.

AIAPI AIErr(* AIUserSuite::IUAIRealToStringUnits)(AIReal value, ai::int32 precision, ai::UnicodeString &string)

Converts a number of document points to a formatted Unicode string containing a number and ruler units modified according to the scale of the document, using the localized international utilities (IU) decimal separator, and the passed preference for precision.

If passed precision value is -1 then user preference for precision is used. Uses the currently set ruler units, which can be inches, points, or centimeters. (Note that this function does not return an error code.)

Parameters:

	value	The value to convert.
	precision	The number of digits to the right of the decimal, in the range [0..4]. Pass -1 if user preference for precision should be used.
	string	[out] A buffer in which to return the converted value, at least 12 characters.

AIAPI AIErr(* AIUserSuite::IUAIRealToStringUnitsWithoutScale)(AIReal value, ai::int32 precision, ai::UnicodeString &string)

Converts a number of document points to a formatted Unicode string containing a number and ruler units, using the localized international utilities (IU) decimal separator, and the passed preference for precision.

If passed precision value is -1 then user preference for precision is used. Uses the currently set ruler units, which can be inches, points, or centimeters. (Note that this function does not return an error code.)

Parameters:

	value	The value to convert.
	precision	The number of digits to the right of the decimal, in the range [0..4]. Pass -1 if user preference for precision should be used.
	string	[out] A buffer in which to return the converted value, at least 12 characters.

AIAPI void(* AIUserSuite::IUAIRealToStringWithLocale)(AIReal value, ai::int16 precision, ai::UnicodeString &string, const ai::LocaleID locale)

Converts a number of document points to a Unicode string modified according to the scale of the document, using the localized international utilities (IU) decimal separator.

(Note that this function does not return an error code.)

Parameters:

	value	The value to convert.
	precision	The number of digits to the right of the decimal, in the range [0..4].
	string	[out] A buffer in which to return the converted value, at least 12 characters.
	Locale	unique identifying code like ai::Locale::kSystem.

AIAPI void(* AIUserSuite::IUAIRealToStringWithLocaleWithoutScale)(AIReal value, ai::int16 precision, ai::UnicodeString &string, const ai::LocaleID locale)

Converts a number of document points to a Unicode string, using the localized international utilities (IU) decimal separator.

(Note that this function does not return an error code.)

Parameters:

	value	The value to convert.
	precision	The number of digits to the right of the decimal, in the range [0..4].
	string	[out] A buffer in which to return the converted value, at least 12 characters.
	Locale	unique identifying code like ai::Locale::kSystem.

AIAPI void(* AIUserSuite::IUStringToAIReal)(const ai::UnicodeString &string, AIReal *value)

Converts a Unicode string containing a number to an AIReal value, using the localized international utilities (IU) decimal separator.

(Note that this function does not return an error code.)

Parameters:

	string	The string to convert.
	value	[out] A buffer in which to return the converted value. If the string is not a number, this is set to `kAIRealUnknown`.

AIAPI void(* AIUserSuite::IUStringUnitsToAIReal)(const ai::UnicodeString &string, AIReal *value)

Converts a formatted Unicode string containing a number expressed in ruler units to an AIReal value in points according to the current scale of the document.

The current ruler units for the artwork are used as the original units to scale the result, and the user's preferences for precision are applied. (Note that this function does not return an error code.)

Parameters:

	string	The string to convert, which uses the localized international utilities (IU) decimal separator. It can contain a unit specifier, one of "in", "pt", or "cm". If no unit specifier is included, uses the current ruler units.
	value	[out] A buffer in which to return the converted value. If the string is not a number, this is set to `kAIRealUnknown`.

AIAPI void(* AIUserSuite::IUStringUnitsToAIRealWithoutScale)(const ai::UnicodeString &string, AIReal *value)

Converts a formatted Unicode string containing a number expressed in ruler units to an AIReal value in points {ignores the scale of the document}.

The current ruler units for the artwork are used as the original units to scale the result, and the user's preferences for precision are applied. (Note that this function does not return an error code.)

Parameters:

	string	The string to convert, which uses the localized international utilities (IU) decimal separator. It can contain a unit specifier, one of "in", "pt", or "cm". If no unit specifier is included, uses the current ruler units.
	value	[out] A buffer in which to return the converted value. If the string is not a number, this is set to `kAIRealUnknown`.

AIAPI AIErr(* AIUserSuite::LaunchApp)(const ai::FilePath &spFileSpec, ASBoolean openDoc)

Launches an application, and optionally opens the current document in it.

Parameters:

	spFileSpec	The file specification for the application's executable.
	openDoc	True to open the current document in the new application.

AIAPI AIErr(* AIUserSuite::LaunchFolder)(ai::FilePath folderPath)

Launches a folder.

Parameters:

folderPath

Path of the folder to launch.

Returns:: kBadParameterErr if the path object is invalid or references a file rather than a folder.

AIAPI void(* AIUserSuite::MessageAlert)(const ai::UnicodeString &msg)

Displays a predefined dialog with an informational message.

The dialog displays text specified with a unicodeString, with the platform-specific message icon at the left, and an OK button.

Parameters:

msg

The text string.

Returns:: Nothing.It doesnot return an AIErr

See also:: ErrorAlert(), QuestionAlert(), YesNoAlert()

AIAPI void(* AIUserSuite::MessageAlertEx)(const ai::UnicodeString &msg, const char *dontShowKey)

Displays an modal alert dialog with a warning icon and an OK button which doesnot get dismissed on ESC key.

Parameters:

	msg	The message to display.
	dontShowKey	A preference key to use with the "Do not show again" checkbox, in which to store the user's choice and save it in the application preferences file. When `NULL`, the dialog does not include the checkbox.

Returns:: Nothing. It does not return AIErr

AIAPI AIErr(* AIUserSuite::NextName)(AIAutoNameGenerator &set, ai::UnicodeString &name)

Generates an appropriate name for a named object, such as a layer, swatch, or style, according to the naming rules for that collection.

Parameters:

	set	The naming rules.
	name	[out] An ai::UnicodeString in which to return the generated name.

AIAPI AIBoolean(* AIUserSuite::OKCancelAlert)(const ai::UnicodeString &msg, AIBoolean defaultOk, const char *dontShowKey)

Displays an alert dialog with a warning icon and OK and Cancel buttons.

Parameters:

	msg	The message to display.
	defaultOk	True to make the OK button the default, false to make Cancel the default.
	dontShowKey	A preference key to use with the "Do not show again" checkbox, in which to store the user's choice and save it in the application preferences file. When `NULL`, the dialog does not include the checkbox.

Returns:: True if the dialog was dismissed with the OK button, false if it was canceled.

AIAPI AIBoolean(* AIUserSuite::OKToAllocateMemory)(void)

Reports whether it is safe to allocate memory.

Calls when a timer or other asynchronous event trigger an action that allocates memory. Not needed when handling notifications or user events; the plug-in does not receive these when it is not ok to allocate memory. (Note that this function returns a boolean value, not an error code.)

Parameters:

True

if it is safe to allocate memory. False if it is not safe; in this case, reschedule the action and try again later.

AIAPI AIErr(* AIUserSuite::PutFileDialog)(const ai::UnicodeString &title, const AIFileDialogFilters *, const ai::UnicodeString &defaultName, ai::FilePath &ioFilePath)

Opens a platform-specific dialog for saving a file.

Parameters:

	title	Dialog title.
	AIFileDialogFilters	File types to save. Can be `NULL`.
	defaultName	Default file name to appear in dialog. Can be `NULL`.
	ioFilePath	[in, out] A buffer in which to pass the directory to browse or `NULL`, and return the full path of the file chosen by the user.

AIAPI AIAnswer(* AIUserSuite::QuestionAlert)(const ai::UnicodeString &msg)

Displays a predefined dialog with a yes/no question.

The dialog displays text specified with a unicodeString, and buttons with default labels Yes, No, and Cancel.

Parameters:

msg

The text string.

Returns:: The AIAnswer constant for the button pressed to dismiss the dialog, or kAIAnswer_Invalid in case of error.

See also:: ErrorAlert(), MessageAlert(), YesNoAlert()

AIAPI AIErr(* AIUserSuite::RevealTheFile)(const ai::FilePath &fileSpec)

Reveals a file in the Finder.

Available only in Mac OS.

Parameters:

fileSpec

The file object for the file.

AIAPI AIErr(* AIUserSuite::SameName)(const ai::UnicodeString &name1, const ai::UnicodeString &name2, AIBoolean &same)

Tests for equality of names within a collection of named objects.

Use in the AIAutoNameGenerator::HasName() callback function to test whether an automatically generated name matches a name already in the collection.

Parameters:

	name1	The first name.
	name2	The second name.
	same	[out] An AIBoolean reference in which to return true if the names are the same.

AIAPI AIErr(* AIUserSuite::SetCursor)(ai::int32 cursorID, AIResourceManagerHandle inRscMgr)

Sets the image to be used for the plug-in's cursor.

Parameters:

	cursorID	The resource ID of the cursor, or a `AIPredefinedCursor` constant value to use one of the predefined cursors. Cursor images must be in PNG format.
	inRscMgr	The resource manager, as returned by `CreateCursorResourceMgr()`.

AIAPI void(* AIUserSuite::SetProgressText)(const ai::UnicodeString &text)

Sets the text message displayed in the progress bar.

If not provided, the text line is blank. (Note that this function does not return an error code.)

Parameters:

text

The text message.

AIAPI AIErr(* AIUserSuite::SetSVGCursor)(ai::int32 cursorID, AIResourceManagerHandle inRscMgr)

Sets the SVG image to be used for the plug-in's cursor.

Parameters:

	cursorID	The resource ID of the cursor. Cursor images must be in 2x scaled SVG format.
	inRscMgr	The resource manager, as returned by `CreateCursorResourceMgr()`.

AIAPI void(* AIUserSuite::SetUpdateProgressCallback)(UpdateProgressProc func)

Registers the progress callbacks.

(Note that this function does not return an error code.)

Parameters:

UpdateProgressProc - A function pointer to progress callback. The first parameter to this call is current , a number between 0 and max that represents how far the operation has progressed and the second parameter is max , the maximum value, representing 100% progress.

AIAPI void(* AIUserSuite::StringToAIReal)(const ai::UnicodeString &string, AIReal *value)

Converts a Unicode string containing a number to an AIReal value, using the period as a decimal separator.

(Note that this function does not return an error code.)

Parameters:

	string	The string to convert.
	value	[out] A buffer in which to return the converted value. If the string is not a number, this is set to `kAIRealUnknown`.

AIAPI void(* AIUserSuite::UpdateProgress)(ai::int32 current, ai::int32 max)

Updates the progress bar.

(Note that this function does not return an error code.)

Parameters:

	current	A number between 0 and `max` that represents how far the operation has progressed.
	max	The maximum value, representing 100% progress.

AIAPI void(* AIUserSuite::WarningAlert)(const ai::UnicodeString &msg, const char *dontShowKey)

Displays an alert dialog with a warning icon and an OK button.

Parameters:

	msg	The message to display.
	dontShowKey	A preference key to use with the "Do not show again" checkbox, in which to store the user's choice and save it in the application preferences file. When `NULL`, the dialog does not include the checkbox.

Returns:: Nothing. It does not return AIErr

AIAPI AIAnswer(* AIUserSuite::YesNoAlert)(const ai::UnicodeString &msg)

Displays a predefined dialog with a yes/no question.

The dialog displays text specified with a unicodeString, and buttons with default labels Yes and No.

Parameters:

msg

The text string.

Returns:: The AIAnswer constant for the button pressed to dismiss the dialog, or kAIAnswer_Invalid in case of error.

See also:: ErrorAlert(), MessageAlert(), QuestionAlert()

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

AIUser.h

AIUserSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIUserSuite Struct Reference
[API Suite List]