IMoaDrPlayer

Interface ID: IID_IMoaDrPlayer
Pointer type: PIMoaDrPlayer
Inheritance: IMoaMmPropOwner
Header file: driservc.h

Methods

Property owner methods

GetProp()
SetProp()

Scripting support

CallHandler()
GetGlobalVarValue()
SetGlobalVarValue()

Movie access

GetActiveMovie()
GetMovieCount()
GetNthMovie()

Accessing files

ResolveFileName() A change to a parameter type was made for D7 & later.

Cast member access

GetCastMemTypeCount()
GetNthCastMemTypeSymbol()
GetCastMemTypeDisplayName()

CallHandler()

Syntax

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

Parameters

name

MoaMmSymbolThe MoaMmSymbol for the name of the method to call

nArgs

MoaLongThe number of arguments you are passing to the handler

pArgs

PMoaMmValueThe array of MoaMmValue arguments

pResult

PMoaMmValuePointer to a caller-owned MoaMmValue to receive a result value from the handler

Returns

MoaError

Description

Calls the Lingo handler name in the currently active 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.

This method has the same behavior as obtaining the active movie interface by calling GetActiveMovie(), and then calling IMoaDrMovie::CallHandler(). This method is supplied as a convenience, as it eliminates the extra call needed to GetActiveMovie() for this common operation.

GetActiveMovie()

Syntax

GetActiveMovie(PIMoaDrMovie FAR * ppIMoaDrMovie)

Parameters

ppIMoaDrMovie

PIMoaDrMovie FAR * Pointer to a PIMoaDrMovie to receive new interface

Returns

MoaError

Description

Gets an interface to the currently active movie. The active movie may vary depending upon the context in which this method is called. If there are no MIAWs executing, the active movie is the single main movie currently being played. If MIAWs are present, the active movie can be a MIAW. This is the case if a Lingo Xtra is being called by a MIAW Lingo script; if an asset Xtra is being used by a MIAW; or if a Transition Xtra is being called on behalf of a MIAW. The caller is responsible for releasing the movie interface when it is no longer needed.

GetCastMemTypeCount()

Syntax

GetCastMemTypeCount(MoaLong FAR * pTypeCount)

Parameters

pTypeCount

MoaLong FAR * Pointer to a MoaLong to receive the count

Returns

MoaError

Description

Obtains the number of currently registered cast member types. This value is the sum of Director's built-in types and any types registered by external asset Xtras.

GetCastMemTypeDisplayName()

Syntax

GetCastMemTypeDisplayName(MoaMmSymbol typeSymbol, PMoaChar pName, MoaLong maxLen)

Parameters

typeSymbol

MoaMmSymbol The symbol of the type of interest

pName

PMoaChar Pointer to buffer to receive null-terminated C string text of the display name

maxLen

MoaLong Size of the caller's name buffer

Returns

MoaError

Description

Obtains the user-readable text string associated with a cast member type. This is the same string that appears in the Insert submenu in Director. You can obtain typeSymbol using StringToSymbol() or GetNthCastMemTypeSymbol().

GetGlobalVarValue()

Syntax

GetGlobalVarValue(MoaMmSymbol globalVarName, PMoaMmValue pValue)

Parameters

globalVarName

MoaMmSymbol The symbol of the global variable of interest

pValue

PMoaMmValue Pointer to a MoaMmValue to receive the value

Returns

MoaError

Description

Obtains the value of a Lingo global variable. Use IMoaMmUtils::StringToSymbol() to get a symbol from a string for globalVarName. The caller is responsible for releasing the value with IMoaMmUtils::ValueRelease() when it is no longer needed.

GetMovieCount()

Syntax

GetMovieCount(MoaLong FAR *pMovieCount)

Parameters

pMovieCount

MoaLong FAR * Pointer to a MoaLong to receive count of open movies

Returns

MoaError

Description

Obtains the current number of movies open in the player. In Director 5.0, there is always at least one open movie, the main stage movie. Each open movie in a window also contributes to the movie count. Using GetNthMovie(), you can access any open movie directly.

GetNthCastMemTypeSymbol()

Syntax

GetNthCastMemTypeSymbol(MoaLong typeIndex, PMoaMmSymbol pSymbol)

Parameters

typeIndex

MoaLong Index (from 1 to GetCastMemTypeCount()) of the cast member type of interest

pSymbol

PMoaMmSymbol Pointer to a MoaMmSymbol to receive the type's symbol

Returns

MoaError

Description

Obtains the unique run-time symbol for the specified cast member type by index. This symbol is then passed as a parameter to callback methods operating on cast member types, such as GetCastMemTypeDisplayName().

GetNthMovie()

Syntax

GetNthMovie(MoaLong movieIndex, PIMoaDrMovie FAR * ppIMoaDrMovie)

Parameters

movieIndex

MoaLong Index of movie to obtain interface for; ranges from 1 to the number of open movies

ppIMoaDrMovie

PIMoaDrMovie FAR * Pointer to a PIMoaDrMovie to receive new interface

Returns

MoaError

Description

Gets an interface to the nth movie in the player's movie list. There's always at least one open movie in Director 5.0, the main stage movie. Use GetMovieCount() to determine the number of open movies. Using this method, you could, for example, access data in a Movie In A Window even though you're currently being called in the context of the main stage movie. The caller is responsible for releasing the movie interface 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 caller-owned MoaMmValue structure to receive the value of the property

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 player property. To get the symbol from a string, use the IMoaMmUtils::StringToSymbol().The caller is responsible for releasing the value with IMoaMmUtils::ValueRelease() when it is no longer needed.

ResolveFileName()

Syntax

ResolveFileName(ConstPMoaChar pFileName, PMoaChar pPathName, MoaLong maxLen)

Parameters

pFileName

ConstPMoaChar Pointer to C string of filename in native platform format to resolve. Prior to D7, this parameter was a PMoaChar.

pPathName

PMoaChar Pointer to C string to receive resolved full pathname

maxLen

MoaLong Size of the caller's pPathName buffer

Returns

MoaError

Description

Resolves a file name to a full path name using Director's standard filename resolution algorithm. This can include scanning the searchPaths, and so on, for the appropriate file. Director's "@:" filename notation is also supported here.

SetGlobalVarValue()

Syntax

SetGlobalVarValue(MoaMmSymbol globalVarName, PMoaMmValue pValue)

Parameters

globalVarName

MoaMmSymbol The symbol of the global variable of interest

pValue

PMoaMmValue Pointer to a MoaMmValue to copy the new value from

Returns

MoaError

Description

Sets the value of a Lingo global variable. Use IMoaDrUtils->StringToSymbol() to get a symbol from a string for globalVarName. The caller maintains ownership of the value passed in, and should release it using IMoaMmUtils::ValueRelease() when it is no longer needed.

SetProp()

Syntax

SetProp(MoaMmSymbol symbol, ConstPMoaMmValue pPropValue)

Parameters

symbol

MoaMmSymbol The MoaMmSymbol for the property of interest

pPropValue

ConstPMoaMmValue Pointer to a caller-owned MoaMmValue structure from which to copy the 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, can't set--internal error
kMoaMmErr_NoMemForString	Can't allocate memory for setting string value data
kMoaErr_OutOfMem	Can'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 a player property to a new value. To get the symbol from a string, use the IMoaMmUtils::StringToSymbol(). The caller continues to maintain ownership of the value passed in, and should release it using IMoaMmUtils::ValueRelease() when it is no longer needed.