Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Previewing Files
QuickTime includes extensions to the Standard File Package that allow you to create and display file previews, information that gives the user an idea of a file’s contents without opening the file. Typically, a file’s preview is a small PICT image (called a thumbnail ), but previews may also contain other types of information that is appropriate to the type of file being considered. For example, a text file’s preview might tell the user when the file was created and what it discusses. You can use the Image Compression Manager to create thumbnail images.
Standard File Functions
QuickTime provides standard file functions that your application can use to display a file’s preview during the Open dialog box. These functions allow your application to support previews automatically.
The Movie Toolbox provides two standard file functions that allow you to display file previews in an Open dialog box using standard file reply structures: SFGetFilePreview
and SFPGetFilePreview
. The SFGetFilePreview
function corresponds to the existing SFGetFile
function; the SFPGetFilePreview
function corresponds to the existing SFPGetFile
function.
The SFGetFilePreview
function uses the dialog box shown in Figure 8-1. The SFPGetFilePreview
function can also use this dialog box, if you do not supply your own.
You use these new functions in place of the existing standard file functions to indicate whether or not you want to allow the user to display previews during the Open dialog box. The user displays a file’s preview by selecting a file in the dialog box and clicking Show Preview. When the user does so, the functions display the preview for the file, as shown in Figure 8-2.
The preview area of the dialog box is displayed whenever previewing is enabled.
Customizing Your Interface
If your application requires it, you can customize the user interface for identifying files. The SFGetFilePreview
function does not allow you to use a custom dialog box by creating your own dialog template resource. However, the SFPGetFilePreview
function does let you access a custom dialog box of any resource type with the dlgID
parameter.
Figure 8-3 shows the standard dialog box used by SFPGetFilePreview
and SFGetFilePreview
. Your dialog box and dialog filter function must support at least these dialog items.
Items to the left of item 13 are visible only when previewing. If you want to define items that are visible only during a file preview, place them to the left of item 13 in your custom dialog box.
If your application defines a custom dialog box, be sure to include the following items in your dialog box definition:
enum |
{ |
/* dialog items to include in dialog box definition for use |
with SFPGetFilePreview function |
*/ |
sfpItemPreviewAreaUser = 11, /* user preview area */ |
sfpItemPreviewStaticText = 12, /* static text preview */ |
sfpItemPreviewDividerUser = 13, /* user divider preview */ |
sfpItemCreatePreviewButton = 14, /* create preview button */ |
sfpItemShowPreviewButton = 15 /* show preview button */ |
}; |
Previewing Files Using Standard File Reply Structures
The Movie Toolbox provides two standard file functions, standardGetFilePreview
and CustomGetFilePreview
, that allow you to display file previews in an Open dialog box using standard file reply structures (of type StandardFileReply
). The StandardGetFilePreview
function corresponds to the existing StandardGetFile
function; the CustomGetFilePreview
function corresponds to the existing CustomGetFile
function. Both of these new functions take the same parameters as their existing counterparts.
The StandardGetFilePreview
function uses the dialog box shown in Figure 8-4. The CustomGetFilePreview
function can also use this dialog box, if you do not supply your own.
You use these new functions in place of the existing standard file functions whenever you want to allow the user to display previews during the Open dialog box. The user causes a file’s preview to be displayed by selecting a file in the dialog box and clicking Show Preview. When the user does so, the functions display the preview for the file, as shown in Figure 8-5.
The preview portion of the dialog box is displayed only when the dialog box is showing a file’s preview.
The SFGetFilePreview
, SFPGetFilePreview
, StandardGetFilePreview
, and CustomGetFilePreview
functions allow the user to automatically convert files to movies if your application requests movies. If there is a file that can be converted into a movie file using a movie import component, then the file is shown in the Standard File dialog box in addition to any movies. When the user selects the file, the Open button changes to a Convert button. Figure 8-6 provides an example of this dialog box.
Choosing Convert displays a dialog box that allows the user to choose where the converted file should be saved. Figure 8-7 shows this dialog box.
When conversion is complete, the converted file is returned to the calling application as the movie that the user chose. If you want to disable automatic file conversion in your application, you must write a file filter function and pass it to the file preview display function you are using. Your file filter function must call the File Manager’s FSpGetFileInfo
function on each file that is passed to it to determine its actual file type. If the File System parameter block pointer passed to your file filter function indicates that the file type is 'MooV'
, and the actual type returned by FSpGetFileInfo
is not 'MooV'
, then the file filter function will convert this file. If you do not wish a file to be displayed as a candidate for conversion, your file filter function should return a value of true
when it is called for that file.
A file filter function filters the files that are displayed to the user in a dialog box. You specify this function in the fileFilter
parameter of the SFGetFilePreview
, StandardGetFilePreview
, and CustomGetFilePreview
routines. If this parameter is not nil
, SFGetFilePreview
calls the function for each file to determine whether to display the file to the user. The SFGetFilePreview
function supplies you with the information it receives from the File Manager’s GetFileInfo
routine.
Functions for Creating File Previews
The Movie Toolbox provides two functions that allow you to create file previews. File previews contain information that gives the user an idea of a file’s contents without opening the file. Typically, a file’s preview is a small PICT image (called a thumbnail ), but previews may also contain other types of information that is appropriate to the type of file being considered. For example, a text file’s preview might tell the user when the file was created and what it discusses.
You can use the MakeFilePreview
function to create a preview for a file. The AddFilePreview
function allows you to add a preview that you have created to a file.
Generating Pictures From Movies
The Movie Toolbox provides a set of functions that allow your application to create QuickDraw pictures from movies, tracks, and posters. This section discusses those functions.
You can use the GetMoviePict
function to create a picture from a movie or its preview; you can use the GetTrackPict
function to create a picture from a track. The GetMoviePosterPict
function lets you create a picture that contains a movie’s poster. If a movie or track has no spatial representation, the returned picture is empty (that is, the upper-left and lower-right coordinates are equal).
When memory is low, the GetMoviePict
function now reports out of memory errors instead of returning empty pictures.
Copyright © 2005, 2018 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2018-06-04