AIFileFormatSuite Struct Reference
[API Suite List]

This suite provides functions for creating and managing file-format plug-ins, which extend the number of file formats that Illustrator can read and write. More...

#include <AIFileFormat.h>

List of all members.

Public Attributes
AIAPI AIErr(*	AddFileFormat )(SPPluginRef self, const char name, PlatformAddFileFormatData data, ai::int32 options, AIFileFormatHandle *fileFormat, ai::int32 extendedOptions)
	Adds a file format to the standard file dialog.
AIAPI AIErr(*	GetFileFormatName )(AIFileFormatHandle fileFormat, const char **name)
	Retrieves the name of a file format.
AIAPI AIErr(*	GetFileFormatOptions )(AIFileFormatHandle fileFormat, ai::int32 *options)
	Retrieves the option flags of a file format.
AIAPI AIErr(*	SetFileFormatOptions )(AIFileFormatHandle fileFormat, ai::int32 options)
	Sets the option flags of a file format, which specify what file operations can be handled.
AIAPI AIErr(*	GetFileFormatPlugin )(AIFileFormatHandle fileFormat, SPPluginRef *plugin)
	Retrieves a reference to the plug-in that installed a file format, to be passed to `AIPluginSuite` functions.
AIAPI AIErr(*	CountFileFormats )(ai::int32 *count)
	Gets the number of installed plug-in file formats.
AIAPI AIErr(*	GetNthFileFormat )(ai::int32 n, AIFileFormatHandle *fileFormat)
	Retrieves a plug-in file format reference by position index.
AIAPI AIErr(*	GetFileFormatExtension )(AIFileFormatHandle fileFormat, ai::UnicodeString &extension)
	Retrieves the file extension for a plug-in file format.
AIAPI AIErr(*	AddFileFormatEx )(SPPluginRef self, const char name, PlatformAddFileFormatExData dataEx, ai::int32 options, AIFileFormatHandle *fileFormat, ai::int32 extendedOptions)
	Adds a plug-in file format.
AIAPI AIErr(*	GetFileFormatTitle )(AIFileFormatHandle fileFormat, ai::UnicodeString &szTitle)
	Retrieves the localizable display name of a plug-in file format.
AIAPI AIErr(*	GetFileFormatType )(AIFileFormatHandle fileFormat, ai::int32 maxNumTypes, ai::int32 typeList)
	Retrieves the Mac OS file types for a plug-in file format.
AIAPI AIErr(*	SetFileFormatFilter )(AIFileFormatHandle fileFormat, ai::int32 numPairs, AICreatorTypePair *pairList, const ai::UnicodeString &extensions)
	Associates a file format with a file type filter.
AIAPI AIErr(*	GetFileFormatCreatorType )(AIFileFormatHandle fileFormat, ai::int32 maxNumPairs, AICreatorTypePair pairList)
	Retrieves the file type filter for a file format, as specified by (creator, type) pairs for Mac OS.
AIAPI AIErr(*	PutFile )(ai::int32 options, const unsigned char dlgTitle, ai::FilePath &fileSpec, AIFileFormatHandle fileFormat, AIBoolean *good)
	Invokes the File > Save dialog, allowing you to filter the available file formats.
AIAPI AIErr(*	SetFileFormatPriority )(AIFileFormatHandle fileFormat, ai::int32 priority)
	Sets the priority of a file format.
AIAPI AIErr(*	FindMatchingFileFormats )(ai::int32 options, const ai::FilePath &file, ai::int32 maxMatches, AIFileFormatHandle matchingFormats[], ai::int32 *numMatches)
	Finds all plug-in file formats that can perform a specified operation for a file.
AIAPI AIErr(*	ResolveImportConflicts )()
	Obsolete.
AIAPI AIVersion(*	GetFirstVersionUsingPlacedArt )(AIFileFormatHandle fileFormat)
	Reports the version of Illustrator in which a raster file format, for example the JPEG file format plug-in, was converted from using raster art to using placed art in order to perform a place link operation.
AIAPI AIErr(*	SetFirstVersionUsingPlacedArt )(AIFileFormatHandle fileFormat, AIVersion version)
	Sets the version of Illustrator in which a raster file format was converted from using raster art to using placed art in order to perform a place link operation.
AIAPI AIErr(*	GetFileStartupProfileType )(const ai::FilePath &file, AIDocumentStartupProfile *docStartupProfile)
	Retrieves the Illustrator startup profile type from the XMP metadata embedded in a file.
AIAPI AIErr(*	GetStartupFileOfType )(const AIDocumentStartupProfile docStartupProfile, ai::FilePath &profile)
	Retrieves the Illustrator default document profile from the startup-profile type.
AIAPI AIErr(*	GetFileFormatExtendedOptions )(AIFileFormatHandle fileFormat, ai::int32 *extendedOptions)
	Retrieves the extended option flags of a file format.
AIAPI AIErr(*	SetFileFormatExtendedOptions )(AIFileFormatHandle fileFormat, ai::int32 extendedOptions)
	Sets the extended option flags of a file format, which specify what file operations can be handled.
AIAPI AIErr(*	GoExport )(AIActionParamValueRef actionParam)
	Used for exporting the current document as one whole file or as multiple artBoards.

Detailed Description

This suite provides functions for creating and managing file-format plug-ins, which extend the number of file formats that Illustrator can read and write.

Reading a format can be transparent to the user; when a file of the defined type is selected in the Open dialog, your file format plug-in creates artwork in the Illustrator document. If there is a plug-in that writes a file format, that format appears in the Save As dialog as an option for the user to select. If it is selected, the plug-in walks the artwork tree and writes out information on the artwork in the appropriate manner. If your plug-in needs more parameters for either reading or writing, it defines a modal dialog to interact with the user.

Plug-ins tell Illustrator about the file formats they support by specifying platform file information: the type (such as 'ART3') in Mac OS, or the extension (such as '.AI') in Windows. Plug-ins also indicate what read/write capabilities they support.

One plug-in can register multiple formats. Illustrator handles some parts of the file I/O process, and the plug-in does the rest.

A file-format plug-in receives message actions telling it to:

Check if a file can be read, The Check selector is sent only to plug-ins that can read files. It extends the simple type checking done by the Open dialog.
Ask for parameters. This selector can be ignored if the plug-in does not need user input.
Go. In response, your plug-in executes the read or write operation.

If a file format plug-in can read, files of its registered file type appear in the file list of the Open dialog. In addition to screening by file type, Illustrator sends a selector giving a plug-in a chance to check that the file can be read. This is useful in the case of text files or files from a different file system. If more than one format matches the type, Illustrator determines which plug-in should actually open the file, asking the user if necessary.

If a file format plug-in supports both reading and writing, when reading it should store any information about the file needed to write the file back to disk. It can store data (for example, the pixel depth of an EPS preview) in the plug-ins globals, or in a parameter block. The reference to a block should be attached to the document using AIDocumentSuite::SetDocumentFileFormatParameters(). Illustrator keeps this parameter-block reference with the document. The plug-in can retrieve it when the document is being saved.

When the user does a Save, by default Illustrator uses the same file format that was used to read the file. If the file format does not support writing, the Save As dialog appears to let the user choose the save format. All file format plug-ins that support saving appear in the format menu of this dialog.

If you need information from the user to open or save a file, you can present a dialog when the ask-for-parameters message is received. When saving files, this will be after the Save As dialog has appeared. Your plug-in should save the information it collects, keeping it with the document to use for later saves.

When the go message is received, file formats that read files typically parse the input file and create Illustrator artwork using API calls. File formats for saving Illustrator artwork traverse the artwork database and write out all pertinent information.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIFileFormatSuite and kAIFileFormatVersion.

Member Data Documentation

AIAPI AIErr(* AIFileFormatSuite::AddFileFormat)(SPPluginRef self, const char *name, PlatformAddFileFormatData *data, ai::int32 options, AIFileFormatHandle *fileFormat, ai::int32 extendedOptions)

Adds a file format to the standard file dialog.

Call during startup to install a plug-in file format.

Parameters:

	self	A reference to this plug-in, which adds the format.
	name	The unique name of the new file format. You can use your company name with a descriptor to make it unique. Not displayed or localized.
	data	Information about the file format.
	options	File format operations that this plug-in supports. A logical OR of these `AIFileFormatOptions` values: kFileFormatRead kFileFormatImportArt kFileFormatExport kFileFormatExportSelection kFileFormatPlaceArt kFileFormatImportStyles kFileFormatSuppliesPrintRecordOption kFileFormatIsDefaultOption kFileFormatConvertTemplate kFileFormatLinkArt kFileFormatWrite kFileFormatNoAutoCheckFormat kFileFormatSkipStartupObjectsOption kFileFormatHasExtendedData kFileFormatSuppressUI kFileFormatCheckAlways
	fileFormat	[out] A buffer in which to return the handle of the new plug-in file format. If you install multiple file formats, store this reference in the plug-ins `globals` record, so that your plug-in can use it to determine which file format command is to be processed.
	extendedOptions	File format extended operations that this plug-in supports. A logical OR of these `AIFFExtendedOptions` values: kNoExtendedOptions kSaveMultiArtboards kFileFormatPlaceInTouch

See also:: AddFileFormatEx()

AIAPI AIErr(* AIFileFormatSuite::AddFileFormatEx)(SPPluginRef self, const char *name, PlatformAddFileFormatExData *dataEx, ai::int32 options, AIFileFormatHandle *fileFormat, ai::int32 extendedOptions)

Adds a plug-in file format.

This extended version allows you to specify a list of Mac OS file types. Call during startup to install a plug-in file format.

Parameters:

	self	A reference to this plug-in, which adds the format.
	name	The unique name of the new file format. You can use your company name with a descriptor to make it unique. Not displayed or localized.
	dataEx	Information about the file format. This extended version uses a data structure with additional fields that allow you to specify a list of Mac OS file types. Use `SetFileFormatFilter()` to specify a creator/type pair as the file filter.
	options	File format operations that this plug-in supports. A logical OR of `AIFileFormatOptions` values. When the format is called with a Go selector, one of these flags is set in the `option` field to indicate the requested operation.
	fileFormat	[out] A buffer in which to return the handle of the new plug-in file format. If you install multiple file formats, store this reference in the plug-ins `globals` record, so that your plug-in can use it to determine which file format command is to be processed.
	extendedOptions	File format extended operations that this plug-in supports. A logical OR of these `AIFFExtendedOptions` values: kNoExtendedOptions kSaveMultiArtboards kFileFormatPlaceInTouch

See also:: AddFileFormat(), SetFileFormatFilter()

AIAPI AIErr(* AIFileFormatSuite::CountFileFormats)(ai::int32 *count)

Gets the number of installed plug-in file formats.

Use with GetNthFileFormat() to iterate through all plug-in formats.

Parameters:

count

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

AIAPI AIErr(* AIFileFormatSuite::FindMatchingFileFormats)(ai::int32 options, const ai::FilePath &file, ai::int32 maxMatches, AIFileFormatHandle matchingFormats[], ai::int32 *numMatches)

Finds all plug-in file formats that can perform a specified operation for a file.

Parameters:

	options	The operation, a `AIFileFormatOptions` value.
	file	The file.
	maxMatches	The maximum number of formats to return.
	matchingFormats	[out] An array of size `maxMatches` in which to return the matching file formats.
	numMatches	[out] A buffer in which to return the number of matching file formats found.

AIAPI AIErr(* AIFileFormatSuite::GetFileFormatCreatorType)(AIFileFormatHandle fileFormat, ai::int32 *maxNumPairs, AICreatorTypePair *pairList)

Retrieves the file type filter for a file format, as specified by (creator, type) pairs for Mac OS.

Parameters:

	fileFormat	The file format.
	maxNumTypes	[in, out] A buffer in which to specify the maximum number and return the actual number of (creator, type) pairs specified in `pairList`.
	pairList	[out] A buffer in which to return the array of (creator, type) pairs.

AIAPI AIErr(* AIFileFormatSuite::GetFileFormatExtendedOptions)(AIFileFormatHandle fileFormat, ai::int32 *extendedOptions)

Retrieves the extended option flags of a file format.

Parameters:

	fileFormat	The file format.
	extendedOptions	[out] A buffer in which to return the extended options `AIFFExtendedOptions` values kNoExtendedOptions kSaveMultiArtboards kFileFormatPlaceInTouch

AIAPI AIErr(* AIFileFormatSuite::GetFileFormatExtension)(AIFileFormatHandle fileFormat, ai::UnicodeString &extension)

Retrieves the file extension for a plug-in file format.

Parameters:

	fileFormat	The file format.
	extension	[out] A buffer in which to return the file extension string.

AIAPI AIErr(* AIFileFormatSuite::GetFileFormatName)(AIFileFormatHandle fileFormat, const char **name)

Retrieves the name of a file format.

Parameters:

	fileFormat	The file format.
	name	[out] A buffer in which to return the name string, as passed to `AddFileFormat()`. Do not modify this string.

AIAPI AIErr(* AIFileFormatSuite::GetFileFormatOptions)(AIFileFormatHandle fileFormat, ai::int32 *options)

Retrieves the option flags of a file format.

Parameters:

	fileFormat	The file format.
	options	[out] A buffer in which to return the options, a logical OR of `AIFileFormatOptions` values

AIAPI AIErr(* AIFileFormatSuite::GetFileFormatPlugin)(AIFileFormatHandle fileFormat, SPPluginRef *plugin)

Retrieves a reference to the plug-in that installed a file format, to be passed to AIPluginSuite functions.

Parameters:

	fileFormat	The file format.
	plugin	[out] A buffer in which to return the plug-in reference.

AIAPI AIErr(* AIFileFormatSuite::GetFileFormatTitle)(AIFileFormatHandle fileFormat, ai::UnicodeString &szTitle)

Retrieves the localizable display name of a plug-in file format.

Parameters:

	fileFormat	The file format.
	szTitle	[out] A buffer in which to return the display name.

AIAPI AIErr(* AIFileFormatSuite::GetFileFormatType)(AIFileFormatHandle fileFormat, ai::int32 *maxNumTypes, ai::int32 *typeList)

Retrieves the Mac OS file types for a plug-in file format.

Parameters:

	fileFormat	The file format.
	maxNumTypes	[in, out] A buffer in which to specify the maximum number and return the actual number of values in `typeList`.
	typeList	[out] A buffer in which to return the 4-character Mac OS type codes.

See also:: GetFileFormatCreatorType() to get the full Mac OS file information.

AIAPI AIErr(* AIFileFormatSuite::GetFileStartupProfileType)(const ai::FilePath &file, AIDocumentStartupProfile *docStartupProfile)

Retrieves the Illustrator startup profile type from the XMP metadata embedded in a file.

Parameters:

	file	The file path.
	docStartupProfile	[out] A buffer in which to return the Illustrator startup profile constant. If the information is not in the metadata, or if the file does not contain XMP metadata, this is `kAIStartupProfileUnknown`.

Returns:: The error kBadParameterErr if file is empty or does not exist.

AIAPI AIVersion(* AIFileFormatSuite::GetFirstVersionUsingPlacedArt)(AIFileFormatHandle fileFormat)

Reports the version of Illustrator in which a raster file format, for example the JPEG file format plug-in, was converted from using raster art to using placed art in order to perform a place link operation.

The information is needed so that Illustrator knows when it should convert placed linked art back to raster art when saving to a legacy file format. For example, if the JPEG file format used raster art in version 10 and started using placed art in version 11 then Illustrator must convert placed linked JPEG images back to raster art when saving to a version 10 or earlier Illustrator file. (Note that this function returns a version value, not an error code.)

Parameters:

fileFormat

The file format.

Returns:: The Illustrator version. The default version is 0, meaning that placed objects are not converted on export.

See also:: SetFirstVersionUsingPlacedArt() to set the version.

AIAPI AIErr(* AIFileFormatSuite::GetNthFileFormat)(ai::int32 n, AIFileFormatHandle *fileFormat)

Retrieves a plug-in file format reference by position index.

Use with CountFileFormats() to iterate through all installed formats.

Parameters:

	n	The index, in the range `[1..numFormats]`.
	fileFormat	[out] A buffer in which to return the file format reference.

AIAPI AIErr(* AIFileFormatSuite::GetStartupFileOfType)(const AIDocumentStartupProfile docStartupProfile, ai::FilePath &profile)

Retrieves the Illustrator default document profile from the startup-profile type.

Parameters:

	docStartupProfile	The startup profile type.
	profile	[out] A buffer in which to return the file-path object for the default document profile.

Returns:: The error kCantHappenErr if the file does not exists.
The error kBadParameterErr if the startup profile is invalid,

AIAPI AIErr(* AIFileFormatSuite::GoExport)(AIActionParamValueRef actionParam)

Used for exporting the current document as one whole file or as multiple artBoards.

Parameters:

actionParam

An action parameter block containing keys "name", "frmt", "ext", "smab", "sall", "sran" as defined in AIDocumentAction.h Will return error (and not throw a dialog) if the above action keys are missing.

AIAPI AIErr(* AIFileFormatSuite::PutFile)(ai::int32 options, const unsigned char *dlgTitle, ai::FilePath &fileSpec, AIFileFormatHandle *fileFormat, AIBoolean *good)

Invokes the File > Save dialog, allowing you to filter the available file formats.

Parameters:

	options	Limits available file formats to those that support these write operations. A logical OR of write operation constants: `kFileFormatExport<` `kFileFormatWrite`
	dlgTitle	The title for the Save dialog.
	fileSpec	[in, out] A buffer in which to pass the initial file specification and return the user-chosen specification.
	fileFormat	[out] A buffer in which to return the user-chosen file format.
	good	[out] A buffer in which to return true if the user clicked Save, or false if the user clicked Cancel.

AIAPI AIErr(* AIFileFormatSuite::ResolveImportConflicts)()

Obsolete.

AIAPI AIErr(* AIFileFormatSuite::SetFileFormatExtendedOptions)(AIFileFormatHandle fileFormat, ai::int32 extendedOptions)

Sets the extended option flags of a file format, which specify what file operations can be handled.

Parameters:

	fileFormat	The file format.
	extendedOptions	File format operations that this plug-in supports. A logical OR of these `AIFFExtendedOptions` values: kNoExtendedOptions kSaveMultiArtboards kFileFormatPlaceInTouch

AIAPI AIErr(* AIFileFormatSuite::SetFileFormatFilter)(AIFileFormatHandle fileFormat, ai::int32 numPairs, AICreatorTypePair *pairList, const ai::UnicodeString &extensions)

Associates a file format with a file type filter.

File types are specified by (creator, type) pairs in Mac OS, and by filename extensions in Windows.

Note:: This function extends the AddFileFormat() and AddFileFormatEx() functions by allowing filters based on (creator, type) pairs in Mac OS, rather than simple type values.

Parameters:

	fileFormat	The file format.
	numPairs	In Mac OS, the number of (creator, type) pairs specified in `pairList`. Ignored in Windows.
	pairList	In Mac OS, a pointer to an array of (creator, type) pairs. These can use the Mac OS wild-card value '****' for creator or type. Ignored in Windows.
	extensions	In Windows, a comma-delimited list of DOS-style extensions that are filtered in the Open dialog, or appended to the file name in the Saves As dialog. For example, `"ai,eps"`.

AIAPI AIErr(* AIFileFormatSuite::SetFileFormatOptions)(AIFileFormatHandle fileFormat, ai::int32 options)

Sets the option flags of a file format, which specify what file operations can be handled.

Parameters:

	fileFormat	The file format.
	options	The options, a logical OR of `AIFileFormatOptions` values

AIAPI AIErr(* AIFileFormatSuite::SetFileFormatPriority)(AIFileFormatHandle fileFormat, ai::int32 priority)

Sets the priority of a file format.

which determines the order in which Illustrator searches through formats in deciding which one to use to open a file. The first format found that handles a file type is used to open the file.

Parameters:

	fileFormat	The file format.
	priority	The new priority, an `AIFileFormatPriority` value,

AIAPI AIErr(* AIFileFormatSuite::SetFirstVersionUsingPlacedArt)(AIFileFormatHandle fileFormat, AIVersion version)

Sets the version of Illustrator in which a raster file format was converted from using raster art to using placed art in order to perform a place link operation.

Parameters:

	fileFormat	The file format.
	The	Illustrator version value. The default version is 0, meaning that placed objects are not converted on export.

See also:: GetFirstVersionUsingPlacedArt().

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

AIFileFormat.h

AIFileFormatSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIFileFormatSuite Struct Reference
[API Suite List]