Callbacks and Events

Registering a Callback

Callbacks.addCallback(callbackType, callbackFcn, callbackObjectHash=None)
Callbacks.delCallback(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)

Adds the description of an event to the event queue, based on the given arguments.

Parameters
  • eventType (str) – The type of event to add to the event queue, e.g. 'node_create'.

  • eventID (hashable) – A hashable object that can be checked in event handlers to filter event handling.

  • priority (int) – The level of importance of the event to add, in relation to other events in the event queue: - priority < 0 - low priority - priority = 0 - normal priority - priority > 0 - high priority

  • kwargs (dict) – A dictionary of keyword arguments that provides information about or data associated with the event to add.

Utils.EventModule.QueuePriorityEvent(eventType, eventID, **kwargs)

Adds the description of some important event to the event queue, based on the given arguments, indicating that is should be handled as soon as possible.

Parameters
  • eventType (str) – The type of event to add to the event queue, e.g. 'node_create'.

  • eventID (hashable) – A hashable object that can be checked in event handlers to filter event handling.

  • kwargs (dict) – A dictionary of keyword arguments that provides information about or data associated with the event to add.

Utils.EventModule.ProcessEvents()

Processes all events that are currently in the event queue, by calling any event handlers that were registered against combinations of event type and event ID.

Return type

bool

Returns

True if more events are still to be processed, as events were added to the event queue while processing events, otherwise False.

See

ProcessAllEvents()

Utils.EventModule.ProcessAllEvents()

Processes events until the event queue is empty.

Some handlers will add new events of their own. When this happens, a single ProcessEvents() call will not clear the queue completely, but a call of ProcessAllEvents() will.

See

ProcessEvents()

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, otherwise False.

Utils.EventModule.UnregisterEventFilter(eventFilter)

Un-registers 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 un-register.

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.Initialize()

Initializes the processing of events.

Utils.EventModule.IsCollapsedHandlerRegisteredAfterEventLoop(handler, eventType, eventID)

Determines if the specified handler is already registered and still will be once the event loop is over.

I.e. takes into account whether UnregisterEventHandler has been called from within the event loop.

Utils.EventModule.IsCollapsedRegistered(handler, eventType=None, eventID=None)

Determines if the specified collapsed handler is already registered.

This corresponds with whether or not RegisterEventHandler / UnregisterEventHandler will raise ValueError exception.

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.IsHandlerRegisteredAfterEventLoop(handler, eventType, eventID)

Determines if the specified handler is already registered and still will be once the event loop is over.

I.e. takes into account whether UnregisterEventHandler has been called from within the event loop.

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()

Context manager that forces all events that are queued through a call to QueueEvent to be processed synchronously, as soon as they are queued.

Deprecated

No longer supported since Katana 3.1v1.

Utils.EventModule.SetRegistrationCallbackForType(cls, 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
  • cls (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.

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()

Schedules the processing of events that indicate that the application is idle, triggering event handlers that were registered for 'event_idle' events.

Callback Types

To see a list of callback types:

from Katana import Callbacks

print(dir(Callbacks.Type))

Event Types

To see a list of event types:

from Katana import Utils

print(sorted(Utils.EventModule.GetAllRegisteredEventTypes()))
node_create

A node is created

Parameters
  • eventIDhash(Node)

  • node – the created node

  • nodeType – the type used to create the node

  • nodeName – the name of the node created

See

NodegraphAPI.CreateNode()

node_setName

Node name changed

Parameters
  • eventIDhash(Node)

  • node – the node renamed

  • oldName – previous node name

  • newName – current node name

See

NodegraphAPI.Node.setName()

node_setParent

Indicates a change of parent node for a particular node.

Parameters
  • eventIDhash(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

See

NodegraphAPI.Node.setParent()

node_setLocked

Node locked or unlocked

Parameters
  • eventIDhash(Node)

  • node – node locked

  • locked – boolean state of node lock

See

NodegraphAPI.Node.setLocked()

node_setBypassed

Node ignored

Parameters
  • eventIDhash(Node)

  • node – node locked

  • bypassed – boolean state of node bypass

See

NodegraphAPI.Node.setBypassed()

node_setFloating

Node floating state changed

Parameters
  • eventIDhash(Node)

  • node – node floated

See

NodegraphAPI.SetNodeFloating()

node_setHidden

Node hidden state changed

Parameters
  • eventIDhash(Node)

  • node – node hidden

See

NodegraphAPI.SetNodeHidden()

node_setEdited

Node edit state changed

Parameters
  • eventIDhash(Node)

  • node – node edited

See

NodegraphAPI.SetNodeEdited()

node_setViewed

Node view state changed

Parameters
  • eventIDhash(Node)

  • node – node viewed

See

NodegraphAPI.SetNodeViewed()

node_setSelected

Node selection state changed

Parameters
  • eventIDhash(Node)

  • node – node selected

See

NodegraphAPI.SetNodeSelected()

node_attributeEditorSetActive

AttributeEditor node active state changed

Parameters
  • eventIDhash(Node)

  • node – AttributeEditor node changed

See

NodegraphAPI.SetAttributeEditorNodeActive()

node_setPosition

Node moved in graph view

Parameters
  • eventIDhash(Node)

  • node – node moved

  • nodeName – name of the node moved

  • oldPosition – previous (x,y) position

  • newPosition – current (x,y) position

See

NodegraphAPI.SetNodePosition()

node_delete

Node destroyed

Parameters
  • eventIDhash(Node)

  • node – node in a zombie state

  • oldName – name of the node before death

See

NodegraphAPI.Node.delete()

node_addInputPort

Node input port added

Parameters
  • eventIDhash(Node)

  • node – node modified

  • nodeName – name of node modified

  • port – port object added

  • portName – name of new port

See

NodegraphAPI.Node.addInputPort()

node_addOutputPort

Node output port added

Parameters
  • eventIDhash(Node)

  • node – node modified

  • nodeName – name of node modified

  • port – port object added

  • portName – name of new port

See

NodegraphAPI.Node.addOutputPort()

node_renameInputPort

Node input port renamed

Parameters
  • eventIDhash(Node)

  • node – node modified

  • nodeName – name of node modified

  • oldPortName – old name of renamed input port

  • newPortName – new name of renamed input port

See

NodegraphAPI.Node.renameInputPort()

node_renameOutputPort

Node output port renamed

Parameters
  • eventIDhash(Node)

  • node – node modified

  • nodeName – name of node modified

  • oldPortName – old name of renamed output port

  • newPortName – new name of renamed output port

See

NodegraphAPI.Node.renameOutputPort()

node_removeInputPort

Node input port removed

Parameters
  • eventIDhash(Node)

  • node – node modified

  • nodeName – name of node modified

  • port – port object removed

  • portName – name of removed port

See

NodegraphAPI.Node.removeInputPort()

node_removeOutputPort

Node output port removed

Parameters
  • eventIDhash(Node)

  • node – node modified

  • nodeName – name of node modified

  • port – port object removed

  • portName – name of removed port

See

NodegraphAPI.Node.removeOutputPort()

node_tagFlavor

Node flavor changed

Parameters
  • eventID0

  • flavor – the flavor that was added, removed, or cleared

See

NodegraphAPI.AddNodeFlavor(), NodegraphAPI.RemoveNodeFlavor(), NodegraphAPI.ClearFlavorNodes()

parameter_setValue

Parameter’s value changed (during continuous manipulation)

Parameters
  • eventIDhash(Node)

  • param – parameter changed

  • node – parameter node

See

NodegraphAPI.Parameter.setValue()

parameter_finalizeValue

Parameter’s value changed (on pen up)

Parameters
  • eventIDhash(Node)

  • param – parameter changed

  • node – parameter node

See

NodegraphAPI.Parameter.setValue()

parameter_setKey

Key about to be added to parameter curve

Parameters
  • eventIDhash(Node)

  • param – parameter changed

  • keyTime – time of keyframe added

  • node – parameter node

See

NodegraphAPI.Parameter.setKey()

parameter_removeKey

Key about to be removed from parameter curve

Parameters
  • eventIDhash(Node)

  • param – parameter changed

  • keyTime – time of keyframe changed

  • node – parameter node

See

NodegraphAPI.Parameter.removeKey()

parameter_removeKeys

Keys about to be removed from parameter curve

Parameters
  • eventIDhash(Node)

  • param – parameter changed

  • node – parameter node

See

NodegraphAPI.Parameter.removeKeys()

parameter_moveKeys

Keys about to be moved on parameter curve

Parameters
  • eventIDhash(Node)

  • param – parameter changed

  • node – parameter node

See

NodegraphAPI.Parameter.moveKeys()

parameter_createChild

Child parameter created

Parameters
  • eventIDhash(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

See

NodegraphAPI.Parameter.createChildGroup(), NodegraphAPI.Parameter.createChildNumber(), NodegraphAPI.Parameter.createChildNumberArray(), NodegraphAPI.Parameter.createChildString(), NodegraphAPI.Parameter.createChildStringArray(), NodegraphAPI.Parameter.createChildXmlIO(),

parameter_deleteChild

Child parameter deleted

Parameters
  • eventIDhash(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

See

NodegraphAPI.Parameter.deleteChild()

parameter_replaceXML

Parameter hierarchy changed

Parameters
  • eventIDhash(Node)

  • param – root parameter changed

  • paramName – root parameter name

  • oldXML – previous XML representation

  • newXML – current XML representation

  • node – parameter node

See

NodegraphAPI.Parameter.replaceXML(), NodegraphAPI.Parameter.replaceXmlIO()

parameter_setAutoKeyAll

Global auto-key state changed

Parameters

eventID0

See

NodegraphAPI.SetAutoKeyAll()

port_connect

Ports of nodes have been connected

Parameters
  • eventIDhash(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.

See

NodegraphAPI.Port.connect()

port_disconnect

Ports of nodes have been disconnected

Parameters
  • eventIDhash(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.

See

NodegraphAPI.Port.disconnect()

nodegraph_changed

Called once per idle when any action has changed the node graph.

Parameters

eventID0

nodegraph_setRootNode

A new root node has been set

Parameters

eventID0

See

NodegraphAPI.SetRootNode()

nodegraph_loadBegin

About to load nodes from a node graph document.

Parameters

eventID0

See

NodegraphAPI.ParseNodegraphXmlIO(), NodegraphAPI.ParseNodesXmlIO()

nodegraph_loadEnd

Finished loading nodes from a node graph document.

Parameters

eventID0

See

NodegraphAPI.ParseNodegraphXmlIO(), NodegraphAPI.ParseNodesXmlIO()

nodegraph_setCurrentTime

Current frame changed.

Parameters
  • eventID0

  • currentTime – current frame

See

NodegraphAPI.SetCurrentTime()

nodegraph_setTimeRange

inTime and outTime frames changed.

Parameters

eventID0

See

NodegraphAPI.SetInTime(), NodegraphAPI.SetOutTime()

nodegraph_setWorkingTimeRange

workingInTime and workingOutTime frames changed.

Parameters

eventID0

See

NodegraphAPI.SetWorkingInTime(), NodegraphAPI.SetWorkingOutTime()

nodegraph_setTimeIncrement

Time increment changed.

Parameters

eventID0

See

NodegraphAPI.SetTimeIncrement()

nodegraph_registerType

New node type registered

Parameters
  • eventID0

  • type – Name of the newly registered type

See

NodegraphAPI.RegisterPythonNodeFactory(), NodegraphAPI.RegisterPythonNodeType(),` NodegraphAPI.RegisterPythonGroupType(),`

event_idle

Sent when each call to Utils.EventModule.ProcessEvents() is finished.