The Sprite control lets you create and control image source-based flipbook-style animation for a Web page, and allows 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 Properties or Methods in the list below. |
PropertyValue | Valid value for that property or method. |
Some properties and methods are scriptable only. Please see the desired topic for syntax details.
Property | Description |
AutoStart | Determines whether or not the sprite starts playback upon loading. |
ColorKey | Sets the transparency color for a source image. |
FinalFrame | Sets sprite to display designated frame when playback is stopped. |
Frame | Returns the sprite image frame currently displayed. |
FrameMap | Sets or returns the order in which sprite frames play back and the length of time each frame is displayed. |
Image | Sets or returns a DirectAnimation image from the sprite control (script only). |
InitialFrame | Sets or returns the frame number that the sprite displays when it becomes visible. |
Library | Returns the DirectAnimation Library reference (script only). |
MaximumRate | Sets or returns the maximum rendering speed of the sprite (number of times the control will render per second). |
MouseEventsEnabled | Sets or returns whether or not the sprite responds to mouse events. |
NumFrames | Sets or returns the number of frames in the Sprite source. |
NumFramesAcross | Sets or returns the width (in frames) of the Sprite Source. |
NumFramesDown | Sets or returns the length (in frames) of the Sprite source. |
PlayRate | Sets or returns the playback speed of the sprite. Can be used to speed up or slow down sprite playback or even play sprite backwards. |
PlayState | Returns the playback state of the sprite, whether stopped, playing or paused. |
Repeat | Sets or returns the number of times the sprite is to loop during playback |
SourceURL | Sets or returns the URL that points to the sprite source image. |
Time | Returns 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 returns whether or not 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 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 non-transparent area of the sprite. |
onmouseout | Occurs when the cursor leaves the non-transparent area of the sprite. |
onmouseover | Occurs when the cursor enters a non-transparent 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 are 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 or not the sprite starts playback immediately after loading.
PARAM Tag Syntax <PARAM NAME="AutoStart" VALUE="fStart">
Script Syntax object.AutoStart [=fStart]
Parameter Description 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 runtime; write access is available at run time only when the sprite is stopped.
Sets the transparency color to be used with this specific sprite. Read-write at runtime; 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
Parameter Description r Sets the red value (0-255). g Sets the green value (0-255). b Sets the blue value (0-255). object The name of the sprite. IDAColor An IDAColor constructor. For more information, see the DirectAnimation documentation.
Sets the sprite to display the designated frame when playback is stopped. Read-write at runtime, write accessible only when sprite is stopped.
PARAM Tag Syntax <PARAM Name="FinalFrame" Value="fframeflag"> Script Syntax object.FinalFrame [=fframeflag]
Parameter Description object The name of the sprite. fframeflag An 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.
The sprite image frame currently displayed on the page. Read-only at runtime.
Script Syntax nFrame = object.Frame
Parameter Description nFrame An 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.
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 ...] "
Parameter Description 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 giving the frame's duration (seconds.milliseconds, 0.000). The default value is the TimerInterval duration.
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.
Example
The following examples creates a frame map with six frames.
- Frame 1 displays image 6 for 100 milliseconds.
- Frame 2 displays image 5 for 200 milliseconds.
- Frame 3 displays image 4 for 300 milliseconds.
- Frame 4 displays image 3 for 400 milliseconds.
- Frame 5 displays image 2 for 100 milliseconds.
- Frame 6 displays image 1 for 100 milliseconds.
<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 returns an IDAImage from the sprite control. For more information, see the DirectAnimation documentation.
Script Syntax object.Image = IDAImage
Parameter Description object The name of the sprite control IDAImage The 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]
Parameter Description 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 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 once media has been completely downloaded. The default value is 1.
NOTE: 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.
Example
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
Returns the reference to the DirectAnimation Library functions. For more information, see the DirectAnimation documentation.
Script Syntax IDALibrary=object.Library
Parameter Description IDALibrary The DirectAnimation Library pointer. object String identifying the Sprite object.
Sets or returns the maximum rendering speed of the sprite (number of times the control will render per second). Read-write at runtime; 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]
Parameter Description fps the number of frames per second. Default is 30.
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]
Parameter Description object Name of sprite object nframes Integer giving the total number of frames in the image for this frame source.
If the sprite includes a frame map, the NumFrames property gives the number of frames defined in the map. If you change theNumFrames, 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]
Parameter Description object Name of sprite. nAcross Integer giving the number of frames across in the sprite source image.
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]
Parameter Description object Name of sprite. nDown Integer giving the number of frames down in the sprite source image.
If you change the NumFrames, NumFramesAcross, or NumFramesDown properties, the sprite does not refresh until you set the SourceURL property again.
Sets or returns the playback speed of the sprite. Can be used to speed up or slow down sprite playback or even play sprite backwards. Read-write at runtime; 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
Parameter Description rSpeed A real expression giving the number used to multiply the duration for each frame. The default value is 1.0. Possible values are:
Argument Description Positive (> 0.0) Sprite plays forward. 0.0 Disables the PlayRate property. Negative (< 0.0) Sprite plays backwards.
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.
Example
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
Returns the playback state of the sprite, whether stopped, playing or paused.
Script Syntax state = object.PlayState
Parameter Description state Integer value. 0 if the control is stopped, 1 if the control is being played, 2 if the media is paused.
Sets or returns the number of times the sprite is to loop during playback. Read-write at runtime; 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
Parameter Description object The name of the sprite. nRepeat An integer expression giving 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.
Sets or returns the URL that points to the sprite source image. Read-write at runtime; 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
Parameter Description object The name of the sprite. URL String pointing to the image file.
Returns the elapsed playback time (in milliseconds) for the sprite. Playback repetitions are included in the time calculations. Read only at run time.
Script Syntax object.Time = eTime
Parameter Description object The name of the sprite. eTime Number of milliseconds into the animation. The default value is 0.
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]
Parameter Description object The name of the sprite. nInterval An 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.
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.
Example
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 returns whether or not to use the sprite's transparency information. Read-write at runtime; 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
Parameter Description object The 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.
If the ColorKey value is set in a PARAM tag then the UseColorKey value should also be set 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 ])
Parameter Description x If you are adding more than one Frame Marker through PARAM Tag syntax, you must make each AddFrameMarker method call distinct by adding an sequential integer at the end of the AddFrameMarker Param name, starting at 1 (PARAM Tag syntax only) object The 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 0 (false) or nonzero (true) and for script use predefined constants True and False. For the Preview Release, fRelative should be set to True (nonzero).
onmarker events are fired whether or not the sprite is playing. OnPlayMarker events are only fired when the sprite is playing.
Example
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 ])
Parameter Description object The 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 an sequential integer at the end of the AddTimeMarker Param name, starting at 1 (PARAM Tag syntax only) time The 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 0 (false) or nonzero (true) and for script use predefined constants True and False. For the Preview Release, fAbsolute must be set to True (nonzero).
For details on the events fired for markers. onmarker events are fired whether or not the sprite is playing. onplaymarker events are only fired 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)>
Parameter Description object The name of the sprite. frame The new playback frame for the sprite.
The following example seeks the sprite named SpriteHorse in response to an OnClick event:
Example
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 current frame and maintains current frame position.
Script Syntax object.Pause
Parameter Description object The name of the sprite.
Does not rewind the media.
Example
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
Parameter Description object The name of the sprite.
The following example starts playing the sprite named SpriteHorse in response to a Click event:
Example
SUB Play_onclick SpriteHorse.Play END SUB
Sets the sprite playback to a specific elapsed time.
Script Syntax object.Seek (time)
Parameter Description object The name of the sprite. time The new elapsed time for the sprite.
The following example seeks the sprite named SpriteHorse in response to an OnClick event:
Example
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
Parameter Description object The name of the sprite.
The following example stops playing the sprite named SpriteHorse in response to an onclick event:
Example
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>
Parameter Description object The name of the sprite. script Script to be executed. newframe The new frame to which the current playback position has been set.
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>
Parameter Description object String identifying the Sprite object. markername String containing the marker name established in the AddTimeMarker or AddFrameMarker methods. script Script to be executed.
This event occurs whenever 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>
Parameter Description object The name of the sprite. script Script to be executed. URL The URL used to load the media.
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>
Parameter Description object The name of the sprite. script Script to be executed when the event occurs.
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>
Parameter Description object The name of the sprite. script Script to be executed when the event occurs.
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>
Parameter Description object String identifying the Sprite object. markername String containing the marker name established in the AddTimeMarker or AddFrameMarker methods. script Script to be executed.
This event occurs whenever the sprite playback position reaches the marker point when the sprite is currently 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>
Parameter Description object The name of the sprite. newtime A variable that contains the time value of the new playback position, in seconds.milliseconds (0.000). script Script to be run.
OnSeek can be used 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>
Parameter Description object The name of the sprite.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.