3D Lingo Dictionary > O-S > registerForEvent()

 

registerForEvent()

Syntax

member(whichCastmember).registerForEvent(eventName, handlerName, scriptObject {, begin, period, repetitions})

Description

3D command; declares the specified handler as the handler to be called when the specified event occurs within the specified cast member.

The following parameter descriptions apply to both the registerForEvent() and the registerScript() commands.

The handlerName parameter is the name of the handler that will be called; this handler is found in the script object indicated by scriptObject.

If 0 is specified for scriptObject, then the first event handler with the given name found in a movie script is called.

The eventName parameter can be any of the following predefined Lingo events, or any custom event that you define:

#collideAny is a collision event.

#collideWith is a collision event involving this specific model. The setCollisionCallback() command is a shortcut for using the registerScript() command for the #collideWith event.

#animationStarted and #animationEnded are notification events that occur when a bones or keyframe animation starts or stops playing. The handler will receive three arguments: eventName, motion, and time. The eventName argument is either #animationStarted or #animationEnded. The motion argument is the name of the motion that has started or stopped playing, and time is the current time of the motion.

For looping animations, the #animationStarted event is issued only for the first loop, not for subsequent loops. During a blend of two animations, this event will be sent when the blending begins.

When a series of animations is queued for the model and the animation's autoBlend property is set to TRUE, the #animationEnded event may occur before the apparent end of a given motion. This is because the autoBlend property may make the motion appear to continue even though the animation has completed as defined.

#timeMS is a time event. The first #timeMS event occurs when the number of milliseconds specified in the begin parameter have elapsed after registerForEvent is called. The period parameter determines the number of milliseconds between #timeMS events when the value of repetitions is greater then 0. If repetitions is 0, the #timeMS event occurs indefinitely.

The handler you specify is sent the following arguments:

type is always 0.

delta is the elapsed time in milliseconds since the last #timeMS event.

time is the number of milliseconds since the first #timeMS event occurred. For example, if there are three iterations with a period of 500 ms, the first iteration's time will be 0, the second iteration will be 500, and the third will be 1000.

duration is the total number of milliseconds that will elapse between the registerForEvent call and the last #timeMS event. For example, if there are five iterations with a period of 500 ms, the duration is 2500 ms. For tasks with unlimited iterations, the duration is 0.

systemTime is the absolute time in milliseconds since the Director movie started.

Note: You can associate the registration of a script with a particular node rather than a cast member by using the registerScript() command.

Examples

This statement registers the promptUser event handler found in a movie script to be called twice at an interval of 5 seconds:

member("Scene").registerForEvent(#timeMS, #promptUser, 0,5000, 5000, 2)

This statement registers the promptUser event handler found in a movie script to be called each time a collision occurs within the cast member named Scene:

member("Scene").registerForEvent(#collideAny, #promptUser, 0)

This statement declares the on promptUser handler in the same script that contains the registerForEvent command to be called when any object collides with the model named Pluto in the cast member named Scene:

member("Scene").registerForEvent(#collideWith, #promptUser, me, member("Scene").model("Pluto"))

See also

setCollisionCallback(), registerScript(), play(), playNext(), autoblend, blendTime, sendEvent