DABehavior Class

All behaviors are potentially time-varying and/or reactive values such as colors, numbers and images. They can be used to construct animated objects. All behavior subclasses inherit the functions of the DABehavior class.

Because all behaviors (animated objects) are potentially time-varying and/or reactive, their values can change as a function of time or as the result of user input. Time-varying behaviors are created by combining time-based default behaviors (such as LocalTime) with other behaviors. Reactive behaviors are created using the Until and UntilEx functions and by specifying input events, such as mouse clicks. Complex behaviors can be built by combining existing behaviors. The value of a complex behavior always depends on the values of the behaviors that comprise it.

When a behavior runs, its time-varying and reactive qualities are active. This means the user can experience any changes that occur in the behavior as time passes or events occur.

For relevant functions in the DAStatics class, see DAStatics Functions Relevant to DABehavior Objects.

DABehavior Functions

Duration Creates an animation fragment by associating a local "stop time" with a behavior. Same as DurationAnim except the duration is not animated.

DurationAnim Creates an animation fragment by associating a local "stop time" with a behavior.

GetClassName Retrieves the name of an object's class.

Hook Enables a running behavior to be sampled.

Importance Sets the relative importance of the behavior to a scene.

Init Initializes an uninitialized object.

IsReady Determines if all the imports for the behavior have been downloaded.

Repeat Creates a behavior that repeats itself the number of times specified.

RepeatForever Creates a behavior that repeats infinitely.

RunOnce References a running behavior once it starts running, but doesn't explicitly start that behavior.

SubstituteTime Creates a new behavior in which all occurrences of LocalTime in the original behavior are replaced by the specified value.

SwitchTo Replaces one behavior with another.

SwitchToEx Extends the DABehavior SwitchTo function by enabling you to specify flags that control the switching.

SwitchToNumber Replaces a behavior with a number (a double).

SwitchToString Replaces a behavior with a string.

DABehavior Properties

EndEvent A read-only property that specifies the event on which the behavior will finish.

DABehavior Functions

This section contains reference material for the DABehavior functions.

Duration

DABehavior Class

Creates an animation fragment by associating a local "stop time" with a behavior. Same as DurationAnim except the duration is nonanimated.

Syntax

behaviorObj.Duration( length )

Parameters

length
A double value representing the length of time, in seconds, that the duration lasts. This is a nonanimated number.

Return Value

Returns the DABehavior object.

DurationAnim

DABehavior Class

Creates an animation fragment by associating a local "stop time" with a behavior. The result is a new behavior that is the same as the original behavior for the length of the duration. Once the duration is over, the behavior is a snapshot of the behavior's state when the duration ended.

Syntax

behaviorObj.DurationAnim( length )

Parameters

length
DANumber object representing the length of time, in seconds, that the duration lasts. This must be an animated number.

Return Value

Returns the DABehavior object.

GetClassName

DABehavior Class

Retrieves the name of an object's class.

Syntax

behaviorObj.GetClassName( )

Return Value

Returns a string.

Hook

DABehavior Class

Enables a running behavior to be sampled.

Syntax

behaviorObj.Hook( notifier )

Parameters

notifier
The IDABvrHook object that controls the sampling of the DABehavior.

Return Value

Returns a DABehavior object that is the sampled behavior returned from the IDABvrHook method Notify.

Importance

DABehavior Class

Creates a new behavior and assigns it relative importance. The importance value enables you to sample scene elements at different update rates. Objects with lower importance are redrawn less often than objects with higher importance. You can use this function to set the importance of different behaviors in a scene. For example, you might set a background to an importance of 0.5 and a foreground object to an importance of 1.0.

Syntax

behaviorObj.Importance( relativeImportance )

Parameters

relativeImportance
A number (double) between 0 and 1.0, inclusive, that specifies the relative importance of the behavior in a scene.

Return Value

Returns the DABehavior object.

Init

DABehavior Class

Initializes an uninitialized object.

Syntax

behaviorObj.Init( behavior )

Parameters

behavior
The behavior whose current value will be used to initialize the object.

Remarks

Here is an example of how to create an uninitialized DAPoint2 object in VBScript:
Set myPt = CreateObject("DirectAnimation.DAPoint2")
And here is how to create an uninitialized object in JScript:
myPt = new ActiveXObject("DirectAnimation.DAPoint2");
To initialize the object in VBScript, use:
myPt.Init(...)
The only difference in JScript is that it needs a semicolon at the end of the line. For example, consider the following JScript code:
myPt.Init(m.Until(position, resetEvent, resetPosition));
The Init function can also be used on uninitialized arrays (UninitializedArray) and uninitialized DATuple objects (UninitializedTuple).

IsReady

DABehavior Class

Determines if all the imports for the behavior have been downloaded. Only works when the behavior itself is an import. Otherwise returns E_NOTIMPL.

Syntax

behaviorObj.IsReady( bBlock )

Parameters

bBlock
A Boolean which, if FALSE, indicates that IsReady should return immediately and, if TRUE, indicates that it should block until the behavior is ready.

Return Value

Returns a Boolean which, if TRUE, means all the imports have been downloaded.

Repeat

DABehavior Class

Creates a behavior that repeats itself the number of times specified by repetitions.

Syntax

behaviorObj.Repeat( repetitions )

Parameters

repetitions
Number of times the behavior will repeat.

Return Value

Returns the DABehavior object.

RepeatForever

DABehavior Class

Creates a behavior that repeats infinitely.

Syntax

behaviorObj.RepeatForever( )

Return Value

Returns the DABehavior object.

RunOnce

DABehavior Class

Used when applications must reference a running behavior once it starts running, but don't require the application to explicitly start that behavior.

Syntax

behaviorObj.RunOnce( )

SubstituteTime

DABehavior Class

Creates a new behavior from an existing DABehavior and a DANumber. In the new behavior, the animated number replaces all occurrences of LocalTime in the original behavior. (This includes behaviors where LocalTime is implicit, such as imported movies. The function can be used even if LocalTime isn't explicitly in the code.) For example, this allows behaviors to be time-scaled to run faster or slower, time-shifted to start at a different time, or frozen at a particular point in time.

Syntax

behaviorObj.SubstituteTime( a )

Parameters

a
DANumber object that replaces LocalTime.

Return Value

Returns the DABehavior object.

SwitchTo

DABehavior Class

Replaces one behavior with another. The initial behavior is set with the ModifiableBehavior function in the DAStatics class or with the CurrentBehavior property in the DAModifiableBehavior class.

Syntax

behaviorObj.SwitchTo( newBehavior )

Parameters

newBehavior
DABehavior object that will replace the initial behavior.

SwitchToEx

DABehavior Class

Extends the DABehavior SwitchTo function by enabling you to specify flags that control the switching.

Note You can only use this function with Microsoft® DirectAnimation® version 6.x or later.

Syntax

behaviorObj.SwitchToEx( newBvr, dwFlags )

Parameters

newBvr
DABehavior object that will replace the initial behavior.

dwFlags
DWORD (32-bit unsigned integer) value that contains the switcher flags, which can be one or more of the following values.

DAContinueTimeline = 1
Indicates that the time line of the behavior switched to will start at the beginning of the initial behavior's time line, not at the time of the switch. For example, if the initial behavior started at time t0, and the switch occurs at time ts, the switched-to behavior will behave as if it began at time t0 and has continued through to ts. If you switch to a reactive behavior with this flag set, events that might have altered the behavior between t0 and ts will have no effect.

DASwitchFinal = 2
Indicates that this switch is final and the behavior won't switch again, so DirectAnimation can perform optimization based on the fact that switching won't occur again.

DASwitchNextTick = 4
Indicates that the switch should occur at the next tick. Typically, there is a tick with every new frame.

Return Value

Returns the DABehavior object with the specified switching behavior.

Remarks

The following code switches bvr to newbvr and sets the switching flags to DAContinueTimeline and DASwitchNextTick. The | operator is a bit-wise logical OR.
bvr.SwitchToEx(newbvr, (1 | 4));

SwitchToNumber

DABehavior Class

Changes the value of a modifiable DANumber object. You can create a modifiable DANumber object with the DAStatics function ModifiableNumber.

Note You can only use this function with DirectAnimation version 6.x or later.

Syntax

behaviorObj.SwitchToNumber( numToSwitchTo )

Parameters

numToSwitchTo
Number (double) that will replace the initial value of the modifiable DANumber object.

SwitchToString

DABehavior Class

Changes the value of a modifiable DAString object. You can create a modifiable DAString object with the DAStatics function ModifiableString.

Note You can only use this function with DirectAnimation 6.x or later.

Syntax

behaviorObj.SwitchToString( strToSwitchTo )

Parameters

strToSwitchTo
A string that will replace the initial value of the modifiable DAString object.

DABehavior Properties

This section contains reference material for the DABehavior properties.

EndEvent

DABehavior Class

Retrieves the DAEvent object that defines when the behavior will finish. This event is most likely a timer.

Note You can only use this function with DirectAnimation 6.x or later.

Syntax

behaviorObj.EndEvent

Return Value

Returns the DAEvent object.