Change Handlers and When Constructs

Change Handlers are used to detect when certain types of user events are performed on objects in the scene, allowing you to write scripts that respond to user operations like object moves, vertex edits, object deletions, name changes, etc.. Change Handlers are applied to individual MAXWrapper objects and specify an attribute to monitor for that object and an expression to evaluate when that attribute changes. Example attributes that can be monitored are geometry, name, transform, and parameters. Change Handlers are not stored in a 3ds Max scene.

The ChangeHandler : Value class instances represent change handler setups. ChangeHandler values are created using the when construct. Each time a when construct is executed, it creates and returns a new ChangeHandler instance. You should store this ChangeHandler value in a variable or array so that you can dismiss the handler when it is appropriate to do so.

The when construct defines a change handler function for a certain type of event on one or more objects. The system then automatically calls this function whenever the event occurs.

The syntax of the when construct has two forms as follows:

when <attribute> <objects> change[s] [ id:<name> ] \ [handleAt:#redrawViews|#timeChange] \ [ <object_parameter> ] do <expr>

 

when <objects> deleted [ id:<name> ] \ [handleAt:#redrawViews|#timeChange] \ [ <object_parameter> ] do <expr> \

 

In the first form, the <attribute> can be one of:

topology

geometry

name[s]

transform

select

parameters

subAnimStructure

controller

children

These specify the attribute of the given object(s) to be tracked for change (see below for more details).

The second form tracks object deletion by the user or other scripts. For object deletion events, the handler is called after the object is deleted, so you cannot perform any 3ds Max operations on it. This is typically used if you have tables or other structures containing MAXScript object values and you want to remove deleted objects from them as the user modifies the scene.

In both forms, the <objects> argument can be one of the following:

If more than one object is specified, the handler is called each time the given attribute of any of the objects is signaled as changed by the 3ds Max core.

The optional id: parameter specifies an ID for one or more handlers as a name literal. The ID name can later be used to delete the handler and, if the same name is given to several handlers, they can be deleted as a group.

The optional handleAt: parameter signals that the change handler expression should not be executed immediately upon notification, but delayed until the either the 3ds Max viewports are redrawn (#redrawViews) or current 3ds Max animation time is changed (#timeChange). Delaying the processing of the change handler expression is highly recommended, as described in the Caution section below. An example usage of the handleAt: parameter is:when select $ changes id:#foo handleAt:#redrawViews do ...

The optional <object_parameter> lets you specify the name of a parameter variable that will be accessible in the do <expr> and will hold the actual object that has changed. You typically specify this parameter name if the handler will respond to changes in many objects, so you can determine which one has changed. The <expr> can be a single expression or block expression.

Examples

when transform $box01 changes do

$box02.pos = $box01.pos + delta

when names selection change obj do update_name_table obj

when #($foo, $baz, $bar) deleted obj do

(

messageBox "Warning!"

deleteItem obj_table (findItem obj_table obj)

)

The change attributes are interpreted as follows:

topology

Signaled when the topology of an object changes in the Modify panel, such as via a mesh smooth, optimize, or vertex delete.

geometry

Signaled when the geometry of an object changes, such as by moving a vertex or via an animated modifier.

name or names

Signaled when the name of an object is changed if this occurs because a user edits the name in one of the 3ds Max command panels. The handler is called repeatedly with each character that is changed.

transform

Signaled when the transform of an object is changed, such as by a move, rotate, or scale.

select

Signaled when a scene node moves into or out of the current selection set. You should interrogate the <node>.isSelected property to determine the new state.

parameters

Signaled when any parameters are changed in the object. This is something of a catch all, because the core signals this event in many situations.

subAnimStructure

Signaled when the dynamic subAnim structure changes, such as when a new vertex becomes animated in an editable mesh, or when a new controller is added to a list controller. Also called when subAnims are reassigned, for example, when a material is changed in an object.

controller

Signaled when a new controller is assigned to one of the object's tracks.

children

Signaled when an object has immediate children added or removed.

You can use the following two methods for deleting change handlers:

deleteChangeHandler <change_handler>

deletes specified change handler. change_handler is the value returned by a when construct.

deleteAllChangeHandlers [ id:<name> ]

If optional id: parameter is not specified, deletes all change handlers. If optional id: parameter is specified, deletes all change handlers with the specified id.

For example:

deleteAllChangeHandlers id:#foo

 

For efficiency reasons, you don't want irrelevant change handlers running in the background, so it is essential that you delete those that you no longer need.

Special Considerations

For example, if you say:

when select $ changes obj do update_modifier_list obj

 

The function update_modifier_list is called whenever any object is selected or deselected. This is true even if you do an Edit / Select All. In this case, update_modifier_list will be called once for each object currently selected (as the objects are deselected), and then once for all objects in the scene (as the objects are selected). If update_modifier_list is at all processor-intensive, a significant system slowdown can occur.

Caution:

The change handler system is based on 3ds Max's internal notification system which essentially drives all animation and interactivity within 3ds Max. There are cases when the core sends many, many signals for the same change, so setting up change handlers on many objects that do vast amounts of computing can significantly slow down the system. Strictly speaking, change handlers are supposed to be used to just set "dirty flags" in a lightweight, order-independent way, and then use Redraw Views or Time Change callbacks to actually cause the triggered processing. You should attempt to use change handlers judiciously, and not, for example, as a simple way to get scripted controllers. If you do find that a desired setup is being flooded with unnecessary signals, you should use the handleAt: to delay the actual processing of the event handler script until a redrawViews or timeChange event occurs.

See also

Change Handlers and Callbacks

Time Change Callback Mechanism

Viewport Redraw Callback Mechanism

General Event Callback Mechanism