AIPreferenceSuite Struct Reference
[API Suite List]

This suite provides cross-platform access to Illustrator preferences. More...

#include <AIPreference.h>

Public Attributes
AIAPI AIErr(*	GetBooleanPreference )(const char prefix, const char suffix, AIBoolean *value)
	Retrieves a boolean preference.
AIAPI AIErr(*	PutBooleanPreference )(const char prefix, const char suffix, AIBoolean value)
	Sets a boolean preference.
AIAPI AIErr(*	GetIntegerPreference )(const char prefix, const char suffix, ai::int32 *value)
	Retrieves an integer preference.
AIAPI AIErr(*	PutIntegerPreference )(const char prefix, const char suffix, ai::int32 value)
	Sets an integer preference.
AIAPI AIErr(*	GetRealPreference )(const char prefix, const char suffix, double *value)
	Retrieves a real-number preference.
AIAPI AIErr(*	PutRealPreference )(const char prefix, const char suffix, double value)
	Sets a real-number preference.
AIAPI AIErr(*	GetStringPreference )(const char prefix, const char suffix, char *value)
	Retrieves a C-string preference.
AIAPI AIErr(*	PutStringPreference )(const char prefix, const char suffix, const char *value)
	Sets a C-string preference.
AIAPI AIErr(*	GetUnicodeStringPreference )(const char prefix, const char suffix, ai::UnicodeString &value)
	Retrieves a Unicode string preference.
AIAPI AIErr(*	PutUnicodeStringPreference )(const char prefix, const char suffix, const ai::UnicodeString &value)
	Sets a Unicode string preference.
AIAPI AIErr(*	GetBlockPreference )(const char prefix, const char suffix, void *address, ai::int32 size)
	Retrieves a block preference created with `PutBlockPreference()`.
AIAPI AIErr(*	PutBlockPreference )(const char prefix, const char suffix, void *address, ai::int32 size)
	Sets a block preference.
AIAPI AIErr(*	GetFixedPreference )(const char prefix, const char suffix, AIFixed *value)
	Retrieves a fixed-number preference.
AIAPI AIErr(*	PutFixedPreference )(const char prefix, const char suffix, AIFixed value)
	Sets a fixed-number preference.
AIAPI AIErr(*	GetFractPreference )(const char prefix, const char suffix, AIFract *value)
	Retrieves a fractional preference.
AIAPI AIErr(*	PutFractPreference )(const char prefix, const char suffix, AIFract value)
	Sets a fractional preference.
AIAPI AIErr(*	GetPascalPreference )(const char prefix, const char suffix, unsigned char *value)
	Retrieves a Pascal-string preference.
AIAPI AIErr(*	PutPascalPreference )(const char prefix, const char suffix, const unsigned char *value)
	Sets a Pascal-string preference.
AIAPI AIErr(*	GetDateTimePreference )(const char prefix, const char suffix, AIPreferenceDateTime *value)
	Retrieves a date-time preference.
AIAPI AIErr(*	PutDateTimePreference )(const char prefix, const char suffix, AIPreferenceDateTime *value)
	Sets a date-time preference.
AIAPI AIErr(*	GetPointPreference )(const char prefix, const char suffix, AIPoint *value)
	Retrieves a point preference.
AIAPI AIErr(*	PutPointPreference )(const char prefix, const char suffix, AIPoint *value)
	Sets a point preference.
AIAPI AIErr(*	GetRectPreference )(const char prefix, const char suffix, AIRect *value)
	Retrieves a rectangle preference.
AIAPI AIErr(*	PutRectPreference )(const char prefix, const char suffix, AIRect *value)
	Sets a rectangle preference.
AIAPI AIErr(*	GetFilePathSpecificationPreference )(const char prefix, const char suffix, ai::FilePath &value)
	Retrieves a file path specification preference.
AIAPI AIErr(*	PutFilePathSpecificationPreference )(const char prefix, const char suffix, const ai::FilePath &value)
	Sets a file path specification preference.
AIAPI AIErr(*	RemovePreference )(const char prefix, const char suffix)
	Deletes a preference that was defined by your plug-in.
AIAPI AIErr(*	AddPreferencePanel )(SPPluginRef pluginRef, unsigned char itemText, ai::int32 dialogID, ai::int32 options, AIPreferenceItemGroupHandle prefItemGroup, AIMenuItemHandle *menuItem)
	Adds a panel to the Preferences dialog, using a dialog you define to query the user for your plug-in preferences.
AIAPI AIErr(*	GetPreferencePanelBaseItemIndex )(AIPreferenceItemGroupHandle prefItemGroup, ai::int32 *baseIndex)
	Retrieves the index position of the base item from a preference item group.
AIAPI AIErr(*	ShowPreferencePanel )(AIPreferenceItemGroupHandle prefItemGroup)
	Displays a plug-in-defined panel in the Preferences dialog.
AIAPI AIErr(*	GetLargeIntegerPreference )(const char prefix, const char suffix, ai::int64 *value)
	Retrieves an integer preference for 64 bit data type.
AIAPI AIErr(*	PutLargeIntegerPreference )(const char prefix, const char suffix, ai::int64 value)
	Sets an integer preference for 64 bit data type.

Detailed Description

This suite provides cross-platform access to Illustrator preferences.

It allows you to store your plug-in�s preferences, save them at shutdown, and restore them at startup. The suite also allows you to access Illustrator application preferences at any time.

Illustrator reads the preferences file from disk only once, when the application is first launched, and writes it only once, when the application quits. The Preference suite functions interact with the preferences stored in memory, not with the preferences file on disk.

Accessing Plug-in Preferences

This suite also allows you to add your plug-in preferences to the Preferences dialog box. Generally, your plug-in reads its own preferences during the startup message action and writes them at shutdown.

You get and set values according to their data type. The suite provides accessors (get and put functions) for each of the basic data types: boolean, integer, real, C string, block, fixed, fract, Pascal string, date/time stamp, point, rect, and file spec.

Each function in the suite takes three arguments:

The prefix, which is generally your plug-in�s name.
The suffix, which is the name of a specific preference item in your plug-in.
The value, which is the new value to be associated with the named preference (for put) or a buffer in which to return its current value (for get). If a get function does not find the prefix/suffix pair in the preferences file, the value argument remains unchanged; you should preset the buffer to the default value for the preference you are retrieving.

For predefined prefixes and suffixes of application and Adobe plug-in preferences, see AIPreferenceKeys.h.

This example saves and retrieves preferences for a window position and visibility status:

// save preferences for plug-in dialog
error = sPref->PutBooleanPreference(kPluginName, "dialogShowing", g->dialogShowing);
error = sPref->PutPointPreference(kPluginName, "dialogPosition", &g->dialogPosition);
//retrieve preferences for plug-in dialog
g->dialogShowing = false; // default is not visible
error = sPref->GetBooleanPreference(kPluginName, "dialogShowing", &g->dialogShowing);
g->dialogPosition = { 100 , 100 }; // default position
error = sPref->GetPointPreference(kPluginName, "dialogPosition", &g->dialogPosition);

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIPreferenceSuite and kAIPreferenceVersion.

Accessing Application Preferences

Application preferences are predefined. You can examine the preferences file to find their names.

To specify an application preference, use NULL for the prefix. For the suffix, use a path derived from the preference file without the leading slash character. See also predefined suffixes in AIPreferenceKeys.h.
There is no direct way to determine the data type of an application preference. You must determine the data type based on your knowledge of Illustrator and the appearance of the value in the preference file.

For example, the constrain angle used by the Illustrator tools is an application preference. It is stored in the preference file at follows:

/constrain {
	/sin 0.0
	/cos 16.0
	/angle 0.0
	}

These values are real numbers. To retrieve the value of sin, use the accessor for the AIReal type:

AIReal r;
error = sPref->GetRealPreference(nil, "constrain/sin", &r);

The snap-to-point option is displayed as a checkbox in the General Preferences dialog, which implies that it has a boolean value. It is stored in the file as follows:

/snapToPoint 1

To retrieve the setting, use the boolean accessor:

AIBoolean snap;
error = sPref->GetBooleanPreference(nil, "snapToPoint", &snap);

Member Data Documentation

AIAPI AIErr(* AIPreferenceSuite::AddPreferencePanel)(SPPluginRef pluginRef, unsigned char *itemText, ai::int32 dialogID, ai::int32 options, AIPreferenceItemGroupHandle *prefItemGroup, AIMenuItemHandle *menuItem)

Adds a panel to the Preferences dialog, using a dialog you define to query the user for your plug-in preferences.

Adds a menu item for your panel to the Preferences submenu, creating and returning the menu item object.

Parameters:

	pluginRef	The plug-in object.
	itemText	The localizable string that appears in the Preferences submenu and in the Preferences dialog pop-up menu.
	dialogID	The unique identifier of the dialog you have defined in your plug-in resources. The elements are added to the Preferences dialog as an item group. See `ADMDialogSuite10` and `ADMItemSuite9`.
	options	Not used. Pass 0.
	prefItemGroup	[out] A buffer in which to return the new dialog item-group reference for the panel. This panel object is passed back as part of the `AIPreferencePanelMessage` when the panel is shown in the dialog. Use it with `GetPreferencePanelBaseItemIndex()` to access the dialog items when the panel is displayed.
	menuItem	[out] A buffer in which to return the new menu item reference.

AIAPI AIErr(* AIPreferenceSuite::GetBlockPreference)(const char *prefix, const char *suffix, void *address, ai::int32 size)

Retrieves a block preference created with PutBlockPreference().

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	address	[out] A buffer in which to return the value.
	size	The number of bytes allocated at `address`.

AIAPI AIErr(* AIPreferenceSuite::GetBooleanPreference)(const char *prefix, const char *suffix, AIBoolean *value)

Retrieves a boolean preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetDateTimePreference)(const char *prefix, const char *suffix, AIPreferenceDateTime *value)

Retrieves a date-time preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetFilePathSpecificationPreference)(const char *prefix, const char *suffix, ai::FilePath &value)

Retrieves a file path specification preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetFixedPreference)(const char *prefix, const char *suffix, AIFixed *value)

Retrieves a fixed-number preference.

(For compatibility with AI7 and earlier.)

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetFractPreference)(const char *prefix, const char *suffix, AIFract *value)

Retrieves a fractional preference.

(For compatibility with AI7 and earlier.)

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetIntegerPreference)(const char *prefix, const char *suffix, ai::int32 *value)

Retrieves an integer preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetLargeIntegerPreference)(const char *prefix, const char *suffix, ai::int64 *value)

Retrieves an integer preference for 64 bit data type.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetPascalPreference)(const char *prefix, const char *suffix, unsigned char *value)

Retrieves a Pascal-string preference.

(For compatibility with AI7 and earlier.)

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetPointPreference)(const char *prefix, const char *suffix, AIPoint *value)

Retrieves a point preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetPreferencePanelBaseItemIndex)(AIPreferenceItemGroupHandle prefItemGroup, ai::int32 *baseIndex)

Retrieves the index position of the base item from a preference item group.

All identifiers for items in your Preferences panel are offset by this value. The call is only valid when the Preferences dialog is displayed.

Parameters:

	prefItemGroup	TThe panel item-group object, as returned by `AddPreferencePanel()`.
	baseIndex	[out] A buffer in which to return the 0-based position index of the base item.

AIAPI AIErr(* AIPreferenceSuite::GetRealPreference)(const char *prefix, const char *suffix, double *value)

Retrieves a real-number preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetRectPreference)(const char *prefix, const char *suffix, AIRect *value)

Retrieves a rectangle preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetStringPreference)(const char *prefix, const char *suffix, char *value)

Retrieves a C-string preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::GetUnicodeStringPreference)(const char *prefix, const char *suffix, ai::UnicodeString &value)

Retrieves a Unicode string preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIPreferenceSuite::PutBlockPreference)(const char *prefix, const char *suffix, void *address, ai::int32 size)

Sets a block preference.

Use this to store data that does not fit one of the basic types. For example, you could store a color value as a single block preference rather than three or four separate integer preferences.

The preference file is a human-readable (and editable) ASCII file, and you should respect this in block data that you create. For example, write out color values as ASCII strings, not as binary values.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	address	A buffer containing the new value.
	size	The number of bytes allocated at `address`.

AIAPI AIErr(* AIPreferenceSuite::PutBooleanPreference)(const char *prefix, const char *suffix, AIBoolean value)

Sets a boolean preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutDateTimePreference)(const char *prefix, const char *suffix, AIPreferenceDateTime *value)

Sets a date-time preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutFilePathSpecificationPreference)(const char *prefix, const char *suffix, const ai::FilePath &value)

Sets a file path specification preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutFixedPreference)(const char *prefix, const char *suffix, AIFixed value)

Sets a fixed-number preference.

(For compatibility with AI7 and earlier.)

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutFractPreference)(const char *prefix, const char *suffix, AIFract value)

Sets a fractional preference.

(For compatibility with AI7 and earlier.)

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutIntegerPreference)(const char *prefix, const char *suffix, ai::int32 value)

Sets an integer preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutLargeIntegerPreference)(const char *prefix, const char *suffix, ai::int64 value)

Sets an integer preference for 64 bit data type.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutPascalPreference)(const char *prefix, const char *suffix, const unsigned char *value)

Sets a Pascal-string preference.

(For compatibility with AI7 and earlier.)

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutPointPreference)(const char *prefix, const char *suffix, AIPoint *value)

Sets a point preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutRealPreference)(const char *prefix, const char *suffix, double value)

Sets a real-number preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutRectPreference)(const char *prefix, const char *suffix, AIRect *value)

Sets a rectangle preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutStringPreference)(const char *prefix, const char *suffix, const char *value)

Sets a C-string preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::PutUnicodeStringPreference)(const char *prefix, const char *suffix, const ai::UnicodeString &value)

Sets a Unicode string preference.

Parameters:

	prefix	The name of the plug-in, or `NULL` for an application preference.
	suffix	The name of the preference.
	value	The new value.

AIAPI AIErr(* AIPreferenceSuite::RemovePreference)(const char *prefix, const char *suffix)

Deletes a preference that was defined by your plug-in.

Do not attempt to remove any other preferences.

Parameters:

	prefix	The name of the plug-in.
	suffix	The name of the preference.

AIAPI AIErr(* AIPreferenceSuite::ShowPreferencePanel)(AIPreferenceItemGroupHandle prefItemGroup)

Displays a plug-in-defined panel in the Preferences dialog.

Called by the menu item that was created by AddPreferencePanel().

Parameters:

prefItemGroup The panel item-group object, as returned by AddPreferencePanel().

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

AIPreference.h

AIPreferenceSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Accessing Plug-in Preferences

Accessing Application Preferences

Member Data Documentation

AIPreferenceSuite Struct Reference
[API Suite List]