Sprite Control

The Sprite control enables you to create and control image-source-based, flip-book-style animation for an HTML page, and enables you to have frame-by-frame control over your animation. You can set markers to trigger events at desired points in sprite playback or create individual mouse events for each frame of the animation. To use the Sprite control you must first instantiate it on the HTML page.

See the appropriate topic for syntax details.

HTML and Scripting Properties
HTML and Scripting Methods
Events

A Sprite control renders its visual display based on a source file that contains a series of frames. Each frame contains one of the images used to create the animation. This image can be a separate image file or part of a file that provides images for multiple frames in a sequential strip. The file providing the images for a sprite is known as the sprite source.

The images used for a Sprite control can be in different formats. For example, you can use images in .gif, .jpg, .png (Portable Network Graphics), and .wmf (Microsoft® Windows® metafile) formats. You can't mix image formats within the same sprite source, but you can change the sprite source image dynamically.

A Sprite control can use a frame map to define a specific order in which to display frames. The frame map also defines how long each frame is displayed. If the sprite does not include a frame map, frames are displayed in their order of appearance within the image source file, and each frame appears for the same length of time, as specified by the TimerInterval property.

A Sprite control will not begin its animation sequence until all of its media is downloaded.

HTML and Scripting Properties

This topic contains a list of the Sprite control properties and the HTML and scripting syntax for them. Note that some properties can only be used in script.

Syntax

HTML <OBJECT ID=spriteObj
CLASSID="clsid: FD179533-D86E-11d0-89D6-00A0C90833E6">
<PARAM NAME="PropertyName" VALUE="Value">
</OBJECT>

Scripting spriteObj.PropertyName=Value

HTML	<OBJECT ID=spriteObj CLASSID="clsid: FD179533-D86E-11d0-89D6-00A0C90833E6"> <PARAM NAME="PropertyName" VALUE="Value"> </OBJECT>
Scripting	spriteObj.PropertyName=Value

Possible Values

spriteObj
String identifying the Sprite control object.
PropertyName
One of the Sprite control properties in the following table.
Value
Valid value for the PropertyName property.

Property	Description
AutoStart	Determines whether the sprite starts playback upon loading.
ColorKey	Sets the transparency color for a source image.
FinalFrame	Sets the sprite to display a designated frame when playback is stopped.
Frame	Retrieves the sprite image frame currently displayed (script only).
FrameMap	Sets or retrieves the order in which sprite frames play back, and the length of time each frame is displayed.
Image	Sets or retrieves a Microsoft DirectAnimation® image from the Sprite control (script only).
InitialFrame	Sets or retrieves the frame number that the sprite displays when it becomes visible.
Library	Retrieves the DirectAnimation Library reference (script only).
MaximumRate	Sets or retrieves the sprite's maximum rendering rate (number of times the control will render per second).
MouseEventsEnabled	Sets or retrieves whether the sprite responds to mouse events.
NumFrames	Sets or retrieves the number of frames in the sprite source.
NumFramesAcross	Sets or retrieves the width (in frames) of the sprite source.
NumFramesDown	Sets or retrieves the length (in frames) of the sprite source.
PlayRate	Sets or retrieves the sprite's playback speed.
PlayState	Retrieves the sprite's playback state, whether stopped, playing, or paused. Can be used from Script only.
Repeat	Sets or retrieves the number of times the sprite will loop during playback.
SourceURL	Sets or retrieves the URL that points to the sprite source image.
Time	Retrieves the elapsed playback time for the sprite, including looping. Can be used from Script only.
TimerInterval	Sets or retrieves the length of time between frames, (in milliseconds) for the sprite's rendering.
UseColorKey	Sets or retrieves whether to use the sprite's transparency information.

HTML and Scripting Methods

This topic contains a list of the Sprite control methods and the HTML and scripting syntax for them. Note that some properties can only be used in script.

Syntax

HTML <OBJECT ID=spriteObj
CLASSID="clsid: FD179533-D86E-11d0-89D6-00A0C90833E6">
<PARAM NAME="MethodName" VALUE="Parameters">
</OBJECT>

Scripting spriteObj.MethodName(Parameters)

HTML	<OBJECT ID=spriteObj CLASSID="clsid: FD179533-D86E-11d0-89D6-00A0C90833E6"> <PARAM NAME="MethodName" VALUE="Parameters"> </OBJECT>
Scripting	spriteObj.MethodName(Parameters)

Possible Values

spriteObj
String identifying the Sprite control object.
MethodName
One of the Sprite control methods in the following table.
Parameters
Valid parameters for the MethodName method. These parameters are separated by commas, as shown in the following HTML example.
<PARAM NAME="AddTimeMarker1" VALUE="1, West, 0"> 
<PARAM NAME="AddTimeMarker2" VALUE="2, Atlantic, 0">
<PARAM NAME="AddTimeMarker3" VALUE="3, East, 0">
<PARAM NAME="AddTimeMarker4" VALUE="4, Pacific, 0">

Method	Description
AddTimeMarker	Sets a marker to fire an event when playback reaches the designated time.
FrameSeek	Sets the sprite playback to a specific frame.
Pause	Stops playback at the current frame and maintains current frame position.
Play	Begins playback from the current frame.
Seek	Sets the sprite playback to a specific elapsed time.
Stop	Ends playback at the current frame.

Events

This topic contains a list of the Sprite control events.

Syntax

Scripting <SCRIPT LANGUAGE="JavaScript" FOR=spriteObj EVENT=event ( parameters ) >

</SCRIPT>

Scripting	<SCRIPT LANGUAGE="JavaScript" FOR=spriteObj EVENT=event ( parameters ) > <!--script--> </SCRIPT>

Possible Values

spriteObj
String identifying the Sprite control object.
event
One of the Sequencer control events in the following table.
Parameters
Valid parameters for the event.

Note that  in the preceding syntax and in the syntax for each event is the script executed if the event occurs.

Event	Description
onclick	Occurs when the user clicks the sprite once.
ondblclick	Occurs when the user double-clicks the sprite.
onframeseek	Occurs after the FrameSeek method has been called.
onmarker	Occurs when a time marker has been reached, either during sprite playback or when stopped.
onmedialoaded	Occurs when a piece of sprite media is completely downloaded.
onmousedown	Occurs when the user presses the mouse button down while the mouse pointer is over a sprite.
onmousemove	Occurs when the user moves the mouse pointer across the sprite's nontransparent area.
onmouseout	Occurs when the cursor leaves the sprite's nontransparent area.
onmouseover	Occurs when the cursor enters a nontransparent area of the sprite.
onmouseup	Occurs when the user releases the mouse button while the mouse pointer is over a sprite.
onpause	Occurs when sprite playback pauses.
onplay	Occurs when the sprite begins playback.
onplaymarker	Occurs when a time marker is reached during sprite playback.
onseek	Occurs after the Seek method is called.
onstop	Occurs when the sprite playback stops.