Mac Developer Library

Developer

QuickLook Framework Reference QLThumbnailRequest Reference

Options
Deployment Target:

On This Page
Language:

QLThumbnailRequest Reference

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.

Functions

  • Creates a graphics context to draw the thumbnail in.

    Declaration

    Swift

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

    Objective-C

    CGContextRef QLThumbnailRequestCreateContext ( QLThumbnailRequestRef thumbnail, 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.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Sets the thumbnail request to a specified image.

    Declaration

    Swift

    func QLThumbnailRequestSetImage(_ thumbnail: QLThumbnailRequest!, _ image: CGImage!, _ properties: CFDictionary!)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

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

    Declaration

    Swift

    func QLThumbnailRequestSetImageWithData(_ thumbnail: QLThumbnailRequest!, _ data: CFData!, _ properties: CFDictionary!)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Flush the graphics context and sets the thumbnail response.

    Declaration

    Swift

    func QLThumbnailRequestFlushContext(_ preview: QLThumbnailRequest!, _ context: CGContext!)

    Objective-C

    void QLThumbnailRequestFlushContext ( QLThumbnailRequestRef thumbnail, 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.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

  • Returns the UTI for the thumbnail request.

    Declaration

    Swift

    func QLThumbnailRequestCopyContentUTI(_ thumbnail: QLThumbnailRequest!) -> Unmanaged<CFString>!

    Objective-C

    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.

    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 thumbnail request.

    Declaration

    Swift

    func QLThumbnailRequestCopyOptions(_ thumbnail: QLThumbnailRequest!) -> Unmanaged<CFDictionary>!

    Objective-C

    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.

    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 the thumbnail request is requested.

    Declaration

    Swift

    func QLThumbnailRequestCopyURL(_ thumbnail: QLThumbnailRequest!) -> Unmanaged<CFURL>!

    Objective-C

    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.

    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 thumbnail request.

    Declaration

    Swift

    func QLThumbnailRequestGetGeneratorBundle(_ thumbnail: QLThumbnailRequest!) -> Unmanaged<CFBundle>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

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

    Declaration

    Swift

    func QLThumbnailRequestGetMaximumSize(_ thumbnail: QLThumbnailRequest!) -> CGSize

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

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

    Declaration

    Swift

    func QLThumbnailRequestIsCancelled(_ thumbnail: QLThumbnailRequest!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X v10.5 and later.

  • Gets the type identifier for the QLThumbnailRequest opaque type.

    Declaration

    Swift

    func QLThumbnailRequestGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID QLThumbnailRequestGetTypeID ( void );

    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.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X version 10.5 and later.

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.

    Declaration

    Swift

    func QLThumbnailImageCreate(_ allocator: CFAllocator!, _ url: CFURL!, _ maxThumbnailSize: CGSize, _ options: CFDictionary!) -> Unmanaged<CGImage>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickLook;

    Swift

    import QuickLook

    Availability

    Available in OS X v10.5 and later.

Callbacks

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

    Declaration

    Objective-C

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

    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.

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

    Declaration

    Objective-C

    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.

Data Types

  • An opaque reference representing an QLThumbnailRequest object.

    Declaration

    Swift

    typealias QLThumbnailRequestRef = QLThumbnailRequest

    Objective-C

    typedef struct __QLThumbnailRequest *QLThumbnailRequestRef;

    Availability

    Available in OS X version 10.5 and later.

Constants

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

    Declaration

    Swift

    let kQLThumbnailOptionScaleFactorKey: CFString!

    Objective-C

    QL_EXPORT const CFStringRef kQLThumbnailOptionScaleFactorKey;

    Constants

    • kQLThumbnailOptionScaleFactorKey

      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.

    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.

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

    Declaration

    Swift

    let kQLThumbnailOptionIconModeKey: CFString!

    Objective-C

    QL_EXPORT const CFStringRef kQLThumbnailOptionIconModeKey;

    Constants

    • kQLThumbnailOptionIconModeKey

      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.