Mac Developer Library

Developer

Foundation Framework Reference NSFilePresenter Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSFilePresenter

The NSFilePresenter protocol should be implemented by objects that allow the user to view or edit the content of files or directories. You use file presenters in conjunction with an NSFileCoordinator object to coordinate access to a file or directory among the objects of your application and between your application and other processes. When changes to an item occur, the system notifies objects that adopt this protocol and gives them a chance to respond appropriately. More...

Inheritance


Not Applicable

Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.7 and later.
  • The URL of the presented file or directory. (required) (read-only)

    Declaration

    Swift

    @NSCopying var presentedItemURL: NSURL? { get }

    Objective-C

    @property(readonly, copy) NSURL *presentedItemURL

    Discussion

    File presenters must implement this property and use it to return the file or directory of interest. If this object presents a group of related files that all reside in the same directory, specify the URL of the directory instead of creating separate presenter objects for each file. For example, a single-window application that manages multiple files inside a project directory should monitor the project directory.

    The URL associated with your item may be requested by objects not associated with your presenter. Therefore, your implementation of the accessor method for this property must be thread safe and capable of running in multiple dispatch or operation queues simultaneously.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • The operation queue in which to execute presenter-related messages. (required) (read-only)

    Declaration

    Swift

    var presentedItemOperationQueue: NSOperationQueue { get }

    Objective-C

    @property(readonly, retain) NSOperationQueue *presentedItemOperationQueue

    Discussion

    As other objects and processes interact with the presented item, the system queues relevant messages for this presenter object on the operation queue in this property. For example, when another process attempts to read a file presented by this object, the system places an invocation of this object’s relinquishPresentedItemToReader: method on the queue for execution. The other process must wait to read the file until that method is dequeued and executed. Requests for an object’s presented URL are not processed on this queue.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • The URL of a secondary item’s primary presented file or directory. (read-only)

    Declaration

    Swift

    @NSCopying optional var primaryPresentedItemURL: NSURL? { get }

    Objective-C

    @property(readonly, copy) NSURL *primaryPresentedItemURL

    Discussion

    This property supports App Sandbox in OS X.

    Some apps require access to secondary files or directories with names that are related to the primary, user-selected file. For example, a subtitle file, by convention, has the same name as its corresponding movie file, but with a different filename extension. If a movie player is sandboxed, an NSOpenPanel object will grant access only to the user-selected movie file (the primary item) and not its associated subtitle file (the secondary item).

    To gain access to a secondary item, first register an NSFilePresenter object for it. At any point in its existence, a secondary item must be able to return an NSURL object to its primary item. This is done by using this property. When done accessing the secondary item, unregister the file presenter object.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.8 and later.

  • Notifies your object that another object or process wants to read the presented file or directory.

    Declaration

    Swift

    optional func relinquishPresentedItemToReader(_ reader: ((() -> Void)!) -> Void)

    Objective-C

    - (void)relinquishPresentedItemToReader:(void (^)(void (^reacquirer)(void)))reader

    Parameters

    reader

    A Block object that takes another block as a parameter and returns no value. The reacquirer block is one you pass to the reader block so that your object can be notified when the reader is done. If your object does not need to be notified, it can pass nil for the reacquirer block.

    Discussion

    You use this method to provide an appropriate response when another object wants to read from your presented URL. For example, when this method is called, you might temporarily stop making changes to the file or directory. After taking any appropriate steps, you must execute the block in the reader parameter to let the waiting object know that it may now proceed with its task. If you want to be notified when the reader has completed its task, pass your own block to the reader and use that block to reacquire the file or URL for your own uses.

    The following listing shows a simple implementation of this method that sets a Boolean flag that the file being monitored is not writable at the moment. After setting the flag, it executes the reader block and passes in yet another block for the reader to execute when it is done.

    • - (void)relinquishPresentedItemToReader:(void (^)(void (^reacquirer)(void))) reader
    • {
    • // Prepare for another object to read the file.
    • self.fileIsWritable = NO;
    • // Now let the reader know that it can have the file.
    • // But pass a reacquisition block so that this object
    • // can update itself when the reader is done.
    • reader(^{
    • self.fileIsWritable = YES;
    • });
    • }

    Your implementation of this method is executed using the queue in the presentedItemOperationQueue property. Your reacquirer block is executed on the queue associated with the reader.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Notifies your object that another object or process wants to write to the presented file or directory.

    Declaration

    Swift

    optional func relinquishPresentedItemToWriter(_ writer: ((() -> Void)!) -> Void)

    Objective-C

    - (void)relinquishPresentedItemToWriter:(void (^)(void (^reacquirer)(void)))writer

    Parameters

    writer

    A Block object that takes another block as a parameter and returns no value. The reacquirer block is one you pass to the writer block so that your object can be notified when the writer is done. If your object does not need to be notified, it can pass nil for the reacquirer block.

    Discussion

    You use this method to provide an appropriate response when another object wants to write to your presented URL. For example, when this method is called, you would likely stop making changes to the file or directory. After taking any appropriate steps, you must execute the block in the writer parameter to let the waiting object know that it may now proceed with its task. If you want to be notified when the writer has completed its task, pass your own block to the writer and use that block to reacquire the file or URL for your own uses.

    If the writer changes the file or directory, you do not need to incorporate those changes in your reacquirer block. Instead, implement the presentedItemDidChange method and use it to detect when a writer actually wrote its changes to disk.

    The following listing shows a simple implementation of this method that sets a Boolean flag that the file being monitored is not writable at the moment. After setting the flag, it executes the writer block and passes in yet another block for the writer to execute when it is done.

    • - (void)relinquishPresentedItemToWriter:(void (^)(void (^reacquirer)(void))) writer
    • {
    • // Prepare for another object to write to the file.
    • self.fileIsWritable = NO;
    • // Now let the writer know that it can have the file.
    • // But pass a reacquisition block so that this object
    • // can update itself when the writer is done.
    • writer(^{
    • self.fileIsWritable = YES;
    • });
    • }

    Your implementation of this method is executed using the queue in the presentedItemOperationQueue property. Your reacquirer block is executed on the queue associated with the writer.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells your object to save any unsaved changes for the presented item.

    Declaration

    Swift

    optional func savePresentedItemChangesWithCompletionHandler(_ completionHandler: (NSError!) -> Void)

    Objective-C

    - (void)savePresentedItemChangesWithCompletionHandler:(void (^)(NSError *errorOrNil))completionHandler

    Parameters

    completionHandler

    The Block object to call after you save your changes. If you saved your changes successfully, pass nil for the block’s errorOrNil parameter; otherwise, pass an error object indicating why the changes could not be saved.

    Discussion

    The file coordinator calls this method to ensure that all objects trying to access the file or directory see the same contents. Implement this method if your object can change the presented item in a way that requires you to write those changes back to disk. If your presenter object does not make changes that need to be saved, you do not need to implement this method.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells your object that its presented item is about to be deleted.

    Declaration

    Swift

    optional func accommodatePresentedItemDeletionWithCompletionHandler(_ completionHandler: (NSError!) -> Void)

    Objective-C

    - (void)accommodatePresentedItemDeletionWithCompletionHandler:(void (^)(NSError *errorOrNil))completionHandler

    Parameters

    completionHandler

    The Block object to call after updating your data structures. Pass nil to the block’s errorOrNil parameter if you were able to successfully prepare for the deletion of the item. Pass an error object if your object could not prepare itself properly.

    Discussion

    A file coordinator calls this method when your object’s presented item is about to be deleted. You can use this method to perform any actions that are needed to prepare for the deletion. For example, document objects typically use this method to close the document.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells your object that the presented item moved or was renamed.

    Declaration

    Swift

    optional func presentedItemDidMoveToURL(_ newURL: NSURL)

    Objective-C

    - (void)presentedItemDidMoveToURL:(NSURL *)newURL

    Parameters

    newURL

    The URL containing the new path to the presented item.

    Discussion

    Use this method to update the value returned by the presentedItemURL property of your object.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

    See Also

    presentedItemURL

  • Tells your object that the presented item’s contents or attributes changed.

    Declaration

    Swift

    optional func presentedItemDidChange()

    Objective-C

    - (void)presentedItemDidChange

    Discussion

    You can use this method to update your internal data structures to reflect the changes to the presented item. This method reports both changes to the file’s contents, such as the data in a file or the files in a directory, or the attributes of the item, such as whether the Hide extension checkbox of a file was toggled.

    Because this method notifies you of both attribute and content changes, you might want to check the modification date before needlessly rereading the contents of a file. To do that, you must store the date when your object last made changes to the file and compare that date with the item’s current modification date. Use the coordinateReadingItemAtURL:options:error:byAccessor: method of a file coordinator to ensure exclusive access to the file when reading the current modification date.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells the delegate that a new version of the file or file package was added. (required)

    Declaration

    Swift

    optional func presentedItemDidGainVersion(_ version: NSFileVersion)

    Objective-C

    - (void)presentedItemDidGainVersion:(NSFileVersion *)version

    Parameters

    version

    The file version object containing information about the new file version.

    Discussion

    Your delegate can use this method to determine how to incorporate data from the new version of the file or file package. If the file has not been modified by your code, you might simply update to the new version quietly. However, if your application has its own changes, you might need to ask the user how to proceed.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells the delegate that a version of the file or file package was removed. (required)

    Declaration

    Swift

    optional func presentedItemDidLoseVersion(_ version: NSFileVersion)

    Objective-C

    - (void)presentedItemDidLoseVersion:(NSFileVersion *)version

    Parameters

    version

    The file version object containing information about the version that was removed.

    Discussion

    Your delegate can use this method to determine how to handle the loss of the specified file version. You can try to revert the presented document to a previous version or you might want to prompt the user about how to proceed.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells the delegate that some other entity resolved a version conflict for the presenter’s file or file package. (required)

    Declaration

    Swift

    optional func presentedItemDidResolveConflictVersion(_ version: NSFileVersion)

    Objective-C

    - (void)presentedItemDidResolveConflictVersion:(NSFileVersion *)version

    Parameters

    version

    The version object containing the conflicting change.

    Discussion

    Your delegate can use this method to respond to the resolution of a version conflict by a different file presenter. This might occur if a version of your application running on another device resolves the conflict first. You might then use this method to update your user interface to indicate that there is no longer a conflict.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells the delegate that the item inside the presented directory gained a new version. (required)

    Declaration

    Swift

    optional func presentedSubitemAtURL(_ url: NSURL, didGainVersion version: NSFileVersion)

    Objective-C

    - (void)presentedSubitemAtURL:(NSURL *)url didGainVersion:(NSFileVersion *)version

    Parameters

    url

    The URL of the item inside the presented directory that gained a new version. The item need not be at the top level of the presented directory but may itself be inside a nested subdirectory.

    version

    The file version object containing information about the new file version.

    Discussion

    Your delegate can use this method to determine how to incorporate data from the new version of the item. This might involve incorporating the version silently or asking the user about how to proceed.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells the delegate that the item inside the presented directory lost an existing version. (required)

    Declaration

    Swift

    optional func presentedSubitemAtURL(_ url: NSURL, didLoseVersion version: NSFileVersion)

    Objective-C

    - (void)presentedSubitemAtURL:(NSURL *)url didLoseVersion:(NSFileVersion *)version

    Parameters

    url

    The URL of the item inside the presented directory that lost a version. The item need not be at the top level of the presented directory but may itself be inside a nested subdirectory.

    version

    The file version object containing information about the version that was removed.

    Discussion

    Your delegate can use this method to determine how to handle the loss of the specified file version. For an old version, you might not have to do anything. However, if your application is currently using the lost version, you would need to update your application’s user interface or prompt the user about how to proceed.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells the delegate that the item inside the presented directory had a version conflict resolved by an outside entity. (required)

    Declaration

    Swift

    optional func presentedSubitemAtURL(_ url: NSURL, didResolveConflictVersion version: NSFileVersion)

    Objective-C

    - (void)presentedSubitemAtURL:(NSURL *)url didResolveConflictVersion:(NSFileVersion *)version

    Parameters

    url

    The URL of the item inside the presented directory that was in conflict. The item need not be at the top level of the presented directory but may itself be inside a nested subdirectory.

    version

    The version object containing the conflicting change.

    Discussion

    Your delegate can use this method to respond to the resolution of a version conflict by a different file presenter. This might occur if a version of your application running on another device resolves the conflict first. You might then use this method to update your user interface to indicate that there is no longer a conflict.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells the delegate that some entity wants to delete an item that is inside of a presented directory. (required)

    Declaration

    Swift

    optional func accommodatePresentedSubitemDeletionAtURL(_ url: NSURL, completionHandler completionHandler: (NSError!) -> Void)

    Objective-C

    - (void)accommodatePresentedSubitemDeletionAtURL:(NSURL *)url completionHandler:(void (^)(NSError *errorOrNil))completionHandler

    Parameters

    url

    The URL of the item being deleted from the presented directory. The item need not be at the top level of the presented directory but may itself be inside a nested subdirectory.

    completionHandler

    The Block object to call after updating your data structures. Pass nil to the block’s errorOrNil parameter if you were able to successfully prepare for the deletion of the item. Pass an error object if your object could not prepare itself properly.

    Discussion

    This method is relevant for applications that present directories. This might occur if the delegate manages the contents of a directory or manages a file that is implemented as a file package. When called, your implementation of this method should take whatever actions needed to update your application to handle the deletion of the specified file.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells the delegate that an item was added to the presented directory. (required)

    Declaration

    Swift

    optional func presentedSubitemDidAppearAtURL(_ url: NSURL)

    Objective-C

    - (void)presentedSubitemDidAppearAtURL:(NSURL *)url

    Parameters

    url

    The URL of the item being added to the presented directory. The item need not be at the top level of the presented directory but may itself be inside a nested subdirectory.

    Discussion

    This method is relevant for applications that present directories. This might occur if the delegate manages the contents of a directory or manages a file that is implemented as a file package. Your implementation of this method should take whatever actions necessary to incorporate the new file or directory into the presented content. For example, you might add the new item to your application’s data structures and refresh your user interface.

    If the presented directory is a file package, the system calls the presentedItemDidChange method if your delegate does not implement this method.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells the delegate that an item in the presented directory moved to a new location. (required)

    Declaration

    Swift

    optional func presentedSubitemAtURL(_ oldURL: NSURL, didMoveToURL newURL: NSURL)

    Objective-C

    - (void)presentedSubitemAtURL:(NSURL *)oldURL didMoveToURL:(NSURL *)newURL

    Parameters

    oldURL

    The original URL of the item inside the presented directory. The item need not be at the top level of the presented directory but may itself be inside a nested subdirectory.

    newURL

    The new URL for the item. This URL may or may not be located inside the presented directory.

    Discussion

    This method is relevant for applications that present directories. This might occur if the delegate manages the contents of a directory or manages a file that is implemented as a file package. Your implementation of this method should take whatever actions necessary to handle the change in location of the specified item. For example, you might update references to the item in your application’s data structures and refresh your user interface.

    If the presented directory is a file package, the system calls the presentedItemDidChange method if your delegate does not implement this method.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • Tells the delegate that the contents or attributes of the specified item changed. (required)

    Declaration

    Swift

    optional func presentedSubitemDidChangeAtURL(_ url: NSURL)

    Objective-C

    - (void)presentedSubitemDidChangeAtURL:(NSURL *)url

    Parameters

    url

    The URL of the item in the presented directory that changed. The item need not be at the top level of the presented directory but may itself be inside a nested subdirectory.

    Discussion

    This method is relevant for applications that present directories. This might occur if the delegate manages the contents of a directory or manages a file that is implemented as a file package. Your implementation of this method should take whatever actions necessary to handle the change in content or attributes of the specified item.

    If the presented directory is a file package, the system calls the presentedItemDidChange method if your delegate does not implement this method.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.7 and later.