Advanced Search

Log In | Not a Member?

Contact ADC

Overview

Protocol definition for the Aperture Edit interface. You should only call these methods from the main thread.

Methods

-addCustomMetadata:toVersions:

Adds the specified key-value pairs to the Custom Metadata for this image.

-addHierarchicalKeywords:toVersions:

Pass in an array of arrays specifying a keyword hierarchy.

-apertureWindow

Returns Aperture's main window

-cancelEditSession

Similar to -endEditSession, but automatically deletes any editable versions created by the plug-in during this session.

-canImport

Returns YES if Aperture allows the plug-in to import images into the current album; NO otherwise.

-deleteVersions:

Deletes the specified versions and their master files from the user's library.

-editableVersionIds

Returns the unique ids that the plug-in can edit.

-editableVersionsOfVersions:requestedFormat:stackWithOriginal:

Returns an array of unique IDs.

-editableVersionsOfVersions:stackWithOriginal:

Returns an array of unique IDs.

-endEditSession

Notifies Aperture that the plug-in has completed its work.

-importedVersionIds

Returns the unique ids of images the plug-in has imported during the session.

-importImageAtPath:

Asynchronously imports an image into the current album.

-importImageAtPath:referenced:stackWithVersions:

Asynchronously imports an image into the current album.

-pathOfEditableFileForVersion:

Returns the path to the file that the plug-in should read/write for this version.

-propertiesWithoutThumbnailForVersion:

Accesses all the available properties for the specified image.

-selectedVersionIds

Returns the unique ids of the versions the user selected in Aperture.

-setUserDefaultsValue:forKey:

Sets the users preferences values.

-thumbnailForVersion:size:

Returns the thumbnail for an image.

-userDefaultsObjectForKey:

Reads the specified user preferences values.

Adds the specified key-value pairs to the Custom Metadata for this image.

- (void)addCustomMetadata:(NSDictionary *)customMetadata 
        toVersions:(NSArray *)versionUniqueIDs; 

Parameters

customMetadata

versionUniqueIDs

Discussion

This data appears in the "Other" tab in the metadata inspector. If an image already has a value for the specified key, it is updated to the new value

Pass in an array of arrays specifying a keyword hierarchy.

- (void)addHierarchicalKeywords:(NSArray *)hierarchicalKeywords 
        toVersions:(NSArray *)versionUniqueIDs; 

Parameters

hierarchicalKeywords

versionUniqueIDs

Returns Aperture's main window

- (NSWindow *)apertureWindow; 

Return Value

An NSWindow.

Discussion

The Edit plug-in uses this method in case it needs to present a sheet.

Similar to -endEditSession, but automatically deletes any editable versions created by the plug-in during this session.

- (void)cancelEditSession; 

Discussion

Note that this method does NOT delete any versions that were edited by the plug-in, but not created during this session. This call also does not delete any referenced master files imported by the plug-in.

Returns YES if Aperture allows the plug-in to import images into the current album; NO otherwise.

- (BOOL)canImport; 

Return Value

A Boolean.

Discussion

For example, Aperture does not allow import into smart albums.

Deletes the specified versions and their master files from the user's library.

- (void)deleteVersions:(NSArray *)versionUniqueIDs; 

Parameters

versionUniqueIDs

Discussion

Aperture only performs this operation for versions created by the plug-in during the current session. Unique IDs for any images that were not created by the plug-in are ignored. This includes images that were already editable that the plug-in has modified. Note this call will delete master files for editable versions, whether those masters are referenced or not. However, it will only delete master files of imported versions if those files are managed (not referenced).

Returns the unique ids that the plug-in can edit.

- (NSArray *)editableVersionIds; 

Return Value

An NSArray.

Discussion

The array may include some images the user selected if they were already marked as editable.

Returns an array of unique IDs.

- (NSArray *)editableVersionsOfVersions:(NSArray *)versionUniqueIDs 
        requestedFormat:(ApertureImageFormat)format 
        stackWithOriginal:(BOOL)stackWithOriginal; 

Parameters

versionUniqueIDs

format

stackWithOriginal

Return Value

An NSArray. Each entry in the array contains the properties dictionary for the editable version.

Discussion

If an image was already editable and the user did not want to guarantee a copy (by holding the option key when selecting the plug-in from the menu) then this method will return the unique ID passed in for that version. Otherwise, this method tells Aperture to write out an editable image in the format specified by format and creates a new entry in the user's library. Normally, the plug-in would then call the -pathOfEditableFileForVersion: for the unique IDs returned from this method, or the -propertiesWithoutThumbnailForVersion: and -thumbnailForVersion: methods.

Returns an array of unique IDs.

- (NSArray *)editableVersionsOfVersions:(NSArray *)versionUniqueIDs 
        stackWithOriginal:(BOOL)stackWithOriginal; 

Parameters

versionUniqueIDs

stackWithOriginal

Return Value

An NSArray. Each entry in the array contains the properties dictionary for the editable version.

Discussion

If an image was already editable and the user did not want to guarantee a copy (by holding the option key when selecting the plug-in from the menu), then this method returns the unique ID passed in for that version. Otherwise, this method tells Aperture to write out an editable image in the format specified in the user's preferences (PSD or TIFF) and creates a new entry in the user's library. Normally, the plug-in then calls -pathOfEditableFileForVersion: for the unique IDs returned from this method, or the -propertiesWithoutThumbnailForVersion: and -thumbnailForVersion: methods.

Notifies Aperture that the plug-in has completed its work.

- (void)endEditSession; 

Discussion

The plug-in should be ready to dealloc at the time of this call and should not be running tasks on any other threads, or anything on the run loop that may call back after this call is finished.

Returns the unique ids of images the plug-in has imported during the session.

- (NSArray *)importedVersionIds; 

Return Value

An NSArray.

Asynchronously imports an image into the current album.

importImageAtPath:referenced:stackWithVersions:

- (void)importImageAtPath:(NSString *)imagePath referenced:(BOOL)isReferenced 
        stackWithVersions:(NSArray *)versionUniqueIdsToStack; 

Parameters

imagePath

isReferenced

versionUniqueIdsToStack

Discussion

This method calls the -editManager:didImportImageAtPath:versionUniqueID: method upon successful completion, or -editManager:didNotImportImageAtPath:error: if the import was unsuccessful. If -canImport returns NO, this method does nothing and the plug-in does not get a callback. The plug-in should not call -endEditSession or -cancelEditSession until it has received the import callback.

Asynchronously imports an image into the current album.

importImageAtPath:

- (void)importImageAtPath:(NSString *)imagePath referenced:(BOOL)isReferenced 
        stackWithVersions:(NSArray *)versionUniqueIdsToStack; 

Parameters

imagePath

isReferenced

versionUniqueIdsToStack

Discussion

This method calls the -editManager:didImportImageAtPath:versionUniqueID: method upon successful completion, or -editManager:didNotImportImageAtPath:error: if the import was unsuccessful. If -canImport returns NO, this method does nothing and the plug-in does not get a callback. The plug-in should not call -endEditSession or -cancelEditSession until it has received the import callback.

Returns the path to the file that the plug-in should read/write for this version.

- (NSString *)pathOfEditableFileForVersion:(NSString *)versionUniqueID; 

Parameters

versionUniqueID

Return Value

An NSString

Discussion

This path is also available via the properties dictionary, but if this version is not editable, the method returns nil.

Accesses all the available properties for the specified image.

- (NSDictionary *)propertiesWithoutThumbnailForVersion:(NSString *)versionUniqueID; 

Parameters

versionUniqueID

Return Value

An NSDictionary

Discussion

A thumbnail image is not included. You can obtain a thumbnail using the method -thumbnailForVersion:.

Returns the unique ids of the versions the user selected in Aperture.

- (NSArray *)selectedVersionIds; 

Return Value

An NSArray.

Discussion

The IDs are ordered in the same order that the user selected them, except the primary selection is always first.

Sets the users preferences values.

- (void)setUserDefaultsValue:(id)value forKey:(NSString *)key; 

Parameters

value

key

Discussion

Writes preferences values into a preferences file specific to the plug-in, not Aperture's preferences file.

Returns the thumbnail for an image.

- (NSImage *)thumbnailForVersion:(NSString *)versionUniqueID 
        size:(ApertureExportThumbnailSize)size; 

Parameters

versionUniqueID

size

Return Value

An NSImage.

Discussion

Some plug-ins may choose to operate on the large thumbnail and not request an editable version of the image until the user is done.

Reads the specified user preferences values.

- (id)userDefaultsObjectForKey:(NSString *)key; 

Parameters

key

Return Value

id

Discussion

Reads the specified preferences values from a preferences file specific to the plug-in, not Aperture's preferences file.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-04-18