Sprite Control


The Sprite control lets you create and control image source-based, flip book-style animation for a Web 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.

Property Syntax


PARAM Tag Syntax

<OBJECT ID=object 
CLASSID="clsid: FD179533-D86E-11d0-89D6-00A0C90833E6 ">
[<PARAM NAME="Property | Method" VALUE="Value">]
</OBJECT>

Script Syntax

object.Property | Method [= Value]

Parameters
object String identifying the object.
Property | Method One of the Sprite control properties or methods in the following lists.
PropertyValue Valid value for that property or method.

Some properties and methods are scriptable only. See the desired topic for syntax details.
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.
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. You can use this to speed up or slow down sprite playback or even play the sprite backwards.
PlayState Retrieves the sprite's playback state, whether stopped, playing, or paused.
Repeat Sets or retrieves the number of times the sprite is to 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.
TimerInterval 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.
Method Description
AddFrameMarker Sets a marker to fire an event when playback reaches the designated frame.
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.
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 is paused.
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 stops playback.

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 .png, .gif, .jpg, and .wmf. 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.


AutoStart Property

Sprite Control

Determines whether the sprite starts playback immediately after loading.


PARAM Tag Syntax

<PARAM NAME="AutoStart" VALUE="fStart">


Script Syntax

object.AutoStart [=fStart]

Parameters
object
String identifying the Sprite object.
fStart
Starts playback as soon as the sprite is loaded if TRUE (–1 or nonzero), or if FALSE (0) simply loads and does not play until explicitly started with a Play method. The default value is False. Read-write at run time; write access is available at run time only when the sprite is stopped.


ColorKey Property

Sprite Control

Sets the transparency color to be used with this specific sprite. Read-write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="ColorKey " VALUE= "r,
  g,
  b ">


Script Syntax

object.ColorKey = lib.IDAColor

Parameters
r
Sets the red value (0-255).
g
Sets the green value (0-255).
b
Sets the blue value (0-255).
object
Name of the sprite.
IDAColor
IDAColor constructor. For more information, see the DirectAnimation documentation.


FinalFrame Property

Sprite Control

Sets the sprite to display the designated frame when playback is stopped. Read-write at run time, write accessible only when sprite is stopped.


PARAM Tag Syntax

<PARAM Name="FinalFrame" Value="fframeflag">


Script Syntax

object.FinalFrame [=fframeflag]

Parameters
object
Name of the sprite.
fframeflag
Integer expression identifying the desired frame to be displayed when sprite playback stops. Values can be –1 (display current frame), 0 (return to InitialFrame), or any valid frame number, from 1 to n where n represents the last frame in the sprite source. The default value is 0, return to InitialFrame.


Frame Property

Sprite Control

The sprite image frame currently displayed on the page. Read-only at run time.


Script Syntax

nFrame = object.Frame

Parameters
nFrame
Integer expression identifying the current frame, from 0 to n, where n represents the last frame in the sprite source. The default value is 1.
Remarks

If the sprite has a frame map, the value of the Frame property is a one-based index into the frame map. For example, if the frame map defines 10 frames, the Frame property value is 10 when the last frame in the frame map appears on the page.

VBScript note: To use the value returned by the Frame property, you will have to use the cInt function to convert the value from an unsigned integer into a variant that VBScript will accept. An example would be FrameNum = cInt(sprite.Frame).

The following example sets the indicator for a form to the value of the current frame for the sprite named SpriteHorse:


document.MyForm.txtFrame.value = SpriteHorse.Frame


FrameMap Property

Sprite Control

The order in which sprite frames play back and the length of time each frame is displayed. Read/write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="FrameMap" VALUE="nImage1,
  t1 [; nImage2,
  t2 ...] ">


Script Syntax

object.FrameMap="nImage1,
  t1 [; nImage2,
  t2 ...] "

Parameters
nImage1, nImage2,...
Integer expression denoting the image to draw from the frame source over the duration. The first frame in the sprite is numbered 1. The default value is the order in the source file.
t1, t2, ...
Expression indicating the frame's duration (seconds.milliseconds, 0.000). The default value is the TimerInterval duration.
Remarks

Sprites that use frame maps can display source images in an order other than the images' consecutive order of appearance within the source file. They can also display each frame in the sprite for a different length of time.

If the sprite has not been authored with a FrameMap property setting, frames appear in their order of appearance within the frame source file. The frames are in order from left to right, from top to bottom, within the file. Each frame appears for the number of seconds.milliseconds given by the TimerInterval property.

The following examples create a frame map with six frames.


<PARAM NAME="FrameMap"
VALUE="6,0.100;5,0.200;4,0.300;3,0.400;2,0.100;1,0.100">


object.FrameMap="6,0.100;5,0.200;4,0.300;3,0.400;2,0.100;1,0.100"


Image Property

Sprite Control

Sets or retrieves an IDAImage from the Sprite control. For more information, see the DirectAnimation documentation.


Script Syntax

object.Image = IDAImage

Parameters
object
Name of the Sprite control.
IDAImage
The IDAImage.


InitialFrame Property

Sprite Control

The frame the sprite displays when it becomes visible. Read/write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="InitialFrame" VALUE="nFrame">


Script Syntax

object.InitialFrame [= nFrame]

Parameters
nFrame
An integer expression specifying the frame that the sprite should seek to before starting playback. The value of the Frame property is a one-based index into the frame map. For example, if the frame map defines 10 frames, the Frame property value is 10 when the last frame in the frame map appears on the page. If the InitialFrame property is set to 0, the sprite will load the media but will display a blank frame until the Play method is invoked. If the InitialFrame property is set to –1 (or any number less than zero), the sprite will not load the media and will display a blank frame until the Play method is invoked, at which point it will begin media download and start playback after the media has been completely downloaded. The default value is 1.
Remarks

This property is scriptable, but if it is set from a script, only the InitialFrame value of the sprite as it is set in the HTML-persistence is changed. The current frame of the sprite is not changed.

The following example sets an initial frame indicator on the page to the value of the InitialFrame property for the sprite named SpriteHorse:


document.MyForm.txtInitialFrame.value = SpriteHorse.InitialFrame


Library Property

Sprite Control

Retrieves the reference to the DirectAnimation Library functions.


Script Syntax

IDALibrary=object.Library

Parameters
IDALibrary
DirectAnimation Library pointer.
object
String identifying the Sprite object.


MaximumRate Property

Sprite Control

Sets or retrieves the sprite's maximum rendering speed (number of times the control will render per second). Read-write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="MaximumRate" VALUE="fps"


Script Syntax

object.MaximumRate [= fps]

Parameters
fps
Number of frames per second. Default is 30.


NumFrames Property

Sprite Control

The number of frames in the Sprite source. Read/write at run time; write access is available only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="NumFrames" VALUE="nframes">


Script Syntax

object.NumFrames [ = nframes]

Parameters
object
Name of the Sprite object.
nframes
Integer indicating the total number of frames in the image for this frame source.
Remarks

If the sprite includes a frame map, the NumFrames property gives the number of frames defined in the map. If you change the NumFrames, NumFramesAcross, or NumFramesDown properties, the sprite does not refresh until you set the SourceURL property again.


NumFramesAcross Property

Sprite Control

The width (in frames) of the Sprite Frame Source image. Read/write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="NumFramesAcross" VALUE="nAcross">


Script Syntax

object.NumFramesAcross [= nAcross]

Parameters
object
Name of sprite.
nAcross
Integer indicating the number of frames across in the sprite source image.
Remarks

If you change the NumFrames, NumFramesAcross, or NumFramesDown properties, the sprite does not refresh until you set the SourceURL property again.


NumFramesDown Property

Sprite Control

The length (in frames) of the Sprite Frame Source. Read/write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="NumFramesDown" VALUE="nDown">


Script Syntax

object.NumFramesDown [= nDown]

Parameters
object
Name of sprite.
nDown
Integer indicating the number of frames down in the sprite source image.
Remarks

If you change the NumFrames, NumFramesAcross, or NumFramesDown properties, the sprite does not refresh until you set the SourceURL property again.


PlayRate Property

Sprite Control

Sets or retrieves the sprite's playback speed. Can be used to speed up or slow down sprite playback, or even play the sprite backward. Read-write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="PlayRate" VALUE="rSpeed">


Script Syntax

object.PlayRate = rSpeed

Parameters
rSpeed
Real expression indicating the number used to multiply the duration for each frame. The default value is 1.0. Possible values are:
Argument Meaning
Positive (>0.0) Sprite plays forward.
0.0 Disables the PlayRate property.
Negative (<0.0) Sprite plays backward.
Remarks

If the sprite does not have a frame map, the timer interval is divided by the value of PlayRate to determine the duration for all frames. PlayRate values greater than 1.0 speed up playback; values smaller than 1.0 slow down playback.

The following example sets the play rate for the sprite named SpriteHorse to the value the user enters on the page:


SUB PlayRate_onclick
SpriteHorse.PlayRate = document.MyForm.txtPlayRate.value


PlayState Property

Sprite Control

Retrieves the playback state of the sprite: stopped, playing, or paused.


Script Syntax

state = object.PlayState

Parameters
state
Integer value. Zero if the control is stopped, 1 if the control is being played, 2 if the media is paused.


Repeat Property

Sprite Control

Sets or retrieves the number of times the sprite is to loop during playback. Read-write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="Repeat" VALUE="nRepeat" >


Script Syntax

object.Repeat = nRepeat

Parameters
object
Name of the sprite.
nRepeat
Integer expression indicating the number of times the sprite repeats playback. The default is 1. To loop infinitely, use –1. The value 0 disables the Repeat property. Negative values are treated as unsigned.


SourceURL Property

Sprite Control

Sets or retrieves the URL that points to the sprite source image. Read-write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="SourceURL" VALUE= "URL">


Script Syntax

object.SourceURL = URL

Parameters
object
Name of the sprite.
URL
String pointing to the image file.


Time Property

Sprite Control

Retrieves the sprite's elapsed playback time (in milliseconds). Playback repetitions are included in the time calculations. Read-only at run time.


Script Syntax

object.Time = eTime

Parameters
object
Name of the sprite.
eTime
Number of milliseconds into the animation. The default value is zero.
Remarks

The OnSeek event is fired upon completion of the Time change.


TimerInterval Property

Sprite Control

The length of time, in seconds.milliseconds, between the sprite's frame updates. Read/write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="TimerInterval" VALUE="nInterval">


Script Syntax

object.TimerInterval [=nInterval]

Parameters
object
Name of the sprite.
nInterval
Expression defining the number of seconds.milliseconds between sprite frame updates. The default interval is 0.100 seconds (0.100) or 10 frames per second.
Remarks

This value specifies the minimum length of time between sprite frame updates. For example, if the timer interval is set to 0.100 seconds and an image is scheduled to display at 0.150 seconds, the image will not be displayed until 0.200 seconds because the timer interval resolution is set to 0.100 milliseconds. If the image is scheduled to appear for 0.050 seconds or less (because of a frame map) it might not even appear.

The following example sets the value of the timer interval indicator on the page to the value of the TimerInterval property for the sprite named SpriteHorse:


document.MyForm.txtTimerInterval.value = SpriteHorse.TimerInterval


UseColorKey Property

Sprite Control

Sets or retrieves whether to use the sprite's transparency information. Read-write at run time; write access is available at run time only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="UseColorKey" VALUE="0 | 1">


Script Syntax

object.UseColorKey = fFalse

Parameters
object
Name of the sprite.
fFalse
Boolean value, True (1) or False (0). Sets whether to use the transparency information in the image, as determined by the ColorKey property. The default is False.
Remarks

If the ColorKey value is set in a PARAM tag, then you should also set the UseColorKey value in a PARAM tag


AddFrameMarker Method

Sprite Control

Sets a marker to fire an event when playback reaches the designated frame. This method can be used or modified only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="AddFrameMarkerx" VALUE=" frame ,
  marker name ,
  [fRelative]">


Script Syntax

object.AddFrameMarker(
  frame ,
  " marker name " ,
  [ fRelative ]
  )

Parameters
x
If you are adding more than one Frame Marker through PARAM Tag syntax, you must make each AddFrameMarker method call distinct by adding a sequential integer to the end of the AddFrameMarker Param name, starting at 1 (PARAM Tag syntax only)
object
Name of the sprite.
Frame
Number or key name of the frame for the onmarker, or OnPlayMarker event fires on.
marker name
Name of the marker.
fRelative
Optional parameter, default is True. Sets the Relative flag as either True (relative — fires every time, includes looping) or False (absolute — fires at specified time once and ignores looping). For PARAM Tag syntax, use zero (false) or nonzero (true); for script use predefined constants True and False. For the Preview Release, you should set fRelative to True (nonzero).
Remarks

onmarker events are fired whether or not the sprite is playing. OnPlayMarker events are only fired when the sprite is playing.

The following sprite has three markers defined.


<PARAM name="AddFrameMarker1" value="0,FrameEight,0">
<PARAM name="AddFrameMarker2" value="4,FrameFour,0">
<PARAM name="AddFrameMarker3" value="8,FrameZero,0">


AddTimeMarker Method

Sprite Control

Sets a marker to fire an event when playback reaches the designated time. This method can be used or modified only when the sprite is stopped.


PARAM Tag Syntax

<PARAM NAME="AddTimeMarker x " VALUE=" time ,
  marker name,
  [ fAbsolute ]">


Script Syntax

object.AddTimeMarker(
  time ,
  " marker name",
  [ fAbsolute ]
  )

Parameters
object
Name of the sprite.
x
If you are adding more than one Time Marker through PARAM Tag syntax, you must make each AddTimeMarker method call distinct by adding a sequential integer at the end of the AddTimeMarker Param name, starting at 1 (PARAM Tag syntax only)
time
Time for the onmarker or onplaymarker event to fire.
marker name
Name of the marker.
fAbsolute
Optional parameter, default is True. Sets the Absolute flag as either True (absolute — fires at specified time once and ignores looping) or False (relative — fires every time, includes looping). For PARAM Tag syntax, use zero (false) or nonzero (true); for script use predefined constants True and False. For the Preview Release, fAbsolute must be set to True (nonzero).
Remarks

For details on the events fired for markers. onmarker events are fired whether or not the sprite is playing. onplaymarker events are fired only when the sprite is playing.

Example


<PARAM name="AddTimeMarker1" value="0.0,Foo,1">
<PARAM name=" AddTimeMarker2" value="4.7,FrameFour,1">
<PARAM name=" AddTimeMarker3" value="8.0,FrameZero,1">


FrameSeek Method

Sprite Control

Sets the sprite playback to a specific frame.


Script Syntax

object.FrameSeek(
  frame
  ) >

Parameters
object
Name of the sprite.
frame
New playback frame for the sprite.
Remarks

The following example seeks the sprite named SpriteHorse in response to an onclick event:


SUB SpriteHorse_onclick
	SpriteHorse.FrameSeek(5)
END SUB

mouseover example Right click inside the frame and View Source to get source code.



Pause Method

Sprite Control

Stops playback at the current frame and maintains current frame position.


Script Syntax

object.Pause

Parameters
object
Name of the sprite.
Remarks

Does not rewind the media.

The following example stops playing the sprite named SpriteHorse in response to an onclick event:


SUB SpriteHorse_onclick
	SpriteHorse.Pause
END SUB


Play Method

Sprite Control

Begins playback from the current frame. This method is scriptable only.


Script Syntax

object.Play

Parameters
object
Name of the sprite.
Remarks

The following example starts playing the sprite named SpriteHorse in response to an onclick event:


SUB Play_onclick
	SpriteHorse.Play
END SUB


Seek Method

Sprite Control

Sets the sprite playback to a specific elapsed time.


Script Syntax

object.Seek (
  time
  )

Parameters
object
Name of the sprite.
time
New elapsed time for the sprite.
Remarks

The following example seeks the sprite named SpriteHorse in response to an onclick event:


SUB SpriteHorse_onclick
	SpriteHorse.seek(0.0)
END SUB


Stop Method

Sprite Control

Ends playback at the current frame and resets its playback position to the beginning. This method is scriptable only.


Script Syntax

object.Stop

Parameters
object
Name of the sprite.
Remarks

The following example stops playing the sprite named SpriteHorse in response to an onclick event:


SUB SpriteHorse_onclick
	SpriteHorse.Stop
END SUB


onframeseek Event

Sprite Control

Occurs after the FrameSeek method has been invoked and the current playback frame has been changed.


VBScript Syntax

Sub object_onframeseek(
  newframe
  )
script
End Sub


JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onframeseek(
  newframe
  ) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
script
Script to be executed.
newframe
New frame to which the current playback position has been set.


onmarker Event

Sprite Control

Occurs when a frame or time marker has been reached.


VBScript Syntax

Sub object_onmarker(
  markername
  )
script
End Sub


JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onmarker(
  markername
  ) >
script
<SCRIPT>

Parameters
object
String identifying the Sprite object.
markername
String containing the marker name established in the AddTimeMarker or AddFrameMarker methods.
script
Script to be executed.
Remarks

This event occurs when the sprite playback position reaches the marker point, either when the sprite is playing or stopped. For example, if you seek to the marker position while the sprite is paused or stopped, the onmarker event will occur.


onmedialoaded Event

Sprite Control

Occurs when a piece of sprite media is fully downloaded.


VBScript Syntax

Sub object_ onmedialoaded(
  URL
  )
script
End Sub


JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onmedialoaded(
  URL
  ) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
script
Script to be executed.
URL
URL used to load the media.


onpause Event

Sprite Control

Occurs when sprite playback is paused.


VBScript Syntax

Sub object_onpause( )
script
End Sub


JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onpause( ) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
script
Script to be executed when the event occurs.


onplay Event

Sprite Control

Occurs when the sprite starts. The sprite will not start until all media is downloaded.


VBScript Syntax

Sub object_onplay( )
script
End Sub


JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onplay( ) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
script
Script to be executed when the event occurs.


onplaymarker Event

Sprite Control

Occurs when a marker is reached during sprite playback.


VBScript Syntax

Sub object_onplaymarker(
  markername
  )
script
End Sub


JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR= object EVENT= onplaymarker(
  markername
  ) >
script
<SCRIPT>

Parameters
object
String identifying the Sprite object.
markername
String containing the marker name established in the AddTimeMarker or AddFrameMarker methods.
script
Script to be executed.
Remarks

This event occurs when the sprite playback position reaches the marker point while the sprite is playing.


OnSeek Event

Sprite Control

Occurs after a Seek method has been invoked and the playback position has changed.


Sub object_onseek(
  newtime
  )
script
End Sub


JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onseek(
  newtime
  ) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
newtime
Variable that contains the time value of the new playback position, in seconds.milliseconds (0.000).
script
Script to be run.
Remarks

You can use OnSeek to set up conditional behavior.


	Sub sprite1_onseek(newtime)
		If newtime = 2.000 then
			sprite1.stop
		Else
			sprite1.play
		End If
	End Sub


onstop Event

Sprite Control

Occurs when the sprite stops playback.


Script Syntax

Sub object_onstop( )
script
End Sub


JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onstop( ) >
script
<SCRIPT>

Parameters
object
Name of the sprite.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.