Path Control

A windowless DirectAnimation control that animates the position of other controls along a defined vector or spline shape - based path.


PARAM Tag Syntax

<OBJECT ID=object
CLASSID="CLSID:D7A7D7C3-D47F-11d0-89D3-00A0C90833E6">
[<PARAM NAME="property" VALUE="setting">]
</OBJECT>

Parameters
object String identifying the object.
property One of the properties in the table below.
setting A value for the property.
Property Description
AutoStart Determines whether or not the path starts playback upon loading.
Bounce Sets the path behavior to either reverse direction and return to the beginning, or stop at the end of its playback.
Direction Sets the direction of the path playback.
Duration Sets the duration of the path playback.
Library Returns the DirectAnimation Library reference.
PlayState Returns the path's current playback state.
Relative Determines whether the Path control starts playing from its current position or from the absolute position in the target object's coordinate space.
Repeat Sets the number of times the path loops during playback.
Target Sets the object that is to follow the path.
Time Returns the elapsed playback time from the start of the path.
TimerInterval Sets or returns the length of time, in seconds.milliseconds, between the path update.
Method Description
AddTimeMarker Sets a marker to fire an event when playback reaches the marker position.
Oval Specifies an oval structured graphics primitive to be used as the path, with starting point at top center (12 o'clock)
KeyFrame Specifies points along the path in X, Y coordinates and a designated time to reach each point.
Pause Stops playback and maintains current elapsed time.
Play Begins playback from the current elapsed time.
Polygon Specifies a closed series of line segments to use a path.
PolyLine Specifies an open set of line segments to be used as the path.
Rect Specifies a rectangular structured graphics primitive to be used as the path, with starting point at top left.
Seek Resets the current playback position to a new, specified position.
Spline Specifies a spline to be used as the path.
Stop Stops playback at current elapsed time and returns path to the beginning
Event Description
OnMarker Occurs when a time marker has been reached either during path playback or when stopped.
OnPause Occurs when path playback is paused.
OnPlay Occurs when path playback is played.
OnPlayMarker Occurs when a time marker is reached during path playback.
OnSeek Occurs when a seek call has been completed..
OnStop Occurs when path playback is stopped.


AutoStart Property

Description

Determines whether or not the path starts playback immediately after loading. Read-write at runtime; write access is available at run time only when the path is stopped.

Syntax
PARAM Tag Syntax

<PARAM NAME="AutoStart" VALUE= 0 | -1>

Syntax

Script Syntax

object.AutoStart=[fStart]

ParameterDescription
object String identifying the Path object.
fStart Starts playback as soon as the path 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.


Bounce Property

Description

Sets the path to either stop at the end of the path or reverse direction and continue playback. Read-write at runtime; write access is available at run time only when the path is stopped.

Syntax
PARAM Tag Syntax

<PARAM NAME="Bounce" VALUE=0 | -1>

Syntax

Script Syntax

object.Bounce=[fBounce]

ParameterDescription
object String identifying the Path object.
fBounce Stops playback at the end of the path if FALSE (0), or reverses direction and continues playback if TRUE (-1 or nonzero). The default value is False.


Direction Property

Description

Sets the direction of the path playback, either forward or reverse. Read/write at run time; write access is available at run time only when the path is stopped.

Syntax
PARAM Tag Syntax

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

Syntax

Script Syntax

object .Direction=  fDirection

ParameterDescription
object String identifying the Path object.
fDirection Forward (0) or reverse (1). Default setting is 0 (forward).


Duration Property

Description

Sets the duration of the path playback. Read/write at run time; write access is available at run time only when the path is stopped.

Syntax

PARAM Tag Syntax

<PARAM NAME=" Duration " VALUE=" time ">

Syntax

Script Syntax

 object . Duration=[ time ]

ParameterDescription
object String identifying the Path object.
time Double value, format 0.000 (seconds.milliseconds), that sets the length of time for the object to move from start to end of path.

Remarks

Duration property does not take Bounce behavior into account. If the path is set to bounce, duration property sets the start to end playback, not the subsequent reversal of direction and return to the start of the path.


Library Property

Description

Returns the reference to the DirectAnimation Library functions. For more information, see the DirectAnimation documentation.

Syntax

Script Syntax

IDALibrary = object . Library

ParameterDescription
IDALibrary The DirectAnimation Library pointer.
object String identifying the Path object.


Playstate Property

Description

Returns the playback state of the path, whether stopped, playing, or paused. Read-only at runtime.

Syntax

Script Syntax

state = object . Playstate

ParameterDescription
state Playback state of the Path object. 0 if stopped, 1 if playing, 2 if paused.
object String identifying the Path object.


Relative Property

Description

Determines whether the Path control starts playing from its current position or from the absolute position in the target object's coordinate space. Read/write at run time; write access is available at run time only when the path is stopped.

Syntax
PARAM Tag Syntax

 <PARAM NAME= Relative VALUE= 0 | -1> 

Syntax

Script Syntax

object.Relative = fPos

ParameterDescription
object The Path object
fpos TRUE (-1 or nonzero) or FALSE (0). If True, then the path starts playback from the target's current position. If false, then the path starts playback from the absolute position in the target's coordinate space. The default value is False (0).

Remarks

The Relative property means with respect to the target object's position, as designated by the STYLE="POSITION: ABSOLUTE | RELATIVE" attribute.

Relative Method example

Right click inside the frame and select View Source to see the HTML code for this example.



Repeat Property

Description

Sets the number of times the path loops playback. Read-write at runtime; write access is available at run time only when the path is stopped.

Syntax

PARAM Tag Syntax

<PARAM NAME=" Repeat " VALUE= nRepeat >

Syntax

Script Syntax

 object . Repeat = [ nRepeat ]

ParameterDescription
object String identifying the Path object.
nRepeat An integer expression setting the number of times the path repeats playback. Default value is 1. -1 causes the path to repeat infinitely; other negative values are treated as unsigned. 0 disables the Repeat property.


Target Property

Description

Sets the object to follow the Path. Read-write at runtime; write access is available at run time only when the path is stopped.

Syntax

PARAM Tag Syntax

<PARAM NAME=" Target" VALUE=" objTarget ">

Syntax

Script Syntax

 object . Target = [ objTarget ]

ParameterDescription
object String identifying the Path object.
objTarget String identifying the Path's target object.

Remarks

The target object must have Top and Left properties. These can be set from script, or in the target object's STYLE attribute.

Target Method example

Right click inside the frame and select View Source to see the HTML code for this example.



Time Property

Description

Returns the elapsed playback time (in milliseconds) from the start of the path playback. Repeat count is included in returned time calculations. Read-only at runtime.

Syntax

Script Syntax

 time  =  object.Time

ParameterDescription
object String identifying the Path object.
time Number of milliseconds into path playback. Default value is 0.


TimerInterval Property

Description

The default length of time, in seconds.milliseconds, between the path update. Read/write at run time; write access is available at run time only when the path is stopped.

Syntax

PARAM Tag Syntax

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

Syntax

Script Syntax

object.TimerInterval = nInterval

ParameterDescription
nInterval An integer expression giving the minimum number of seconds.milliseconds between path updates. The default interval is 0.100.


AddTimeMarker Method

Description

Adds marker at specified playback position, allowing author to generate an event when that playback position is reached. This method can be used or modified only when the path is stopped.

Syntax

PARAM Tag Syntax

<PARAM NAME=" AddTimeMarkerX" VALUE=" time, markername , [ 0 | -1 ]">

Syntax

Script Syntax

 object . AddTimeMarker (time, "markername", [fAbsolute] )

ParameterDescription
object String identifying the Path object.
X If you are adding more than one Time Markers 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 at which the OnMarker or OnPlayMarker event fires.
markername 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 for false or -1 or nonzero for true and for script use predefined constants True and False.

Remarks

The OnMarker event occurs whenever the path is at the specified marker, whether or not the path is playing. The OnPlayMarker event only occurs when the path is playing.

This example sets three time markers named Foo, FrameFour, and FrameZero at 0.0, 4.7, and 8.0 respectively. Foo and FrameZero are set to occur every time the path reaches that time marker, and FrameFour is set to occur only the first time the path reaches that time marker during uninterruped playback.


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

AddFrameMarker Method example

Right click inside the frame and select View Source to see the HTML code for this example.



KeyFrame Method

Description

Specifies x and y coordinates along the path and a time to reach each point. The first point defines the starting point of the path. This method can be used or modified only when the path is stopped.

Syntax

PARAM Tag Syntax

<PARAM NAME=" Shape" VALUE=" KeyFrame (  npoints,    [ x1, y1 ,..., xN, yN ], [ time2,..., timeN ])">

Syntax

Script Syntax

 KeyFrameArray = Array( x1, y,...,xN, yN )
 TimeFrameArray = Array( time2 , ...,  timeN )
 object . KeyFrame(npoints,  KeyFrameArray ,  TimeFrameArray )

ParameterDescription
object String identifying the Path object.
npoints Number of points to be used to define the polyline
x1, y1,...,xN, yN The set of X and Y coordinates that identify the keyframe points.
time2,..., timeN The respective times that the path takes to reach each of the respective points from the previous point.
KeyFrameArray The array that contains the X and Y point definitions (script only).
TimeFrameArray The array that contains the time values between the points that define the path, starting at the X1 and Y1 point through XN and YN points (the last set of points in the path). The path begins at point x1 and y1 with a time value of 0. Script only.

Remarks

The Duration property is ignored when this method is invoked.

KeyFrame Method example

Right click inside the frame and select View Source to see the HTML code for this example.



Oval Method

Description

Specifies an oval path, with its starting point at the top center point of the oval (12 o'clock position). This method can be used or modified only when the path is stopped.

Syntax

PARAM Tag Syntax

<PARAM NAME="Shape" VALUE=" Oval( xpos, ypos, width, height) ">

Syntax

Script Syntax

 object . Oval( xpos ,  ypos ,  width ,  height )

ParameterDescription
object String identifying the Path object.
xpos The x position defining the topmost point of the oval.
ypos The y position defining the leftmost point of the oval.
width The width of the oval.
height The height of the oval.

Oval Method example

Right click inside the frame and select View Source to see the HTML code for this example.



Pause Method

Description

Pauses Path playback at current elapsed time and maintains current playback position.

Syntax

VBscript Syntax

 object . Pause

Syntax

JScript Syntax

 object . Pause( )

ParameterDescription
object String identifying the Path object.


Play Method

Description

Begins Path playback at current elapsed time.

Syntax

VBscript Syntax

 object . Play

Syntax

JScript Syntax

 object . Play( )

ParameterDescription
object String identifying the Path object.

Remarks

Calls to the Play Method while a path is playing are ignored.


Polygon Method

Description

Specifies a set of closed line segments to use as a path. The first point defines the starting point of the path. This method can be used or modified only when the path is stopped.

Syntax

PARAM Tag Syntax

<PARAM NAME="Shape" VALUE="  Polygon(npoints,  [ x1, y1,...,xN, yN ])"> 

Syntax

Script Syntax

PolygonArray = Array( x1, y1,..., xN, yN )
object.Polygon( npoints, PolygonArray  ) 

ParameterDescription
object String identifying the Path object.
n_Points The number of points in the polygon.
x1, y1,..., xN, yN The set of X and Y coordinates that identify the polygon points..
PolygonArray The array that contains the X and Y point definitions (script only).

Remarks

The array of x, y coordinates can be specified either as an array, or as comma delimited string of numbers that will be passed into the coordinates.

Polygon Method example

Right click inside the frame and select View Source to see the HTML code for this example.



PolyLine Method

Description

Specifies a set of line segments to use as a path. The first point defines the starting point of the path. This method can be used or modified only when the path is stopped.

Syntax

PARAM Tag Syntax

<PARAM NAME="Shape" VALUE="  PolyLine (npoints,  [ x1, y1,...,xN, yN ])">

Syntax

Script Syntax

 PolyLineArray = Array( x1, y1,..., xN, yN )
 object . PolyLine ( npoints, PolyLineArray)

ParameterDescription
object String identifying the Path object.
npoints Number of points to be used to define the PolyLine.
x1, y1,..., xN, yN The set of X and Y coordinates that identify the polygon points..
PolyLineArray The array that contains the X and Y point definitions (script only).

Polyline Method example

Right click inside the frame and select View Source to see the HTML code for this example.



Rect Method

Description

Specifies a rectangular path, with its starting point at the top left point of the rectangle. This method can be used or modified only when the path is stopped.

Syntax

PARAM Tag Syntax

<PARAM NAME="Shape" VALUE="Rect(xpos, ypos, width, height )">

Syntax

Script Syntax

 object . Rect ( xpos ,  ypos ,  width ,  height )

ParameterDescription
object String identifying the Path object.
xpos The x position for the starting point of the rectangle.
ypos The y position for the starting point of the rectangle.
width The width of the rectangle.
height The height of the rectangle.

Rect Method example

Right click inside the frame and select View Source to see the HTML code for this example.



Seek Method

Description

Seeks to another position in the Path playback.

Syntax

Script Syntax

 object . Seek ( time )

ParameterDescription
object String identifying the Path object.
time Double value, format seconds.milliseconds (s.mss) that represents a different path playback elapsed time.


Spline Method

Description

Specifies a vector spline to be used as a path. The first point defines the starting point of the path. This method can be used or modified only when the path is stopped.

Syntax

PARAM Tag Syntax

<PARAM NAME="Shape" VALUE=" Spline(npoints,  [ x1, y1, x2, y2... ])">

Syntax

Script Syntax

 object . Spline ( npoints,  [ x1, y1, x2, y2... ] )

ParameterDescription
object String identifying the Path object.
npoints Number of points to be used to define the Spline.
x1 The first x point for the spline.
y1 The first y point for the spline.
x2 The second x point for the spline.
y2 The second y point for the spline.

Remarks

You need to specify 4 points for each curve in the spline. The array of x,y coordinates can be specified either as an array or as a comma delimited string of number that will be passed as the coordinate set. The number of points in the spline and their spacing can have an effect upon the speed of the path. Having too many points too close together along the path can cause the path to seem as if it is slowing down when it traverses those points.

Spline Method example

Right click inside the frame and select View Source to see the HTML code for this example.



Stop Method

Description

Stops playback of the path at the current position and rewinds the path to its beginning.

Syntax

VBscript Syntax

 object . Stop

Syntax

Jscript Syntax

 object . Stop( )


OnMarker Event

Description

Occurs when a time marker has been reached.

Syntax

VBScript Syntax

Sub  object _ onmarker ( markername )
	
 script
End Sub

Syntax

JScript Syntax

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

ParameterDescription
object String identifying the Path object.
markername String containing the marker name established in the AddTimeMarker method.
script Script to be executed.

Remarks

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


OnPause Event

Description

Occurs when path playback is paused.

Syntax

VBScript Syntax

Sub  object _ onpause ()
	script
End Sub

Syntax

JScript Syntax

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

ParameterDescription
object String identifying the Path object.
script Script to be executed.


OnPlay Event

Description

Occurs when path playback starts.

Syntax

VBScript Syntax

Sub  object _ onplay ()
 script
End Sub

Syntax

JScript Syntax

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

ParameterDescription
object String identifying the Path object.
script Script to be executed.


OnPlayMarker Event

Description

Occurs when a marker is reached during path playback.

Syntax

VBScript Syntax

Sub  object _ onplaymarker ( markername )
script
End Sub

Syntax

JScript Syntax

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

ParameterDescription
object String identifying the Path object.
markername String containing the marker name established in the AddTimeMarker method.
script Script to be executed.


OnSeek Event

Description

Occurs after a Seek call has been completed.

Syntax

VBScript Syntax

Sub  object _ onseek ( newtime )
script
End Sub

Syntax

JScript Syntax

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

ParameterDescription
object String identifying the Path object.
newtime Double value, format seconds.milliseconds (s.mss) that represents the new different path playback elapsed time.
script Script to be executed.


OnStop Event

Description

Occurs when the path stops playing.

Syntax

VBScript Syntax

Sub  object _ onstop ()
script
End Sub

Syntax

JScript Syntax

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

ParameterDescription
object String identifying the Path object.

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