Node Event System

new.gif NEW in 3ds Max 2009: The Node Event System introduced in 3ds Max 2009 lets you define a scripted function that is triggered in response to any of various node-related scene events. The events map one-to-one with the event methods of class INodeEventCallback in the 3ds Max SDK. For detailed information on each, read the methods comments for class INodeEventCallback in maxsdk\include\ISceneEventManager.h

 

The Node Event System is similar to the General Event Callback Mechanism. It operates as a layer over the General Event Callback system, but also receives some node messages which the older system cannot handle, like geometry, topology and mapping changes. This system will also catch events which happen as a result of undo/redo, while the older system sometimes would not.

Thus, if you wish to catch nodes-related events and changes to nodes, the Node Event System is your best option.

NOTE:

The Node Event System is inappropriate for catching any events except those specifically related to scene nodes!

Contructor:

<callbackItem>NodeEventCallback [mouseUp:<bool>] [delay:<integer>] \

[callbackBegin:<fn>] [all:<fn>] \

[added:<fn>] [deleted:<fn>] \

[linkChanged:<fn>] [layerChanged:<fn>] \

[groupChanged:<fn>] [hierarchyOtherEvent:<fn>] \ [modelStructured:<fn>] [geometryChanged:<fn>] \

[topologyChanged:<fn>] [mappingChanged:<fn>] \

[extentionChannelChanged:<fn>] [modelOtherEvent:<fn>] \

[materialStructured:<fn>] [materialOtherEvent:<fn>] \

[controllerStructured:<fn>] [controllerOtherEvent:<fn>] \

[nameChanged:<fn>] \

[wireColorChanged:<fn>] [renderPropertiesChanged:<fn>] \ [displayPropertiesChanged:<fn>] [userPropertiesChanged:<fn>] \

[propertiesOtherEvent:<fn>] \

[subobjectSelectionChanged:<fn>] [selectionChanged:<fn>] \

[hideChanged:<fn>] [freezeChanged:<fn>] \ [displayOtherEvent:<fn>] [callbackEnd:<fn>]

 

The example script below prints a message to the MAXScript Listener when any message is received by registering a function to the optional keyword argument all:

The script also displays a message box when the linkChanged or layerChanged event occurs, that is, whenever one node is linked or unlined from another node, or moved to a different layer.

 

EXAMPLE SCRIPT:

 

--Define a callback function to handle linking and layer changes:

fn CallbackFn1 ev nd = (

 messageBox ("Event Detected: Event "+(ev as string)+ \

 ", Nodes " + (nd as string))

)

 

--Define a callback function to handle ALL messages:

fn CallbackFn2 ev nd = (

 format "Event Detected: Event %, Nodes %\n" ev nd )

 

--Register callbacks for link changes, layer changes using the

--first function and for all changes using the second function.

--Act only when mouse is up and there have been no other events

--within one second (1000 milliseconds):

callbackItem = NodeEventCallback mouseUp:true delay:1000 linkChanged:CallbackFn1 layerChanged:CallbackFn1 all:CallbackFn2

 

 

Handling optional keyword parameters:

mouseup:

If the optional keyword argument mouseUp: is set to true, the callback will only be triggered when the mouse button is released.

 

delay:

When the optional keyword argument delay: is supplied (as time in milliseconds), the callback is only triggered if the given time passes with no events, that is, only after the system is idle for the specified time.

Callback Function optional keyword parameters:

One or more of the other optional keyword arguments can be supplied with pre-defined MAXScript Functions to be executed if a callback of the specified type is found in the message received by the Node Event System.

The callback functions take two parameters: the first is the event name that triggered the function call, the second is a list of node AnimHandles. The GetAnimByHandle() method must be used to get the node itself.

Callback Batch Handling:

callbackBegin:

callbackEnd:

When a callback is triggered, messages for all queued events will be sent in one batch.

The callbackBegin: message indicates the start of a batch, while callbackEnd: indicates the end of a batch.

Registering functions using these two optional keyword arguments lets you get notification of the beginning and the end of a single message batch.

 

all:

The supplied function will be called whenever ANY of the node-related messages listed below has been received.

Node Creation and Removal Callbacks:

added:

The supplied function will be called whenever a node has been added to the scene.

 

deleted:

The supplied function will be called whenever a node has been deleted from the scene.

Node Hierarchy, Layer and Group Callbacks:

linkChanged:

The supplied function will be called whenever the node is linked to or unlinked from another node.

 

layerChanged:

The supplied function will be called whenever the node has moved to another layer.

 

groupChanged:

The supplied function will be called whenever the node has been added or removed from a group.

 

hierarchyOtherEvent:

The supplied function will be called whenever the node's hierarchy has been changed in some other way.

Node Model, Geometry, Topology and Mapping Callbacks:

modelStructured:

The supplied function will be called whenever the model's structure has been modified.

 

geometryChanged:

The supplied function will be called whenever the geometry of the node has changed, for example a vertex has been moved.

 

topologyChanged:

The supplied function will be called whenever the topology of the node's geometry has changed, for example an edge has been added or removed.

 

mappingChanged:

The supplied function will be called whenever the mapping of the node's geometry has changed, for example UV coordinates have been assigned or modified.

 

extentionChannelChanged:

The supplied function will be called whenever the a non-mapping channel of the node has been changed, for example Vertex Alpha, Soft-Selection and so on.

 

modelOtherEvent:

The supplied function will be called whenever the node's model has been changed in some other way.

Node Material Callbacks:

materialStructured:

The supplied function will be called whenever a material has been added or removed from the node.

 

materialOtherEvent:

The supplied function will be called whenever the node's material has been changed.

Node Controller Callbacks:

controllerStructured:

The supplied function will be called whenever a controller has been assigned or removed to a SubAnim track of the node.

 

controllerOtherEvent:

The supplied function will be called whenever a node's controller has been changed in another way.

Node Name and Properties Callbacks:

nameChanged:

The supplied function will be called whenever the name of the node has been changed.

 

wireColorChanged:

The supplied function will be called whenever the wireframe color of the node has been changed.

 

renderPropertiesChanged:

The supplied function will be called whenever the Render Properties of the node has been changed, including Renderable, Visible To Camera, Visible To Reflections and so on.

 

displayPropertiesChanged:

The supplied function will be called whenever a disdlay property of the node has been changed, for example "Display As Box", "Show Vertex Ticks", "Backface Culling" and so on.

 

userPropertiesChanged:

The supplied function will be called whenever the User Properties buffer of the node has been changed.

 

propertiesOtherEvent:

The supplied function will be called whenever any other properties of a node have been changed.

Node Selection Callbacks:

subobjectSelectionChanged:

The supplied function will be called whenever the sub-object selection of a node has changed.

 

selectionChanged:

The supplied function will be called whenever the selected state of the node has changed, for example a node has been selected or deselected.

Node Display Callbacks:

hideChanged:

The supplied function will be called whenever the Hidden flag of a node has changed.

 

freezeChanged:

The supplied function will be called whenever the Frozen flag of a node has changed.

 

displayOtherEvent:

The supplied function will be called whenever other display flags of a node have changed.

 

See also:

General Event Callback Mechanism

Change Handlers and When Constructs

 

Change Handlers and Callbacks