Callbacks and Events¶
Registering a Callback¶
-
Callbacks.
addCallback
(self, callbackType, callbackFcn, callbackObjectHash=None)¶
-
Callbacks.
delCallback
(self, callbackType, callbackFcn, callbackObjectHash=None)¶
Registering an Event Handler¶
A queue for passing and handling events.
Events are a combination of a string eventType and an eventID. The eventID is almost always an integer value, but special event types could use other hashable objects.
Handlers can filter on the eventType and/or eventID. Handlers for all
queued events are called when ProcessEvents
is called.
The callback handlers are held with weak references. If they are attached to an object that is destroyed, the callback will not be made.
Handlers can be registered to eventType None
and eventID
None
which will be called for every event that is sent.
-
Utils.EventModule.
QueueEvent
(eventType, eventID, priority=0, **kwargs)¶ Add an event to the queue. The additional named arguments are passed to the event handlers.
Parameters: - eventType (
str
) – the event type that will be queued. - eventID (
hashable
) – hashable value - priority (
int
) – the priority of this event priority < 0 - low priority priority = 0 - normal priority priority > 0 - high priority - kwargs (
dict
) – other keyword arguments
- eventType (
-
Utils.EventModule.
QueuePriorityEvent
(eventType, eventID, **kwargs)¶ Add an event to the queue indicating that is should be handled as soon as possible.
-
Utils.EventModule.
ProcessEvents
()¶ All queued events are passed to the registered handlers.
Returns: True
if events were processed elseFalse
.Return type: bool
See: ProcessAllEvents
-
Utils.EventModule.
ProcessAllEvents
()¶ Process events until the queue is empty.
Some handlers will add new events of their own. When this happens a single
ProcessEvents
call does not clear the queue completely.
-
Utils.EventModule.
RegisterEventFilter
(eventFilter)¶ Registers a new event filter.
Filters are callbacks that happen when all events are placed on the queue, not at
ProcessEvents
time.If the filter callback returns False, the event is blocked from getting onto the queue, and never reaches the handlers.
The filter should not raise an exception. A raised exception will block other Filters and abort the new event.
-
Utils.EventModule.
IsEventFilterRegistered
(eventFilter)¶ Return type: bool
Parameters: eventFilter ( callable
) – The callback to check.Returns: True
if the given callback is registered as an event filter callback, otherwiseFalse
.
-
Utils.EventModule.
UnregisterEventFilter
(eventFilter)¶ Unregisters an existing event filter.
Filters are callbacks that happen when all events are placed on the queue, not at
ProcessEvents
time.Parameters: eventFilter ( function
) – The event filter function to unregister.
-
Utils.EventModule.
RegisterEventHandler
(handler, eventType=None, eventID=None, enabled=True)¶ Registers a handler to be called when events are processed. By supplying specific eventType and eventID arguments, you can limit which events actually call the handler. Setting enabled to False unregisters the handler. Event handlers are protected from exceptions.
This will raise a ValueError exception if a duplicate handler is registered for the same eventType and eventID.
Raises: ValueError – duplicate handler found
-
Utils.EventModule.
UnregisterEventHandler
(handler, eventType=None, eventID=None)¶ Unregisters a handler from processing events. This is the same as calling RegisterEventHandler(..., enabled=False)
This will raise a ValueError exception if an existing handler for this eventType and eventID is not registered.
Raises: ValueError – handler not found
-
Utils.EventModule.
RegisterCollapsedHandler
(handler, eventType=None, eventID=None, enabled=True)¶ Registers a handler to be called when events are processed.
This handler will be called at most one time per ProcessEvents. It will be passed a sequence of argument values that would have been passed to a normally registered event handler.
This will raise a ValueError exception if a duplicate handler is registered for the same eventType and eventID.
Raises: ValueError – duplicate handler found
-
Utils.EventModule.
UnregisterCollapsedHandler
(handler, eventType=None, eventID=None)¶ Unregisters a collapsed handler from processing events. This is the same as calling RegisterCollapsedHandler(..., enabled=False)
This will raise a ValueError exception if an existing handler for this eventType and eventID is not registered.
Raises: ValueError – handler not found
-
Utils.EventModule.
RegisterDebugEventHandler
()¶ This registers a simplistic event debugger. The debug handler logs every event as it is processed. Note that this ignores the ‘event_idle’ which happens on every process.
-
Utils.EventModule.
IsHandlerRegistered
(handler, eventType=None, eventID=None)¶ Determines if the specified handler is already registered. This corresponds with whether or not RegisterEventHandler / UnregisterEventHandler will raise ValueError exception.
-
Utils.EventModule.
IsHandlerRegisteredForEventType
(eventType, checkEventID=True)¶ For the specified eventType, are any handlers (both collapsed or individual) registered?
If checkEventID is False, this will only look for handlers that are register using the ‘None’ eventID. If checkEventID is True, this will also check for those callbacks.
-
Utils.EventModule.
GetAllRegisteredEventTypes
()¶ Get all of the event types that have been registered. (both collapsed and individual)
-
Utils.EventModule.
GetNumRegisteredHandlersForEventType
(eventType)¶ Get the number of handlers that have been registered for the specified eventType (both collapsed and individual).
-
Utils.EventModule.
SynchronousEventProcessingScope
(*args, **kwds)¶ Context manager that forces all events that are queued through a call to
QueueEvent
to be processed synchronously, as soon as they are queued.
-
Utils.EventModule.
SetRegistrationCallbackForType
(objectType, callback)¶ Sets a callback to be called when an event handler is registered that operates on an instance of a class derived from the given class.
Parameters: - objectType (
type
) – The class to use when checking instances of event handler objects. - callback (
callable
) – The callback to call when an event handler is registered.
Raises: ValueError – If the given callback object is not callable.
- objectType (
-
Utils.EventModule.
UnregisterObjectEventHandlers
(objectID)¶ Unregisters all event handlers, both regular and collapsed, that are currently registered to operate on the event handler object with the given ID.
Parameters: objectID ( int
) – The ID of the event handler object whose event handlers to unregister.
-
Utils.EventModule.
PumpIdleQueue
()¶ Causes the EventModule implementation to schedule the processing of idle event handlers (handlers registered for event type: event_idle).
Event Types¶
To see a list of event types:
import Utils.EventModule
print Utils.EventModule.GetAllRegisteredEventTypes()
-
node_create
¶ A node is created
Parameters: - eventID –
hash(Node)
- node – the created node
- nodeType – the type used to create the node
- nodeName – the name of the node created
- eventID –
-
node_setName
¶ Node name changed
Parameters: - eventID –
hash(Node)
- node – the node renamed
- oldName – previous node name
- newName – current node name
- eventID –
-
node_setParent
¶ Node parent changed
Parameters: - eventID –
hash(Node)
- node – node parented
- nodeName – name of the node parented
- oldParent – old parent node
- oldParentName – old parent node name
- newParent – new parent node
- newParentName – new parent node name
- eventID –
-
node_setLocked
¶ Node locked or unlocked
Parameters: - eventID –
hash(Node)
- node – node locked
- locked – boolean state of node lock
- eventID –
-
node_setBypassed
¶ Node ignored
Parameters: - eventID –
hash(Node)
- node – node locked
- bypassed – boolean state of node bypass
- eventID –
-
node_setFloating
¶ Node floating state changed
Parameters: - eventID –
hash(Node)
- node – node floated
- eventID –
-
node_setHidden
¶ Node hidden state changed
Parameters: - eventID –
hash(Node)
- node – node hidden
- eventID –
-
node_setEdited
¶ Node edit state changed
Parameters: - eventID –
hash(Node)
- node – node edited
- eventID –
-
node_setViewed
¶ Node view state changed
Parameters: - eventID –
hash(Node)
- node – node viewed
- eventID –
-
node_setSelected
¶ Node selection state changed
Parameters: - eventID –
hash(Node)
- node – node selected
- eventID –
-
node_attributeEditorSetActive
¶ AttributeEditor node active state changed
Parameters: - eventID –
hash(Node)
- node – AttributeEditor node changed
- eventID –
-
node_setPosition
¶ Node moved in graph view
Parameters: - eventID –
hash(Node)
- node – node moved
- nodeName – name of the node moved
- oldPosition – previous (x,y) position
- newPosition – current (x,y) position
- eventID –
-
node_delete
¶ Node destroyed
Parameters: - eventID –
hash(Node)
- node – node in a zombie state
- oldName – name of the node before death
- eventID –
-
node_addInputPort
¶ Node input port added
Parameters: - eventID –
hash(Node)
- node – node modified
- nodeName – name of node modified
- port – port object added
- portName – name of new port
- eventID –
-
node_addOutputPort
¶ Node output port added
Parameters: - eventID –
hash(Node)
- node – node modified
- nodeName – name of node modified
- port – port object added
- portName – name of new port
- eventID –
-
node_renameInputPort
¶ Node input port renamed
Parameters: - eventID –
hash(Node)
- node – node modified
- nodeName – name of node modified
- oldPortName – old name of renamed input port
- newPortName – new name of renamed input port
- eventID –
-
node_renameOutputPort
¶ Node output port renamed
Parameters: - eventID –
hash(Node)
- node – node modified
- nodeName – name of node modified
- oldPortName – old name of renamed output port
- newPortName – new name of renamed output port
- eventID –
-
node_removeInputPort
¶ Node input port removed
Parameters: - eventID –
hash(Node)
- node – node modified
- nodeName – name of node modified
- port – port object removed
- portName – name of removed port
- eventID –
-
node_removeOutputPort
¶ Node output port removed
Parameters: - eventID –
hash(Node)
- node – node modified
- nodeName – name of node modified
- port – port object removed
- portName – name of removed port
- eventID –
-
node_tagFlavor
¶ Node flavor changed
Parameters: - eventID –
0
- flavor – the flavor that was added, removed, or cleared
- eventID –
-
parameter_setValue
¶ Parameter’s value changed (during continuous manipulation)
Parameters: - eventID –
hash(Node)
- param – parameter changed
- node – parameter node
- eventID –
-
parameter_finalizeValue
¶ Parameter’s value changed (on pen up)
Parameters: - eventID –
hash(Node)
- param – parameter changed
- node – parameter node
- eventID –
-
parameter_setKey
¶ Key about to be added to parameter curve
Parameters: - eventID –
hash(Node)
- param – parameter changed
- keyTime – time of keyframe added
- node – parameter node
- eventID –
-
parameter_removeKey
¶ Key about to be removed from parameter curve
Parameters: - eventID –
hash(Node)
- param – parameter changed
- keyTime – time of keyframe changed
- node – parameter node
- eventID –
-
parameter_removeKeys
¶ Keys about to be removed from parameter curve
Parameters: - eventID –
hash(Node)
- param – parameter changed
- node – parameter node
- eventID –
-
parameter_moveKeys
¶ Keys about to be moved on parameter curve
Parameters: - eventID –
hash(Node)
- param – parameter changed
- node – parameter node
- eventID –
-
parameter_createChild
¶ Child parameter created
Parameters: - eventID –
hash(Node)
- param – the parent parameter under which a child parameter has been created
- paramName – the full name of the parent parameter
- node – the node that contains the parent parameter and its new child
- childParam – the child parameter that has been created
- element – a PyXmlIO element representing the new child parameter
- index – the index of the child parameter within its parent parameter
- eventID –
-
parameter_deleteChild
¶ Child parameter deleted
Parameters: - eventID –
hash(Node)
- param – the parent parameter under which a child parameter has been deleted
- paramName – the full name of the parent parameter
- node – the node that contains the parent parameter
- childParam – the child parameter that has been deleted
- element – a PyXmlIO element representing the deleted child parameter
- childName – the name of the deleted child parameter
- index – the previous index of the child parameter within its parent parameter
- eventID –
-
parameter_replaceXML
¶ Parameter hierarchy changed
Parameters: - eventID –
hash(Node)
- param – root parameter changed
- paramName – root parameter name
- oldXML – previous XML representation
- newXML – current XML representation
- node – parameter node
- eventID –
-
parameter_setAutoKeyAll
¶ Global autokey state changed
Parameters: eventID – 0
-
port_connect
¶ Ports of nodes have been connected
Parameters: - eventID –
hash(Port)
- portA – The output port that was connected to an input port.
- nodeNameA – The name of the node that contains the output port.
- portNameA – The name of the output port that was connected.
- portB – The input port that was connected to the output port.
- nodeNameB – The name of the node that contains the input port.
- portNameB – The name of the input port that was connected.
- oldSourceNode – The name of a node that contained the output port that was previously connected to the input port, if any.
- oldSourcePort – The name of an output port that was previously connected to the input port, if any.
- eventID –
-
port_disconnect
¶ Ports of nodes have been disconnected
Parameters: - eventID –
hash(Port)
- portA – The output port that was connected to an input port.
- nodeNameA – The name of the node that contains the output port.
- portNameA – The name of the output port that was connected.
- portB – The input port that was connected to the output port.
- nodeNameB – The name of the node that contains the input port.
- portNameB – The name of the input port that was connected.
- isPortASendPort – True if the upstream port A is a send port on the inside of a GroupNode, otherwise False.
- isPortBReturnPort – True if the downstream port B is a return port on the inside of a GroupNode, otherwise False.
- nodeAShapeAttrs – The node shape attributes of the node on which port A belongs.
- nodeBShapeAttrs – The node shape attributes of the node on which port B belongs.
- eventID –
-
nodegraph_changed
¶ Called once per idle when any action has changed the node graph.
Parameters: eventID – 0
-
nodegraph_setRootNode
¶ A new root node has been set
Parameters: eventID – 0
-
nodegraph_loadBegin
¶ About to load nodes from a node graph document.
Parameters: eventID – 0
-
nodegraph_loadEnd
¶ Finished loading nodes from a node graph document.
Parameters: eventID – 0
-
nodegraph_setCurrentTime
¶ Current frame changed.
Parameters: - eventID –
0
- currentTime – current frame
- eventID –
-
nodegraph_setTimeRange
¶ inTime and outTime frames changed.
Parameters: eventID – 0
-
nodegraph_setWorkingTimeRange
¶ workingInTime and workingOutTime frames changed.
Parameters: eventID – 0
-
nodegraph_setTimeIncrement
¶ Time increment changed.
Parameters: eventID – 0
-
nodegraph_registerType
¶ New node type registered
Parameters: - eventID –
0
- type – Name of the newly registered type
- eventID –
-
event_idle
¶ Sent when each call to
EventModuleProcessEvents()
is finished.