Quicktime Kit Framework Reference

QuickTime Kit Framework Reference

2006-05-23 Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR Apple Computer, Inc. REPRESENTATION, EITHER EXPRESS OR © 2004, 2006 Apple Computer, Inc. IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, All rights reserved. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND No part of this publication may be YOU, THE READER, ARE ASSUMING THE reproduced, stored in a retrieval system, or ENTIRE RISK AS TO ITS QUALITY AND transmitted, in any form or by any means, ACCURACY. mechanical, electronic, photocopying, IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, recording, or otherwise, without prior OR CONSEQUENTIAL DAMAGES written permission of Apple Computer, Inc., RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if with the following exceptions: Any person advised of the possibility of such damages. is hereby authorized to store documentation THE WARRANTY AND REMEDIES SET on a single computer for personal use only FORTH ABOVE ARE EXCLUSIVE AND IN and to print copies of documentation for LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, personal use provided that the or employee is authorized to make any documentation contains Apple’s copyright modification, extension, or addition to this notice. warranty. Some states do not allow the exclusion or The Apple logo is a trademark of Apple limitation of implied warranties or liability for Computer, Inc. incidental or consequential damages, so the above limitation or exclusion may not apply to Use of the “keyboard” Apple logo you. This warranty gives you specific legal rights, and you may also have other rights which (Option-Shift-K) for commercial purposes vary from state to state. without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010

Apple, the Apple logo, Carbon, Cocoa, Mac, Mac OS, Macintosh, QuickTime, and Xcode are trademarks of Apple Computer, Inc., registered in the United States and other countries. Times is a registered trademark of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. Simultaneously published in the United States and Canada. Contents

Introduction The QuickTime Kit 9

Introduction 9 QuickTime Kit Classes 9 Encapsulating QuickTime Movies 10 Movie Playback and Media Processing 11 Movie Display and Control 11 Getting and Setting Movie Track Properties 12 Controlling Media Properties 12 Creating Data Reference Objects 12 Defining Time Scales and Time Ranges 12

Part I Classes 13

Chapter 1 NSCoder QuickTime Kit Additions Reference 15

Class Description 15 Methods by Task 15 Instance Methods 16

Chapter 2 NSValue QuickTime Kit Additions Reference 17

Class Description 17 Methods by Task 17 Class Methods 18 Instance Methods 18

Chapter 3 QTDataReference Class Reference 19

Class Description 19 Methods by Task 19 Class Methods 21 Instance Methods 22 Constants 26

Chapter 4 QTMedia Class Reference 27

Class Description 27

Methods by Task 27 Class Methods 28 Instance Methods 29 Constants 30

Chapter 5 QTMovie Class Reference 35

Class Description 35 Methods by Task 36 Class Methods 41 Instance Methods 47 Delegate Methods by Task 61 Delegate Methods 62 Constants 63 Notifications 69

Chapter 6 QTMovieView Class Reference 73

Class Description 73 Adopted Protocols 73 Methods by Task 74 Instance Methods 76

Chapter 7 QTTrack Class Reference 85

Class Description 85 Methods by Task 85 Class Methods 87 Instance Methods 87 Constants 91

Part II Functions 93

Chapter 8 QuickTime Kit Functions Reference 95

Introduction 95 Functions by Task 95 Functions 97

Part III Data Types 103

Chapter 9 QuickTime Kit Data Types Reference 105

Introduction 105 Data Types 105

Document Revision History 107

Index 109

Introduction The QuickTime Kit 9

Figure I-1 The QuickTime Kit framework class hierarchy 10

The QuickTime Kit

Framework QTKit.framework Header file directories QTKit/QTKit.h

Introduction

The QuickTime Kit is a new framework (QTKit.framework) developed by Apple for working with QuickTime movies in Cocoa applications on Mac OS X. The QuickTime Kit framework, which offers a rich set of APIs for manipulating time-based media, is designed as an alternative to and eventual replacement for the existing Cocoa Application Kit classes NSMovie and NSMovieView. Using this new API provides developers with more extensive coverage of the QuickTime APIs than is offered by those Application Kit classes and achieves this in a way that minimizes the requirement for Cocoa programmers to be conversant with Carbon data types such as handles, aliases, file-system specifications, and the like.

The QuickTime Kit also comes with a new QuickTime palette, which lets you drag and drop a QuickTime movie object into your project window, and display, control, and edit that movie without writing a single line of code.

To work with this new framework, you don’t need to know anything about the existing NSMovie and NSMovieView classes, but you should be familiar with developing Cocoa applications using Xcode and Interface Builder. Because the framework is flexible and relatively easy to use in Cocoa, you won’t need to have a comprehensive understanding of the QuickTime procedural C API in order to build your application or extend its functionality.

The QuickTime Kit framework is available in Mac OS X v10.4 and later. The framework will also support applications running in Mac OS X v10.3. Note, however, that the framework requires QuickTime 7 or later on Mac OS X v10.3.

QuickTime Kit Classes

The QuickTime Kit framework contains only five classes, along with a number of useful methods, functions, and protocols. Using these classes and methods, you can display, control, and edit QuickTime movies in your Cocoa application. Figure I-1 shows the QuickTime Kit framework’s class hierarchy.

Figure I-1 The QuickTime Kit framework class hierarchy

QuickTime Kit Framework

QTMovie NSObject QTTrack

QTMedia

QTDataReference

NSView QTMovieView

Encapsulating QuickTime Movies

Two of the new classes in the QuickTime Kit framework––QTMovie and QTMovieView––are similar in concept to the existing Application Kit classes NSMovie and NSMovieView, but offer the advantage for Cocoa developers of providing greater functionality than those classes, which were limited to simple movie playback and rudimentary pasteboard editing. They also expose more of QuickTime’s capabilities in an object-oriented fashion. For example, QuickTime Kit provides Cocoa methods for working with data references, thus reducing the need for developers to work with Macintosh Carbon APIs, such as the File Manager and the Memory Manager.

The principal class in the QTKit framework is QTMovie. This class serves as a Cocoa representation of a QuickTime movie and its associated movie controller. QTMovie objects can be associated with movie data contained in files, URLs, memory blocks, the pasteboard, or even an existing open QuickTime movie. QTMovie provides methods for getting and setting movie properties and for editing movies.

To display a QTMovie object in a window, you use the QTMovieView class. QTMovieView is a subclass of NSView that supports movie playback and editing. A movie controller bar is displayed in the view, but can optionally be hidden.

A QuickTime movie consists of one or more tracks, each of which is associated with a single media. Similarly, a QTMovie is associated with one or more objects of type QTTrack, each of which is associated with a single QTMedia object. The QTTrack and QTMedia classes provide a number of methods for operating on QuickTime tracks and media

The QTDataReference class represents a data reference, which is QuickTime’s standard way of picking out movie data, whether stored in files, URLs, memory blocks, or elsewhere.

The QuickTime Kit also defines several structures for representing specific times and time ranges in a movie or track: QTTime and QTTimeRange.

Movie Playback and Media Processing

The QTMovie class represents both a QuickTime movie and a movie controller. A movie is a collection of playable and editable media content, describing the sources and types of the media in that collection and their spatial and temporal organization. These collections may be used for presentation (such as playback on the screen) or for the organization of media for processing (such as composition and transcoding to a different compression type).

Just as a QuickTime movie contains a set of tracks, each of which defines the type, the segments, and the ordering of the media data it presents, a QTMovie object is associated with instances of the QTTrack class. In turn, a QTTrack object is associated with a single QTMedia object.

A QTMovie object can be initialized from a file, from a resource specified by a URL, from a block of memory, from a pasteboard, or from an existing QuickTime movie.

Once a QTMovie object has been initialized, it is typically used in combination with a QTMovieView for playback.

The QTMovie class includes an extensive number of instance and class methods that let you perform a wide range of operations on QuickTime movies, from basic initialization and movie creation to getting movie tracks and controlling movie playback. Some of these capabilities include:

■ Creating and initializing a QTMovie object

■ Getting a list of supported file types

■ Setting movie properties and attributes

■ Getting and setting selection times

■ Getting movie tracks and movie images

■ Storing movie data

■ Controlling movie playback

■ Editing and saving a movie

■ Getting QTMovie primitives, that is, getting the movie or movie controller associated with a QTMovie object

The QTMovie class also includes a large number of constants you can use to specify movie attributes.

Movie Display and Control

The QTMovieView is a subclass of NSView that you use to display and control QuickTime movies. A QTMovieView is typically used, for example, in combination with a QTMovie object, which supplies the movie being displayed. A QTMovieView also supports editing operations on the movie.

The movie may be placed within an arbitrary bounding rectangle in the view’s coordinate system, and the remainder of the view can be filled with a fill color. The movie controller, if visible, can also be placed within an arbitrary bounding rectangle in the view’s coordinate system.

For user interface management, use:

- (BOOL)validateMenuItem:(NSMenuItem*)cell

For pasteboard editing:

- (IBAction)selectAll:(id)sender; - (IBAction)cut:(id)sender; - (IBAction)copy:(id)sender; - (IBAction)paste:(id)sender; - (IBAction)delete:(id)sender; - (IBAction)undo:(id)sender; - (IBAction)redo:(id)sender; - (IBAction)add:(id)sender; - (IBAction)addScaled:(id)sender; - (IBAction)trim:(id)sender;

Getting and Setting Movie Track Properties

The QTTrack class represents a QuickTime track (of type Track). QTTrack objects are associated with QTMovie objects and support methods for getting and setting the track properties. If necessary, you can retrieve the track identifier associated with a QTTrack object by calling its quickTimeTrackmethod.

Controlling Media Properties

The QTMedia class represents a QuickTime media (of type Media). QTMedia objects are associated with QTTrack objects and support methods for getting and setting the media properties. If necessary, you can retrieve the media identifier associated with a QTMedia object by calling its quickTimeMedia method.

Creating Data Reference Objects

A QTDataReference object is a representation of a QuickTime data reference, which is used to specify the location of a movie or its media data. You can create QTDataReference objects that refer to data stored in files accessed using file names or URLs, or in memory accessed using handles, pointers, or NSData objects.

Defining Time Scales and Time Ranges

The QTTime structure defines the value and time scale of a time. Functions are available for creating a QTTime structure, getting and setting times, comparing QTTime structures, adding and subtracting times, and getting a description.

The QTTimeRange structure defines a range of time. You use this, for instance, to specify the active segment of a movie or track. Functions are also available for creating a QTTimeRange structure, querying time ranges, unioning and intersecting time ranges, and getting a description.

Classes

NSCoder QuickTime Kit Additions Reference

Inherits from: NSObject Conforms to: NSObject (NSObject)

Framework QTKit.framework Declared in: QTKit/QTTime.h QTKit/QTTimeRange.h

Availability: Available in Mac OS X v10.4 and later.

Class Description

The QuickTime Kit supports categories on the NSCoder class that allow you to encode and decode structures of type QTTime and QTTimeRange.

Methods by Task

The following method types are intended to work with time and time ranges:

– decodeQTTimeForKey: (page 16) Decodes a QTTime structure. This method matches an encode QTTime message used during encoding.

– decodeQTTimeRangeForKey: (page 16) Decodes a QTTimeRange structure. This method matches an encode QTTimeRange message used during encoding.

– encodeQTTime:forKey: (page 16)

– encodeQTTimeRange:forKey: (page 16)

Instance Methods

decodeQTTimeForKey: Decodes a QTTime structure. This method matches an encode QTTime message used during encoding.

- (QTTime)decodeQTTimeForKey:(NSString *)key

Availability Available in Mac OS X v10.3 and later.

decodeQTTimeRangeForKey: Decodes a QTTimeRange structure. This method matches an encode QTTimeRange message used during encoding.

- (QTTimeRange)decodeQTTimeRangeForKey:(NSString *)key

Availability Available in Mac OS X v10.3 and later.

encodeQTTime:forKey: - (void)encodeQTTime:(QTTime)time forKey:(NSString *)key

Discussion Encodes a QTTime structure. This method must be matched by a decode QTTime message.

Availability Available in Mac OS X v10.3 and later.

encodeQTTimeRange:forKey: - (void)encodeQTTimeRange:(QTTimeRange)range forKey:(NSString *)key

Discussion Encodes a QTTimeRange structure range. This method must be matched by a decode QTTimeRange message.

Availability Available in Mac OS X v10.3 and later.

NSValue QuickTime Kit Additions Reference

Inherits from: NSObject Conforms to: NSObject (NSObject)

Framework QTKit.framework Declared in: QTKit/QTTime.h QTKit/QTTimeRange.h

Availability: Available in Mac OS X v10.4 and later.

Class Description

The QuickTime Kit supports categories on the NSValue class that allow you get QTTime and QTTimeRange structures as objects of type NSValue.

Methods by Task

The following method types are intended to work with time and time ranges:

+ valueWithQTTime: (page 18) Creates an NSValue object that wraps the specified QTTime structure.

+ valueWithQTTimeRange: (page 18) Creates an NSValue object that wraps the specified QTTimeRange structure.

– QTTimeValue (page 18) Returns a QTTime structure that contains the time in an NSValue object.

– QTTimeRangeValue (page 18) Returns a QTTimeRange structure that contains the range in an NSValue object.

Class Methods

valueWithQTTime: Creates an NSValue object that wraps the specified QTTime structure.

+ (NSValue *)valueWithQTTime:(QTTime)time

Availability Available in Mac OS X v10.3 and later.

valueWithQTTimeRange: Creates an NSValue object that wraps the specified QTTimeRange structure.

+ (NSValue *)valueWithQTTimeRange:(QTTimeRange)range

Availability Available in Mac OS X v10.3 and later.

Instance Methods

QTTimeRangeValue Returns a QTTimeRange structure that contains the range in an NSValue object.

- (QTTimeRange)QTTimeRangeValue

Availability Available in Mac OS X v10.3 and later.

QTTimeValue Returns a QTTime structure that contains the time in an NSValue object.

- (QTTime)QTTimeValue

Availability Available in Mac OS X v10.3 and later.

QTDataReference Class Reference

Inherits from: NSObject Conforms to: NSObject (NSObject)

Framework QTKit.framework Declared in: QTKit/QTDataReference.h

Availability: Available in Mac OS X v10.4 and later.

Class Description

A QTDataReference object is a representation of a QuickTime data reference which specifies the location of a QuickTime movie or some media data. You can create QTDataReference objects that refer to data stored in files accessed using file names or URLs, or in memory accessed using handles, pointers, or NSData objects.

Methods by Task

Creating a QTDataReference

+ dataReferenceWithDataRef:type: (page 21)

+ dataReferenceWithDataRefData:type: (page 21)

+ dataReferenceWithReferenceToFile: (page 22)

+ dataReferenceWithReferenceToURL: (page 22)

+ dataReferenceWithReferenceToData: (page 21)

+ dataReferenceWithReferenceToData:name:MIMEType: (page 21)

Initializing a QTDataReference

– initWithDataRef:type: (page 23)

– initWithDataRefData:type: (page 23)

– initWithReferenceToFile: (page 24)

– initWithReferenceToURL: (page 24)

– initWithReferenceToData: (page 23)

– initWithReferenceToData:name:MIMEType: (page 23)

Getting and setting data reference information

– dataRef (page 22)

– dataRefData (page 22)

– dataRefType (page 23)

– referenceFile (page 25)

– referenceURL (page 25)

– referenceData (page 24)

– name (page 24)

– MIMEType (page 24)

– setDataRef: (page 25)

– setDataRefType: (page 25)

Class Methods

dataReferenceWithDataRef:type: + (id)dataReferenceWithDataRef:(Handle)dataRef type:(NSString *)type

Discussion Creates a QTDataReference object of type type initialized with data from dataRef. You can use this call to convert an existing QuickTime data reference (stored as a handle) into a QTDataReference.

Availability Available in Mac OS X v10.3 and later.

dataReferenceWithDataRefData:type: + (id)dataReferenceWithDataRefData:(NSData *)dataRefData type:(NSString *)type

Discussion Creates a QTDataReference object of type type initialized with data from dataRefData.

Availability Available in Mac OS X v10.3 and later.

dataReferenceWithReferenceToData: + (id)dataReferenceWithReferenceToData:(NSData *)data

Discussion Creates a QTDataReference object for the data block data.

Availability Available in Mac OS X v10.3 and later.

dataReferenceWithReferenceToData:name:MIMEType: + (id)dataReferenceWithReferenceToData:(NSData *)data name:(NSString *)name MIMEType:(NSString *)MIMEType

Discussion Creates a QTDataReference object for the data block data; this data reference has two data reference extensions, a filenaming extension and a MIME type extension.

Availability Available in Mac OS X v10.3 and later.

dataReferenceWithReferenceToFile: + (id)dataReferenceWithReferenceToFile:(NSString *)fileName

Discussion Creates a QTDataReference object for the file fileName. The fileName is assumed to be a full path name for a file.

Availability Available in Mac OS X v10.3 and later.

dataReferenceWithReferenceToURL: + (id)dataReferenceWithReferenceToURL:(NSURL *)url

Discussion Creates a QTDataReference object for the URL url.

Availability Available in Mac OS X v10.3 and later.

Instance Methods

dataRef - (Handle)dataRef

Discussion Returns the QuickTime data reference associated with a QTDataReference object.

Availability Available in Mac OS X v10.3 and later.

dataRefData - (NSData *)dataRefData

Discussion Returns the QuickTime data reference data associated with a QTDataReference object, stored in an NSData object.

Availability Available in Mac OS X v10.3 and later.

dataRefType - (NSString *)dataRefType

Discussion Returns the type of the data reference associated with a QTDataReference object.

Availability Available in Mac OS X v10.3 and later. initWithDataRef:type: - (id)initWithDataRef:(Handle)dataRef type:(NSString *)type

Discussion Initializes a newly created QTDataReference object with data from dataRef; the QTDataReference is of type dataRefType. You can use this call to convert an existing QuickTime data reference (stored as a handle) into a QTDataReference.

Availability Available in Mac OS X v10.3 and later. initWithDataRefData:type: - (id)initWithDataRefData:(NSData *)dataRefData type:(NSString *)type

Discussion Initializes a newly created QTDataReference object with data from dataRefData; the QTDataReference is of type dataRefType.

Availability Available in Mac OS X v10.3 and later. initWithReferenceToData: - (id)initWithReferenceToData:(NSData *)data

Discussion Initializes a newly created QTDataReference object for the data block data.

Availability Available in Mac OS X v10.3 and later. initWithReferenceToData:name:MIMEType: - (id)initWithReferenceToData:(NSData *)data name:(NSString *)name MIMEType:(NSString *)MIMEType

Discussion Initializes a newly created QTDataReference object for the data block data; this data reference has two data reference extensions, a filenaming extension and a MIME type extension.

Availability Available in Mac OS X v10.3 and later.

initWithReferenceToFile: - (id)initWithReferenceToFile:(NSString *)fileName

Discussion Initializes a newly created QTDataReference object for the file fileName. The fileName is assumed to be a full path name for a file.

Availability Available in Mac OS X v10.3 and later.

initWithReferenceToURL: - (id)initWithReferenceToURL:(NSURL *)url

Discussion Initializes a newly created QTDataReference object for the URL url.

Availability Available in Mac OS X v10.3 and later.

MIMEType - (NSString *)MIMEType

Discussion Returns the type in a MIME type extension associated with a QTDataReference object.

Availability Available in Mac OS X v10.3 and later.

name - (NSString *)name

Discussion Returns the name in a filenaming extension associated with a QTDataReference object

Availability Available in Mac OS X v10.3 and later.

referenceData - (NSData *)referenceData

Discussion Returns the reference data of a QTDataReference object, that is, the NSData object passed to initWithReferenceToData or initWithReferenceToData:name:MIMEType. For some QTDataReference objects, this may be NIL.

Availability Available in Mac OS X v10.3 and later. referenceFile - (NSString *)referenceFile

Discussion Returns the file name of the data reference associated with a QTDataReference object. For some QTDataReference objects, this name may be NIL.

Availability Available in Mac OS X v10.3 and later. referenceURL - (NSURL *)referenceURL

Discussion Returns the URL of the data reference associated with a QTDataReference object. For some QTDataReference objects, this URL may be NIL.

Availability Available in Mac OS X v10.3 and later. setDataRef: - (void)setDataRef:(Handle)dataRef

Discussion Sets the data reference data of a QTDataReference object to dataRef. The previous data reference data is disposed of.

Availability Available in Mac OS X v10.3 and later. setDataRefType: - (void)setDataRefType:(NSString *)type

Discussion Sets the data reference type of a QTDataReference object to type.

Availability Available in Mac OS X v10.3 and later.

Constants

The following constants are Cocoa identifiers for the basic data reference types. One of these types would be returned, for instance, by this method: - (NString *) dataRefType.

Constant Description

QTDataReferenceTypeFile The file type for a QTDataReference object. Available in Mac OS X v10.3 and later.

QTDataReferenceTypeHandle The handle type for a QTDataReference object. Available in Mac OS X v10.3 and later.

QTDataReferenceTypePointer The pointer type for a QTDataReference object. Available in Mac OS X v10.3 and later.

QTDataReferenceTypeResource The resource type for a QTDataReference object. Available in Mac OS X v10.3 and later.

QTDataReferenceTypeURL The URL type for a QTDataReference object. Available in Mac OS X v10.3 and later.

QTMedia Class Reference

Inherits from: NSObject Conforms to: NSObject (NSObject)

Framework QTKit.framework Declared in: QTKit/QTMedia.h

Availability: Available in Mac OS X v10.4 and later.

Class Description

Methods by Task

Creating a QTMedia

+ mediaWithQuickTimeMedia:error: (page 28)

Initializing a QTMedia

– initWithQuickTimeMedia:error: (page 29)

Getting media properties

– track (page 30)

– hasCharacteristic: (page 29)

– attributeForKey: (page 29)

– mediaAttributes (page 29)

Setting media properties

– setMediaAttributes: (page 30)

– setAttribute:forKey: (page 30)

Getting QTMedia primitives

– quickTimeMedia (page 30)

Class Methods

mediaWithQuickTimeMedia:error: + (id)mediaWithQuickTimeMedia:(Media)media error:(NSError **)errorPtr

Discussion Creates a QTMedia object with data from the QuickTime media media. If a QTMedia object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

Instance Methods

attributeForKey: - (id)attributeForKey:(NSString *)attributeKey

Discussion Returns the current value of the media attribute attributeKey. A list of supported media attributes and their acceptable values can be found in “Constants” (page 30).

Availability Available in Mac OS X v10.3 and later.

hasCharacteristic: - (BOOL)hasCharacteristic:(NSString *)characteristic

Discussion Returns YES if a QTMedia object has the specified characteristic. See the list of constants given in “Constants” (page 30) for the characteristics you can query.

Availability Available in Mac OS X v10.3 and later.

initWithQuickTimeMedia:error: - (id)initWithQuickTimeMedia:(Media)media error:(NSError **)errorPtr

Discussion Initializes a newly created QTMedia object with data from the QuickTime media media. If a QTMedia object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

mediaAttributes - (NSDictionary *)mediaAttributes

Discussion Returns a dictionary containing the current values of all defined media attributes. A list of supported media attributes and their acceptable values can be found in “Constants” (page 30).

Availability Available in Mac OS X v10.3 and later.

quickTimeMedia - (Media)quickTimeMedia

Discussion Returns the QuickTime media associated with a QTMedia object.

Availability Available in Mac OS X v10.3 and later.

setAttribute:forKey: - (void)setAttribute:(id)value forKey:(NSString *)attributeKey

Discussion Set the media attribute attributeKey to the value specified by the value parameter. A list of supported media attributes and their acceptable values can be found in “Constants” (page 30).

Availability Available in Mac OS X v10.3 and later.

setMediaAttributes: - (void)setMediaAttributes:(NSDictionary *)attributes

Discussion Set the media attributes using the key-value pairs specified in the dictionary attributes. A list of supported media attributes and their acceptable values can be found in “Constants” (page 30).

Availability Available in Mac OS X v10.3 and later.

track - (QTTrack *)track

Discussion Returns the QTTrack that contains a QTMedia object.

Availability Available in Mac OS X v10.3 and later.

Constants

The following constants specify the media attributes that you can get and set using the mediaAttributes and setMediaAttributes methods. To get or set a single attribute, use attributeForKey: or setAttribute:.

Note: The QTMediaTypeAttribute attribute indicates the type of media data contained in a QTMedia object. These constants are used to indicate media types, as shown in the portion of the table beginning with the QTMediaTypeVideo constant.

Constant Description

QTMediaCreation- The creation time of a QTMedia object; the value for this key is TimeAttribute of type NSDate. Available in Mac OS X v10.3 and later.

QTMediaDurationAttribute The duration of a QTMedia object; the value for this key is of type NSValue, interpreted as a QTTime. Available in Mac OS X v10.3 and later.

QTMediaModification- The modification time of a QTMedia object; the value for this key TimeAttribute is of type NSDate. Available in Mac OS X v10.3 and later.

QTMediaSampleCountAttribute The media sample count; the value for this key is of type NSNumber, interpreted as a long. Available in Mac OS X v10.3 and later.

QTMediaQualityAttribute The media quality; the value for this key is of type NSNumber, interpreted as a short. Available in Mac OS X v10.3 and later.

QTMediaTimeScaleAttribute The media time scale; the value for this key is of type NSNumber, interpreted as a long. Available in Mac OS X v10.3 and later.

QTMediaTypeAttribute The media type; the value for this key is of type NSString; see below for the values this attribute can return. Available in Mac OS X v10.3 and later.

QTMediaTypeVideo Video media. Available in Mac OS X v10.3 and later.

QTMediaTypeSound Sound media. Available in Mac OS X v10.3 and later.

QTMediaTypeText Text media. Available in Mac OS X v10.3 and later.

QTMediaTypeBase Base media. Available in Mac OS X v10.3 and later.

QTMediaTypeMPEG MPEG media Available in Mac OS X v10.3 and later.

QTMediaTypeMusic Music media Available in Mac OS X v10.3 and later.

Constant Description

QTMediaTypeTimeCode Timecode media. Available in Mac OS X v10.3 and later.

QTMediaTypeSprite Sprite media. Available in Mac OS X v10.3 and later.

QTMediaTypeFlash Flash media. Available in Mac OS X v10.3 and later.

QTMediaTypeMovie Movie media. Available in Mac OS X v10.3 and later.

QTMediaTypeTween Tween media. Available in Mac OS X v10.3 and later.

QTMediaType3D 3D media. Available in Mac OS X v10.3 and later.

QTMediaTypeSkin Skin media Available in Mac OS X v10.3 and later.

QTMediaTypeQTVR QuickTime VR media. Available in Mac OS X v10.3 and later.

QTMediaTypeHint Hint media. Available in Mac OS X v10.3 and later.

QTMediaTypeStream Stream media. Available in Mac OS X v10.3 and later.

Note: The constants beginning with QTMediaCharacteristic indicate the characteristics of a media that you can query using the hasCharacteristic method.

Constant Description

QTMediaCharacteristicVisual The media has video data. This is a BOOL. Available in Mac OS X v10.3 and later.

QTMediaCharacteristicAudio The media has audio data. This is a BOOL. Available in Mac OS X v10.3 and later.

QTMediaCharacteristicCan- The media can send visual data to another track. This is a SendVideo BOOL. Available in Mac OS X v10.3 and later.

QTMediaCharacteristic- The media has actions. This is a BOOL. ProvidesActions Available in Mac OS X v10.3 and later.

QTMediaCharacteristicNonLinear The media is non-linear. This is a BOOL. Available in Mac OS X v10.3 and later.

Constant Description

QTMediaCharacteristicCanStep The media can step. This is a BOOL. Available in Mac OS X v10.3 and later.

QTMediaCharacteristicHasNo- The media has no duration. This is a BOOL. Duration Available in Mac OS X v10.3 and later.

QTMediaCharacteristicHas- The media has skin data. This is a BOOL. SkinData Available in Mac OS X v10.3 and later.

QTMediaCharacteristic- Key events can be focused at the media. This is a BOOL. ProvidesKeyFocus Available in Mac OS X v10.3 and later.

QTMediaCharacteristicHas- The media has a video frame rate. This is a BOOL. VideoFrameRate Available in Mac OS X v10.3 and later.

QTMovie Class Reference

Inherits from: NSObject Conforms to: NSObject (NSCoding)

Framework QTKit.framework Declared in: QTKit/QTMovie.h

Availability: Available in Mac OS X v10.4 and later.

Class Description

The QTMovie class represents both a QuickTime movie and a movie controller. A movie is a collection of playable and editable media content. It describes the sources and types of the media in that collection and their spatial and temporal organization. These collections may be used for presentation (such as playback on the screen) or for the organization of media for processing (such as composition and transcoding to a different compression type). The collection may be as simple as a single file that plays at its natural size for its intrinsic duration, or it may be very complex (with multiple sources of content, rich composition rules, interactivity, and a variety of contingencies).

A QTMovie object can be initialized from a file, from a resource specified by a URL, from a block of memory, from a pasteboard, or from an existing QuickTime movie.

Once a QTMovie object has been initialized, it will typically be used in combination with a QTMovieView for playback.

An exception, QTMovieUneditableException, is raised whenever the client attempts to directly or indirectly edit a QTMovie object that is not currently set as editable (for instance, by calling appendSelectionFromMovie: on an uneditable movie).

Methods by Task

Determining whether a movie can be initialized

+ canInitWithFile: (page 41)

+ canInitWithURL: (page 41)

+ canInitWithPasteboard: (page 41)

+ canInitWithDataReference: (page 41)

– initWithPasteboard:error: (page 53)

Getting a list of supported file types

+ movieFileTypes: (page 42)

+ movieUnfilteredFileTypes (page 43)

+ movieUnfilteredPasteboardTypes (page 43)

Creating a QTMovie

+ movie (page 41)

+ movieNamed:error: (page 42)

+ movieWithData:error: (page 45)

+ movieWithURL:error: (page 46)

+ movieWithPasteboard:error: (page 46)

+ movieWithFile:error: (page 45)

+ movieWithDataReference:error: (page 45)

+ movieWithQuickTimeMovie:disposeWhenDone:error: (page 46)

+ movieWithAttributes:error: (page 43)

Controlling movie playback

– play (page 55)

– stop (page 60)

– setCurrentTime: (page 58)

– gotoBeginning (page 49)

– gotoEnd (page 49)

– gotoNextSelectionPoint (page 50)

– gotoPreviousSelectionPoint (page 50)

– gotoPosterTime (page 50)

– stepBackward (page 59)

– stepForward (page 59)

Initializing a QTMovie

– initWithFile:error: (page 52)

– initWithURL:error: (page 54)

– initWithData:error: (page 52)

– initWithDataReference:error: (page 52)

– initWithMovie:timeRange:error: (page 53)

– initWithQuickTimeMovie:disposeWhenDone:error: (page 53)

– initWithAttributes:error: (page 50)

Inspecting movie properties

– duration (page 49)

– currentTime (page 48)

– rate (page 56)

– volume (page 60)

– muted (page 55)

– movieWithTimeRange:error: (page 55)

– attributeForKey: (page 47)

– movieAttributes (page 54)

Setting QTMovie properties

– setRate: (page 59)

– setVolume: (page 59)

– setMuted: (page 58)

Setting movie attributes

– setAttribute:forKey: (page 58)

– setMovieAttributes: (page 58)

Getting and setting selection times

– selectionStart (page 57)

– selectionEnd (page 57)

– selectionDuration (page 57)

– setSelection: (page 59)

Getting movie tracks

– tracks (page 60)

– tracksOfMediaType: (page 60)

Getting movie images

– posterImage (page 56)

– currentFrameImage (page 48)

– frameImageAtTime: (page 49)

Storing movie data

– movieFormatRepresentation (page 55)

– writeToFile:withAttributes: (page 61)

Editing a movie

– replaceSelectionWithSelectionFromMovie: (page 57)

– appendSelectionFromMovie: (page 47)

– insertSegmentOfMovie:timeRange:atTime: (page 54)

– insertSegmentOfMovie:fromRange:scaledToRange: (page 54)

– insertEmptySegmentAt: (page 54)

– deleteSegment: (page 48)

– scaleSegment:newDuration: (page 57)

– addImage:forDuration:withAttributes: (page 47)

Saving a movie

– canUpdateMovieFile (page 47)

– updateMovieFile (page 60)

Getting QTMovie primitives

– quickTimeMovie (page 56)

– quickTimeMovieController (page 56)

Getting and setting QTMovie delegates

– delegate (page 48)

– setDelegate: (page 58)

Class Methods

canInitWithDataReference: + (BOOL)canInitWithDataReference:(QTDataReference*)dataReference

Discussion Returns YES if the specified data reference can be used to initialize a QTMovie object.

Availability Available in Mac OS X v10.3 and later.

canInitWithFile: + (BOOL)canInitWithFile:(NSString *)fileName

Discussion Returns YES if the contents of the specified file can be used to initialize a QTMovie object.

Availability Available in Mac OS X v10.3 and later.

canInitWithPasteboard: + (BOOL)canInitWithPasteboard:(NSPasteboard *)pasteboard

Discussion Returns YES if the contents of the specified pasteboard can be used to initialize a QTMovie object.

Availability Available in Mac OS X v10.3 and later.

canInitWithURL: + (BOOL)canInitWithURL:(NSURL *)url

Discussion Returns YES if the contents of the specified URL can be used to initialize a QTMovie object.

Availability Available in Mac OS X v10.3 and later.

movie + (id)movie

Discussion Creates an empty QTMovie object.

Availability Available in Mac OS X v10.3 and later.

movieFileTypes: + (NSArray *)movieFileTypes:(QTMovieTypeOptions)types

Discussion Returns an array of file types that can be opened as QuickTime movies. Passing zero as the options parameter returns an array of all the common file types that QuickTime can open in place on the current system. This array includes the file type .mov and .mqv, and any files types that can be opened using a movie importer that does not need to write data into a new file while performing the import. This array excludes any file types for still images and any file types that require an aggressive movie importer (for instance, the movie importer for text files). The following values can be used to include some or all of the file types that are normally excluded:

enum { QTIncludeStillImageTypes = 1 << 0, QTIncludeTranslatableTypes = 1 << 1, QTIncludeAggressiveTypes = 1 << 2, QTIncludeCommonTypes = 0, QTIncludeAllTypes = 0xffff } QTMovieFileTypeOptions;

Constants Description

QTIncludeStillImageTypes This value adds to the array all file types for still images that can be opened using a graphics importer.

QTInclude- This value adds to the array all file types for files that can be opened TranslatableTypes using a movie importer but for which a new file must be created.

QTIncludeAggressiveTypes This value adds to the array all file types for files that can be opened using a movie importer but that are not commonly used in connection with movies (for instance, text or HTML files).

QTIncludeCommonTypes This value adds to the array all common file types that QuickTime can open in place on the current system.

QTIncludeAllTypes This value adds to the array all file types that QuickTime can open on the current system, using any available movie or graphics importer.

Availability Available in Mac OS X v10.3 and later.

movieNamed:error: + (id)movieNamed:(NSString *)name error:(NSError **)errorPtr

Discussion Creates a QTMovie object initialized with the data from the QuickTime movie of the specified name in the application’s bundle. If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later. movieUnfilteredFileTypes + (NSArray *)movieUnfilteredFileTypes

Discussion Returns an array of file types that can be used to initialize a QTMovie object.

Availability Available in Mac OS X v10.3 and later. movieUnfilteredPasteboardTypes + (NSArray *)movieUnfilteredPasteboardTypes

Discussion Returns an array of pasteboard types that can be used to initialize a QTMovie object.

Availability Available in Mac OS X v10.3 and later. movieWithAttributes:error: + (id)movieWithAttributes:(NSDictionary *)attributes error:(NSError **)errorPtr

Discussion Creates a QTMovie object initialized with the attributes specified in attributes. If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

A new QTMovie object is created using the specified attributes. There are three types of attributes that can be included in this dictionary:

1. attributes that specify the location of the movie data

2. attributes that specify how the movie is to be instantiated

3. attributes that specify playback characteristics of the movie or other properties of the QTMovie object

The following is a list of the keys that specify the location of the movie data; at least one of these must occur in the dictionary. If more than one occurs, the first one in the dictionary is used.

Attribute Description

QTMovieFileNameAttribute The file name string of a QTMovie object; the value for this key is of type NSString.

QTMovieURLAttribute The URL of a QTMovie object; the value for this key is of type NSURL.

QTMovieDataReferenceAttribute The data reference of a QTMovie object; the value for this key is of type QTDataReference.

QTMoviePasteboardAttribute The pasteboard of a QTMovie object; the value for this key is of type NSPasteboard.

QTMovieDataAttribute The data of a QTMovie object; the value for this key is of type NSData.

The following is a list of the keys that specify movie instantiation options; none of these keys is required. If a key is missing, the specified default value is used.

Attribute Description

QTMovieFileOffsetAttribute The file offset of a QTMovie. The value for this key is of type NSNumber, which is interpreted as a long long. The default is 0.

QTMovieResolveData- The resolved data reference of a QTMovie. The value for this key RefsAttribute is of type NSNumber, which is interpreted as a BOOL. Default: YES.

QTMovieAskUnresolved- The asked unresolved data reference of a QTMovie. The value for DataRefsAttribute this key is of type NSNumber, which is interpreted as a BOOL. Default: YES.

QTMovieOpenAsyncOKAttribute The opened synchronization of a QTMovie. The value for this key is of type NSNumber, which is interpreted as a BOOL. Default: YES.

The following is a list of the new keys that specify movie playback characteristics or other properties of the QTMovie object; most other existing movie attributes can be included as well.

Attribute Description

QTMovieAuto- The auto-alternate of a QTMovie object. The value for this key is AlternatesAttribute of type NSNumber, interpreted as a BOOL.

QTMovieIsActiveAttribute The active setting; the value for this key is of type NSNumber, interpreted as a BOOL.

QTMovieDontInteract- When set in a dictionary passed to movieWithAttributes or WithUserAttribute initWithAttributes, this prevents QuickTime from interacting with the user during movie initialization. The value for this key is of type NSNumber, interpreted as a BOOL.

Attribute Description

QTMovieDelegateAttribute The delegate for a QTMovie object. The value for this key is of type NSObject.

Availability Available in Mac OS X v10.3 and later. movieWithData:error: + (id)movieWithData:(NSData *)data error:(NSError **)errorPtr

Discussion Creates a QTMovie object initialized with the data specified by data.

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later. movieWithDataReference:error: + (id)movieWithDataReference:(QTDataReference *)dataReference error:(NSError **)errorPtr

Discussion Creates a QTMovie object intitalized with the data specified by the data reference dataReference.

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later. movieWithFile:error: + (id)movieWithFile:(NSString *)fileName error:(NSError **)errorPtr

Discussion Creates a QTMovie object initialized with the data in the file specified by the name fileName. The fileName is assumed to be a full path name for a file.

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

movieWithPasteboard:error: + (id)movieWithPasteboard:(NSPasteboard *)pasteboard error:(NSError **)errorPtr

Discussion Creates a QTMovie object initialized with the contents of the pasteboard specified by pasteboard. These contents can be a QuickTime movie (of type Movie), a file path, or data of type QTMoviePasteboardType.

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

movieWithQuickTimeMovie:disposeWhenDone:error: + (id)movieWithQuickTimeMovie:(Movie)movie disposeWhenDone:(BOOL)dispose error:(NSError **)errorPtr

Discussion Creates a QTMovie object initialized with the data from an existing QuickTime movie movie. The dispose parameter (a BOOL) indicates whether the QTKit should call DisposeMovie on the specified movie when the QTMovie object is deallocated. Passing YES effectively transfers “ownership” of the Movie to the QTKit. (Note that most applications will probably want to pass YES; passing NO means that the application wants to call DisposeMovie itself, perhaps so that it can operate on a Movie after it has been disassociated with a QTMovie object.)

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Note that command-line tools that pass NO for the disposeWhenDone parameter must make sure to release the active autorelease pool before calling DisposeMovie on the specified QuickTime movie. Failure to do this may result in a crash. Tools that need to call DisposeMovie before releasing the main autorelease pool can create another autorelease pool associated with the movie.

Availability Available in Mac OS X v10.3 and later.

movieWithURL:error: + (id)movieWithURL:(NSURL *)url error:(NSError **)errorPtr

Discussion Creates a QTMovie object initialized with the data in the URL specified by url.

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

Instance Methods

addImage:forDuration:withAttributes: - (void)addImage:(NSImage *)image forDuration:(QTTime)duration withAttributes:(NSDictionary *)attributes

Discussion Adds an image for the specified duration to the receiver, using attributes specified in the attributes dictionary. Keys in the dictionary can be QTAddImageCodecType to select a codec type and QTAddImageCodecQuality to select a quality. Qualities are expected to be specified as NSNumbers, using the codec values like codecNormalQuality. (See ImageCompression.h for the complete list.)

Availability Available in Mac OS X v10.3 and later.

appendSelectionFromMovie: - (void)appendSelectionFromMovie:(id)movie

Discussion Appends to a QTMovie the current selection in movie. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

attributeForKey: - (id)attributeForKey:(NSString *)attributeKey

Discussion Returns the current value of the movie attribute attributeKey. A list of supported movie attributes and their acceptable values can be found in the “Constants” (page 63) section.

Availability Available in Mac OS X v10.3 and later.

canUpdateMovieFile - (BOOL)canUpdateMovieFile

Discussion Indicates whether a movie file can be updated with changes made to the movie object. This method returns NO if any of the following conditions are true:

1. The movie is not associated with a file.

2. The movie is not savable (has 'nsav' user data set to 1).

3. The movie file is not writable.

4. The movie file does not contain a movie atom (indicating that the movie was imported from a non-movie format).

Otherwise, the method returns YES.

Using this method, an application can check first to see if the movie file can be updated; if not, it can prompt the user for a new name and location of a file in which to save the updated movie.

Availability Available in Mac OS X v10.3 and later.

currentFrameImage - (NSImage *)currentFrameImage

Discussion Returns an NSImage for the frame at the current time in a QTMovie.

Availability Available in Mac OS X v10.3 and later.

See Also – frameImageAtTime: (page 49) – posterImage (page 56)

currentTime - (QTTime)currentTime

Discussion Returns the current time of a QTMovie object as a structure of type QTTime.

Availability Available in Mac OS X v10.3 and later.

delegate - (id)delegate

Discussion Returns the delegate of a QTMovie object.

Availability Available in Mac OS X v10.3 and later.

deleteSegment: - (void)deleteSegment:(QTTimeRange)segment

Discussion Deletes from a QTMovie the segment delimited by segment. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later. duration - (QTTime)duration

Discussion Returns the duration of a QTMovie object as a structure of type QTTime.

Availability Available in Mac OS X v10.3 and later. frameImageAtTime: - (NSImage *)frameImageAtTime:(QTTime)time

Discussion Returns an NSImage for the frame at the time time in a QTMovie.

Availability Available in Mac OS X v10.3 and later.

See Also – currentFrameImage (page 48) – posterImage (page 56) gotoBeginning - (void)gotoBeginning

Discussion Repositions the play position to the beginning of the movie. If the movie is playing, the movie continues playing from the new position.

Availability Available in Mac OS X v10.3 and later. gotoEnd - (void)gotoEnd

Discussion Repositions the play position to the end of the movie. If the movie is playing in one of the looping modes, the movie continues playing accordingly; otherwise, play stops.

Availability Available in Mac OS X v10.3 and later.

gotoNextSelectionPoint - (void)gotoNextSelectionPoint

Discussion Repositions the movie to the next selection point.

Availability Available in Mac OS X v10.3 and later.

gotoPosterTime - (void)gotoPosterTime

Discussion Repositions the play position to the movie’s poster time. If no poster time is defined, the movie jumps to the beginning. If the movie is playing, the movie continues playing from the new position.

Availability Available in Mac OS X v10.3 and later.

gotoPreviousSelectionPoint - (void)gotoPreviousSelectionPoint

Discussion Repositions the movie to the previous selection point.

Availability Available in Mac OS X v10.3 and later.

initWithAttributes:error: - (id)initWithAttributes:(NSDictionary *)attributes error:(NSError **)errorPtr

Discussion Initializes a QTMovie object with the attributes specified in attributes.

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

A new QTMovie object is created using the specified attributes. There are three types of attributes that can be included in this dictionary:

1. attributes that specify the location of the movie data

2. attributes that specify how the movie is to be instantiated

3. attributes that specify playback characteristics of the movie or other properties of the QTMovie object

The following is a list of the keys that specify the location of the movie data; at least one of these must occur in the dictionary. If more than one occurs, the first one in the dictionary is used.

Attribute Description

QTMovieFileNameAttribute The file name string of a QTMovie object; the value for this key is of type NSString.

QTMovieURLAttribute The URL of a QTMovie object; the value for this key is of type NSURL.

QTMovieDataReferenceAttribute The data reference of a QTMovie object; the value for this key is of type QTDataReference.

QTMoviePasteboardAttribute The pasteboard of a QTMovie object; the value for this key is of type NSPasteboard.

QTMovieDataAttribute The data of a QTMovie object; the value for this key is of type NSData.

The following is a list of the keys that specify movie instantiation options; none of these keys is required. If a key is missing, the specified default value is used.

Attribute Description

QTMovieFileOffsetAttribute The file offset of a QTMovie. The value for this key is of type NSNumber, which is interpreted as a long long. The default is 0.

QTMovieResolveData- The resolved data reference of a QTMovie. The value for this key RefsAttribute is of type NSNumber, which is interpreted as a BOOL. Default: YES.

QTMovieAskUnresolved- The asked unresolved data reference of a QTMovie. The value for DataRefsAttribute this key is of type NSNumber, which is interpreted as a BOOL. Default: YES.

QTMovieOpenAsyncOKAttribute The opened synchronization of a QTMovie. The value for this key is of type NSNumber, which is interpreted as a BOOL. Default: YES.

The following is a list of the new keys that specify movie playback characteristics or other properties of the QTMovie object; most other existing movie attributes can be included as well.

Attribute Description

QTMovieAuto- The auto-alternate of a QTMovie object. The value for this key is AlternatesAttribute of type NSNumber, interpreted as a BOOL.

QTMovieIsActiveAttribute The active setting; the value for this key is of type NSNumber, interpreted as a BOOL.

Attribute Description

QTMovieDelegateAttribute The delegate for a QTMovie object. The value for this key is of type NSObject.

Availability Available in Mac OS X v10.3 and later.

initWithData:error: - (id)initWithData:(NSData *)data error:(NSError **)errorPtr

Discussion Initializes a QTMovie object with the data specified by data. If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

initWithDataReference:error: - (id)initWithDataReference:(QTDataReference *)dataReference error:(NSError **)errorPtr

Discussion Initializes a QTMovie object with the data reference specified by dataReference. If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

initWithFile:error: - (id)initWithFile:(NSString *)fileName error:(NSError **)errorPtr

Discussion Initializes a QTMovie object with the data in the file specified by the name fileName. The fileName is assumed to be a full path name for a file. If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Note that alias files should not be passed into this method; the client application is responsible for resolving aliases before handing them to QTKit methods.

Availability Available in Mac OS X v10.3 and later. initWithMovie:timeRange:error: - (id)initWithMovie:(QTMovie *)movie timeRange:(QTTimeRange)range error:(NSError **)errorPtr

Discussion Initializes a QTMovie object with some or all of the data from an existing QTMovie object movie. The section of data used is delimited by the range range. If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Note that alias files should not be passed into this method; the client application is responsible for resolving aliases before handing them to QTKit methods.

Availability Available in Mac OS X v10.3 and later. initWithPasteboard:error: - (id)initWithPasteboard:(NSPasteboard *)pasteboard error:(NSError **)errorPtr

Discussion Initializes a QTMovie object with the contents of the pasteboard specified by pasteboard. These contents can be a QuickTime movie (of type Movie), a file path, or data of type QTMoviePasteBoardType. If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later. initWithQuickTimeMovie:disposeWhenDone:error: - (id)initWithQuickTimeMovie:(Movie)movie disposeWhenDone:(BOOL)dispose error:(NSError **)errorPtr

Discussion Initializes a QTMovie object with the data from an existing QuickTime movie movie. The dispose parameter (a BOOL) indicates whether the QTKit should call DisposeMovie on the specified movie when the QTMovie object is deallocated. Passing YES effectively transfers “ownership” of the Movie to the QTKit. (Note that most applications will probably want to pass YES; passing NO means that the application wants to call DisposeMovie itself, perhaps so that it can operate on a Movie after it has been disassociated from a QTMovie object.)

If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

initWithURL:error: - (id)initWithURL:(NSURL *)url error:(NSError **)errorPtr

Discussion Initializes a QTMovie object with the data in the URL specified by url. If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

insertEmptySegmentAt: - (void)insertEmptySegmentAt:(QTTimeRange)range

Discussion Inserts into a QTMovie an empty segment delimited by the range range. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

insertSegmentOfMovie:fromRange:scaledToRange: - (void)insertSegmentOfMovie:(QTMovie *)movie fromRange:(QTTimeRange)srcRange scaledToRange:(QTTimeRange)dstRange

Discussion Inserts the specified segment from the movie into the receiver, scaled to the range dstRange. This is essentially an Add Scaled operation on a movie. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

insertSegmentOfMovie:timeRange:atTime: - (void)insertSegmentOfMovie:(QTMovie *)movie timeRange:(QTTimeRange)range atTime:(QTTime)time

Discussion Inserts into a QTMovie at time time the selection in movie delimited by the time range range. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

movieAttributes - (NSDictionary *)movieAttributes

Discussion Returns a dictionary containing the current values of all defined movie attributes. A list of supported movie attributes and their acceptable values can be found in the “Constants” (page 63) section.

Availability Available in Mac OS X v10.3 and later. movieFormatRepresentation - (NSData *)movieFormatRepresentation

Discussion Returns the movie’s data in an NSData object.

Availability Available in Mac OS X v10.3 and later.

See Also – writeToFile:withAttributes: (page 61) movieWithTimeRange:error: - (QTMovie *)movieWithTimeRange:(QTTimeRange)range error:(NSError **)errorPtr

Discussion Returns a QTMovie object whose data is the data in the specified time range. If a QTMovie object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later. muted - (BOOL)muted

Discussion Returns the movie’s mute setting.

Availability Available in Mac OS X v10.3 and later. play - (void)play

Discussion Plays the movie.

Availability Available in Mac OS X v10.3 and later.

posterImage - (NSImage *)posterImage

Discussion Returns an NSImage for the poster frame of a QTMovie.

Availability Available in Mac OS X v10.3 and later.

See Also – currentFrameImage (page 48), – frameImageAtTime: (page 49)

quickTimeMovie - (Movie)quickTimeMovie

Discussion Returns the QuickTime movie associated with a QTMovie object.

Availability Available in Mac OS X v10.3 and later.

See Also – quickTimeMovieController (page 56)

quickTimeMovieController - (MovieController)quickTimeMovieController

Discussion Returns the QuickTime movie controller associated with a QTMovie object.

Availability Available in Mac OS X v10.3 and later.

See Also – quickTimeMovie (page 56)

rate - (float)rate

Discussion Returns the current rate of a QTMovie object.

Availability Available in Mac OS X v10.3 and later.

replaceSelectionWithSelectionFromMovie: - (void)replaceSelectionWithSelectionFromMovie:(id)movie

Discussion Replaces the current selection in a QTMovie with the current selection in movie. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later. scaleSegment:newDuration: - (void)scaleSegment:(QTTimeRange)segment newDuration:(QTTime)newDuration

Discussion Scales the QTMovie segment delimited by the segment segment so that it will have the new duration newDuration. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later. selectionDuration - (QTTime)selectionDuration

Discussion Returns the duration of the movie’s current selection as a QTTime structure.

Availability Available in Mac OS X v10.3 and later. selectionEnd - (QTTime)selectionEnd

Discussion Returns the end point of the movie’s current selection as a QTTime structure.

Availability Available in Mac OS X v10.3 and later. selectionStart - (QTTime)selectionStart

Discussion Returns the start time of the movie’s current selection as a QTTime structure.

Availability Available in Mac OS X v10.3 and later.

setAttribute:forKey: - (void)setAttribute:(id)value forKey:(NS String *)attributeKey

Discussion Set the movie attribute attributeKey to the value specified by the value parameter. A list of supported movie attributes and their acceptable values can be found in the “Constants” (page 63) section.

Availability Available in Mac OS X v10.3 and later.

setCurrentTime: - (void)setCurrentTime:(QTTime)time

Discussion Sets the movie’s current time setting to time.

Availability Available in Mac OS X v10.3 and later.

setDelegate: - (void)setDelegate:(id)delegate

Discussion Sets the movie’s delegate to delegate.

Availability Available in Mac OS X v10.3 and later.

setMovieAttributes: - (void)setMovieAttributes:(NSDictionary *)attributes

Discussion Set the movie attributes using the key-value pairs specified in the dictionary attributes. A list of supported movie attributes and their acceptable values can be found in the “Constants” (page 63) section.

Availability Available in Mac OS X v10.3 and later.

setMuted: - (void)setMuted:(BOOL)mute

Discussion Sets the movie’s mute setting to mute. Note that this does not affect the volume.

Availability Available in Mac OS X v10.3 and later. setRate: - (void)setRate:(float)rate

Discussion Sets the movie’s rate to rate. For instance, 0.0 is stop, 1.0 is playback at normal speed, 2.0 is twice normal speed, and so on.

Availability Available in Mac OS X v10.3 and later. setSelection: - (void)setSelection:(QTTimeRange)selection

Discussion Sets the movie’s selection to selection.

Availability Available in Mac OS X v10.3 and later. setVolume: - (void)setVolume:(float)volume

Discussion Sets the movie’s volume to volume. Note that this does not affect the movie’s stored settings.

Availability Available in Mac OS X v10.3 and later. stepBackward - (void)stepBackward

Discussion Sets the movie backward a single frame.

Availability Available in Mac OS X v10.3 and later. stepForward - (void)stepForward

Discussion Sets the movie forward a single frame.

Availability Available in Mac OS X v10.3 and later.

stop - (void)stop

Discussion Stops the movie playing.

Availability Available in Mac OS X v10.3 and later.

tracks -(NSArray *)tracks

Discussion Returns an array of QTTrack objects associated with the receiver.

Availability Available in Mac OS X v10.3 and later.

tracksOfMediaType: -(NSArray *)tracksOfMediaType:(NSString *)type

Discussion Returns an array of tracks with the specified media type.

Availability Available in Mac OS X v10.3 and later.

updateMovieFile - (BOOL)updateMovieFile

Discussion Updates the movie file of a QTMovie. Returns YES if the update succeeds and NO otherwise.

Availability Available in Mac OS X v10.3 and later.

volume - (float)volume

Discussion Returns the movie’s volume as a scalar value of type float. The valid range is 0.0 to 1.0.

Availability Available in Mac OS X v10.3 and later.

writeToFile:withAttributes: -(BOOL)writeToFile:(NSString *)fileName withAttributes:(NSDictionary *)attributes

Discussion Creates a new movie file of the specified name and having the specified attributes. If the dictionary attributes contains an object whose key is QTMovieFlatten, then the movie is flattened into the specified file. If the dictionary attributes contains an object whose key is QTMovieExport, then the movie is exported into the specified file using a movie exporter whose type is specified by the value of the key QTMovieExportType. The value associated with the QTMovieExportSettings key should be an object of type NSData that contains an atom container of movie export settings.

Availability Available in Mac OS X v10.3 and later.

See Also – movieFormatRepresentation (page 55)

Delegate Methods by Task

Getting an external movie

– externalMovie: (page 62)

Handling movie processing

– movieShouldTask: (page 63)

Determining whether a movie should continue operation

– movie:shouldContinueOperation:withPhase:atPercent:withAttributes: (page 62)

Handling mcActions linked to URLs

– movie:linkToURL: (page 62)

Delegate Methods

externalMovie: - (QTMovie *)externalMovie:(NSDictionary *)dictionary

Discussion This method is called, if implemented by a QTMovie delegate object, when an external movie needs to be found (usually for a wired action targeted at an external movie). The keys for the dictionary in this delegate method are: QTMovieTargetIDNotificationParameter and QTMovieTargetNameNotificationParameter. The QTMovieTargetIDNotificationParameter key indicates that the delegate should return a QTMovie object that has the specified movie ID. The QTMovieTargetNameNotificationParameter key indicates that the delegate should return a QTMovie object that has the specified movie name.

Availability Available in Mac OS X v10.3 and later.

movie:linkToURL: - (BOOL)movie:(QTMovie *)movie linkToURL:(NSURL *)url

Discussion This delegate method is called to handle the mcAction mcActionLinkToURL. Most applications will not need to install a delegate to handle this.

Availability Available in Mac OS X v10.3 and later.

movie:shouldContinueOperation:withPhase:atPercent:withAttributes: - (BOOL)movie:(QTMovie *)movie shouldContinueOperation:(NSString *)op withPhase:(QTMovieOperationPhase)phase atPercent:(NSNumber *)percent withAttributes:(NSDictionary *)attributes

Discussion A delegate can implement this method. If implemented, this method is called periodically during lengthy operations (such as exporting a movie). The op string is a localized string that indicates what the operation is. The phase indicates whether the operation is just beginning, ending, or is at a certain percentage of completion. If the phase is QTMovieOperationUpdatePercentPhase, then the percent parameter indicates the percentage of the operation completed. The attributes dictionary may be NIL; if not NIL, it is the same dictionary passed to a QTMovie method that caused the lengthy operation (for example, the attributes dictionary passed to writeToFile). The constants for this method are defined as follows:

typedef enum { QTMovieOperationBeginPhase = movieProgressOpen, QTMovieOperationUpdatePercentPhase = movieProgressUpdatePercent, QTMovieOperationEndPhase = movieProgressClose }

Availability Available in Mac OS X v10.3 and later.

movieShouldTask: - (BOOL)movieShouldTask:(id)movie

Discussion If a QTMovie object has a delegate and that delegate implements this method, that method will be called before QTKit performs the standard idle processing on a movie. The delegate can cancel that normal processing by returning NO.

Availability Available in Mac OS X v10.3 and later.

Constants

The following constants specify the movie attributes that you can get and set using the movieAttributes and setMovieAttributes methods. To get or set a single attribute, use attributeForKey or setAttribute.

Constant Description

QTMovieActiveSegment- The active segment of a QTMovie object; the value for this key is of Attribute type NSValue, interpreted as a QTTimeRange structure. Available in Mac OS X v10.3 and later.

QTMovieAuto- The auto-alternate state of a QTMovie object. The value for this key is AlternatesAttribute of type NSNumber, interpreted as a BOOL. Available in Mac OS X v10.3 and later.

QTMovieCopyright- The copyright string of a QTMovie object; the value for this key is of Attribute type NSString. Available in Mac OS X v10.3 and later.

QTMovieCreation- The creation time of a QTMovie object; the value for this key is of type TimeAttribute NSDate. Available in Mac OS X v10.3 and later.

QTMovieCurrent- The current size of a QTMovie object; the value for this key is of type SizeAttribute NSValue, interpreted as an NSSize structure. Available in Mac OS X v10.3 and later.

Constant Description

QTMovieCurrent- The current time of a QTMovie object; the value for this key is of type TimeAttribute NSValue, interpreted as a QTTime structure. Available in Mac OS X v10.3 and later.

QTMovieDataSize- The data size of a QTMovie. The value for this key is of type NSNumber, Attribute which is interpreted as a long long. Available in Mac OS X v10.3 and later.

QTMovieDelegate- The delegate for a QTMovie object. The value for this key is of type Attribute NSObject. Available in Mac OS X v10.3 and later.

QTMovieDisplay- The display name of a QTMovie object. A display name is stored as NameAttribute user data in a movie file and hence may differ from the base name of the movie’s filename or URL. The value for this key is of type NSString. Available in Mac OS X v10.3 and later.

QTMovieDuration- The duration of a QTMovie object; the value for this key is of type Attribute NSValue, interpreted as a QTTime structure. Available in Mac OS X v10.3 and later.

QTMovieEditable- The editable setting; the value for this key is of type NSNumber, Attribute interpreted as a BOOL. This value is YES if the movie can be edited. Available in Mac OS X v10.3 and later.

QTMovieFileName- The file name string of a QTMovie object; the value for this key is of Attribute type NSString. Available in Mac OS X v10.3 and later.

QTMovieHasAudio- The audio data setting; the value for this key is of type NSNumber, Attribute interpreted as a BOOL. This value is YES if the movie contains audio data. Available in Mac OS X v10.3 and later.

QTMovieHasDuration- The duration setting; the value for this key is of type NSNumber, Attribute interpreted as a BOOL. This value is YES if the movie has a duration. (Some types of movies, for instance QuickTime VR movies, have no duration.) Available in Mac OS X v10.3 and later.

QTMovieHasVideo- The video data setting; the value for this key is of type NSNumber, Attribute interpreted as a BOOL. This value is YES if the movie contains video data. Available in Mac OS X v10.3 and later.

Constant Description

QTMovieIsActive- The active setting; the value for this key is of type NSNumber, interpreted Attribute as a BOOL. Available in Mac OS X v10.3 and later.

QTMovieIsInteractive- The interactive setting; the value for this key is of type NSNumber, Attribute interpreted as a BOOL. This value is YES if the movie is interactive. Available in Mac OS X v10.3 and later.

QTMovieIsLinear- The linear setting; the value for this key is of type NSNumber, interpreted Attribute as a BOOL. This value is YES if the movie is linear, as opposed to a non-linear QuickTime VR movie. Available in Mac OS X v10.3 and later.

QTMovieIsSteppable- The steppable setting; the value for this key is of type NSNumber, Attribute interpreted as a BOOL. This value is YES if the movie can step from frame to frame. Available in Mac OS X v10.3 and later.

QTMovieLoadState- The load state value; the value for this key is of type NSNumber, Attribute interpreted as a long. Available in Mac OS X v10.3 and later.

QTMovieLoopsAttribute The looping setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie is set to loop. Available in Mac OS X v10.3 and later.

QTMovieLoopsBackAnd- The palindrome looping setting; the value for this key is of type ForthAttribute NSNumber, interpreted as a BOOL. This value is YES if the movie is set to loop back and forth. Note that QTMovieLoopsAttribute and QTMovieLoopsBackAndForthAttribute are independent and indeed exclusive. QTMovieLoopsAttribute is used to get and set the state of normal looping; QTMovieLoopsBackAndForthAttribute is used to get and set the state of palindrome looping. Available in Mac OS X v10.3 and later.

QTMovieModification- The modification time of a QTMovie object; the value for this key is of TimeAttribute type NSDate. Available in Mac OS X v10.3 and later.

QTMovieMutedAttribute The mute setting; the value for this key is of type NSNumber, interpreted as a BOOL. This value is YES if the movie volume is muted. Available in Mac OS X v10.3 and later.

QTMovieNatural- The natural size of a QTMovie object; the value for this key is of type SizeAttribute NSValue, interpreted as an NSSize structure. Available in Mac OS X v10.3 and later.

QTMoviePlaysAll- The play-all-frames setting; the value for this key is of type NSNumber, FramesAttribute interpreted as a BOOL. This value is YES if the movie will play all frames. Available in Mac OS X v10.3 and later.

Constant Description

QTMoviePlays- The play-selection setting; the value for this key is of type NSNumber, SelectionOnlyAttribute interpreted as a BOOL. This value is YES if the movie will play only the current selection. Available in Mac OS X v10.3 and later.

QTMoviePosterTime- The movie poster time of a QTMovie object; the value for this key is Attribute of type NSValue, interpreted as a QTTime structure. Available in Mac OS X v10.3 and later.

QTMoviePreferred- The preferred mute setting; the value for this key is of type NSNumber, MutedAttribute interpreted as a BOOL. This value is YES if the movie preferred mute setting is muted. Available in Mac OS X v10.3 and later.

QTMoviePreferred- The preferred rate; the value for this key is of type NSNumber, RateAttribute interpreted as a float. Available in Mac OS X v10.3 and later.

QTMoviePreferred- The preferred volume; the value for this key is of type NSNumber, VolumeAttribute interpreted as a float. Available in Mac OS X v10.3 and later.

QTMoviePreview- The preview mode setting; the value for this key is of type NSNumber, ModeAttribute interpreted as a BOOL. This value is YES if the movie is in preview mode. Available in Mac OS X v10.3 and later.

QTMoviePreviewRange- The preview range of a QTMovie object; the value for this key is of Attribute type NSValue, interpreted as a QTTimeRange structure. Available in Mac OS X v10.3 and later.

QTMovieRateAttribute The movie rate; the value for this key is of type NSNumber, interpreted as a float. Available in Mac OS X v10.3 and later.

QTMovieRateChanges- When the playback rate is not unity, audio must be resampled in order PreservePitchAttribute to play at the new rate. The default resampling affects the pitch of the audio (for example, playing at 2x speed raises the pitch by an octave, 1/2x lowers an octave). If this property is set on the Movie, an alternative algorithm is used, which alters the speed without changing the pitch. As this is more computationally expensive, this property may be silently ignored on some slow CPUs. Available in Mac OS X v10.3 and later.

QTMovieSelection- The selection range of a QTMovie object; the value for this key is of Attribute type NSValue, interpreted as a QTTimeRange structure. Available in Mac OS X v10.3 and later.

QTMovieTimeScale- The movie time scale; the value for this key is of type NSNumber, Attribute interpreted as a long. Available in Mac OS X v10.3 and later.

Constant Description

QTMovieURLAttribute The URL of a QTMovie object; the value for this key is of type NSURL. Available in Mac OS X v10.3 and later.

QTMovieVolumeAttribute The movie volume; the value for this key is of type NSNumber, interpreted as a float. Available in Mac OS X v10.3 and later.

The following constants specify items in dictionaries passed to QTMovie notifications and delegate methods.

Constant Description

QTMovieMessage- Used as a key in the userInfo dictionary passed to the NotificationParameter QTMovieMessageNotification notification to indicate the message. The associated value is an NSString. Available in Mac OS X v10.3 and later.

QTMovieRateDid- Used as a key in the userInfo dictionary passed to the ChangeNotification- QTMovieRateDidChangeNotification notification to indicate the Parameter new playback rate. The associated value is an NSNumber that holds a float. Available in Mac OS X v10.3 and later.

QTMovieStatusFlags- Used as a key in the userInfo dictionary passed to the NotificationParameter QTMovieStatusStringPostedNotification notification to indicate status flags. The associated value is an NSNumber that holds a long. Available in Mac OS X v10.3 and later.

QTMovieStatusCode- Used as a key in the userInfo dictionary passed to the NotificationParameter QTMovieStatusStringPostedNotification notification to indicate a status code (or error code). The associated value is an NSNumber that holds an int. Available in Mac OS X v10.3 and later.

QTMovieStatusString- Used as a key in the userInfo dictionary passed to the NotificationParameter QTMovieStatusStringPostedNotification notification to indicate a status string. Available in Mac OS X v10.3 and later.

QTMovieTarget- Used as a key in the dictionary passed to the externalMovie: IDNotificationParameter delegate method to indicate that the delegate should return a QTMovie object that has the movie ID specified by the key’s value. Available in Mac OS X v10.3 and later.

QTMovieTargetName- Used as a key in the dictionary passed to the externalMovie: NotificationParameter delegate method to indicate that the delegate should return a QTMovie object that has the movie name specified by the key’s value. Available in Mac OS X v10.3 and later.

The following constants are dictionary keys that you can use to specify movie attributes, using the writeToFile method.

Constant Description

QTMovieExport The movie export setting; the value for this key is of type NSNumber, interpreted as a BOOL. Available in Mac OS X v10.3 and later.

QTMovieExportType The movie export type; the value for this key is of type NSNumber, interpreted as a long. Available in Mac OS X v10.3 and later.

QTMovieFlatten The movie flatten setting; the value for this key is of type NSNumber, interpreted as a BOOL. Available in Mac OS X v10.3 and later.

QTMovieExportSettings Information to come. Available in Mac OS X v10.3 and later.

QTMovieExport- The export manufacturer value; the value for this key is of type Manufacturer NSNumber, interpreted as a long. Available in Mac OS X v10.3 and later.

The following constants are dictionary keys that you can use to specify movie attributes, using the addImage method.

Constant Description

QTAddImageCodecType The image codec string; the value for this key is of type NSString. Available in Mac OS X v10.3 and later.

QTAddImageCodecQuality The image codec value; the value for this key is of type NSNumber. Available in Mac OS X v10.3 and later.

The following constants are data locators that you can use to specify movie attributes, using the movieWithAttributes and initWithAttributes methods.

Constant Description

QTMovieDataReferenceAttribute The data reference of a QTMovie object. Available in Mac OS X v10.3 and later.

QTMoviePasteboardAttribute The pasteboard setting of a QTMovie object. Available in Mac OS X v10.3 and later.

QTMovieDataAttribute The data of a QTMovie object. Available in Mac OS X v10.3 and later.

The following constants are movie instantiation options that you can use to specify movie attributes, using the movieWithAttributes and initWithAttributes methods.

Constant Description

QTMovieFileOffsetAttribute The file offset value; the value for this key is of type NSNumber, interpreted as a long long. Available in Mac OS X v10.3 and later.

QTMovieResolveData- The resolved data reference setting; the value for this key is of RefAttribute type NSNumber, interpreted as a BOOL.

QTMovieAskUnresolved- The unresolved data reference setting; the value for this key is DataRefAttribute of type NSNumber, interpreted as a BOOL.

QTMovieOpenAsyncOKAttribute The open async setting; the value for this key is of type NSNumber, interpreted as a BOOL. Available in Mac OS X v10.3 and later.

Notifications

QTMovieChapterDidChangeNotification Sent when there is a change in the movie’s current chapter. This notification contains no information in the userInfo dictionary.

Availability Available in Mac OS X v10.3 and later.

QTMovieChapterListDidChangeNotification Sent when there is a change in the movie’s chapter list. This notification contains no information in the userInfo dictionary.

Availability Available in Mac OS X v10.3 and later.

QTMovieCloseWindowRequestNotification Sent when a request is made to close the movie’s window. This notification contains no information in the userInfo dictionary.

Availability Available in Mac OS X v10.3 and later.

QTMovieDidEndNotification Sent when the movie is “done” or at its end. This notification contains no userInfo parameters. It is equivalent to the standard player controller’s mcActionMovieFinished action.

Availability Available in Mac OS X v10.3 and later.

QTMovieEditabilityDidChangeNotification Sent when the editable state of a movie has changed.

Availability Available in Mac OS X v10.3 and later.

QTMovieEditedNotification Sent when a movie has been edited. This notification contains no userInfo dictionary.

Availability Available in Mac OS X v10.3 and later.

QTMovieEnterFullScreenRequestNotification Sent when a request is made to play back a movie in full screen mode. This notification contains no information in the userInfo dictionary.

Availability Available in Mac OS X v10.3 and later.

QTMovieExitFullScreenRequestNotification Sent when a request is made to play back a movie in normal windowed mode. This notification contains no information in the userInfo dictionary.

Availability Available in Mac OS X v10.3 and later.

QTMovieLoadStateDidChangeNotification Sent when the load state of a movie has changed.

Availability Available in Mac OS X v10.3 and later.

QTMovieLoopModeDidChangeNotification Sent when a change is made in a movie’s looping mode. This notification contains no information in the userInfo dictionary.

Availability Available in Mac OS X v10.3 and later.

QTMovieMessageStringPostedNotification Sent when a movie message has been received by the movie controller. Movie messages can be sent to an application by wired actions (for instance, a wired sprite) or by code that issues the mcActionShowMessageString movie controller action. The userInfo dictionary contains a single entry whose value is of type NSString, which is the movie message.

Availability Available in Mac OS X v10.3 and later.

QTMovieRateDidChangeNotification Sent when the rate of a movie has changed. The userInfo dictionary contains a single entry whose value is of type NSNumber that represents a float, which is the new rate.

Availability Available in Mac OS X v10.3 and later.

QTMovieSelectionDidChangeNotification Sent when the selection of a movie has changed. This notification contains no userInfo dictionary.

Availability Available in Mac OS X v10.3 and later.

QTMovieSizeDidChangeNotification Sent when the size of a movie has changed. This notification contains no userInfo dictionary.

Availability Available in Mac OS X v10.3 and later.

QTMovieStatusStringPostedNotification Status messages can be sent by QuickTime’s streaming components or by any code that wants to display a message in the movie controller bar status area. The userInfo dictionary contains a single entry whose value is of type NSString, which is the status message.

The following are keys (notification parameters) for userInfo items for the QTMovieStatusStringPostedNotification notification QTMovieStatusCodeNotificationParameter and QTMovieStatusStringNotificationParameter.

A status string notification can indicate an error (in which case QTMovieStatusCodeNotificationParameter will have a value), or it can contain a string (in which case QTMovieStatusStringNotificationParameter will have a value). For more information, see mcActionShowStatusString.

Availability Available in Mac OS X v10.3 and later.

QTMovieTimeDidChangeNotification Sent when the time in a movie has changed.

Availability Available in Mac OS X v10.3 and later.

QTMovieVolumeDidChangeNotification Sent when the volume of a movie has changed.

Availability Available in Mac OS X v10.3 and later.

QTMovieView Class Reference

Inherits from: NSView : NSResponder : NSObject Conforms to: NSCoding (NSResponder) NSObject (NSObject)

Framework QTKit.framework Declared in: QTKit/QTMovieView.h

Availability: Available in Mac OS X v10.4 and later.

Class Description

A QTMovieView is a subclass of NSView that can be used to display and control QuickTime movies. You normally use a QTMovieView in combination with a QTMovie object, which supplies the movie being displayed. A QTMovieView also supports editing operations on the movie.

The movie can be placed within an arbitrary bounding rectangle in the view’s coordinate system, and the remainder of the view can be filled with a fill color. The movie controller, if it is visible, can also be placed within an arbitrary bounding rectangle in the view’s coordinate system.

Adopted Protocols

NSMenuValidations - validateMenuItem:

NSUserInterfaceValidations - validateUserInterfaceItem

Methods by Task

Initializing the view

– initWithFrame: (page 79)

Getting view characteristics

– movie (page 79)

– isControllerVisible (page 79)

– isEditable (page 79)

– preservesAspectRatio (page 81)

– fillColor (page 77)

– movieBounds (page 79)

– movieControllerBounds (page 80)

– controllerBarHeight (page 76)

Setting view characteristics

– setMovie: (page 82)

– setControllerVisible: (page 81)

– setPreservesAspectRatio: (page 82)

– setShowsResizeIndicator: (page 83)

– setFillColor: (page 82)

– setEditable: (page 82)

– selectNone: (page 81)

Controlling movie playback

– play: (page 80)

– pause: (page 80)

– gotoBeginning: (page 77)

– gotoEnd: (page 78)

– gotoNextSelectionPoint: (page 78)

– gotoPreviousSelectionPoint: (page 78)

– gotoPosterFrame: (page 78)

– stepForward: (page 83)

– stepBackward: (page 83)

Editing a movie

– cut: (page 77)

– copy: (page 77)

– paste: (page 80)

– selectAll: (page 81)

– delete: (page 77)

– add: (page 76)

– addScaled: (page 76)

– replace: (page 81)

– trim: (page 83)

Instance Methods

add: -(IBAction)add:(id)sender

Discussion This action method adds the contents of the clipboard to the movie at the current movie time. This action is undoable. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

addScaled: -(IBAction)addScaled:(id)sender

Discussion This action method adds the contents of the clipboard to the movie, scaled to fit into the current movie selection. This action is undoable. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

controllerBarHeight -(float)controllerBarHeight

Discussion Returns the height of the controller bar.

Availability Available in Mac OS X v10.3 and later.

copy: -(IBAction)copy:(id)sender

Discussion This action method copies the current movie selection onto the clipboard. If there is no selection, the current frame is copied. The movie does not need to be editable.

Availability Available in Mac OS X v10.3 and later. cut: -(IBAction)cut:(id)sender

Discussion This action method deletes the current movie selection from the movie, placing it on the clipboard. If there is no selection, the current frame is deleted. This action is undoable. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later. delete: -(IBAction)delete:(id)sender

Availability Available in Mac OS X v10.3 and later. fillColor - (NSColor* )fillColor

Discussion Returns the fill color of the QTMovieView.

Availability Available in Mac OS X v10.3 and later. gotoBeginning: -(IBAction)gotoBeginning:(id)sender

Discussion This action method sets the current movie time to the beginning of the movie. If the movie is playing, the movie continues playing from the new position.

Availability Available in Mac OS X v10.3 and later.

gotoEnd: - (IBAction)gotoEnd:(id)sender

Discussion This action method sets the current movie time to the end of the movie. If the movie is playing in one of the looping modes, the movie continues playing accordingly; otherwise, play stops.

Availability Available in Mac OS X v10.3 and later.

gotoNextSelectionPoint: -(IBAction)gotoNextSelectionPoint:(id)sender

Discussion This action method sets the current movie time to the next selection point.

Availability Available in Mac OS X v10.3 and later.

gotoPosterFrame: -(IBAction)gotoPosterFrame:(id)sender

Discussion This action method sets the current movie time to the movie poster frame.

Availability Available in Mac OS X v10.3 and later.

gotoPreviousSelectionPoint: -(IBAction)gotoPreviousSelectionPoint:(id)sender

Discussion This action method sets the current movie time to the previous selection point.

Availability Available in Mac OS X v10.3 and later.

initWithFrame: -(id)initWithFrame:(NSRect)frame

Discussion Initializes a newly allocated QTMovieView with frame as its frame rectangle. The new movie view object must be inserted into the view hierarchy of an NSWindow before it can be used. This method is the designated initializer for the QTMovieView class.

Availability Available in Mac OS X v10.3 and later. isControllerVisible -(BOOL)isControllerVisible

Discussion Returns YES if the movie controller bar of the QTMovieView object is visible. The default is YES.

Availability Available in Mac OS X v10.3 and later. isEditable -(BOOL)isEditable

Discussion Returns YES if the QTMovieView object is editable. When editable, a movie can be modified using editing methods and associated key commands. The default is NO.

Availability Available in Mac OS X v10.3 and later. movie -(QTMovie *)movie

Discussion Returns the QTMovie object associated with the QTMovieView.

Availability Available in Mac OS X v10.3 and later. movieBounds -(NSRect)movieBounds

Discussion Returns the rectangle currently occupied by the movie in a QTMovieView. This rectangle does not include the area occupied by the movie controller bar (if it’s visible).

Availability Available in Mac OS X v10.3 and later.

movieControllerBounds -(NSRect)movieControllerBounds

Discussion Returns the rectangle currently occupied by the movie controller bar (if it’s visible) in a QTMovieView.

Availability Available in Mac OS X v10.3 and later.

paste: -(IBAction)paste:(id)sender

Discussion This action method inserts the contents of the clipboard (if it contains a movie clip) into the movie at the current play position. This action is undoable. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

pause: -(IBAction)pause:(id)sender

Discussion This action method pauses the movie playback. This method does nothing if the movie is already paused.

Availability Available in Mac OS X v10.3 and later.

play: -(IBAction)play:(id)sender

Discussion This action method starts the movie playing at its current location. This method does nothing if the movie is already playing.

Availability Available in Mac OS X v10.3 and later.

preservesAspectRatio -(BOOL)preservesAspectRatio

Discussion Returns YES if the QTMovieView object maintains the aspect ratio of the movie when drawing it in the view. The remainder is filled with fillColor.

Availability Available in Mac OS X v10.3 and later. replace: -(IBAction)replace:(id)sender

Discussion This action method replaces the current movie selection with the contents of the clipboard. If there is no selection, the contents of the clipboard replace the entire movie. This action is undoable. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later. selectAll: -(IBAction)selectAll:(id)sender

Discussion This action method selects the entire movie.

Availability Available in Mac OS X v10.3 and later. selectNone: -(IBAction)selectNone:(id)sender

Discussion This action method selects nothing. Note that it does not change the movie time.

Availability Available in Mac OS X v10.3 and later. setControllerVisible: -(void)setControllerVisible:(BOOL)controllerVisible

Discussion Sets the visibility state of the movie controller bar in a QTMovieView to controllerVisible.

Availability Available in Mac OS X v10.3 and later.

setEditable: -(void)setEditable:(BOOL)editable

Discussion Sets the edit state of a QTMovieView to editable. The default state is NO.

Availability Available in Mac OS X v10.3 and later.

setFillColor: -(void)setFillColor:(NSColor *)fillColor

Discussion Sets the fill color of a QTMovieView to fillColor. Note that this may cause a redraw.

Availability Available in Mac OS X v10.3 and later.

setMovie: -(void)setMovie:(id)movie

Discussion Sets the QTMovie object in a QTMovieView to movie. The currently set QuickTime movie is disposed of using DisposeMovie, unless the QTMovie was created with a call to initWithQuickTimeMovie and the disposeWhenDone flag was NO.

Availability Available in Mac OS X v10.3 and later.

setPreservesAspectRatio: -(void)setPreservesAspectRatio:(BOOL)preservesAspectRatio

Discussion Sets the aspect ratio state of a QTMovieView to preservesAspectRatio. If preservesAspectRatio is YES, the longer side of the movie rectangle is scaled to exactly fit into the view’s frame and the other side is centered in the view frame; the remaining area is filled with the view’s fill color. Note that the movie view may be redrawn, but not resized.

Availability Available in Mac OS X v10.3 and later.

setShowsResizeIndicator: -(void)setShowsResizeIndicator:(BOOL)show

Discussion Shows or hides the movie controller grow box.

Availability Available in Mac OS X v10.3 and later. stepBackward: -(IBAction)stepBackward:(id)sender

Discussion This action method steps the movie backward one frame.

Availability Available in Mac OS X v10.3 and later. stepForward: -(IBAction)stepForward:(id)sender

Discussion This action method steps the movie forward one frame.

Availability Available in Mac OS X v10.3 and later. trim: -(IBAction)trim:(id)sender

Discussion This action method trims the movie to the current movie selection. If there is no selection, the current frame is retained and the remainder of the movie is deleted. This action is undoable. If the movie is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

QTTrack Class Reference

Inherits from: NSObject Conforms to: NSObject (NSObject)

Framework QTKit.framework Declared in: QTKit/QTTrack.h

Availability: Available in Mac OS X v10.4 and later.

Class Description

Methods by Task

Creating a QTTrack

+ trackWithQuickTimeTrack:error: (page 87)

Initializing a QTTrack

– initWithQuickTimeTrack:error: (page 88)

Getting track properties

– movie (page 89)

– media (page 89)

– isEnabled (page 89)

– volume (page 91)

– attributeForKey: (page 87)

– trackAttributes (page 91)

Setting track properties

– setEnabled: (page 90)

– setVolume: (page 90)

– setAttribute:forKey: (page 90)

– setTrackAttributes: (page 90)

Editing track properties

– addImage:forDuration:withAttributes: (page 87)

– deleteSegment: (page 88)

– insertEmptySegmentAt: (page 88)

– insertSegmentOfTrack:timeRange:atTime: (page 88)

– insertSegmentOfTrack:fromRange:scaledToRange: (page 88)

– scaleSegment:newDuration: (page 90)

Getting QTTrack primitives

– quickTimeTrack (page 89)

Class Methods

trackWithQuickTimeTrack:error: + (id)trackWithQuickTimeTrack:(Track)track error:(NSError **)errorPtr

Discussion Creates a QTTrack object with data from the QuickTime track track. If a QTTrack object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

Instance Methods

addImage:forDuration:withAttributes: - (void)addImage:(NSImage *)image forDuration:(QTTime)duration withAttributes:(NSDictionary *)attributes

Availability Available in Mac OS X v10.3 and later.

attributeForKey: -(id)attributeForKey:(NSString *)attributeKey

Discussion Returns the current value of the track attribute attributeKey. A list of supported track attributes and their acceptable values can be found in the “Constants” (page 91) section.

Availability Available in Mac OS X v10.3 and later.

deleteSegment: - (void)deleteSegment:(QTTimeRange)segment

Discussion Deletes from a QTTrack the segment delimited by segment. If the track is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

initWithQuickTimeTrack:error: - (id)initWithQuickTimeTrack:(Track)track error:(NSError **)errorPtr

Discussion Initializes a newly created QTTrack object with data from the QuickTime track track. If a QTTrack object cannot be created, an NSError object is returned in the location pointed to by errorPtr. Pass NIL if you do not want an NSError object returned.

Availability Available in Mac OS X v10.3 and later.

insertEmptySegmentAt: - (void)insertEmptySegmentAt:(QTTimeRange)range

Discussion Inserts into a QTTrack an empty segment delimited by the range range. If the track is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

insertSegmentOfTrack:fromRange:scaledToRange: - (void)insertSegmentOfTrack:(QTTrack *)track fromRange:(QTTimeRange)srcRange scaledToRange:(QTTimeRange)dstRange

Discussion Inserts the specified segment from the track into the receiver, scaled to the range dstRange. This is essentially an Add Scaled operation on a track. If the track is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

insertSegmentOfTrack:timeRange:atTime: - (void)insertSegmentOfTrack:(QTTrack *)track timeRange:(QTTimeRange)range atTime:(QTTime)time

Discussion Inserts into a QTTrack at time time the selection in movie delimited by the time range range. If the track is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later. isEnabled - (BOOL)isEnabled

Discussion Returns YES if the QTTrack object is currently enabled, NO otherwise.

Availability Available in Mac OS X v10.3 and later. media - (QTMedia *)media

Discussion Returns the media associated with a QTTrack object.

Availability Available in Mac OS X v10.3 and later. movie - (QTMovie *)movie

Discussion Returns the movie that contains a QTTrack object.

Availability Available in Mac OS X v10.3 and later. quickTimeTrack -(Track)quickTimeTrack

Discussion Returns the QuickTime track associated with a QTTrack object.

Availability Available in Mac OS X v10.3 and later.

scaleSegment:newDuration: - (void)scaleSegment:(QTTimeRange)segment newDuration:(QTTime)newDuration

Discussion Scales the QTTrack segment delimited by the segment segment so that it will have the new duration newDuration. If the track is not editable, this method raises an exception.

Availability Available in Mac OS X v10.3 and later.

setAttribute:forKey: -(void)setAttribute:(id)value forKey:(NSString *)attributeKey

Discussion Set the track attribute attributeKey to the value specified by the value parameter. A list of supported track attributes and their acceptable values can be found in the “Constants” (page 91) section.

Availability Available in Mac OS X v10.3 and later.

setEnabled: - (void)setEnabled:(BOOL)enabled

Discussion Sets the enabled state of a QTTrack to enabled.

Availability Available in Mac OS X v10.3 and later.

setTrackAttributes: -(void)setTrackAttributes:(NSDictionary *)attributes

Discussion Set the track attributes using the key-value pairs specified in the dictionary attributes. A list of supported track attributes and their acceptable values can be found in the “Constants” (page 91) section.

Availability Available in Mac OS X v10.3 and later.

setVolume: -(void)setVolume:(float)volume

Discussion Sets the volume of a QTTrack to volume. The valid range is 0.0 to 1.0.

Availability Available in Mac OS X v10.3 and later.

trackAttributes -(NSDictionary *)trackAttributes

Discussion Returns a dictionary containing the current values of all defined track attributes. A list of supported track attributes and their acceptable values can be found in the “Constants” (page 91) section.

Availability Available in Mac OS X v10.3 and later.

volume -(float)volume

Discussion Returns the volume of a QTTrack object. The valid range is 0.0 to 1.0.

Availability Available in Mac OS X v10.3 and later.

Constants

The following constants specify the track attributes that you can get and set using the trackAttributes and setTrackAttributes methods. To get or set a single attribute, use attributeForKey or setAttribute.

Constant Description

QTTrackBoundsAttribute The bounding rectangle of a QTTrack object; the value for this key is of type NSValue, interpreted as an NSRect. Available in Mac OS X v10.3 and later.

QTTrackCreation- The creation time of a QTTrack object; the value for this key is of TimeAttribute type NSDate. Available in Mac OS X v10.3 and later.

QTTrackDimensions- The dimensions of a QTTrack object; the value for this key is of type Attribute NSValue, interpreted as an NSSize. Available in Mac OS X v10.3 and later.

QTTrackDisplay- The display name of a QTTrack object; the value for this key is of NameAttribute type NSString. Available in Mac OS X v10.3 and later.

Constant Description

QTTrackEnabledAttribute The track enabled state of a QTTrack object; the value for this key is of type NSNumber, interpreted as a BOOL. Available in Mac OS X v10.3 and later.

QTTrackIDAttribute The track ID of a QTTrack object; the value for this key is of type NSNumber, interpreted as a long. Available in Mac OS X v10.3 and later.

QTTrackLayerAttribute The track layer of a QTTrack object; the value for this key is of type NSNumber, interpreted as a short. Available in Mac OS X v10.3 and later.

QTTrackMediaTypeAttribute The media type of a QTTrack object; the value for this key is of type NSString. Available in Mac OS X v10.3 and later.

QTTrackModification- The modification time of a QTTrack object; the value for this key is TimeAttribute of type NSDate. Available in Mac OS X v10.3 and later.

QTTrackRangeAttribute The range of time this track occupies; the value for this key is of type NSValue, interpreted as a QTTimeRange. Available in Mac OS X v10.3 and later.

QTTrackTimeScaleAttribute The track time scale; the value for this key is of type NSNumber, interpreted as a long. Available in Mac OS X v10.3 and later.

QTTrackUsageInMovie- The movie usage setting; the value for this key is of type NSNumber, Attribute interpreted as a BOOL. Available in Mac OS X v10.3 and later.

QTTrackUsageInPoster- The poster usage setting; the value for this key is of type NSNumber, Attribute interpreted as a BOOL. Available in Mac OS X v10.3 and later.

QTTrackUsageIn- The preview usage setting; the value for this key is of type NSNumber, PreviewAttribute interpreted as a BOOL. Available in Mac OS X v10.3 and later.

QTTrackVolumeAttribute The volume of a QTTrack object; the value for this key is of type NSNumber, interpreted as a float. Available in Mac OS X v10.3 and later.

Functions

QuickTime Kit Functions Reference

Framework: QTKit/QTKit.h

Introduction

This chapter describes the functions that are available in the QuickTime Kit framework.

Functions by Task

Creating QTTime Structures The following functions are used to create QTTime structures:

QTMakeTime (page 98) Creates a QTTime structure.

QTMakeTimeScaled (page 98) Returns a QTTime structure.

QTTimeFromString (page 101) Returns a QTTime structure.

QTMakeTimeWithTimeRecord (page 99) Creates a QTTime structure.

QTMakeTimeWithTimeInterval (page 99) Creates a QTTime structure.

Getting and Setting Times The following functions are used to get and set times:

QTGetTimeRecord (page 97) Returns the value of a QTTime structure expressed as a TimeRecord.

QTGetTimeInterval (page 97) Returns the value of a QTTime structure expressed as an NSTimeInterval.

Comparing QTTime Structures The following function is used to compare QTTime structures:

QTTimeCompare (page 100) Returns a value of type NSComparisonResult.

Adding and Subtracting Times The following functions are used to add and subtract times:

QTTimeIncrement (page 101) Adds two QTTime structures.

QTTimeDecrement (page 100) Subtracks one QTTime from another.

Getting a Time Description The following function is used to get a time description:

QTStringFromTime (page 100) Returns a description of a QTTime structure.

Time Range Functions

QTEqualTimeRanges (page 97) Returns YES if the specified time ranges are identical.

QTIntersectionTimeRange (page 98) Returns a QTTimeRange structure that represents the intersection of the two ranges.

QTMakeTimeRange (page 98) Returns a QTTimeRange structure initialized using the QTTime structures time and duration.

QTStringFromTimeRange (page 100) Returns a description of a QTTimeRange structure.

QTTimeInTimeRange (page 101) Returns YES if the specified time time lies in the time range range.

QTTimeRangeEnd (page 101) Returns a QTTime structure representing the end of the specified time range.

QTTimeRangeFromString (page 102) Returns a QTTimeRange structure

QTUnionTimeRange (page 102) Returns a QTTimeRange structure.

QuickTime Helper Functions

QTStringForOSType (page 99) Returns an NSString representing the specified four-character code type.

QTOSTypeForString (page 99) Returns a four-character code representing the specified NSString.

Functions

QTEqualTimeRanges Returns YES if the specified time ranges are identical.

BOOL QTEqualTimeRanges(QTTimeRange range, QTTimeRange range2);

Discussion This function returns YES if the specified time ranges are identical.

Availability Available in Mac OS X v10.3 and later.

QTGetTimeInterval Returns the value of a QTTime structure expressed as an NSTimeInterval.

BOOL QTGetTimeInterval(QTTime time, NSTimeInterval* timeInterval);

Discussion This function returns, in the location to by timeInterval, the value of a QTTime structure expressed as a NSTimeInterval. Returns YES if the method succeeded.

Availability Available in Mac OS X v10.3 and later.

QTGetTimeRecord Returns the value of a QTTime structure expressed as a TimeRecord.

BOOL QTGetTimeRecord(QTTime time, TimeRecord* timeRecord);

Discussion This function returns, in the location pointed to by timeRecord, the value of a QTTime structure expressed as a TimeRecord. Returns YES if the method succeeded.

Availability Available in Mac OS X v10.3 and later.

QTIntersectionTimeRange Returns a QTTimeRange structure that represents the intersection of the two ranges.

QTTimeRange QTIntersectionTimeRange(QTTimeRange range1, QTTimeRange range2);

Discussion This function returns a QTTimeRange structure that represents the intersection of the two ranges. The intersection of two ranges is the largest range that includes all times that are in both ranges.

Availability Available in Mac OS X v10.3 and later.

QTMakeTime Creates a QTTime structure.

QTTime QTMakeTime (long long timeValue, long timeScale);

Discussion This function creates a QTTime structure initialized using the scalar value timeValue and the time scale scale.

Availability Available in Mac OS X v10.3 and later.

QTMakeTimeRange Returns a QTTimeRange structure initialized using the QTTime structures time and duration.

QTTimeRange QTMakeTimeRange(QTTime time, QTTime duration);

Discussion This function returns a QTTimeRange structure initialized using the QTTime structures time and duration. Those structures may have different time scales. In all cases, the time scale used in the new QTTimeRange structure is that of time.

Availability Available in Mac OS X v10.3 and later.

QTMakeTimeScaled Returns a QTTime structure.

QTTime QTMakeTimeScaled (QTTime time, long timeScale);

Discussion This function returns a QTTime structure whose time is set to the time of a QTTime structure interpreted using the time scale scale.

Availability Available in Mac OS X v10.3 and later.

QTMakeTimeWithTimeInterval Creates a QTTime structure.

QTTime QTMakeTimeWithTimeInterval(NSTimeInterval timeInterval);

Discussion Creates a QTTime structure initialized using the NSTimeInterval value timeInterval.

Availability Available in Mac OS X v10.3 and later.

QTMakeTimeWithTimeRecord Creates a QTTime structure.

QTTime QTMakeTimeWithTimeRecord(TimeRecord timeRecord);

Discussion This function creates a QTTime structure initialized using the values in the time record timeRecord.

Availability Available in Mac OS X v10.3 and later.

QTOSTypeForString Returns a four-character code representing the specified NSString.

OSType QTOSTypeForString (NSString *string);

Discussion This function returns a four-character code representing the specified NSString.

Availability Available in Mac OS X v10.3 and later.

QTStringForOSType Returns an NSString representing the specified four-character code type.

String * QTStringForOSType (OSType type);

Discussion This function returns an NSString representing the specified four-character code type.

Availability Available in Mac OS X v10.3 and later.

QTStringFromTime Returns a description of a QTTime structure.

NSString* QTStringFromTime(QTTime time);

Discussion This function returns a description of a QTTime structure. The string is in the form “sign:days:hours:minutes:seconds:timevalue:timescale”, where sign is empty or “-”. Note that this is not for user input, but for archiving and debugging purposes.

Availability Available in Mac OS X v10.3 and later.

QTStringFromTimeRange Returns a description of a QTTimeRange structure.

NSString* QTStringFromTimeRange(QTTimeRange range);

Discussion This function returns a description of a QTTimeRange structure. The string is in the form “hours:minutes:seconds.frames:: hours:minutes:seconds.frames”. Note that this is for archiving and debugging purposes, not for user display.

Availability Available in Mac OS X v10.3 and later.

QTTimeCompare Returns a value of type NSComparisonResult.

NSComparisonResult QTTimeCompare(QTTime time, QTTime otherTime);

Discussion This function returns a value of type NSComparisonResult that indicates the result of comparing a QTTime structure with the specified QTTime structure otherTime.

Availability Available in Mac OS X v10.3 and later.

QTTimeDecrement Subtracks one QTTime from another.

QTTime QTTimeDecrement(QTTime time, QTTime decrement);

Discussion This function returns a QTTime structure whose time is set to the time of a QTTime structure minus that of the structure decrement.

Availability Available in Mac OS X v10.3 and later.

QTTimeFromString Returns a QTTime structure.

QTTime QTTimeFromString(NSString* string);

Discussion This function returns a QTTime structure whose time is set to the time expressed by the string; the string is assumed to be in the form “days:hours:minutes:seconds:frames/timescale”.

Availability Available in Mac OS X v10.3 and later.

QTTimeIncrement Adds two QTTime structures.

QTTime QTTimeIncrement(QTTime time, QTTime increment);

Discussion This function returns a QTTime structure whose time is set to the time of a QTTime structure plus that of the structure increment.

Availability Available in Mac OS X v10.3 and later.

QTTimeInTimeRange Returns YES if the specified time time lies in the time range range.

BOOL QTTimeInTimeRange(QTTime time, QTTimeRange range);

Discussion This function returns YES if the specified time time lies in the time range range.

Availability Available in Mac OS X v10.3 and later.

QTTimeRangeEnd Returns a QTTime structure representing the end of the specified time range.

QTTime QTTimeRangeEnd(QTTimeRange range);

Discussion This function returns a QTTime structure representing the end of the specified time range.

Availability Available in Mac OS X v10.3 and later.

QTTimeRangeFromString Returns a QTTimeRange structure

QTTimeRange QTTimeRangeFromString(NSString* string);

Discussion This function returns a QTTimeRange structure whose range is set to the range expressed by string; the string is assumed to be in the form “days:hours:minutes:seconds.frames/timescale~days:hours:minutes:seconds.frames/timescale”.

Availability Available in Mac OS X v10.3 and later.

QTUnionTimeRange Returns a QTTimeRange structure.

QTTimeRange QTUnionTimeRange(QTTimeRange range1, QTTimeRange range2);

Discussion This function returns a QTTimeRange structure that represents the union of the two ranges. The union of two ranges is the smallest range that includes all times that are in either range.

Availability Available in Mac OS X v10.3 and later.

Data Types

QuickTime Kit Data Types Reference

Framework: QTKit/QTKit.h

Introduction

This chapter describes the data types and constants found in the QuickTime Kit framework.

Data Types

QTTime Defines the value and time scale of a time.

typedef struct { long long timeValue; long timeScale; long flags; }

Discussion The QTTime structure defines the value and time scale of a time. Currently only one flag is defined:

enum { kQTTimeIsIndefinite = 1 << 0 };

If this flag is set in a QTTime structure, the other fields should not be used. The QTKit provides a number of functions for converting and comparing QTTime structures.

QTTimeRange Defines a range of time.

typedef struct { QTTime time; QTTime duration; } QTTimeRange;

Discussion The QTTimeRange structure defines a range of time. It is used, for instance, to specify the active segment of a movie or track. The QTKit provides a number of functions for converting and comparing QTTimeRange structures.

Document Revision History

This table describes the changes to QuickTime Kit Framework Reference.

Date Notes

2006-05-23 First publication of this content as a collection of separate documents.

decodeQTTimeForKey: instance method 16 A decodeQTTimeRangeForKey: instance method 16 delegate instance method 48 add: instance method 76 delete: instance method 77 addImage:forDuration:withAttributes: instance deleteSegment: instance method 48, 88 method 47, 87 duration instance method 49 addScaled: instance method 76 appendSelectionFromMovie: instance method 47 attributeForKey: instance method 29, 47, 87 E

encodeQTTime:forKey: instance method 16 C encodeQTTimeRange:forKey: instance method 16 externalMovie: delegate method 62 canInitWithDataReference: class method 41 canInitWithFile: class method 41 canInitWithPasteboard: class method 41 canInitWithURL: class method 41 F canUpdateMovieFile instance method 47 fillColor instance method 77 controllerBarHeight instance method 76 frameImageAtTime: instance method 49 copy: instance method 77 currentFrameImage instance method 48 currentTime instance method 48 cut: instance method 77 G

gotoBeginning instance method 49, 77 gotoEnd instance method 49, 78 D gotoNextSelectionPoint instance method 50, 78 gotoPosterFrame: instance method 78 dataRef instance method 22 gotoPosterTime instance method 50 dataRefData instance method 22 gotoPreviousSelectionPoint instance method 50, dataReferenceWithDataRefData:type: class 78 method 21 dataReferenceWithDataRef:type: class method 21 dataReferenceWithReferenceToData: class method 21 H dataReferenceWithReferenceToData:name:MIMEType: class method 21 hasCharacteristic: instance method 29 dataReferenceWithReferenceToFile: class method 22 dataReferenceWithReferenceToURL: class method 22 dataRefType instance method 23

I movieNamed:error: class method 42 movie:shouldContinueOperation:withPhase:atPercent: initWithAttributes:error: instance method 50 withAttributes: delegate method initWithData:error: instance method 52 62 initWithDataRefData:type: instance method 23 movieShouldTask: delegate method 63 initWithDataReference:error: instance method movieUnfilteredFileTypes class method 43 52 movieUnfilteredPasteboardTypes class method 43 initWithDataRef:type: instance method 23 movieWithAttributes:error: class method 43 initWithFile:error: instance method 52 movieWithData:error: class method 45 initWithFrame: instance method 79 movieWithDataReference:error: class method 45 initWithMovie:timeRange:error: instance method movieWithFile:error: class method 45 53 movieWithPasteboard:error: class method 46 initWithPasteboard:error: instance method 53 movieWithQuickTimeMovie:disposeWhenDone:error: initWithQuickTimeMedia:error: instance method class method 46 29 movieWithTimeRange:error: instance method 55 initWithQuickTimeMovie:disposeWhenDone:error: movieWithURL:error: class method 46 instance method 53 muted instance method 55 initWithQuickTimeTrack:error: instance method 88 initWithReferenceToData: instance method 23 initWithReferenceToData:name:MIMEType: N instance method 23 name instance method 24 initWithReferenceToFile: instance method 24 initWithReferenceToURL: instance method 24 initWithURL:error: instance method 54 insertEmptySegmentAt: instance method 54, 88 P insertSegmentOfMovie:fromRange:scaledToRange: instance method 54 paste: instance method 80 insertSegmentOfMovie:timeRange:atTime: pause: instance method 80 instance method 54 play instance method 55, 80 insertSegmentOfTrack:fromRange:scaledToRange: posterImage instance method 56 instance method 88 preservesAspectRatio instance method 81 insertSegmentOfTrack:timeRange:atTime: instance method 88 isControllerVisible instance method 79 isEditable instance method 79 Q isEnabled instance method 89 QTAddImageCodecQuality constant 68 QTAddImageCodecType constant 68 QTDataReferenceTypeFile constant 26 M QTDataReferenceTypeHandle constant 26 QTDataReferenceTypePointer constant 26 media instance method 89 QTDataReferenceTypeResource constant 26 mediaAttributes instance method 29 QTDataReferenceTypeURL constant 26 mediaWithQuickTimeMedia:error: class method 28 QTEqualTimeRanges function 97 MIMEType instance method 24 QTGetTimeInterval function 97 movie class method 41 QTGetTimeRecord function 97 movie instance method 79, 89 QTIncludeAggressiveTypes constant 42 movieAttributes instance method 54 QTIncludeAllTypes constant 42 movieBounds instance method 79 QTIncludeCommonTypes constant 42 movieControllerBounds instance method 80 QTIncludeStillImageTypes constant 42 movieFileTypes: class method 42 QTIncludeTranslatableTypes constant 42 movieFormatRepresentation instance method 55 QTIntersectionTimeRange function 98 movie:linkToURL: delegate method 62 QTMakeTime function 98

QTMakeTimeRange function 98 QTMovieCurrentTimeAttribute constant 64 QTMakeTimeScaled function 98 QTMovieDataAttribute constant 68 QTMakeTimeWithTimeInterval function 99 QTMovieDataReferenceAttribute constant 68 QTMakeTimeWithTimeRecord function 99 QTMovieDataSizeAttribute constant 64 QTMediaCharacteristicAudio constant 32 QTMovieDelegateAttribute constant 64 QTMediaCharacteristicCanSendVideo constant 32 QTMovieDidEndNotification notification 69 QTMediaCharacteristicCanStep constant 33 QTMovieDisplayNameAttribute constant 64 QTMediaCharacteristicHasNoDuration constant 33 QTMovieDontInteractWithUserAttribute constant QTMediaCharacteristicHasSkinData constant 33 64 QTMediaCharacteristicHasVideoFrameRate QTMovieDurationAttribute constant 64 constant 33 QTMovieEditabilityDidChangeNotification QTMediaCharacteristicNonLinear constant 32 notification 70 QTMediaCharacteristicProvidesActions constant QTMovieEditableAttribute constant 64 32 QTMovieEditedNotification notification 70 QTMediaCharacteristicProvidesKeyFocus constant QTMovieEnterFullScreenRequestNotification 33 notification 70 QTMediaCharacteristicVisual constant 32 QTMovieExitFullScreenRequestNotification QTMediaCreationTimeAttribute constant 31 notification 70 QTMediaDurationAttribute constant 31 QTMovieExport constant 68 QTMediaModificationTimeAttribute constant 31 QTMovieExportManufacturer constant 68 QTMediaQualityAttribute constant 31 QTMovieExportSettings constant 68 QTMediaSampleCountAttribute constant 31 QTMovieExportType constant 68 QTMediaTimeScaleAttribute constant 31 QTMovieFileNameAttribute constant 64 QTMediaType3D constant 32 QTMovieFileOffsetAttribute constant 69 QTMediaTypeAttribute constant 31 QTMovieFlatten constant 68 QTMediaTypeBase constant 31 QTMovieHasAudioAttribute constant 64 QTMediaTypeFlash constant 32 QTMovieHasDurationAttribute constant 64 QTMediaTypeHint constant 32 QTMovieHasVideoAttribute constant 64 QTMediaTypeMovie constant 32 QTMovieIsActiveAttribute constant 65 QTMediaTypeMPEG constant 31 QTMovieIsInteractiveAttribute constant 65 QTMediaTypeMusic constant 31 QTMovieIsLinearAttribute constant 65 QTMediaTypeQTVR constant 32 QTMovieIsSteppableAttribute constant 65 QTMediaTypeSkin constant 32 QTMovieLoadStateAttribute constant 65 QTMediaTypeSound constant 31 QTMovieLoadStateDidChangeNotification QTMediaTypeSprite constant 32 notification 70 QTMediaTypeStream constant 32 QTMovieLoopModeDidChangeNotification QTMediaTypeText constant 31 notification 70 QTMediaTypeTimeCode constant 32 QTMovieLoopsAttribute constant 65 QTMediaTypeTween constant 32 QTMovieLoopsBackAndForthAttribute constant 65 QTMediaTypeVideo constant 31 QTMovieMessageNotificationParameter constant QTMovieActiveSegmentAttribute constant 63 67 QTMovieAskUnresolvedDataRefAttribute constant QTMovieMessageStringPostedNotification 69 notification 71 QTMovieAutoAlternatesAttribute constant 63 QTMovieModificationTimeAttribute constant 65 QTMovieChapterDidChangeNotification notification QTMovieMutedAttribute constant 65 69 QTMovieNaturalSizeAttribute constant 65 QTMovieChapterListDidChangeNotification QTMovieOpenAsyncOKAttribute constant 69 notification 69 QTMoviePasteboardAttribute constant 68 QTMovieCloseWindowRequestNotification QTMoviePlaysAllFramesAttribute constant 65 notification 69 QTMoviePlaysSelectionOnlyAttribute constant 66 QTMovieCopyrightAttribute constant 63 QTMoviePosterTimeAttribute constant 66 QTMovieCreationTimeAttribute constant 63 QTMoviePreferredMutedAttribute constant 66 QTMovieCurrentSizeAttribute constant 63 QTMoviePreferredRateAttribute constant 66

QTMoviePreferredVolumeAttribute constant 66 QTTrackDisplayNameAttribute constant 91 QTMoviePreviewModeAttribute constant 66 QTTrackEnabledAttribute constant 92 QTMoviePreviewRangeAttribute constant 66 QTTrackIDAttribute constant 92 QTMovieRateAttribute constant 66 QTTrackLayerAttribute constant 92 QTMovieRateChangesPreservePitchAttribute QTTrackMediaTypeAttribute constant 92 constant 66 QTTrackModificationTimeAttribute constant 92 QTMovieRateDidChangeNotification notification QTTrackRangeAttribute constant 92 71 QTTrackTimeScaleAttribute constant 92 QTMovieRateDidChangeNotificationParameter QTTrackUsageInMovieAttribute constant 92 constant 67 QTTrackUsageInPosterAttribute constant 92 QTMovieResolveDataRefAttribute constant 69 QTTrackUsageInPreviewAttribute constant 92 QTMovieSelectionAttribute constant 66 QTTrackVolumeAttribute constant 92 QTMovieSelectionDidChangeNotification QTUnionTimeRange function 102 notification 71 quickTimeMedia instance method 30 QTMovieSizeDidChangeNotification notification quickTimeMovie instance method 56 71 quickTimeMovieController instance method 56 QTMovieStatusCodeNotificationParameter quickTimeTrack instance method 89 constant 67 QTMovieStatusFlagsNotificationParameter constant 67 QTMovieStatusStringNotificationParameter R constant 67 rate QTMovieStatusStringPostedNotification instance method 56 referenceData instance method 24 notification 71 referenceFile instance method 25 QTMovieTargetIDNotificationParameter constant referenceURL instance method 25 67 replace: QTMovieTargetNameNotificationParameter instance method 81 replaceSelectionWithSelectionFromMovie: constant 67 instance method 57 QTMovieTimeDidChangeNotification notification 72 QTMovieTimeScaleAttribute constant 66 QTMovieURLAttribute constant 67 S QTMovieVolumeAttribute constant 67 QTMovieVolumeDidChangeNotification notification scaleSegment:newDuration: instance method 57, 72 90 QTOSTypeForString function 99 selectAll: instance method 81 QTStringForOSType function 99 selectionDuration instance method 57 QTStringFromTime function 100 selectionEnd instance method 57 QTStringFromTimeRange function 100 selectionStart instance method 57 QTTime data type 105 selectNone: instance method 81 QTTimeCompare function 100 setAttribute:forKey: instance method 30, 58, 90 QTTimeDecrement function 100 setControllerVisible: instance method 81 QTTimeFromString function 101 setCurrentTime: instance method 58 QTTimeIncrement function 101 setDataRef: instance method 25 QTTimeInTimeRange function 101 setDataRefType: instance method 25 QTTimeRange data type 105 setDelegate: instance method 58 QTTimeRangeEnd function 101 setEditable: instance method 82 QTTimeRangeFromString function 102 setEnabled: instance method 90 QTTimeRangeValue instance method 18 setFillColor: instance method 82 QTTimeValue instance method 18 setMediaAttributes: instance method 30 QTTrackBoundsAttribute constant 91 setMovie: instance method 82 QTTrackCreationTimeAttribute constant 91 setMovieAttributes: instance method 58 QTTrackDimensionsAttribute constant 91 setMuted: instance method 58

setPreservesAspectRatio: instance method 82 setRate: instance method 59 setSelection: instance method 59 setShowsResizeIndicator: instance method 83 setTrackAttributes: instance method 90 setVolume: instance method 59, 90 stepBackward instance method 59, 83 stepForward instance method 59, 83 stop instance method 60

T track instance method 30 trackAttributes instance method 91 tracks instance method 60 tracksOfMediaType: instance method 60 trackWithQuickTimeTrack:error: class method 87 trim: instance method 83

U updateMovieFile instance method 60

V valueWithQTTime: class method 18 valueWithQTTimeRange: class method 18 volume instance method 60, 91

W writeToFile:withAttributes: instance method 61