| Derived from | |
| Framework | QuickLook/QuickLook.h |
| Companion guide | |
| Declared in | QLGenerator.h QLThumbnailImage.h |
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:
You can create a graphics context to draw the thumbnail in. Graphics contexts for thumbnails are of two kinds: bitmap and single-page vector. You use the QLThumbnailRequestCreateContext for this purpose.
You can extract the thumbnail from the document and return it using the QLThumbnailRequestSetImageWithData function. For this approach, the document’s application must save the thumbnail as part of the document data.
You can create the thumbnail image and assign it to the thumbnail request using the QLThumbnailRequestSetImage function.
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.
QLThumbnailImageCreate function, which is called by clients of Quick Look, not by generator plug-ins. For example, an application could call this function to obtain a thumbnail image of a document that it is listing.QLThumbnailRequestCreateContext
QLThumbnailRequestSetImage
QLThumbnailRequestSetImageWithData
QLThumbnailRequestFlushContext
QLThumbnailRequestCopyContentUTI
QLThumbnailRequestCopyOptions
QLThumbnailRequestCopyURL
QLThumbnailRequestGetGeneratorBundle
QLThumbnailRequestGetMaximumSize
QLThumbnailRequestIsCancelled
The following functions are for use by clients of Quick Look (generally applications), not by generator plug-ins.
Creates a thumbnail image for the specified file.
QL_EXPORT CGImageRef QLThumbnailImageCreate(CFAllocatorRef allocator, CFURLRef url, CGSize maxThumbnailSize, CFDictionaryRef options);
The allocator to use to create the thumbnail image.
The URL locating the file to create a thumbnail image for.
The maximum desired size of the thumbnail image.
A dictionary of options that affect the creation of the thumbnail image. Two options are supported: kQLThumbnailOptionIconModeKey and kQLThumbnailOptionScaleFactorKey.
Returns the thumbnail image or NULL if Quick Look does not support this file type
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.
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.
QLThumbnailImage.hReturns the UTI for the thumbnail request.
QL_EXPORT CFStringRef QLThumbnailRequestCopyContentUTI( QLThumbnailRequestRef thumbnail );
The thumbnail request object.
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.
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.
QLGenerator.hReturns the options specified for the thumbnail request.
QL_EXPORT CFDictionaryRef QLThumbnailRequestCopyOptions( QLThumbnailRequestRef thumbnail );
A thumbnail request object.
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.
The client sets options in the thumbnail request to give hints to the generator. (For Mac OS X v10.5 no options are supported.) You should explicitly release the dictionary when it is no longer needed.
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.
QLGenerator.hReturns the URL of the document for which the thumbnail request is requested.
QL_EXPORT CFURLRef QLThumbnailRequestCopyURL( QLThumbnailRequestRef thumbnail );
The thumbnail request object.
The URL identifying the document for which the thumbnail is requested. You should explicitly release the CFURL object when it is no longer needed.
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.
QLGenerator.hCreates a graphics context to draw the thumbnail in.
QL_EXPORT CGContextRef QLThumbnailRequestCreateContext( QLThumbnailRequestRef preview, CGSize size, Boolean isBitmap, CFDictionaryRef properties );
The thumbnail request object.
The size of the thumbnail; if isBitmap is true the size is in pixels, otherwise it is in points.
true if the thumbnail data is bitmap-based, false if vector-based. This value of this parameter affects the interpretation of the size parameter.
A dictionary containing properties for the thumbnail response. (For Mac OS X v10.5 no properties have been defined.).
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.
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:.
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.
QLGenerator.hFlush the graphics context and sets the thumbnail response.
QL_EXPORT void QLThumbnailRequestFlushContext( QLThumbnailRequestRef preview, CGContextRef context );
The preview request object.
The graphics context to flush.
You should call this method after drawing in the graphics context created by QLThumbnailRequestCreateContext.
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.
QLGenerator.hGet the bundle of the generator receiving the thumbnail request.
QL_EXPORT CFBundleRef QLThumbnailRequestGetGeneratorBundle( QLThumbnailRequestRef thumbnail );
The thumbnail request object.
A reference to the bundle object representing the generator's bundle.
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.
QLGenerator.hReturns the maximum size (in points) specified for the thumbnail image.
QL_EXPORT CGSize QLThumbnailRequestGetMaximumSize( QLThumbnailRequestRef thumbnail );
The thumbnail request object.
The maximum size (in points) specified for the thumbnail image.
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.
QLGenerator.hGets the type identifier for the QLThumbnailRequest opaque type.
QL_EXPORT CFTypeID QLThumbnailRequestGetTypeID();
The type identifier for the QLThumbnailRequest opaque type.
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.
QLGenerator.hReturns whether the thumbnail request has been cancelled by the client.
QL_EXPORT Boolean QLThumbnailRequestIsCancelled( QLThumbnailRequestRef thumbnail );
The thumbnail request object.
true if the request is being cancelled, false otherwise.
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.
QLGenerator.hSets the thumbnail request to a specified image.
QL_EXPORT void QLThumbnailRequestSetImage( QLThumbnailRequestRef thumbnail, CGImageRef image, CFDictionaryRef properties); );
The thumbnail request object.
The image object to be used as the thumbnail of the document.
A dictionary of properties for the thumbnail. (For Mac OS X v10.5 no properties have been defined.).
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.
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.
QLGenerator.hSets the response to the thumbnail request to image data saved within the document.
QL_EXPORT void QLThumbnailRequestSetImageWithData( QLThumbnailRequestRef thumbnail, CFDataRef data, CFDictionaryRef properties); );
The thumbnail request object.
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.)
A dictionary of properties. The only property that you can currently specify is kCGImageSourceTypeIdentifierHint; see Quartz 2D Programming Guide for information about this property.
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.
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.
QLGenerator.hDefines a pointer to a function that Quick Look calls to cancel a thumbnail request.
void (*CancelThumbnailGeneration)( void *thisInterface, QLThumbnailThumbnailRef thumbnail );
The CFPlugIn COM-style interface for the generator.
The object representing the thumbnail request.
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.
Important: Because this function is called on a thread different from the one used to request that the thumbnail be created, you should be extra careful about thread safety. If you have any doubts about thread safety, do not implement this callback.
QuickLook/QLGenerator.hDefines 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.
The CFPlugIn COM-style interface for the generator.
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.
A URL (represented by a CFURLRef object) that locates the document for which a thumbnail is requested.
The UTI specifying the content type of the document for which the thumbnail is requested.
A dictionary of options passed from the client (for example, Finder or Spotlight) that are hints for processing the thumbnail.
The maximum desired size of the thumbnail.
A status code representing the result of the request. For the current version of this callback, you should always return noErr.
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.
Thread-safety: For a discussions of issues and possible approaches, see “Overview of Generator Implementation“ in Quick Look Programming Guide.
QuickLook/QLGenerator.hAn opaque reference representing an QLThumbnailRequest object.
typedef struct __QLThumbnailRequest *QLThumbnailRequestRef;
QLGenerator.hKeys 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;
kQLThumbnailOptionScaleFactorKeyA 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 Mac OS X v10.5 and later.
Declared in QLThumbnailImage.h.
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.
QuickLook/QLThumbnailImage.hClients of Quick Look can specify the following option-dictionary properties for special handling of thumbnail images.
QL_EXPORT const CFStringRef kQLThumbnailOptionIconModeKey;
kQLThumbnailOptionIconModeKeyIf 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 Mac OS X v10.5 and later.
Declared in QLThumbnailImage.h.
QuickLook/QLThumbnailImage.hLast updated: 2007-10-31
Mac OS X Reference Library Data Management: File Management QLThumbnailRequest Reference