Creating and Configuring a Quick Look Project

Xcode projects for Quick Look generators originate from a special template that sets up important aspects of the project. However, you still must specify generator-specific configuration information and add any resources for the generator, typically before you write any code.

Creating and Setting Up the Project

To create a Quick Look generator project, start by choosing New Project from the File menu in the Xcode application. In the project-creation assistant, select Quick Look Plug-In in the list of project templates (as shown in Figure 3-1) and click Next.

Figure 3-1  Choosing the Quick Look plug-in template
Choosing the Quick Look plug-in template

After you specify a name and location for the project, Xcode displays a project window similar to the example in Figure 3-2.

Figure 3-2  Default items in a Quick Look plug-in project
Default items in a Quick Look plug-in project

The following items in this window have some special relevance to Quick Look:

Although a Quick Look generator does not (and should not) have nib files as resources, you can add other resources if necessary.

Project Configuration

For OS X v10.6 and later, you must build Quick Look generators for both 32- and 64-bit.

The information property list (Info.plist) of a Quick Look generator project includes some special properties whose values you should set in addition to standard properties such as CFBundleIdentifier and CFBundleVersion. The following sections describe these properties.

The Content-Type UTI and CFPlugIn Properties

One important property for Quick Look generators is LSItemContentTypes, a subproperty of CFBundleDocumentTypes. Listing 3-1 shows the CFBundleDocumentTypes property when unedited. (Note that the Quick Look project template specifies the value (QLGenerator) of the CFBundleTypeRole property for you.)

Listing 3-1  The subproperties of CFBundleDocumentTypes

    <key>CFBundleDocumentTypes</key>
    <array>
        <dict>
            <key>CFBundleTypeRole</key>
            <string>QLGenerator</string>
            <key>LSItemContentTypes</key>
            <array>
                <string>SUPPORTED_UTI_TYPE</string> // change this!
            </array>
        </dict>
    </array>

Replace the string “SUPPORTED_UTI_TYPE” with one or more UTI s identifying the content types of the documents for which this generator generates thumbnails and previews. For example, the QuickLookSketch example project specifies the UTIs for Sketch documents:

<key>CFBundleDocumentTypes</key>
    <array>
        <dict>
            <key>CFBundleTypeRole</key>
            <string>QLGenerator</string>
            <key>LSItemContentTypes</key>
            <array>
                <string>com.apple.sketch2</string>
                <string>com.apple.sketch1</string>
            </array>
        </dict>
    </array>

For more information on Uniform Type Identifiers (UTIs) for document-content types, see Uniform Type Identifiers Overview.

As Listing 3-2 shows, a large segment of the Info.plist in a Quick Look generator project are properties related to CFPlugIn. You should not have to edit these properties.

Listing 3-2  CFPlugIn properties

    <key>CFPlugInDynamicRegisterFunction</key>
    <string></string>
    <key>CFPlugInDynamicRegistration</key>
    <string>NO</string>
    <key>CFPlugInFactories</key>
    <dict>
        <key>27EB40F9-21D6-4438-9395-692B52DB53FB</key>
        <string>QuickLookGeneratorPluginFactory</string>
    </dict>
    <key>CFPlugInTypes</key>
    <dict>
        <key>5E2D9680-5022-40FA-B806-43349622E5B9</key>
        <array>
            <string>27EB40F9-21D6-4438-9395-692B52DB53FB</string>
        </array>
    </dict>
    <key>CFPlugInUnloadFunction</key>
    <string></string>

Other Property List Keys

You can specify these additional key-value pairs in the information property list (Info.plist) of a Quick Look generator:

Key

Allowed value

Description

QLThumbnailMinimumSize

Real number <real>n</real>

Specifies the minimum use size along one dimension (in points) of thumbnails for the generator. Quick Look does not call the GenerateThumbnailForURL callback function for thumbnail sizes less than this value. The default size is 17. If your generator is fast enough, you can remove this property so the thumbnail image can appear in standard lists.

QLPreviewWidth

Real number <real>n</real>

This number gives Quick Look a hint for the width (in points) of previews. It uses these values if the generator takes too long to produce the preview.

QLPreviewHeight

Real number <real>n</real>

This number gives Quick Look a hint for the height (in points) of previews. It uses these values if the generator takes too long to produce the preview.

QLSupportsConcurrentRequests

YES or NO

Controls whether the generator can handle concurrent thumbnail and preview requests.

QLNeedsToBeRunInMainThread

YES or NO

Controls whether the generator can be run in threads other than the main thread

The properties QLSupportsConcurrentRequests and QLNeedsToBeRunInMainThread are Quick Look properties that affect the multithreaded characteristics of the generator. They are discussed in “Generators and Thread Safety.”