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.
Determines whether the sprite starts playback immediately after loading.
PARAM Tag Syntax
<PARAM NAME="AutoStart" VALUE="fStart">
Script Syntax
object.AutoStart [=fStart]
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
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]
The sprite image frame currently displayed on the page. Read-only at run time.
Script Syntax
nFrame = object.Frame
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
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 ...] "
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"
Sets or retrieves an IDAImage from the Sprite control. For more information, see the DirectAnimation documentation.
Script Syntax
object.Image = IDAImage
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]
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
Retrieves the reference to the DirectAnimation Library functions.
Script Syntax
IDALibrary=object.Library
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]
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]
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.
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]
If you change the NumFrames, NumFramesAcross, or NumFramesDown properties, the sprite does not refresh until you set the SourceURL property again.
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]
If you change the NumFrames, NumFramesAcross, or NumFramesDown properties, the sprite does not refresh until you set the SourceURL property again.
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
Argument | Meaning |
Positive (>0.0) | Sprite plays forward. |
0.0 | Disables the PlayRate property. |
Negative (<0.0) | Sprite plays backward. |
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
Retrieves the playback state of the sprite: stopped, playing, or paused.
Script Syntax
state = object.PlayState
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
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
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
The OnSeek event is fired upon completion of the Time change.
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]
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
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
If the ColorKey value is set in a PARAM tag, then you should also set the UseColorKey value in a PARAM tag
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 ]
)
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">
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 ]
)
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">
Sets the sprite playback to a specific frame.
Script Syntax
object.FrameSeek(
frame
) >
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.
Stops playback at the current frame and maintains current frame position.
Script Syntax
object.Pause
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
Begins playback from the current frame. This method is scriptable only.
Script Syntax
object.Play
The following example starts playing the sprite named SpriteHorse in response to an onclick event:
SUB Play_onclick SpriteHorse.Play END SUB
Sets the sprite playback to a specific elapsed time.
Script Syntax
object.Seek (
time
)
The following example seeks the sprite named SpriteHorse in response to an onclick event:
SUB SpriteHorse_onclick SpriteHorse.seek(0.0) END SUB
Ends playback at the current frame and resets its playback position to the beginning. This method is scriptable only.
Script Syntax
object.Stop
The following example stops playing the sprite named SpriteHorse in response to an onclick event:
SUB SpriteHorse_onclick SpriteHorse.Stop END SUB
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>
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>
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.
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>
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>
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>
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>
This event occurs when the sprite playback position reaches the marker point while the sprite is playing.
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>
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
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>
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.