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

IMoaDrMovie2

Interface ID: IID_IMoaDrMovie2
Pointer type: PIMoaDrMovie2
Inheritance: IMoaDrMovie
Header file: driservc.h
Description
The IMoaDrMovie2 interface is an extension of IMoaDrMovie which represents open movies in Director. You acquire an IMoaDrMovie interface by calling the IMoaDrPlayer methods GetActiveMovie() or GetNthMovie(). This returns to you an IMoaDrMovie interface. You can use the QueryInterface method off this interface to retrieve an IMoaDrMovie2 interface. IMoaDrMovie2 has a few additional methods - for convenience the rest of the methods of these two interfaces are exactly the same.
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 Development Guide document. See the "Properties" section for information on the properties defined for objects providing the MoaDrMovie interfaces.
Movie media
The IMoaDrMovie interfaces inherit from the IMoaDrMediaOwner interface, providing for access to media through the media owner mechanism described in the "Director Services" chapter in the Development 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 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()
Working with cast members
GetCastMemFromCMRef()
GetCMRefFromMemberName()
GetCMRefFromCMId() only in IMoaDrMovie2
GetCMIdFromCMRef() only in IMoaDrMovie2
MoveCastMember() only in IMoaDrMovie2
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
The user reference name for the cast
pPathName
The full path name for an external cast
pNewCastIndex
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
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 attached (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
Symbol of the handler name to call
nArgs
Number of arguments to pass
pArgs
Array of MoaMmValues containing the arguments to the call
pResult
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 can 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 * pCastCount)
Parameters
pCastCount
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 * ppIMoaDrCast)
Parameters
pCastName
Pointer to a null-terminated C string containing the cast name of interest
ppIMoaDrCast
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 * pCastIndex)
Parameters
pCastName
Pointer to a null-terminated C string containing the cast name of interest
pCastIndex
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 * ppIMoaDrCastMem)
Parameters
pCastMemRef
Pointer to a MoaDrCMRef which specifies the cast member of interest
ppIMoaDrCastMem
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 MoaDrCMRef. The caller owns the returned interface and is responsible for releasing it when it is no longer needed.

GetCMIdFromCMRef()

Syntax
GetCMIdFromCMRef(PMoaDrCMRef pCastMemRef, PMoaDrCMId pCastMemId)
Parameters
pCastMemRef
Pointer to a MoaDrCMRef identifying the cast member we want a unique ID from
pCastMemId
Pointer to a MoaDrCMId to recieve the unique cast member identifier
Returns
MoaError
Description
This method is only available in IMoaDrMovie2. Obtains a unique identifier (MoaDrCMId) for the cast member referred to by pCastMemRef. This identifer can be used to retrieve the MoaDrCMRef for this cast member at a later time, even if the cast member has been moved across cast boundaries.

GetCMRefFromCMId()

Syntax
GetCMRefFromCMId(PMoaDrCMId pCastMemId, PMoaDrCMRef pCastMemRef)
Parameters
pCastMemId
Pointer to a MoaDrCMId identifying the cast member to search for
pCastMemRef
Pointer to a MoaDrCMRef to receive cast member reference
Returns
kMoaErr_NoErr Successful
kMoaDrErr_CastMemNotFound Cast member not found
Description
This method is only available in IMoaDrMovie2. Obtains the cast member reference (MoaDrCMRef) for a cast member from its unique identifier. This method scans all of the casts for the movie, and returns the MoaDrCMRef for the cast member whose id matches the one supplied. If no cast member is found with the specified id, kMoaDrErr_CastMemNotFound is returned and pCastMemRef is set to a null reference. Use CMRef_IsNull() to test the result.

GetCMRefFromMemberName()

Syntax
GetCMRefFromMemberName(PMoaChar pMemberName, PMoaDrCMRef pCastMemRef)
Parameters
pMemberName
Pointer to a null-terminated C string containing the cast member name of interest
pCastMemRef
Pointer 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
Pointer to a null-terminated C-string containing the name of the marker associated with the score frame (case-insensitive)
pFrameIndex
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
A MoaDrFrameIndex holding the frame number of interest
pLabelName
Pointer to a string buffer to receive the name of the marker associated with the given score frame
maxLen
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
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 * ppIMoaDrCast)
Parameters
movieCastIndex
Index of the cast (from 1 to GetCastCount()) of interest
ppIMoaDrCast
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
The MoaMmSymbol for the property of interest
pPropValue
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. The properties defined for objects providing the IMoaDrMovie2 interface are listed here.

GetScoreAccess()

Syntax
GetScoreAccess(PIMoaDrScoreAccess * ppScore)
Parameters
ppScore
PIMoaDrScoreAccess *
Returns
MoaError
Description
Gets a ScoreAccess interface provider for the movie's score.

GetStageBufferGC()

Syntax
GetStageBufferGC(PIMoaMmGC * ppBufferGC)
Parameters
ppBufferGC
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 * ppWindowGC)
Parameters
ppWindowGC
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.

MoveCastMember()

Syntax
MoveCastMember(PMoaDrCMRef pSrcMemRef, PMoaDrCMRef pDestMemRef)
Parameters
pSrcMemRef
Pointer to MoaDrCMRef containing cast member to move
pDestMemRef
Pointer to MoaDrCMRef containing location to move to
Returns
MoaError
Description
This method is only available in IMoaDrMovie2. Moves the cast member in the location referred to by pSrcMemRef to the location referred to by pDestMemRef. If there is an existing cast member in the destination slot, it will be removed.

NewCast()

Syntax
NewCast(PMoaChar pCastName, MoaBoolParam bExternal, PMoaDrCastIndex pNewCastIndex)
Parameters
pCastName
Pointer to the name to use for the cast
bExternal
Pass in TRUE if the cast is external or FALSE if it will be internal
pNewCastIndex
Gets the position of the new cast in the movie
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 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
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 movie to a new file. Pass NULL as pNewPathName to save the movie in its previous file.

SendSpriteMessage()

Syntax
SendSpriteMessage(MoaDrSpriteChanIndex chanIndex, MoaMmSymbol handlerName, MoaLong nArgs, PMoaMmValue pArgs, PMoaMmValue pResult, MoaBool * pHandled)
Parameters
chanIndex
Channel number of sprite to which to send the message.
handlerName
Symbol for the handler (message) name
nArgs
Number of arguments you're passing
pArgs
Pointer to an array of MoaMmValues containing arguments
pResult
Pointer to a MoaMmValue to receive a result
pHandled
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
A MoaDrFrameIndex holding the number of the frame
pLabelName
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
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
The MoaMmSymbol for the property of interest
pPropValue
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 froma 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. The properties defined for objects providing the IMoaDrMovie2 interface are listed here.

UpdateStageRect()

Syntax
UpdateStageRect(MoaRect * pWindowRect, MoaRect * pBufferRect)
Parameters
pWindowRect
Pointer to a MoaRect describing the area of the stage window to update
pBufferRect
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-2008 Adobe Macromedia Software LLC, Inc.