QLThumbnailRequest Reference

Derived from
CFType
Framework
QuickLook/QuickLook.h
Companion guide
Quick Look Programming Guide
Declared in
QLGenerator.h
QLThumbnailImage.h

Overview

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

A generator must implement the GenerateThumbnailForURL callback function to create and return a thumbnail image requested for a given document. QLThumbnailRequest gives you four ways to designate a thumbnail for a document:

Most of the other functions of QLThumbnailRequest let you get the data associated with the thumbnail request, such as the URL locating the document, the UTI identifying the content type of the document, and the maximum size allowed for the thumbnail image.

Functions by Task

Assigning content to the thumbnail request

Getting attributes of the thumbnail request

Getting the QLThumbnailRequest Type ID

Client Functions

The following functions are for use by clients of Quick Look (generally applications), not by generator plug-ins.

Functions

QLThumbnailImageCreate

Creates a thumbnail image for the specified file. 

QL_EXPORT CGImageRef QLThumbnailImageCreate(CFAllocatorRef allocator, CFURLRef url, CGSize maxThumbnailSize, CFDictionaryRef options);
Parameters
allocator

The allocator to use to create the thumbnail image.

url

The URL locating the file to create a thumbnail image for.

maxThumbnailSize

The maximum desired size of the thumbnail image.

options

A dictionary of options that affect the creation of the thumbnail image. Two options are supported: kQLThumbnailOptionIconModeKey and kQLThumbnailOptionScaleFactorKey.

Return Value

Returns the thumbnail image or NULL if Quick Look does not support this file type

Discussion

This function does not supplant the use of Icon Services by applications as a way to get generic file icons and custom icons stored in the metadata fork of files.

Special Considerations

Thread-safety: This function is thread-safe so you can call it from any thread. However, because it is synchronous, you should generally call it in a background thread.

Availability
  • Available in OS X v10.5 and later.
Declared In
QLThumbnailImage.h

QLThumbnailRequestCopyContentUTI

Returns the UTI for the thumbnail request.

QL_EXPORT CFStringRef QLThumbnailRequestCopyContentUTI(
    QLThumbnailRequestRef thumbnail
);
Parameters
thumbnail

The thumbnail request object.

Return Value

The UTI identifying the content type of the document for which the thumbnail is requested; returns NULL if the UTI cannot be located. You should explicitly release this string object when it is no longer needed.

Special Considerations

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

Availability
  • Available in OS X version 10.5 and later.
Declared In
QLGenerator.h

QLThumbnailRequestCopyOptions

Returns the options specified for the thumbnail request.

QL_EXPORT CFDictionaryRef QLThumbnailRequestCopyOptions(
    QLThumbnailRequestRef thumbnail
);
Parameters
thumbnail

A thumbnail request object.

Return Value

A dictionary containing the options that the client specified for the thumbnail request. See “General Thumbnail Options” for supported options. You should explicitly release the dictionary when it is no longer needed.

Discussion

The client sets options in the thumbnail request to give hints to the generator. (For OS X v10.5 no options are supported.) You should explicitly release the dictionary when it is no longer needed.

Special Considerations

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

Availability
  • Available in OS X version 10.5 and later.
Declared In
QLGenerator.h

QLThumbnailRequestCopyURL

Returns the URL of the document for which the thumbnail request is requested.

QL_EXPORT CFURLRef QLThumbnailRequestCopyURL(
    QLThumbnailRequestRef thumbnail
);
Parameters
thumbnail

The thumbnail request object.

Return Value

The URL identifying the document for which the thumbnail is requested. You should explicitly release the CFURL object when it is no longer needed.

Special Considerations

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

Availability
  • Available in OS X version 10.5 and later.
Declared In
QLGenerator.h

QLThumbnailRequestCreateContext

Creates a graphics context to draw the thumbnail in. 

QL_EXPORT CGContextRef QLThumbnailRequestCreateContext(
    QLThumbnailRequestRef preview,
    CGSize size,
    Boolean isBitmap,
    CFDictionaryRef properties
);
Parameters
preview

The thumbnail request object.

size

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

isBitmap

true if the thumbnail data is bitmap-based, false if vector-based. This value of this parameter affects the interpretation of the size parameter.

properties

A dictionary containing properties for the thumbnail response. (For OS X v10.5 no properties have been defined.).

Return Value

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

Discussion

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

With this function you can create two types of graphics contexts for drawing thumbnails: bitmap and single-page vector-based; you use the isBitmap flag to distinguish between the two. Quick Look handles bitmap thumbnail context differently than non-bitmap contexts; in the latter case, Quick Look might scale the drawing up or down if necessary, and it respects the scale factor (for HiDPI support).

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 thumbnail request is made in; generally, this is the same thread in which the GenerateThumbnailForURL callback was invoked.

Availability
  • Available in OS X version 10.5 and later.
Related Sample Code
Declared In
QLGenerator.h

QLThumbnailRequestFlushContext

Flush the graphics context and sets the thumbnail response.

QL_EXPORT void QLThumbnailRequestFlushContext(
    QLThumbnailRequestRef preview,
    CGContextRef context
);
Parameters
preview

The preview request object.

context

The graphics context to flush.

Discussion

You should call this method after drawing in the graphics context created by QLThumbnailRequestCreateContext.

Special Considerations

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

Availability
  • Available in OS X version 10.5 and later.
Related Sample Code
Declared In
QLGenerator.h

QLThumbnailRequestGetGeneratorBundle

Get the bundle of the generator receiving the thumbnail request.

QL_EXPORT CFBundleRef QLThumbnailRequestGetGeneratorBundle(
    QLThumbnailRequestRef thumbnail
);
Parameters
thumbnail

The thumbnail request object.

Return Value

A reference to the bundle object representing the generator's bundle.

Special Considerations

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

Availability
  • Available in OS X version 10.5 and later.
Declared In
QLGenerator.h

QLThumbnailRequestGetMaximumSize

Returns the maximum size (in points) specified for the thumbnail image.

QL_EXPORT CGSize QLThumbnailRequestGetMaximumSize(
    QLThumbnailRequestRef thumbnail
);
Parameters
thumbnail

The thumbnail request object.

Return Value

The maximum size (in points) specified for the thumbnail image.

Special Considerations

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

Availability
  • Available in OS X version 10.5 and later.
Declared In
QLGenerator.h

QLThumbnailRequestGetTypeID

Gets the type identifier for the QLThumbnailRequest opaque type.

QL_EXPORT CFTypeID QLThumbnailRequestGetTypeID();
Return Value

The type identifier for the QLThumbnailRequest opaque type.

Special Considerations

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

Availability
  • Available in OS X version 10.5 and later.
Declared In
QLGenerator.h

QLThumbnailRequestIsCancelled

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

QL_EXPORT Boolean QLThumbnailRequestIsCancelled(
    QLThumbnailRequestRef thumbnail
);
Parameters
thumbnail

The thumbnail request object.

Return Value

true if the request is being cancelled, false otherwise.

Special Considerations

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

Availability
  • Available in OS X v10.5 and later.
Declared In
QLGenerator.h

QLThumbnailRequestSetImage

Sets the thumbnail request to a specified image.

QL_EXPORT void QLThumbnailRequestSetImage(
    QLThumbnailRequestRef thumbnail,
    CGImageRef image,
    CFDictionaryRef properties);
);
Parameters
thumbnail

The thumbnail request object.

image

The image object to be used as the thumbnail of the document.

properties

A dictionary of properties for the thumbnail. (For OS X v10.5 no properties have been defined.).

Discussion

You call this function to have Quick Look use the CGImage object supplied in image as the thumbnail. Call QLThumbnailRequestGetMaximumSize to get the maximum allowed size for thumbnail and resize it if necessary before calling QLThumbnailSetImage.

Special Considerations

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

Availability
  • Available in OS X version 10.5 and later.
Declared In
QLGenerator.h

QLThumbnailRequestSetImageWithData

Sets the response to the thumbnail request to image data saved within the document.

QL_EXPORT void QLThumbnailRequestSetImageWithData(
    QLThumbnailRequestRef thumbnail,
    CFDataRef data,
    CFDictionaryRef properties);
);
Parameters
thumbnail

The thumbnail request object.

data

The image data, which must be in a format supported by the Image I/O framework (JPG, PNG, and so on). In other words, a content type of kUTTypeImage is assumed. (ImageIO.framework is a subframework of the umbrella Application Services framework.)

properties

A dictionary of properties. The only property that you can currently specify is kCGImageSourceTypeIdentifierHint; see Quartz 2D Programming Guide for information about this property.

Discussion

This function returns the thumbnail as a CFData object containing image data. The document’s application must save this data as part of the document’s data; the generator retrieves it and uses this function to return it to the client. Before you call this function, call QLThumbnailRequestGetMaximumSize to obtain the maximum allowed size for the thumbnail and resize the image if necessary.

Special Considerations

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

Availability
  • Available in OS X version 10.5 and later.
Declared In
QLGenerator.h

Callbacks

CancelThumbnailGeneration

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

void (*CancelThumbnailGeneration)(
    void *thisInterface,
    QLThumbnailThumbnailRef thumbnail
);
Parameters
thisInterface

The CFPlugIn COM-style interface for the generator.

thumbnail

The object representing the thumbnail request.

Discussion

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

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

Availability
  • Available in OS X version 10.5 and later.
Declared In
QuickLook/QLGenerator.h

GenerateThumbnailForURL

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

OSStatus (*GenerateThumbnailForURL)(
    void *thisInterface,
    QLThumbnailRequestRef thumbnail,
    CFURLRef url,
    CFStringRef contentTypeUTI,
    CFDictionaryRef options,
    CGSize maxSize
);

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

Parameters
thisInterface

The CFPlugIn COM-style interface for the generator.

thumbnail

The object containing all information relevant to the thumbnail request. The generator’s role is to assign a document thumbnail (in one of the native Quick Look types) to this object before it returns.

url

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

contentTypeUTI

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

options

A dictionary of options passed from the client (for example, Finder or Spotlight) that are hints for processing the thumbnail.

maxSize

The maximum desired size of the thumbnail.

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 GenerateThumbnailForURL callback function implemented by a Quick Look generator may be called one or more times concurrently if the QLSupportsConcurrentRequests option in the generator bundle’s Info.plist file is set to true. If this is the case, use the thumbnail 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.
Declared In
QuickLook/QLGenerator.h

Data Types

QLThumbnailRequestRef

An opaque reference representing an QLThumbnailRequest object.

typedef struct __QLThumbnailRequest *QLThumbnailRequestRef;
Availability
  • Available in OS X version 10.5 and later.
Declared In
QLGenerator.h

Constants

General Thumbnail Options

Keys used for the options passed by the client to the generator and by the client when requesting a thumbnail image.

QL_EXPORT const CFStringRef kQLThumbnailOptionScaleFactorKey;
Constants
kQLThumbnailOptionScaleFactorKey

A key used to specify the user scale factor for the thumbnail. The float value is encapsulated in a CFNumber object. If this option is absent, the default value is 1.0

Available in OS X v10.5 and later.

Declared in QLThumbnailImage.h.

Discussion

This constant is a key for accessing the scale-factor value in the dictionary passed into GenerateThumbnailForURL in the options parameter. It can also be used for the QLThumbnailImageCreate function, which is called by clients (generally applications) of Quick Look.

Availability
  • Available in OS X version 10.5 and later.
Declared In
QuickLook/QLThumbnailImage.h

Client-Specfic Thumbnail Options

Clients of Quick Look can specify the following option-dictionary properties for special handling of thumbnail images.

QL_EXPORT const CFStringRef kQLThumbnailOptionIconModeKey;
Constants
kQLThumbnailOptionIconModeKey

If the value is kCFBooleanTrue, Quick Look produces the thumbnail as an icon. The image includes all the typical icon decor, such as shadows and a curled corner. If kCFBooleanFalse (the default) is specified, no icon decor is included with the thumbnail image.

Available in OS X v10.5 and later.

Declared in QLThumbnailImage.h.

Declared In
QuickLook/QLThumbnailImage.h


© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-10-31)

Did this document help you? Yes It's good, but... Not helpful...