Next Previous

Functions For Displaying Previews

Introduction

This chapter describes the functions for displaying previews, handling events in previews, and creating previews that are provided by preview components. These functions are described from the perspective of the Image Compression Manager, which is most likely to call preview components. If you are developing a preview component, your component must behave as described here.

Handling Events

The PreviewEvent function is provided so that your preview component can do standard event filtering.

Creating Previews

Two functions are available for use in creating previews. The PreviewMakePreview function creates previews by allocating a handle to data to be added to the file. On the other hand, the PreviewMakePreviewReference function makes previews by returning the type and identification number of a resource within the file to be used as the preview for the file.

The Preview Resource

This section describes the preview resource, which is used to store a visual preview, and the preview resource item structure, which is an array that allows you to store additional preview information.

The preview display code assumes that the data fork of the file is formatted using QuickTime atoms. See QuickTime Movie Basics for information on atom-based storage.

Adding a preview results in at least two atoms being added to the data file. The first atom has a pnot tag. Its basic structure is the same as the pnotResource structure.

struct PreviewResourceRecord {

    unsigned long       modDate;

    short               version;

    OSType              resType;

    short               resID;

};

Term	Definition
`modDate`	Contains the modification time (in the standard Macintosh format of seconds since midnight, January 1, 1904) of the file for which the preview was created. This parameter allows you to find out if the preview is out of date with the contents of the file.
`version`	Contains the version number of the preview resource. The low bit of the version is a flag for preview components that only reference their data. If the bit is set, it indicates that the resource identified in the preview resource is not owned by the preview component, but is part of the file. It is not removed when the preview is updated or removed (using the Image Compression Manager's `MakeFilePreview` or `AddFilePreview` function), as it would if the version number were 0.
`resType`	Identifies the type of the preview component used to display the preview data and the type of the atom containing the preview data.
`resID`	Contains the index (1-based) of the atom to be used. For example, a `resType` of PICT and a `resID` of 2 tells QuickTime to use the second PICT atom in the file for the preview data.

Data Types

This section defines the component instance used by preview components, and lists the data structures for preview resources and the preview resource item structure. See The Preview Resource above, which includes the new PreviewResourceRecord data structure.

typedef ComponentInstance pnotComponent;

typedef struct pnotResource {

    unsigned long  modDate;     /* modification date */

    short          version;     /* version number of preview resource */

    OSType         resType;     /* type of resource used as preview cache */

    short          resID;       /* resource identification number

                                   of resource used as preview cache */

    short          numResItems; /* number of additional file descriptions */

    pnotResItem    resItem[ ];  /* array of file descriptions */

} pnotResource;

typedef struct pnotResItem {

    unsigned long       modDate;     /* last modification date of item */

    OSType              useType;     /* what type of data */

    OSType              resType;     /* resource type containing item */

    short               resID;       /* resource ID containing this item */

    short               rgnCode;     /* region code */

    long                reserved;    /* set to 0 */

} pnotResItem; *pnotResItemPtr;

Constants

This section defines the constants that are used to communicate with preview components. These are primarily flags that describe the preview components capabilities and requirements.

enum {

    pnotComponentWantsEvents    = 1, /* component requires events */

    pnotComponentNeedsNoCache   = 2  /* component does not require cache */

};

enum {

  kPreviewShowDataSelector             = 1, /* PreviewShowData */

  kPreviewMakePreviewSelector          = 2, /* PreviewMakePreview */

  kPreviewMakePreviewReferenceSelector = 3, /* PreviewMakePreviewReference */

  kPreviewEventSelector                = 4  /* PreviewEvent */

};

#define ShowFilePreviewComponentType 'pnot'     /* creates previews */

#define CreateFilePreviewComponentType 'pmak'   /* displays previews */

Next Previous