Mac Developer Library

Developer

QuickLook Framework Reference QLPreviewRequest Reference

Options
Deployment Target:

On This Page
Language:

QLPreviewRequest Reference

Quick Look generators use the QLPreviewRequest API to help create a document preview that is returned to Quick Look clients (such as Finder and Spotlight) for display. An object of the QLPreviewRequest opaque type represents a request from a client for a preview of a document and is used to return the preview image the generator creates or locates

A generator must implement the GeneratePreviewForURL callback function to create and return a preview image requested for a given document. QLPreviewRequest gives you four ways to create or locate a preview for a document:

  • You can create a graphics context to draw the preview in. Graphics contexts for previews are of three kinds: bitmap, single-page vector, and multi-page vector.

  • The generator can extract the preview data from the document and return it to the client using the QLPreviewRequestSetDataRepresentation function. (For this approach to work the application’s document must save the preview as part of the document.) The generator can also dynamically generate the preview and return it with this function.

  • As a refinement of this same approach, the generator can dynamically generate the preview as HTML data that references attachments. It can then call QLPreviewRequestSetDataRepresentation, passing in a content type of HTML and dictionaries specifying the attachments.

Most of the other functions of QLPreviewRequest let you get the data associated with the preview request, such as the URL locating the document and the UTI identifying the content type of the document.

Functions

  • Creates a graphics context to draw the preview in.

    Declaration

    Swift

    func QLPreviewRequestCreateContext(_ preview: QLPreviewRequest!, _ size: CGSize, _ isBitmap: Boolean, _ properties: CFDictionary!) -> Unmanaged<CGContext>!

    Objective-C

    CGContextRef QLPreviewRequestCreateContext ( QLPreviewRequestRef preview, CGSize size, Boolean isBitmap, CFDictionaryRef properties );

    Parameters

    preview

    The preview request object.

    size

    The size of the preview; if isBitmap is true the size is in pixels, otherwise it is in points.

    isBitmap

    true if the preview uses a bitmap-based graphics context, false otherwise. This value of this parameter affects the interpretation of the size parameter.

    properties

    A dictionary containing properties for the preview response. Preview Properties lists the current property keys and describes their values.

    Return Value

    A Core Graphics graphics-context object that you can draw your preview image in. You should explicitly release this object when it is no longer needed.

    Discussion

    You can directly draw your preview data in the graphics-context object created by this function. After calling this function, you should flush the context with QLPreviewRequestFlushContext. Also be sure to release the CGContext object.

    Quick Look provides three types of graphics contexts for drawing previews: bitmap, single-page vector-based, and multi-page vector-based (for PDF previews). You use this function to acquire a context for bitmap and single-page vector drawing; the isBitmap parameter is used to distinguish between them. For multi-page contexts, use the QLPreviewRequestCreatePDFContext function.

    If you prefer to work in Objective-C code, you can convert the created CGContextRef to a NSGraphicsContext object using graphicsContextWithGraphicsPort:flipped:.

    Special Considerations

    Thread-safety: This function should be called in the same thread as the preview request is made in; generally, this is the same thread in which the GeneratePreviewForURL callback was invoked.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Creates a PDF context suitable to draw a multi-page preview.

    Declaration

    Swift

    func QLPreviewRequestCreatePDFContext(_ preview: QLPreviewRequest!, _ mediaBox: UnsafePointer<CGRect>, _ auxiliaryInfo: CFDictionary!, _ properties: CFDictionary!) -> Unmanaged<CGContext>!

    Objective-C

    CGContextRef QLPreviewRequestCreatePDFContext ( QLPreviewRequestRef preview, const CGRect *mediaBox, CFDictionaryRef auxiliaryInfo, CFDictionaryRef properties );

    Parameters

    preview

    The preview request object.

    mediaBox

    A pointer to the media box of the context.

    A media box is a rectangle that defines the size and location of the PDF page. The origin of the rectangle should typically be (0,0). If you pass NULL, Quartz uses a default page size of 8.5 by 11 inches (612 by 792 points). For information see the description for CGPDFContextCreate.

    auxiliaryInfo

    A dictionary containing PDF auxiliary information. See the description of the auxiliary dictionary keys in CGPDFContext Reference for more information about the keys and values of this dictionary.

    properties

    A dictionary containing additional properties for the preview response. For information on acceptable keys and values, see Preview Properties.

    Return Value

    A reference to a Core Graphics context object that is used to display a PDF version of the preview. You should explicitly release this object when it is no longer needed.

    Discussion

    Be sure to bracket each PDF page written to the context with CGPDFContextBeginPage and CGPDFContextEndPage calls. After calling this function, you should flush the context with QLPreviewRequestFlushContext.

    Special Considerations

    Thread-safety: This function should be called in the same thread as the preview request is made in; generally, this is the same thread in which the GeneratePreviewForURL callback was invoked.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Sets the preview request to data saved within the document or to dynamically generated data.

    Declaration

    Swift

    func QLPreviewRequestSetDataRepresentation(_ preview: QLPreviewRequest!, _ data: CFData!, _ contentTypeUTI: CFString!, _ properties: CFDictionary!)

    Objective-C

    void QLPreviewRequestSetDataRepresentation ( QLPreviewRequestRef preview, CFDataRef data, CFStringRef contentTypeUTI, CFDictionaryRef properties );

    Parameters

    preview

    The preview request object.

    data

    The data of the preview returned to the client. .

    contentTypeUTI

    The UTI specifying the content type of the preview.

    properties

    Additional properties for the preview response. For more on supported keys and values for this dictionary, see Preview Properties. If the saved data is HTML, you may specify a special set of properties; see the discussion below for more information.

    Discussion

    This function returns preview data to the client. The data is either extracted from a document (where the document’s application has saved it,) or it is dynamically generated. How Quick Look handles the data depends upon the value of contentTypeUTI. The content data of the preview must be of a native Quick Look type. Currently supported UTIs for these types are: kUTTypeImage, kUTTypePDF, kUTTypeHTML, kUTTypeXML, kUTTypePlainText, kUTTypeRTF, kUTTypeMovie, and kUTTypeAudio.

    If the UTI type is kUTTypeHTML, you can have the WebKit handle the layout and display of your preview. You must provide the HTML in data plus any attachments (for example, Address Book cards, Mail messages, or Omni Outliner documents) in the properties dictionary. This dictionary takes kQLPreviewPropertyAttachmentsKey as its key and consists of one ore more subdictionaries (one per attachment). Each subdictionary uses an arbitrary string identifier as a key; the attachment should be referenced within the HTML data using the kQLPreviewContentIDScheme URL scheme (“cid”) and the identifier as the URL resource specifier—for example, “cid:the_identifier”. The keys of the subdictionary properties are kQLPreviewPropertyMIMETypeKey, kQLPreviewPropertyTextEncodingNameKey, and kQLPreviewPropertyAttachmentDataKey.

    Special Considerations

    Thread-safety: This function should be called in the same thread as the preview request is made in; generally, this is the same thread in which the GeneratePreviewForURL callback was invoked.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Flush the context and sets the preview response.

    Declaration

    Swift

    func QLPreviewRequestFlushContext(_ preview: QLPreviewRequest!, _ context: CGContext!)

    Objective-C

    void QLPreviewRequestFlushContext ( QLPreviewRequestRef preview, CGContextRef context );

    Parameters

    preview

    The preview request object.

    context

    The graphics context to flush.

    Discussion

    You should call this method immediately after drawing in the graphics contexts created by QLPreviewRequestCreateContext and QLPreviewRequestCreatePDFContext.

    Special Considerations

    Thread-safety: This function should be called in the same thread as the preview request is made in; generally, this is the same thread in which the GeneratePreviewForURL callback was invoked.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Returns the UTI for the preview request.

    Declaration

    Swift

    func QLPreviewRequestCopyContentUTI(_ preview: QLPreviewRequest!) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef QLPreviewRequestCopyContentUTI ( QLPreviewRequestRef preview );

    Parameters

    preview

    The preview request object.

    Return Value

    The UTI of the associated preview request; returns NULL if the UTI is not available. You should explicitly release this object when it is no longer needed.

    Special Considerations

    Thread-safety: This function should be called in the same thread as the preview request is made in; generally, this is the same thread in which the GeneratePreviewForURL callback was invoked.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Returns the options specified for the preview request.

    Declaration

    Swift

    func QLPreviewRequestCopyOptions(_ preview: QLPreviewRequest!) -> Unmanaged<CFDictionary>!

    Objective-C

    CFDictionaryRef QLPreviewRequestCopyOptions ( QLPreviewRequestRef preview );

    Parameters

    preview

    A preview request object.

    Return Value

    A dictionary containing the properties specified for the preview request. See Preview Properties for supported options. You should explicitly release this object when it is no longer needed.

    Discussion

    The client sets options in the preview request to give hints to the generator. (For OS X v10.5 no options are supported.)

    Special Considerations

    Thread-safety: This function should be called in the same thread as the preview request is made in; generally, this is the same thread in which the GeneratePreviewForURL callback was invoked.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Returns the URL of the document for which a preview is requested.

    Declaration

    Swift

    func QLPreviewRequestCopyURL(_ preview: QLPreviewRequest!) -> Unmanaged<CFURL>!

    Objective-C

    CFURLRef QLPreviewRequestCopyURL ( QLPreviewRequestRef preview );

    Parameters

    preview

    The preview request object.

    Return Value

    The URL identifying the file for which the preview is requested.

    Special Considerations

    This function is thread safe.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Get the bundle of the generator receiving the preview request.

    Declaration

    Swift

    func QLPreviewRequestGetGeneratorBundle(_ preview: QLPreviewRequest!) -> Unmanaged<CFBundle>!

    Objective-C

    CFBundleRef QLPreviewRequestGetGeneratorBundle ( QLPreviewRequestRef preview );

    Parameters

    preview

    The preview request object.

    Return Value

    A reference to a bundle object representing the generator’s bundle.

    Special Considerations

    Thread-safety: This function should be called in the same thread as the preview request is made in; generally, this is the same thread in which the GeneratePreviewForURL callback was invoked.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Returns whether the preview request has been cancelled by the client.

    Declaration

    Swift

    func QLPreviewRequestIsCancelled(_ preview: QLPreviewRequest!) -> Boolean

    Objective-C

    Boolean QLPreviewRequestIsCancelled ( QLPreviewRequestRef preview );

    Parameters

    preview

    The object representing the preview request.

    Return Value

    true if the request is being canceled, false otherwise.

    Discussion

    While computing the response, the generator can poll the preview request object with this function to determine if the client has cancelled the request. Alternatively, the generator can implement the CancelPreviewGeneration callback. but since that function is called in a secondary thread, it is generally safer to take the polling approach.

    Special Considerations

    Thread-safety: This function should be called in the same thread as the preview request is made in; generally, this is the same thread in which the GeneratePreviewForURL callback was invoked.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Gets the type identifier for the QLPreviewReqest opaque type.

    Declaration

    Swift

    func QLPreviewRequestGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID QLPreviewRequestGetTypeID ( void );

    Return Value

    The type identifier for the QLPreviewReqest opaque type.

    Special Considerations

    Thread-safety: This function should be called in the same thread as the preview request is made in; generally, this is the same thread in which the GeneratePreviewForURL callback was invoked.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

Callbacks

  • Defines a pointer to the callback function that Quick Look calls to request a preview from a generator.

    Declaration

    Objective-C

    OSStatus (*GeneratePreviewForURL)( void *thisInterface, QLPreviewRequestRef preview, CFURLRef url, CFStringRef contentTypeUTI, CFDictionaryRef options );

    Parameters

    thisInterface

    The CFPlugIn COM-style interface for the generator.

    preview

    The object containing all information relevant to the preview request. The generator’s role is to assign a document preview (in the requested native type) to this object before it returns.

    url

    A URL (represented by a CFURLRef object) that locates the document for which a preview is requested.

    contentTypeUTI

    The UTI specifying the content type of the document for which the preview is requested.

    options

    A dictionary of options for processing the preview. Options may be passed from the client (for example, Finder or Spotlight).

    Return Value

    A status code representing the result of the request. For the current version of this callback, you should always return noErr.

    Discussion

    The GeneratePreviewForURL callback function implemented by a Quick Look generator may be called one or more times concurrenly if the QLSupportsConcurrentRequests property in the generator bundle’s Info.plist file is set to true. If this is the case, use the preview parameter to distinguish among current requests. The generator might also have the QLNeedsToBeRunInMainThread property set to true, in which case the callback is always invoked in the main thread.

    Special Considerations

    Thread-safety: For a discussions of issues and possible approaches, see “Overview of Generator Implementation“ in Quick Look Programming Guide.

    Availability

    Available in OS X version 10.5 and later.

  • Defines a pointer to a function that Quick Look calls to cancel a preview request.

    Declaration

    Objective-C

    void (*CancelPreviewGeneration)( void *thisInterface, QLPreviewRequestRef preview );

    Parameters

    thisInterface

    The CFPlugIn COM-style interface for the generator.

    preview

    The object representing the preview request.

    Discussion

    If the client application indicates (usually because of user choice) that it is no longer interested in the preview currently being created by a Quick Look generator, this callback function is invoked. The generator can implement this function to stop creating the preview and clean up the resources used for creating it.

    An alternative to implementing this callback is to periodically poll the QLPreviewRequestRef object with QLPreviewRequestIsCancelled to see if the request has been canceled.

    Special Considerations

    Thread-safety: For a discussions of issues and possible approaches, see Overview of Generator Implementation in Quick Look Programming Guide.

    Availability

    Available in OS X version 10.5 and later.

Data Types

  • An opaque reference representing an QLPreviewRequest object.

    Declaration

    Swift

    typealias QLPreviewRequestRef = QLPreviewRequest

    Objective-C

    typedef struct __QLPreviewRequest *QLPreviewRequestRef;

    Availability

    Available in OS X version 10.5 and later.

Constants

  • Keys of the properties dictionary in functions used to create a preview.

    Declaration

    Swift

    let kQLPreviewPropertyDisplayNameKey: CFString! let kQLPreviewPropertyWidthKey: CFString! let kQLPreviewPropertyHeightKey: CFString! let kQLPreviewPropertyStringEncodingKey: CFString! let kQLPreviewPropertyMIMETypeKey: CFString! let kQLPreviewPropertyTextEncodingNameKey: CFString! let kQLPreviewPropertyAttachmentDataKey: CFString! let kQLPreviewPropertyAttachmentsKey: CFString! let kQLPreviewContentIDScheme: CFString!

    Objective-C

    QL_EXPORT const CFStringRef kQLPreviewPropertyDisplayNameKey; QL_EXPORT const CFStringRef kQLPreviewPropertyWidthKey; QL_EXPORT const CFStringRef kQLPreviewPropertyHeightKey; QL_EXPORT const CFStringRef kQLPreviewPropertyStringEncodingKey; QL_EXPORT const CFStringRef kQLPreviewPropertyMIMETypeKey; QL_EXPORT const CFStringRef kQLPreviewPropertyTextEncodingNameKey; QL_EXPORT const CFStringRef kQLPreviewPropertyAttachmentDataKey; QL_EXPORT const CFStringRef kQLPreviewPropertyAttachmentsKey; QL_EXPORT const CFStringRef kQLPreviewContentIDScheme;

    Constants

    • kQLPreviewPropertyDisplayNameKey

      kQLPreviewPropertyDisplayNameKey

      Specifies a custom display name in the preview panel. The default display name is the document title. The value must be encapsulated in a CFString object.

      Available in OS X v10.5 and later.

    • kQLPreviewPropertyWidthKey

      kQLPreviewPropertyWidthKey

      Specifies the width (in points) of the preview. Note that this property is a hint; Quick Look might set the width automatically for some types of previews. The value must be encapsulated in a CFNumber object.

      Available in OS X v10.5 and later.

    • kQLPreviewPropertyHeightKey

      kQLPreviewPropertyHeightKey

      Specifies the height (in points) of the preview. Note that this property is a hint; Quick Look might set the height automatically for some types of previews. The value must be encapsulated in a CFNumber object.

      Available in OS X v10.5 and later.

    • kQLPreviewPropertyStringEncodingKey

      kQLPreviewPropertyStringEncodingKey

      Specifies the string encoding (as an CFStringEncoding value) of the preview data if the native type is plain text. The value must be encapsulated in a CFNumber object.

      Available in OS X v10.5 and later.

    • kQLPreviewPropertyMIMETypeKey

      kQLPreviewPropertyMIMETypeKey

      Gives the web content or attachment mime type. For the main data, the default type is “text/html”. The value is a CFString object.

      Available in OS X v10.5 and later.

    • kQLPreviewPropertyTextEncodingNameKey

      kQLPreviewPropertyTextEncodingNameKey

      Specifies the encoding of the web content or attachment text. For the value, use IANA encodings like “UTF-8”. The value value is a CFString object.

      Available in OS X v10.5 and later.

    • kQLPreviewPropertyAttachmentDataKey

      kQLPreviewPropertyAttachmentDataKey

      Gives the attachment data. The value is a CFData object.

      Available in OS X v10.5 and later.

    • kQLPreviewPropertyAttachmentsKey

      kQLPreviewPropertyAttachmentsKey

      Gives the list of attachments (or sub-resources). Value is a CFDictionary object.

      The keys of the dictionary are the attachment identifiers (CFString objects) that can be referenced with the cid:id URL; the values are dictionaries using the kQLPreviewPropertyAttachmentDataKey, kQLPreviewPropertyMIMETypeKey and kQLPreviewPropertyTextEncodingNameKey properties.

      Available in OS X v10.5 and later.

    • kQLPreviewContentIDScheme

      kQLPreviewContentIDScheme

      The cid URL scheme.

      The cid URL scheme permits the HTML of a mail message to refer to the images or other data included in the message. For more information go to http://www.rfc-archive.org/getrfc.php?rfc=2111.

      Available in OS X v10.5 and later.

    Discussion

    You use these keys to specify properties of the generated preview in the dictionary passed into the functions QLPreviewRequestCreateContext, QLPreviewRequestCreatePDFContext, and QLPreviewRequestSetDataRepresentation as the final parameter.

    Availability

    Available in OS X version 10.5 and later.