QLPreviewRequest Reference

Overview

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.

  • For bitmap and single-page vector contexts, use the QLPreviewRequestCreateContext function.

  • For multi-page (PDF) contexts, use the QLPreviewRequestCreatePDFContext function.

• 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 by Task

Assigning content to the preview request

• QLPreviewRequestCreateContext
• QLPreviewRequestCreatePDFContext
• QLPreviewRequestSetDataRepresentation
• QLPreviewRequestFlushContext

Getting attributes of the preview request

• QLPreviewRequestCopyContentUTI
• QLPreviewRequestCopyOptions
• QLPreviewRequestCopyURL
• QLPreviewRequestGetGeneratorBundle
• QLPreviewRequestIsCancelled

Getting the QLPreviewRequest Type ID

• QLPreviewRequestGetTypeID

Functions

QLPreviewRequestCopyContentUTI

Returns the UTI for the preview request.

QL_EXPORT CFStringRef QLPreviewRequestCopyContentUTI(
    QLPreviewRequestRef preview
);

QLPreviewRequestCopyOptions

Returns the options specified for the preview request.

QL_EXPORT CFDictionaryRef QLPreviewRequestCopyOptions(
    QLPreviewRequestRef preview
);

QLPreviewRequestCopyURL

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

QL_EXPORT CFURLRef QLPreviewRequestCopyURL(
    QLPreviewRequestRef preview
);

QLPreviewRequestCreateContext

Creates a graphics context to draw the preview in.

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

QLPreviewRequestCreatePDFContext

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

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

QLPreviewRequestFlushContext

Flush the context and sets the preview response.

QL_EXPORT void QLPreviewRequestFlushContext(
    QLPreviewRequestRef preview,
    CGContextRef context
);

QLPreviewRequestGetGeneratorBundle

Get the bundle of the generator receiving the preview request.

QL_EXPORT CFBundleRef QLPreviewRequestGetGeneratorBundle(
    QLPreviewRequestRef preview
);

QLPreviewRequestGetTypeID

Gets the type identifier for the QLPreviewReqest opaque type.

CFTypeID QLPreviewRequestGetTypeID();

QLPreviewRequestIsCancelled

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

QL_EXPORT Boolean QLPreviewRequestIsCancelled(
    QLPreviewRequestRef preview
);

QLPreviewRequestSetDataRepresentation

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

QL_EXPORT void QLPreviewRequestSetDataRepresentation(
    QLPreviewRequest preview,
    CFDataRef data,
    CFStringRef contentTypeUTI,
    CFDictionary properties
);

Callbacks

CancelPreviewGeneration

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

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

GeneratePreviewForURL

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

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

The Xcode template for Quick Look generators automatically creates a “skeletal” function with the same name as the callback symbol name: GeneratePreviewForURL.

Data Types

QLPreviewRequestRef

An opaque reference representing an QLPreviewRequest object.

typedef struct __QLPreviewRequest *QLPreviewRequestRef;

Constants

Preview Properties

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

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

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.

Declared in QLGenerator.h.

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.

Declared in QLGenerator.h.

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.

Declared in QLGenerator.h.

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.

Declared in QLGenerator.h.

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.

Declared in QLGenerator.h.

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.

Declared in QLGenerator.h.

kQLPreviewPropertyAttachmentDataKey

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

Available in OS X v10.5 and later.

Declared in QLGenerator.h.

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.

Declared in QLGenerator.h.

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.

Declared in QLGenerator.h.