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

IMoaMmXSpriteActor

Interface ID: IID_IMoaMmXSpriteActor
Pointer type: PIMoaMmXSpriteActor
Inheritance: IMoaMmPropOwner
Header file: mmixasst.h

Description

The IMoaMmXSpriteActor interface lets an asset Xtra implement runtime behavior for presenting during playback of a multimedia piece. The methods of this interface enable asset Xtras to describe their capabilities to an application, to draw themselves, to handle events, and to interact with their asset and the application.

Methods

Scripting support

GetProp()
SetProp()
CallFunction()

Asset interaction

SetCallback()
Notify()

Event handling

GetCaps()
ContainsPoint()
Event()

Imaging

CollectChanges()
Image()

CallFunction()

Syntax

CallFunction(PIMoaMmXSpriteActorThis,

MoaMmSymbolmethodName,
MoaLongnArgs,
ConstPMoaMmValuepArgs,
PMoaMmValuepResult)

Parameters

This

Pointer to the IMoaMmXSpriteActor interface

methodName

MoaMmSymbolSymbol of the method (function) to call

nArgs

MoaLongNumber of arguments, excluding reserved value in pArgs[0]

pArgs

ConstPMoaMmValueArray of arguments, with the first valid argument at pArgs[1]

pResult

PMoaMmValuett>Pointer to a MoaMmValue to receive a result value, if any

Returns

kMoaErr_NoErr	Function exists and operation was successful
kMoaErr_BadParam	Invalid nArgs, pArgs, or pResult passed in
kMoaMmErr_FunctionNotFound	Function not supported by this actor
kMoaErr_OutOfMem	Couldn't allocate memory needed to execute function
kMoaMmErr_InternalError	Function exists, args ok, can't execute internal error
kMoaMmErr_NoArgExpected	Wrong number of args: 0 expected
kMoaMmErr_OneArgExpected	Wrong number of args: 1 expected
kMoaMmErr_TwoArgsExpected	Wrong number of args: 2 expected
kMoaMmErr_ThreeArgsExpected	Wrong number of args: 3 expected
kMoaMmErr_FourArgsExpected	Wrong number of args: 4 expected
kMoaMmErr_WrongNumberOfArgs	Wrong number of arguments, non- specific
kMoaMmErr_IntegerExpected	Type mismatch: integer value argument expected
kMoaMmErr_SymbolExpected	Type mismatch: symbol value argument expected
kMoaMmErr_FloatExpected	Type mismatch: float value argument expected
kMoaMmErr_StringExpected	Type mismatch: string value argument expected
kMoaMmErr_PointExpected	Type mismatch: point value argument expected
kMoaMmErr_RectExpected	Type mismatch: rect value argument expected
kMoaMmErr_ValueTypeMismatch	Type mismatch: other value argument expected
kMoaDrErr_CastMemberExpected	Type mismatch: CMRef value argument expected (Director only)

Description

Calls a sprite actor scripting function. This method allows sprite actors to export arbitrary functions to be used in the host application's scripting or expression language. The caller passes the symbol of the function to call in the methodName parameter, along with the argument count (nArgs), the argument array (pArgs), and optionally, a pointer to a MoaMmValue to receive any result value. The argument array, pArgs, contains an array of MoaMmValues corresponding to the function arguments. pArgs[0] is a reserved value and should not be referenced. The function parameters are supplied in pArgs[1] through pArgs[nArgs]. These MoaMmValues are owned by the host application and should not be released by this method. If the method has a return value, it should populate pResult with a new MoaMmValue containing the result. If the Xtra does not support the function specified by methodName, it should return the error code kMoaMmErr_FunctionNotFound. If the number or types of arguments are incorrect, the function should return one of the appropriate MoaMmErrors (see mmtypes.h).

CollectChanges()

Syntax

CollectChanges(PIMoaMmXSpriteActorThis,

ConstPMoaMmXSpriteInfopActorInfo,
PIMoaMmChangeCollectorpChangeCollector)

Parameters

This

Pointer to the IMoaMmXSpriteActor interface

pActorInfo

ConstPMoaMmXSpriteInfoPointer to an ActorInfo structure for context in which actor is imaged

pChangeCollector

PIMoaMmChangeCollectorPointer to an IMoaMmChangeCollector interface

Returns

kMoaErr_NoErr	Successful, change rects (if any) submitted
kMoaMmErr_NotImplemented	Sprite is static, updates are requested using InvalSpriteRect(). You must set the kMoaMmXSpriteCapsFlags_IsStatic sprite caps flag in your GetCaps().

Description

Obtains change rectangles for the actor. This method is called for all actors that have not otherwise changed from the current frame to the next (sprite rectangle, ink mode, color, and so on. are the same). This gives the actor an opportunity to let the host application know of any changes occurring within the actor's bounding box, so that the actor can be called back to image those changes. Using the supplied IMoaMmChangeCollector interface, CollectChanges() can submit multiple change rectangles. For each rectangle, call pChangeCollector->lpVtbl->AddChangeRect() with the rectangle to submit. Submitting an empty rectangle has no effect. If there are no change rectangles, return kMoaErr_NoErr without calling pChangeCollector->lpVtbl->AddChangeRect(). To optimize compositing, you can call AddChangeRectAbove() instead of AddChangeRect(). This should be used only if the rectangle specified is completely opaque in your sprite; this tells the host application that it is not necessary to redraw the area directly behind the supplied rectangle. Even if the host application does not support this optimization, it still accepts AddChangeRectAbove(); in this case, AddChangeRectAbove() has the same effect as AddChangeRect().

ContainsPoint()

Syntax

ContainsPoint(PIMoaMmXSpriteActorThis,

ConstPMoaMmXSpriteInfopActorInfo,
ConstPMoaPointpTestPoint,
MoaBoolParam FAR *pTestResult)

Parameters

This

Pointer to the IMoaMmXSpriteActor interface

pActorInfo

ConstPMoaMmXSpriteInfoPointer to MoaMmXSpriteInfo for context in which actor draw

pTestPoint

ConstPMoaPointPointer to the point to test

pTestResult

MoaBoolParam FAR *Pointer to MoaLong for result: 0 if not within, non-0 if within

Returns

kMoaErr_NoErr

Successful, pTestResult set

Description

Queries the actor to determine if a given point lies within its visual region in the playback window. The actor should use the information in pActorInfo (sprite rectangle, ink mode, and so on) and the point supplied in pTestPoint, to perform the test. The result of the test should be returned in pTestResult: 0 if the point is not within the area occupied by the actor sprite; non-0 if it is. If the actor's shape is non-rectangular, the test should take this into account and not use the sprite rectangle. This is called by the host application when mouse hit-testing and rollover-testing is being performed.

Event()

Syntax

Event(PIMoaMmXSpriteActorThis,

ConstPMoaMmEventInfopEventInfo,
ConstPMoaMmPlayerStateInfopPlayerStateInfo,
MoaBoolParam FAR *pHandled)

Parameters

This

Pointer to the IMoaMmXSpriteActor interface

pEventInfo

ConstPMoaMmEventInfoPointer to a MoaMmEventInfo structure containing information about the event

pPlayerStateInfo

ConstPMoaMmPlayerStateInfoPointer to a caller-owned structure containing various state information about the player

pHandled

MoaBoolParam FAR *Pointer to a MoaLong to receive the handled status of the event; 0 if the event is to be passed along (not handled), or non-0 if the actor absorbed the event.

Returns

kMoaErr_NoErr	Successful, event handled or intentionally passed
kMoaErr_OutOfMem	Wanted event but couldn't handle due to memory error
kMoaMmErr_InternalError	Wanted event but couldn't handle due to an internal error

Description

Notifies an actor that an event of interest has occurred. The actor subscribes to sets of events by setting the appropriate flags in the eventMask field of the MoaMmXSpriteCaps structure returned by its IMoaMmXSpriteActor::GetCaps() method.

Events fall into the following categories:

• mouse events
• keyboard events
• idle events
• step events
• span events
• play events (received only at authoring time)
• environment change events

See the description of the MoaMmEventInfo type and associated constants later in this chapter for more details on these event types.

Each time the Event() method is called, the pEventInfo structure passed in contains the identity of the specific event type being sent. A number of events include additional information, including time and mouse position. These include mouseDown, mouseUp, mouseUpOut, mouseDblClick, rightMouseDown, rightMouseUp, rightMouseUpOut, rightMouseDblClick, keyDown, keyUp, idle, and step.

Note: in Director, the modify key fields of the event info structure are not updated for events received while the mouse button is down. To get the actual values of any modify keys, you'll need to use native OS calls.

The actor should set the value at pHandled to TRUE if it handled the event, or FALSE if it wants to pass the event along to other objects in the event hierarchy (such as sprite scripts in Director).

Important: In almost all cases, imaging should only occur in your Image() method. Only direct-to-screen actors, which need to image independently of the animation tempo (such as digital video or other time-based media) should image in response to events. In this case, only the idle event should be used. Offscreen imaging or imaging in response to any other events is not supported and may have unpredictable results.

The posting of idle events is application and CPU-dependent. Idle events are posted when the host application has free cycles; you are not guaranteed to get any idle events. Idle events should be used only to perform optional background tasks such as the servicing of time-based media. Time- based media should also be serviced when receiving Step events, which are guaranteed to occur once, and only once, per animation frame.

If you need data from the actor information in your Event() method (such as the sprite rectangle), save it in an instance variable from your last Image() method. If you need a graphic context during an Event()method call, (for example to image sprite direct-to-stage during idle events), save a native representation (for example, a WindowPtr) obtained from the graphic context in your Image() method. The WindowPtr/HWND may not be in existance for the entire life of an actor instance. Changing some window properties may cause a window to get destroyed and recreated. Starting with Director MX 2004 this is more likely to occur, as it happens when windows are docked/undocked in authoring, or when the display template properties associated with a window are changed.

The events should be used only to set internal state information. For example, rather than doing span initialization (that may require the actor information and a graphic context) in your SpanBegin code in an Event()method, set an internal state variable, then initialize it when your Image() method is called, so you'll have actor information and a graphic context available.

Pass back the value kMoaMmSprEvent_Handled as pHandled if the event is completely handled by your code and shouldn't be passed to the next event handler. Pass back kMoaMmSprEvent_Pass if the event should be passed to the next event handler.

GetCaps()

Syntax

GetCaps(PIMoaMmXSpriteActorThis,

PMoaMmXSpriteCapspActorCaps)

Parameters

This

Pointer to the IMoaMmXSpriteActor interface

pActorCaps

PMoaMmXSpriteCapsPointer to a MoaMmXSpriteCaps structure to receive actor capabilities

Returns

kMoaErr_NoErr

Successful

Description

Obtains the sprite actor capabilities for this sprite actor. This method is called by the host application directly after the actor instance is created. As it plays, a sprite may update its capabilities by calling the IMoaMmSpriteCallback::InvalSpriteCaps() method; this forces the host to call the GetCaps() method again.

This method should populate all of the fields of the supplied MoaMmXSpriteCaps structure: the eventMask, flags, requiredImageMode, and preferredImageMode. The following tables describe these fields. For more information, see mmtypes.h for the event masks, flags, and image modes.

The eventMask indicates what classes of events the actor wishes to receive (such as mouse events, keyboard events, and so on.).

• kMoaMmEventMask_Every
• kMoaMmEventMask_Idle
• kMoaMmEventMask_Mouse
• kMoaMmEventMask_Key
• kMoaMmEventMask_Play (authoring only)
• kMoaMmEventMask_Step
• kMoaMmEventMask_Span
• kMoaMmEventMask_Environment

The flags field indicates whether the actor supports various capabilities, such as auto-tab keyboard focus handling and persistency across sprite spans.

• kMoaMmXSpriteCapsFlags_IsStatic

Specifies whether the actor can be animates or if it is always a static image. This information can be used to optimize compositing in the host application. When set, the sprite actor does not change in appearance, play sound, or do anything else which would require it to be serviced regularly. When not set, the sprite actor can animate, play sound, and so on. In addition to setting this flag, static actors should not subscribe to idle and step events for optimum performance. This setting is valid only for offscreen imaging actors, since it results in CollectChanges() not being called. A static actor can call IMoaMmSpriteCallback::InvalSpriteRect() method to force the call to its CollectChanges()method.

• kMoaMmXSpriteCapsFlags_AutoTabEnabled

Applies only to actors wanting keyboard events. This is accomplished by setting the kMoaMmEventMask_Key bit in the eventMask part of the actor capabilities structure. When set, pressing the TAB key while this actor has the focus causes the host application to switch to the next focus-capable actor in the current frame, removing focus from this actor. In this mode, the TAB key is not passed to the actor and is absorbed by the host application instead. When not set, pressing the TAB key causes the host application to pass the key through to the actor through the Event() method, like all other keys. In this mode, the TAB key is not absorbed by the application and the actor does not lose focus when it is pressed.

The requiredImageMode field specifies which, if any, imaging modes are required for the Xtra to function.

• kMoaMmXSpriteImageMode_Any

Both offscreen and direct-to-screen imaging are supported. When set, you can specify preferredImageMode.

• kMoaMmXSpriteImageMode_Offscreen

Only offscreen imaging is supported

• kMoaMmXSpriteImageMode_DirectToScreen

Only direct-to-screen imaging is supported.*

The preferredImageMode field is only relevant if the requiredImageMode is set to kMoaMmXSpriteImageMode_Any. When set, preferredImageMode specifies the default or optimal imaging mode for the actor.

• kMoaMmXSpriteImageMode_Any

Both offscreen and direct-to-screen imaging are equally supported; the host application should use whatever default it sees fit.

• kMoaMmXSpriteImageMode_Offscreen

Offscreen imaging is preferred; this mode should be used if possible.

• kMoaMmXSpriteImageMode_DirectToScreen

Direct-to-screen imaging is preferred; this mode should be used if possible.*

*Note: sprites that draw direct-to-screen must always fill their entire default rectangle (provided by the IMoaMmXAsset::GetDefaultRect() method); otherwise, the host application may leave unexpected artifacts in the unfilled areas of the sprite's bounds.

GetProp()

Syntax

GetProp(PIMoaMmXSpriteActorThis,

MoaMmSymbolsymbol,
PMoaMmValuepPropValue)

Parameters

This

Pointer to the IMoaMmXSpriteActor interface

symbol

MoaMmSymbolMoaMmSymbol representing the requested property

pPropValue

PMoaMmValuePointer 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 actor
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

Gets the value of a sprite actor property. The host application passes in the symbol for the requested property; this is an abstract reference to a string in the host application's symbol dictionary. Use IMoaMmUtils::StringToSymbol() to get the MoaMmSymbol for any string, and IMoaMmUtils::SymbolToString() to convert any symbol to a string. This method should populate pPropValue with a new value; the host application then assumes ownership of the value and is responsible for releasing it. This method returns the error code kMoaMmErr_PropertyNotFound if it does not support the specified property symbol.

Image()

Syntax

Image(PIMoaMmXSpriteActorThis,

ConstPMoaMmXSpriteInfopActorInfo,
ConstPMoaMmPlayerStateInfopPlayerStateInfo,
PIMoaMmGCpGC)

Parameters

This

Pointer to the IMoaMmXSpriteActor interface

pActorInfo

ConstPMoaMmXSpriteInfoPointer to MoaMmXSpriteInfo structure for context in which actor is drawn

pPlayerStateInfo

ConstPMoaMmPlayerStateInfoPointer to a caller-owned CMoaMmPlayerStateInfo structure containing state information about the player

pGC

PIMoaMmGCPointer to an IMoaMmGC interface for the graphics context into which the sprite actor should be imaged

Returns

kMoaErr_NoErr	Successful, sprite imaged into supplied GC
kMoaMmErr_NotImplemented	Actor doesn't have a visual representation
kMoaMmErr_GCTypeNotSupported	Doesn't support supplied GC type
kMoaErr_OutOfMem	Couldn't image due to memory error
kMoaMmErr_InternalError	Couldn't image due to an internal error

Description

Images your sprite actor. pActorInfo contains a pointer to a MoaMmXSpriteInfo structure which describes the context in which your actor is to be imaged. This includes information such as the ink mode, sprite rectangle in which to draw, and other imaging parameters. pPlayerStateInfo contains global information about the player's state: whether it's playing or stopped, and whether sound playback is enabled. pGC contains a PIMoaMmGC, a pointer to a graphics context interface describing the native window or offscreen buffer into which the sprite should be drawn.

If you support the direct-to-screen imaging mode, the graphics context supplied can be associated with an operating system window on the playback machine. If the actor is offscreen-only, the graphics context will always be associated with an offscreen buffer.

Windows note: before your actor begins imaging, you must explicitly set the raster drawing mode of the device using the Windows SetROP2() function.

If your actor has no visual component, just return kMoaErr_NoErr.

Notify()

Syntax

Notify(PIMoaMmXSpriteActorThis,

MoaLongmsgCode,
PMoaVoidrefCon)

Parameters

This

Pointer to the IMoaMmXSpriteActor interface

msgCode

MoaLong

refCon

PMoaVoid

Returns

kMoaErr_NoErr	Successful
kMoaMmErr_UnknownNotifyMsgCode	Notify message code not supported Used for communicating between assets and their actors. The NotifySprites() method of the IMoaMmAssetCallback interface calls this method for all active sprite actors.

Description

Used for communicating between assets and their actors. The NotifySprites() method of the IMoaMmAssetCallback interface calls this method for all active sprite actors.

Note: Xtra developers may specify values in the range of 0 to 65535 for their notification codes. Higher values are reserved by Macromedia for future use.

SetCallback()

Syntax

SetCallback(PIMoaMmXSpriteActorThis,

PIMoaMmSpriteCallbackpSpriteCallback)

Parameters

This

Pointer to the IMoaMmXSpriteActor interface

pSpriteCallback

PIMoaMmSpriteCallbackPointer to an instance of the IMoaMmSpriteCallback interface

Returns

kMoaErr_NoErr	Interface set
kMoaMmErr_NotImplemented	Callback interface not used

Description

Receives an IMoaMmSpriteCallback interface containing callback methods for the sprite. In Director, this class also supports the IMoaDrSpriteCallback interface containing Director-specific callbacks. This is called directly after the host application calls an asset's NewXActor() method.

Important: If you want to hold on to the callback interface, you must call AddRef() on the interface and store it in an instance variable, then release it in the MoaDestroy function of your actor class.

SetProp()

Syntax

SetProp(PIMoaMmXSpriteActorThis,

MoaMmSymbolsymbol,
ConstPMoaMmValuepPropValue)

Parameters

This

Pointer to the IMoaMmXSpriteActor interface

symbol

MoaMmSymbolMoaMmSymbol representing the property to set

pPropValue

ConstPMoaMmValuePointer to a ConstPMoaMmValue which contains 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 due to 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 expected (Director only)

Description

Sets the value of a sprite actor property. The host application passes in the symbol for the property to set. This is an abstract reference to a string in the host application's symbol dictionary. Use IMoaMmUtils::StringToSymbol() to get the MoaMmSymbol for any string, and IMoaMmUtils::SymbolToString() to convert any symbol to a string. This method should take the value supplied in pPropValue and use it to update the object's internal representation of the property. The host application continues to maintain ownership of the MoaMmValue. This method should not release the passed-in value. SetProp() should return the error code kMoaMmErr_PropertyNotFound if it does not support the specified property symbol.