apple.quicklook.protocol

Interface QLPreviewingController

public interface QLPreviewingController

For view based previews, the view controller that implements the QLPreviewingController protocol must at least implement one of the two following methods: -[QLPreviewingController preparePreviewOfSearchableItemWithIdentifier:queryString:completionHandler:], to generate previews for Spotlight searchable items. -[QLPreviewingController preparePreviewOfFileAtURL:completionHandler:], to generate previews for file URLs.

The main preview should be presented by the view controller implementing QLPreviewingController. Avoid presenting additional view controllers over your QLPreviewingController. For Catalyst compatibility, avoid using gesture recognizers that take interactions over large portions of the view to avoid collisions with standard macOS preview behaviors. Avoid holding the file open during the duration of the preview. If access to the file is necessary for interaction, it is best to keep the file open only for the duration of the interaction.

For data-based previews, subclass QLPreviewProvider which conforms to this protocol.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	QLPreviewingController.Block_preparePreviewOfFileAtURLCompletionHandler
static interface	QLPreviewingController.Block_preparePreviewOfSearchableItemWithIdentifierQueryStringCompletionHandler
static interface	QLPreviewingController.Block_providePreviewForFileRequestCompletionHandler

Method Summary

Modifier and Type	Method and Description
default void	preparePreviewOfFileAtURLCompletionHandler(NSURL url, QLPreviewingController.Block_preparePreviewOfFileAtURLCompletionHandler handler) Use this method to prepare the content of the view controller with the given file URL.
default void	preparePreviewOfSearchableItemWithIdentifierQueryStringCompletionHandler(java.lang.String identifier, java.lang.String queryString, QLPreviewingController.Block_preparePreviewOfSearchableItemWithIdentifierQueryStringCompletionHandler handler) Use this method to prepare the content of the view controller with the data that the searchable item represents.
default void	providePreviewForFileRequestCompletionHandler(QLFilePreviewRequest request, QLPreviewingController.Block_providePreviewForFileRequestCompletionHandler handler) Use this method to provide a QLPreviewReply that provides preview in the form of NSData, NSURL, PDFDocument, or a drawing into a context.

Method Detail

preparePreviewOfFileAtURLCompletionHandler

default void preparePreviewOfFileAtURLCompletionHandler(NSURL url,
                                                        QLPreviewingController.Block_preparePreviewOfFileAtURLCompletionHandler handler)

Use this method to prepare the content of the view controller with the given file URL.

This method will be called only once. It will be called in the main thread before presenting the view controller. Heavy work potentially blocking the main thread should be avoided in this method.

Parameters:

url - The URL of the file the user is about to preview.

handler - The completion handler should be called whenever the view is ready to be displayed. A loading spinner will be shown until the handler is called. It can be called asynchronously after the method has returned.

preparePreviewOfSearchableItemWithIdentifierQueryStringCompletionHandler

default void preparePreviewOfSearchableItemWithIdentifierQueryStringCompletionHandler(java.lang.String identifier,
                                                                                      java.lang.String queryString,
                                                                                      QLPreviewingController.Block_preparePreviewOfSearchableItemWithIdentifierQueryStringCompletionHandler handler)

Use this method to prepare the content of the view controller with the data that the searchable item represents.

This method will be called only once. It will be called in the main thread before presenting the view controller. Heavy work potentially blocking the main thread should be avoided in this method.

Parameters:

identifier - The identifier of the CSSearchableItem the user interacted with in Spotlight.

queryString - The query string the user entered in Spotlight before interacting with the CSSearchableItem.

handler - The completion handler should be called whenever the view is ready to be displayed. A loading spinner will be shown until the handler is called. It can be called asynchronously after the method has returned.

providePreviewForFileRequestCompletionHandler

default void providePreviewForFileRequestCompletionHandler(QLFilePreviewRequest request,
                                                           QLPreviewingController.Block_providePreviewForFileRequestCompletionHandler handler)

Use this method to provide a QLPreviewReply that provides preview in the form of NSData, NSURL, PDFDocument, or a drawing into a context.

Parameters:

request - An object which contains information about the preview that should be provided. It contains the URL of the file to provide a preview for.

handler - Call the completion handler with a QLPreviewReply if you can provide a preview, or with an NSError if you cannot. If an error is passed or reply is nil, a generic preview will be provided instead. The handler can be called asynchronously after the method has returned.