DR Developer's Guide
DR Interfaces | DR Methods | DR Types and Misc API

IMoaDrMovie


Interface ID: IID_IMoaDrMovie
Pointer type: PIMoaDrMovie
Inheritance: IMoaDrMediaOwner
Header file: driservc.h

Description

The IMoaDrMovie interface represents open movies in Director. You acquire a movie interface by calling the IMoaDrPlayer methods GetActiveMovie() or GetNthMovie().

Movie properties

IMoaDrMovie inherits from the IMoaMmPropOwner interface, providing for access to data through the properties mechanism described in the "Multimedia Services" chapter in the Developer's Guide document. See the "Properties" section for information on the properties defined for objects providing the IMoaDrMovie interface.

Movie media

IMoaDrMovie inherits from the IMoaDrMediaOwner interface, providing for access to media through the media owner mechanism described in the "Director Services" chapter in the Developer's Guide document. Movies have one kind of media: scores. Scores are editable through the IMoaDrScoreAccess interface. You acquire a movie's score data by calling either IMoaDrMovie::GetMedia(), which returns a handle to the score data, or GetScoreAccess(), which returns an IMoaDrScoreAccess interface to the score data.

Methods

Property owner methods

GetProp()
SetProp()

Media owner methods

GetMedia()
SetMedia()
AttachMedia()

Scripting support

CallHandler()
SendSpriteMessage()

Managing casts

GetCastCount()
GetNthCast()
GetCastFromName()
GetCastIndexFromName()
NewCast()
AddExternalCast()
RemoveCast()
GetCMRefFromMemberName()

Acquiring ImoaDrCastMem

GetCastMemFromCMRef()

Imaging support

UpdateStageRect()
GetStageWindowGC()
GetStageBufferGC()

Accessing frame labels

GetFrameIndexFromLabel()
GetFrameLabelFromIndex()
SetFrameLabel()

Acquiring IMoaDrScoreAccess

GetScoreAccess()

Managing movies

Save()

AddExternalCast()

Syntax

AddExternalCast(PMoaChar pCastName, PMoaChar pPathName, PMoaDrCastIndex pNewCastIndex)

Parameters

pCastName
PMoaChar The user reference name for the cast

pPathName
PMoaChar The full path name for an external cast

pNewCastIndex
PMoaDrCastIndex Gets the index for the position in the cast list

Returns

MoaError

Description

Adds an existing external cast to the movie's cast list. Returns in pNewCastIndex the position of the cast in the movie's cast list.

AttachMedia()

Syntax

AttachMedia(PMoaDrMediaInfo pMediaInfo)

Parameters

pMediaInfo
PMoaDrMediaInfo Pointer to a caller-owned media information structure

Returns

MoaError

Description

Attaches media to a movie, releasing it from the caller. This is the same as SetMedia() except instead of copying the data, it is moved to the movie. (In effect, a SetMedia() call followed by ReleaseMedia().) Before making this call, use IMoaDrUtils::NewMediaInfo() to fill out the structure, specifying NULL for the aux field and kMoaDrMediaOpts_None for the options field.

On enter, the labelSymbol and formatSymbol fields should be populated with symbols indicating which chunk of media is to be attach (labelSymbol), and what format the media is supplied in (formatSymbol). The mediaData field should hold the data itself (typically a MoaHandle, Macintosh Handle, or Windows global handle)

Upon return, if there is no error, the media has changed ownership and belongs to the host application, and should no longer be referenced by the caller. This method is provided to allow the host application to optimize media-transfer if possible, preventing an extra copy of the media data, which may occur with separate SetMedia() and ReleaseMedia() calls).

CallHandler()

Syntax

CallHandler(MoaMmSymbol name, MoaLong nArgs, PMoaMmValue pArgs, PMoaMmValue pResult)

Parameters

name
MoaMmSymbol Symbol of the handler name to call

nArgs
MoaLong Number of arguments to pass

pArgs
PMoaMmValue Array of MoaMmValues containing the arguments to the call

pResult
PMoaMmValue Pointer to a caller-owned MoaMmValue to receive the return value

Returns

MoaError

Description

Calls the Lingo handler name in the movie. The nArgs argument is the number of arguments to the handler, the pArgs argument is a reference to the start of the array of arguments as MoaMmValues. You must pass in NULL to pResult if you do not expect a result. You must pass in a valid pointer if you do expect a result.

GetCastCount()

Syntax

GetCastCount(MoaLong FAR * pCastCount)

Parameters

pCastCount
MoaLong FAR * Pointer to a MoaLong to receive the number of casts

Returns

MoaError

Description

Obtains the number of casts in the movie.

GetCastFromName()

Syntax

GetCastFromName(PMoaChar pCastName, PIMoaDrCast FAR * ppIMoaDrCast)

Parameters

pCastName
PMoaChar Pointer to a null-terminated C string containing the cast name of interest

ppIMoaDrCast
PIMoaDrCast FAR * Pointer to a PIMoaDrCast to receive a pointer to the cast interface

Returns

MoaError

Description

Obtains an interface to one of the movie's casts by name, as it appears in the Cast Properties dialog. The interface is then owned by the caller, and the caller is responsible for releasing it when it is no longer needed.

GetCastIndexFromName()

Syntax

GetCastIndexFromName(PMoaChar pCastName, MoaDrCastIndex FAR * pCastIndex)

Parameters

pCastName
PMoaChar Pointer to a null-terminated C string containing the cast name of interest

pCastIndex
MoaDrCastIndex FAR * Pointer to a MoaDrCastIndex to receive the index

Returns

MoaError

Description

Obtains the movie cast index associated with a named cast. This is a value from 1 to GetCastCount().

GetCastMemFromCMRef()

Syntax

GetCastMemFromCMRef(PMoaDrCMRef pCastMemRef, PIMoaDrCastMem FAR * ppIMoaDrCastMem)

Parameters

pCastMemRef
PMoaDrCMRef Pointer to a MoaDrCMRef which specifies the cast member of interest

ppIMoaDrCastMem
PIMoaDrCastMem FAR * Pointer to a PIMoaDrCastMem to receive the interface for the cast member

Returns

MoaError

Description

Obtains the IMoaDrCastMem interface for the cast member with the supplied cast member reference. The cast member reference specifies the movieCastIndex (index to cast in the movie) and memberIndex (index to cast member slot position within the cast); use the CMRef_ macros in drtypes.h to create and access a 0. The caller owns the returned interface and is responsible for releasing it when it is no longer needed.

GetCMRefFromMemberName()

Syntax

GetCMRefFromMemberName(PMoaChar pMemberName, PMoaDrCMRef pCastMemRef)

Parameters

pMemberName
PMoaCharPointer to a null-terminated C string containing the cast member name of interest

pCastMemRef
PMoaDrCMRefPointer to a MoaDrCMRef to receive cast member reference

Returns

kMoaErr_NoErr Successful
kMoaDrErr_CastMemNotFound Cast member not found

Description

Obtains the cast member reference (MoaDrCMRef) for a cast member from its name. This method scans all of the casts for the movie, and returns the MoaDrCMRef for the first cast member whose name matches the one supplied. If no cast member is found with the specified name, kMoaDrErr_CastMemNotFound is returned and pCastMemRef is set to a null reference. Use CMRef_IsNull() to test the result.

GetFrameIndexFromLabel()

Syntax

GetFrameIndexFromLabel(PMoaChar pLabelName, PMoaDrFrameIndex pFrameIndex)

Parameters

pLabelName
PMoaChar Pointer to a null-terminated C-string containing the name of the marker associated with the score frame (case-insensitive)

pFrameIndex
PMoaDrFrameIndex Pointer to a MoaDrFrameIndex to receive the frame number of the label (marker)

Returns

kMoaErr_NoErr if successful, kMoaDrErr_LabelNotFound if marker doesn't exist.

Description

Obtains the frame number from a label (marker) name.

GetFrameLabelFromIndex()

Syntax

GetFrameLabelFromIndex(MoaDrFrameIndex frameIndex, PMoaChar pLabelName, MoaLong maxLen)

Parameters

frameIndex
MoaDrFrameIndex A MoaDrFrameIndex holding the frame number of interest

pLabelName
PMoaChar Pointer to a string buffer to receive the name of the marker associated with the given score frame

maxLen
MoaLong The length in bytes of the caller's C string buffer

Returns

MoaError

Description

Obtains the name of the label (marker) at a given score frame number. Returns an empty string if no marker exists for the frame.

GetMedia()

Syntax

PMoaDrMediaInfo pMediaInfo)

Parameters

pMediaInfo
PMoaDrMediaInfo Pointer to a caller-owned media information structure

Returns

MoaError

Description

Gets movie media data by obtaining a copy of the media associated with a movie. This is how one obtains the score data associated with a movie. Before making this call, use IMoaDrUtils::NewMediaInfo() to fill out the structure, specifying NULL for the aux field and kMoaDrMediaOpts_None for the options field. The caller partially populates a MoaDrMediaInfo structure with symbols indicating the requested chunk of media (labelSymbol) and the requested format (formatSymbol). After the call, the mediaData field is populated with the requested data. The type of this field depends on the format requested. The caller owns the data and is responsible for disposing it, if applicable. Typically, this data is either a MoaHandle, a Macintosh handle or pointer, or a Windows global handle. See Director property.rtf for a table of mediaLabels and mediaFormats supported for movies.

GetNthCast()

Syntax

GetNthCast(MoaDrCastIndex movieCastIndex, PIMoaDrCast FAR * ppIMoaDrCast)

Parameters

movieCastIndex
MoaDrCastIndex Index of the cast (from 1 to GetCastCount()) of interest

ppIMoaDrCast
PIMoaDrCast FAR * Pointer to a PIMoaDrCast to receive a pointer to the cast interface

Returns

MoaError

Description

Obtains an interface to one of the movie's casts by index. The interface is then owned by the caller, and the caller is responsible for releasing it when it is no longer needed.

GetProp()

Syntax

GetProp(MoaMmSymbol symbol, PMoaMmValue pPropValue)

Parameters

symbol
MoaMmSymbol The MoaMmSymbol for the property of interest

pPropValue
PMoaMmValue Pointer to a MoaMmValue to receive the value

Returns

kMoaErr_NoErr Property exists and value was returned
kMoaErr_BadParam Invalid pPropValue passed in
kMoaMmErr_PropertyNotFound Property isn't supported by this class
kMoaMmErr_InternalError Property exists but couldn't get due to internal error
kMoaMmErr_NoMemForString Couldn't allocate memory for string value data
kMoaErr_OutOfMem Couldn't allocate memory for other value data

Description

Obtains the value of the specified movie property. To get the symbol from a string, use the IMoaMmUtils::StringToSymbol(). The caller is responsible for releasing the value at pPropValue with IMoaMmUtils::ValueRelease() when it is no longer needed.

GetScoreAccess()

Syntax

GetScoreAccess(PIMoaDrScoreAccess FAR * ppScore)

Parameters

ppScore
PIMoaDrScoreAccess FAR *

Returns

MoaError

Description

Gets a ScoreAccess interface provider for the movie's score.

GetStageBufferGC()

Syntax

GetStageBufferGC(PIMoaMmGC FAR * ppBufferGC)

Parameters

ppBufferGC
PIMoaMmGC FAR * Pointer to a IMoaMmGC interface for the stage offscreen buffer

Returns

MoaError

Description

Obtains the graphics context for the stage offscreen buffer. This includes the bounds rectangle, pixel depth, as well as platform-specific information (such as the WindowPtr of the window on the Macintosh or the HWND on Windows). This information is valid only for the duration of the current call into your Xtra method, because the stage window can change in depth or size at any time (and may be disposed of and reallocated in the process). You must release the graphics context when done by calling its Release() method.
Important note about graphic contexts
This method should only be called by Lingo and Tool Xtras to do temporary drawing into the stage window. It should be called just before doing your drawing, and the acquired interface should be released before returning control to the calling application. This is because nativeGCInfo for the stage buffer can become invalid at any time. For example, the buffer may be dumped and recreated if window size, monitor depth, or other display characteristics change.

It's not always possible to obtain the a graphics context for the stage buffer. During registration, startup, and shut-down, internal movie data structures may not be initialized, thus trying to get the GC for it will return the err kMoaDrErr_MovieNotOpen. Xtra developers should never attempt to acquire a graphics context and hold onto it; instead, you should acquire the interface each time you need to draw and release it before your method returns.

Finally, this method should not be called to get a context for sprite or transition drawing. Instead, use the graphic context passed to you explicitly in IMoaMmSpriteActor::Image() or IMoaDrTransitionActor::Continue(). If you attempt to use this context, your Xtra will not work correctly in MIAWs, export, or other applications such as Authorware.

GetStageWindowGC()

Syntax

GetStageWindowGC(PIMoaMmGC FAR * ppWindowGC)

Parameters

ppWindowGC
PIMoaMmGC FAR * Pointer to a IMoaMmGC interface for the stage window

Returns

MoaError

Description

Obtains the graphics context for the stage window. This includes the bounds rectangle, pixel depth, as well as platform-specific information (such as the WindowPtr of the window on the Macintosh, or the HWND on Windows). This information is valid only for the duration of the current call into your Xtra method, because the stage window can change in depth or size at any time (and may be disposed of and reallocated in the process). You must release the graphics context when done by calling its Release() method.
Important note about graphic contexts
This method should only be called by Lingo and Tool Xtras to do temporary drawing into the stage window. It should be called just before doing your drawing, and the acquired interface should be released before returning control to the calling application. This is because nativeGCInfo for the stage buffer can become invalid at any time. For example, the buffer may be dumped and recreated if window size, monitor depth, or other display characteristics change.

It's not always possible to obtain the a graphics context for the stage window. During registration, startup, and shut-down, internal movie data structures may not be initialized, thus trying to get the GC for it will return the err kMoaDrErr_MovieNotOpen. Xtra developers should never attempt to acquire a graphics context and hold onto it; instead, you should acquire the interface each time you need to draw and release it before your method returns.

Also, GetStageWindowGC() should not be used to get a parent window for Windows(TM) dialogs. The correct procedure is to use the IMoaMmUtils Windows API cover methods such as WinDialogBox() and WinDialogBoxParam(). If you're putting up a system dialog on Windows, use WinGetParent() to get the parent HWND to use, and bracket your dialog call with WinPrepareDialogBox() and WinUnprepareDialogBox().

Finally, these calls should not be used for sprite or transition drawing. Instead, use the graphic context passed to you explicitly in IMoaMmSpriteActor::Image() or IMoaDrTransitionActor::Continue(). If you do attempt to use this context, your Xtra will not work correctly in MIAWs, export, or other applications such as Authorware.

NewCast()

Syntax

NewCast(PMoaChar pCastName, MoaBoolParam bExternal, PMoaDrCastIndex pNewCastIndex)

Parameters

pCastName
PMoaChar

bExternal
MoaBoolParam

pNewCastIndex
PMoaDrCastIndex

Returns

MoaError

Description

Creates a new cast and add it to the movie's cast list. Returns the position of the new cast in the pNewCastIndex argument.

RemoveCast()

Syntax

MoaDrCastIndex castIndexToRemove)

Parameters

castIndexToRemove
MoaDrCastIndex MoaDrCastIndex for the cast to remove

Returns

MoaError

Description

Removes the cast specified by castToRemove from the movie's cast list.

Save()

Syntax

Save(PMoaChar pNewPathName, MoaBoolParam bSaveExtCasts)

Parameters

pNewPathName
PMoaChar Null-terminated C string for the path

bSaveExtCasts
MoaBoolParam

Returns

kMoaErr_NoErr Successful
kMoaDrErr_DiskIO IO error during file access

Description

Saves the movie to the path. Specify the complete path, including file name, to save the cast to a new file. Pass NULL as pNewPathName to save the cast in its previous file.

SendSpriteMessage()

Syntax

SendSpriteMessage(MoaDrSpriteChanIndex chanIndex, MoaMmSymbol handlerName, MoaLong nArgs, PMoaMmValue pArgs, PMoaMmValue pResult, MoaBool FAR * pHandled)

Parameters

chanIndex
MoaDrSpriteChanIndex Channel number of sprite to which to send the message. Valid values are from 1 to 48.

handlerName
MoaMmSymbol Symbol for the handler (message) name

nArgs
MoaLong Number of arguments you're passing

pArgs
PMoaMmValue Pointer to an array of MoaMmValues containing arguments

pResult
PMoaMmValue Pointer to a MoaMmValue to receive a result

pHandled
MoaBool FAR * arguments to a MoaBool to receive TRUE if the message was handled somewhere down the chain or FALSE if it was not.

Returns

MoaError

Description

Sends a sprite message to be passed through the standard Director sprite message hierarchy beginning with the sprite script of the sprite in the specified channel. This method is similar to IMoaDrSpriteCallback::SendSpriteMessage().You must pass in NULL to pResult if you do not expect a result; you must pass in a valid pointer if you do expect a result.

SetFrameLabel()

Syntax

SetFrameLabel(MoaDrFrameIndex frameIndex, PMoaChar pLabelName)

Parameters

frameIndex
MoaDrFrameIndex A MoaDrFrameIndex holding the number of the frame

pLabelName
PMoaChar Pointer to a MoaChar to receive the name of the marker associated with the given score frame

Returns

MoaError

Description

Adds, modifies, or deletes a score label (marker) or a frame. You pass in the frame number and a C string for the new label. If a label doesn't exist for that frame, one will be added. If one does exist, it'll be replaced with the new one you specify. If you pass in NULL for pLabelName, any current label for that frame is deleted.

SetMedia()

Syntax

SetMedia(PMoaDrMediaInfo pMediaInfo)

Parameters

pMediaInfo
PMoaDrMediaInfo Pointer to a caller-owned media information structure

Returns

MoaError

Description

Sets movie media data. This is how one replaces the score data associated with a movie. This method copies caller-supplied media data and associates it with the movie. Before making this call, use IMoaDrUtils::NewMediaInfo() to fill out the structure, specifying NULL for the aux field and kMoaDrMediaOpts_None for the options field. The caller populates a MoaDrMediaInfo structure with symbols indicating the supplied chunk of media (labelSymbol) and the supplied format (formatSymbol), and the media data itself (mediaData). If the label and format are supported by the movie, a call to this method copies the caller's data and replaces any existing media data for the supplied label for the movie. Since the data is copied, the caller retains ownership of the media data passed in. Typically this data is either a MoaHandle, a Macintosh handle or pointer, or a Windows global handle. See Director property.rtf for a table of mediaLabels and mediaFormats supported for movies.

SetProp()

Syntax

SetProp(MoaMmSymbol symbol, ConstPMoaMmValue pPropValue)

Parameters

symbol
MoaMmSymbol The MoaMmSymbol for the property of interest

pPropValue
ConstPMoaMmValue Pointer to a caller-owned ConstPMoaMmValue structure from which to copy the new value

Returns

kMoaErr_NoErr Property exists and value was set
kMoaErr_BadParam Invalid pPropValue passed in
kMoaMmErr_PropertyNotFound Property isn't supported by this class
kMoaMmErr_InternalError Property exists, value ok, couldn't set--internal error
kMoaMmErr_NoMemForString Couldn't allocate memory for setting string value data
kMoaErr_OutOfMem Couldn't allocate memory for setting other value data
kMoaMmErr_IntegerExpected Type mismatch: integer value expected
kMoaMmErr_SymbolExpected Type mismatch: symbol value expected
kMoaMmErr_FloatExpected Type mismatch: float value expected
kMoaMmErr_StringExpected Type mismatch: string value expected
kMoaMmErr_PointExpected Type mismatch: point value expected
kMoaMmErr_RectExpected Type mismatch: rect value expected
kMoaMmErr_ValueTypeMismatch Type mismatch: other value expected (non-specific)
kMoaDrErr_CastMemberExpected Type mismatch: CMRef value expected

Description

Sets the value of the specified property. To get the symbol from a string, use the IMoaMmUtils::StringToSymbol() method. The caller continues to maintain ownership of the value passed in, and should release it using IMoaMmUtils::ValueRelease() when it is no longer needed.

UpdateStageRect()

Syntax

UpdateStageRect(MoaRect FAR * pWindowRect, MoaRect FAR * pBufferRect)

Parameters

pWindowRect
MoaRect FAR * Pointer to a MoaRect describing the area of the stage window to update

pBufferRect
MoaRect FAR * Pointer to a MoaRect describing the area of the offscreen buffer from where to update

Returns

MoaError

Description

Updates a rectangular area of the stage window from a rectangular area of the stage's offscreen buffer. Stretching or shrinking of parts of the image can be achieved by using a windowRect which differs in size from the bufferRect. Note that this call does not cause all sprites on the stage to be reimaged; it simply refreshes the stage window from Director's offscreen compositing buffer.

Copyright © 1995-2007 Adobe Macromedia Software LLC, Inc.