    Contents  Index  Topic Contents
    Previous Topic: DirectAnimation Multimedia Controls
    Next Topic: Sequencer Control

> ## Path Control

> The Path control is a windowless Microsoft® DirectAnimation™ control that animates the position of other controls along a defined vector or spline shape-based path.

> To use the Path control, you must first instantiate it on the HTML page, as shown in the following syntax:

> 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 following table.
> setting | Value for the property.

> Path Control Properties

> Property | Description
> AutoStart | Determines whether the Path control 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 | Retrieves the DirectAnimation library reference.
> PlayState | Retrieves 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 will follow the path.
> Time | Retrieves the elapsed playback time from the start of the path.
> TimerInterval | Sets or retrieves the length of time, in seconds.milliseconds, between path updates.

> Path Control Methods

> 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 as the path.
> PolyLine | Specifies an open set of line segments to use as the path.
> Rect | Specifies a rectangular structured graphics primitive to use 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.

> Path Control Events

> Event | Description
> onmarker | Occurs when the path playback reaches a marker at the specified playback position, either when the Path control is playing or when it is stopped (and reaches the marker through a Seek call, for example).
> onpause | Occurs when path playback pauses.
> onplay | Occurs when the Path control plays back.
> onplaymarker | Occurs when path playback reaches a marker at the specified playback position.
> onseek | Occurs when the Path control completes a Seek call.
> onstop | Occurs when path playback stops.

> ###

> AutoStart Property

> Path Control

> Determines whether the path starts playback immediately after loading. Read/write at run time; write access is available at run time only when the path is stopped.

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

> Script Syntax
> object.AutoStart=[fStart]

> ##### Parameters

> 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 the Play method. The default value is False.

> ###

> Bounce Property

> Path Control

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

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

> Script Syntax
> object.Bounce=[fBounce]

> ##### Parameters

> 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

> Path Control

> 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.

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

> Script Syntax
> object.Direction=fDirection

> ##### Parameters

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

> ###

> Duration Property

> Path Control

> 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.

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

> Script Syntax
> object.Duration=[ time ]

> ##### Parameters

> 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 the path.

> ##### Remarks

> The Duration property does not take Bounce behavior into account. If the path is set to bounce, the Duration property sets the time between the start and the end of its playback, and does not include the time when the path behavior reverses direction and returns to the start of the path.

> ###

> Library Property

> Path Control

> Retrieves the reference to the DirectAnimation library functions.

> Script Syntax
> IDALibrary=object.Library

> ##### Parameters

> IDALibrary
>   DirectAnimation library pointer.
> object
>   String identifying the Path object.

> ###

> Playstate Property

> Path Control

> Retrieves the path's playback state: stopped, playing, or paused. Read-only at run time.

> Script Syntax
> state=object.Playstate

> ##### Parameters

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

> ###

> Relative Property

> Path Control

> 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.

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

> Script Syntax
> object.Relative=fPos

> ##### Parameters

> object
>   Path object.
> fpos
>   True (–1 or nonzero) or False (0). If True, then the path playback starts from the target's current position. If False, then the path playback starts from the absolute position in the target's coordinate space. (For example, if you are using a Rect path, the absolute position starting point is the top left.) The default value is False.

> ##### Remarks

> The Relative property means relative to the target object's position. The target object's position is set to relative or absolute with 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

> Path Control

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

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

> Script Syntax
> object.Repeat=[ nRepeat ]

> ##### Parameters

> object
>   String identifying the Path object.
> nRepeat
>   Integer expression setting the number of times the path repeats playback. Default value is 1. Set to –1 to cause the path to repeat infinitely; other negative values are treated as unsigned. Set to 0 to disable the Repeat property.

> ###

> Target Property

> Path Control

> Sets the object to follow the path. Read/write at run time; write access is available at run time only when the path is stopped.

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

> Script Syntax
> object.Target=[ objTarget ]

> ##### Parameters

> object
>   String identifying the Path object.
> objTarget
>   String identifying the path's target object.

> ##### Remarks

> The target object must have an initial position. This can be set with the target object's STYLE attribute, as shown in the following examples:

>     <IMG SRC="target1.gif" ID="target1" STYLE="position:relative">

> — or —

>     <IMG SRC="target1.gif" ID="target1" STYLE="position:absolute; left=100; top=100">

> Target Property example

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

> ###

> Time Property

> Path Control

> Retrieves the elapsed playback time (in milliseconds) from the start of the path playback. Repetitions set with Repeat are included in returned time calculations. Read-only at run time.

> Script Syntax
> time=object.Time

> ##### Parameters

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

> ###

> TimerInterval Property

> Path Control

> 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.

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

> Script Syntax
> object.TimerInterval=nInterval

> ##### Parameters

> nInterval
>   Integer expression giving the minimum number of seconds.milliseconds between path updates. The default interval is 0.100.

> ###

> AddTimeMarker Method

> Path Control

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

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

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

> ##### Parameters

> object
>   String identifying the Path object.
> X
>   A sequential integer identifying the time marker, starting at 1 (PARAM tag syntax only). 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.
> time
>   Time at which the onmarker or onplaymarker event fires.
> markername
>   Name of the marker.
> fAbsolute
>   An optional flag that specifies event firing. Default is True. If True (absolute) the event fires at the specified time once and ignores looping. If False (relative) the event fires everytime, including in loops. For PARAM tag syntax, use 0 for False and use –1 or nonzero for True. For script, use the 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 occurs only when the path is playing.

> This example sets three time markers named MyMark, FrameFour, and FrameZero at 0.0, 4.7, and 8.0 respectively. MyMark 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 uninterrupted playback.

>     <PARAM name="AddTimeMarker1" value="0.0, MyMark, 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

> Path Control

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

> PARAM Tag Syntax
> <PARAM NAME=" KeyFrame" VALUE=" npoints,
> [ x1,
> y1 ,
> ...,
> xN,
> yN ],
> [ time2,
> ...,
> timeN ]">

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

> ##### Parameters

> object
>   String identifying the Path object.
> npoints
>   Number of points to be used to define the polyline.
> x1, y1,...,xN, yN
>   Set of x and y coordinates that identify the keyframe points.
> time2,..., timeN
>   Respective times that the path takes to reach each of the respective points from the previous point.
> KeyFrameArray
>   Array that contains the x and y point definitions (script only).
> TimeFrameArray
>   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

> Path Control

> 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.

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

> Script Syntax
> object.Oval(
> xpos ,
> ypos ,
> width ,
> height )

> ##### Parameters

> 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
>   Width of the oval.
> height
>   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

> Path Control

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

> VBscript Syntax
> object.Pause

> JScript Syntax
> object.Pause( )

> ##### Parameters

> object
>   String identifying the Path object.

> ###

> Play Method

> Path Control

> Begins Path playback at current elapsed time.

> VBscript Syntax
> object.Play

> JScript Syntax
> object.Play( )

> ##### Parameters

> object
>   String identifying the Path object.

> ##### Remarks

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

> ###

> Polygon Method

> Path Control

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

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

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

> ##### Parameters

> object
>   String identifying the Path object.
> n_Points
>   Number of points in the polygon.
> x1, y1,..., xN, yN
>   Set of x and y coordinates that identify the polygon points.
> PolygonArray
>   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 a 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

> Path Control

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

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

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

> ##### Parameters

> object
>   String identifying the Path object.
> npoints
>   Number of points to be used to define the PolyLine.
> x1, y1,..., xN, yN
>   Set of x and y coordinates that identify the polygon points.
> PolyLineArray
>   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

> Path Control

> 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.

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

> Script Syntax
> object.Rect (
> xpos ,
> ypos ,
> width ,
> height )

> ##### Parameters

> 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
>   Width of the rectangle.
> height
>   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

> Path Control

> Seeks to another position in the Path playback.

> Script Syntax
> object.Seek (
> time )

> ##### Parameters

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

> ###

> Spline Method

> Path Control

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

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

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

> ##### Parameters

> object
>   String identifying the Path object.
> npoints
>   Number of points to be used to define the Spline.
> x1
>   First x point for the spline.
> y1
>   First y point for the spline.
> x2
>   Second x point for the spline.
> y2
>   Second y point for the spline.

> ##### Remarks

> You need to specify four points for each curve in the spline. You can specify the array of x, y coordinates either as an array or as a comma-delimited string of numbers that will be passed as the coordinate set. The number of points in the spline and their spacing can have an effect on the path's speed. 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

> Path Control

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

> VBscript Syntax
> object.Stop

> JScript Syntax
> object.Stop( )

> ###

> onmarker Event

> Path Control

> Occurs when the path playback reaches a marker at the specified playback position.

> 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 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

> Path Control

> Occurs when path playback is paused.

> VBScript Syntax
> Sub object _ onpause ( )
> script
> End Sub

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

> ##### Parameters

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

> ###

> onplay Event

> Path Control

> Occurs when path playback starts.

> VBScript Syntax
> Sub object _ onplay ( )
> script
> End Sub

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

> ##### Parameters

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

> ###

> onplaymarker Event

> Path Control

> Occurs when a marker is reached during path 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 Path object.
> markername
>   String containing the marker name established in the AddTimeMarker method.
> script
>   Script to be executed.

> ###

> onseek Event

> Path Control

> Occurs after a Seek call has been completed.

> VBScript Syntax
> Sub object _ onseek (
> newtime )
> script
> End Sub

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

> ##### Parameters

> 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

> Path Control

> Occurs when the path stops playing.

> VBScript Syntax
> Sub object _ onstop ( )
> script
> End Sub

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

> ##### Parameters

> object
>   String identifying the Path object.

> © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

> Top of Page