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 |
---|---|
|
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. |
|
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 |
|
Identifies the type of the preview component used to display the preview data and the type of the atom containing the preview data. |
|
Contains the index (1-based) of the atom to be used. For example, a |
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 */ |
Copyright © 2005, 2007 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2007-01-08